Skip to main content

Tutorial: Issue Let's Encrypt SSL Certificates via the Access Server Web API, Including IP Address Certificates

Abstract

Use the Access Server Web API to install a Let's Encrypt SSL certificate via sacli apicall — covers domain (FQDN) and IP address certificates, with automatic renewal. IP address certificates enable browser-trusted connections without a domain name.

Overview

This tutorial shows you how to use the Access Server Web API to request, install, and verify a browser-trusted Let’s Encrypt SSL certificate for the Admin Web UI and Client Web UI.

You can issue a certificate for either:

  • A fully qualified domain name (FQDN), such as vpn.example.com.

  • A public IP address, which lets you use a browser-trusted certificate without a domain name.

Access Server uses the ACME protocol to request the certificate from Let’s Encrypt. After you configure ACME, the Access Server ACME client also manages automatic renewal.

This tutorial demonstrates the Web API workflow by running requests locally with the sacli apicall command. You can also call the same Web API endpoints using cURL or the embedded Swagger UI. Refer to Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0 for examples of each method.

Related certificate tutorials

Choose another method if it better fits your deployment:

Browser-trusted certificates also provide the trusted HTTPS foundation used in Zero Trust Network Access deployments.

Prerequisites

Before you begin, ensure you have:

  • Access Server 3.1.0 or newer.

  • Console access and the ability to get root access.

  • Outbound access to TCP port 443.

  • A public IP address assigned to Access Server.

  • For an FQDN certificate, a domain name that resolves to the Access Server public IP address.

  • Optional: A remote computer if you want to run Web API requests with cURL or Swagger UI instead of sacli apicall.

Review the SSL Certificates reference for background information about web SSL certificates in Access Server.

Note

Web SSL certificates secure the Admin Web UI and Client Web UI. They are separate from the certificates Access Server uses for VPN connections. Replacing the web certificate doesn’t change VPN certificates.

Manually installed certificates

Don’t use the ACME client if you plan to manage a web SSL certificate manually through a third-party certificate authority.

If ACME remains enabled, Access Server can replace the manually installed certificate during the next automatic renewal.

To disable ACME:

  1. Connect to the console and get root privileges.

  2. Run:

    sacli --key "acme.enable" --value "false" ConfigPut

  3. Restart Access Server:

    sacli start

Placeholder values

Replace the following placeholder values with values for your environment:

Placeholder

Description

<ACCESS_SERVER_DOMAIN>

Access Server fully qualified domain name

<ACCESS_SERVER_IP>

Access Server public IP address

Certificate profiles, validity, and renewal

Let’s Encrypt supports different certificate profiles with different validity periods.

  • The default certificate profile issues certificates that are valid for 90 days. Access Server begins automatic renewal after 60 days.

  • The shortlived certificate profile issues certificates that are valid for 160 hours, or approximately 6.7 days. Access Server begins automatic renewal after 3 days.

The shortlived profile is required when requesting a Let’s Encrypt IP address certificate. You can also use the shortlived profile when requesting a certificate for a domain name.

Choose a certificate type

Choose the procedure that matches how users access your Access Server web interfaces.

FQDN certificate

Use an FQDN certificate when users open Access Server with a hostname such as:

https://vpn.example.com

Continue to Issue an SSL certificate for FQDN.

IP address certificate

Use an IP address certificate when users open Access Server directly with its public IP address, such as:

https://203.0.113.5

This provides a browser-trusted certificate without a domain name.

Continue to Issue an SSL certificate for an IP address.

Issue an SSL certificate for FQDN

The Access Server ACME client uses Let’s Encrypt by default.

For domain validation, it uses the TLS-ALPN-01 challenge, which validates control of the domain over TLS port 443 without requiring port 80.

TLS-ALPN-01 doesn’t support wildcard certificates. If you need a wildcard certificate, use the Certbot tutorial instead.

Step 1: Configure the domain

  1. Connect to the console and get root privileges.

  2. Configure the FQDN that should receive the certificate:

    sacli --method POST --url 'api/config-items/Default' --value '{"acme.domains.0": "<ACCESS_SERVER_DOMAIN>"}' apicall

    • A successful request returns:

      null

  3. Restart Access Server services:

    sacli --method POST --url 'api/server/restart?restartMode=warm' --value '' apicall

    • Example output:

      {}

Step 2: Register the ACME account

  1. Register an account with the ACME CA:

    sacli --method POST --url 'api/acme/register-account' --value '{}' apicall

    • Example output:

      {"account":"https://acme-v02.api.letsencrypt.org/acme/acct/3570987755"}

  2. Confirm the response contains an ACME account URL.

Step 3: Request and install the certificate

  1. Request the certificate:

    sacli --method POST --url 'api/acme/request-certificate' --value '{}' apicall

  2. Wait for Access Server to complete the ACME validation.

  3. Confirm that the command completes without an error.

    • Example output:

      null

    • Access Server requests and installs the Let's Encrypt certificate for the configured FQDN.

Continue to Verify an FQDN certificate.

Verify an FQDN certificate

Verify the installed certificate from the browser and Admin Web UI. You can also verify it with the Web API or command-line tools.

Step 1: Verify the certificate in a browser

  1. Open the Admin Web UI using the configured hostname:

    https://<ACCESS_SERVER_DOMAIN>/admin

  2. Open the Client Web UI:

    https://<ACCESS_SERVER_DOMAIN>

  3. Confirm that the browser no longer displays a self-signed certificate warning.

  4. Open the browser's certificate or site information panel.

  5. Confirm that:

    • The certificate hostname matches the Access Server FQDN.

    • Let's Encrypt issued the certificate.

    • The certificate is within its validity period.

    • The browser trusts the certificate chain.

    Note

    Browser interfaces vary. Depending on the browser, certificate and connection details may appear under a lock, tune, shield, or site information icon.

Step 2: Verify the certificate in the Admin Web UI

  1. Sign in to the Admin Web UI.

  2. Navigate to Certificate Management.

  3. Select the Web Server Certificate tab.

  4. Confirm that the expected certificate appears.

  5. Select See full certificate details, if needed.

  6. Verify:

    • Subject.

    • Issuer.

    • Expiration date.

Step 3: Verify the certificate with the Web API

  1. Connect to the console and get root privileges.

  2. Verify via apicall:

    sacli --method POST --url 'api/certificate/info' --value "{\"certificate\": \"$(sacli ConfigQuery|grep cs.cert|cut -d '"' -f 4)\"}" apicall

    • Example output:

      {"serial":"506116826303089592917918274713470173092603","common_name":"<ACCESS_SERVER_DOMAIN>","algorithm":"secp384r1","not_before":"2026-07-26T14:26:50Z","not_after":"2026-10-24T14:26:49Z","self_signed":false,"sha256fp":"10:9b:5f:50:a6:85:ab:b4:94:bb:71:58:13:da:18:6b:80:0c:2a:f8:07:bf:a3:94:7e:c4:63:95:c7:28:e7:8d","subject":["CN=<ACCESS_SERVER_DOMAIN>"],"issuer":["CN=YE1","O=Let's Encrypt","C=US"],"subj_alt_names":["DNS:<ACCESS_SERVER_DOMAIN>"],"ca":false}

  3. Confirm that:

    • self_signed is false.

    • The issuer is Let's Encrypt.

    • The certificate is within its validity period.

    • subj_alt_names contains the expected DNS hostname.

Step 4: (Optional) Verify with OpenSSL

  1. Verify with OpenSSL:

    sacli ConfigQuery|grep cs.cert|cut -d '"' -f 4|sed 's/\\n/\n/g'|openssl x509 -text -noout|head -n 11

    • Example output:

      Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            05:cf:57:fb:1d:10:a7:56:9f:d6:a1:97:75:e9:80:66:9a:fb
        Signature Algorithm: ecdsa-with-SHA384
        Issuer: C = US, O = Let's Encrypt, CN = YE1
        Validity
            Not Before: Jul 26 14:26:50 2026 GMT
            Not After : Oct 24 14:26:49 2026 GMT
        Subject: CN = <ACCESS_SERVER_DOMAIN>

  2. Confirm the issuer, validity period, and subject.

Expected result: The Admin Web UI and Client Web UI present a browser-trusted Let’s Encrypt certificate for the configured FQDN.

Issue an SSL certificate for an IP address

Let’s Encrypt supports IP address certificates, allowing Access Server to present a browser-trusted certificate without a domain name.

IP address certificates are valid for 160 hours, or just over 6 days, rather than the 90-day validity period used for standard domain certificates.

They use Let's Encrypt's shortlived certificate profile.

Note

The shortlived profile is required for IP address certificates, which have a 160-hour validity period. Because these certificates expire quickly, Access Server begins automatic renewal after 3 days.

Step 1: Configure the IP address

  1. Connect to the console and get root privileges.

  2. Configure the public IP address that should receive the certificate:

    sacli --method POST --url 'api/config-items/Default' --value '{"acme.ip_addresses.0": "<ACCESS_SERVER_IP>"}' apicall

    • A successful request returns:

      null

Step 2: Configure the short-lived certificate profile

  1. Configure the certificate profile for IP certificates:

    sacli --method POST --url 'api/config-items/Default' --value '{"acme.cert_profile": "shortlived"}' apicall

    • A successful request returns:

      null

  2. Restart Access Server services:

    sacli --method POST --url 'api/server/restart?restartMode=warm' --value '' apicall

    • Example output:

      {}

Step 3: Register the ACME account

  1. Register an account with the ACME CA:

    sacli --method POST --url 'api/acme/register-account' --value '{}' apicall

    • Example output:

      {"account":"https://acme-v02.api.letsencrypt.org/acme/acct/3570987755"}

  2. Confirm the response contains an ACME account URL.

Step 4: Request and install the IP address certificate

  1. Request the certificate:

    sacli --method POST --url 'api/acme/request-certificate' --value '{}' apicall

  2. Wait for Access Server to complete the ACME validation.

  3. Confirm that the command completes without an error.

    • Example output:

      null

    • Access Server requests and installs the Let's Encrypt IP address certificate.

Continue to Verify an IP address certificate.

Verify an IP address certificate

For an IP address certificate, verify that the IP address appears in the certificate’s Subject Alternative Name (SAN).

Unlike many domain certificates, an IP address certificate may not have a Common Name value.

Step 1: Verify the certificate in a browser

  1. Open the Admin Web UI using the configured hostname:

    https://<ACCESS_SERVER_IP>/admin

  2. Open the Client Web UI:

    https://<ACCESS_SERVER_IP>

  3. Confirm that the browser no longer displays a self-signed certificate warning.

  4. Open the browser's certificate or site information panel.

  5. Confirm that:

    • The certificate covers the Access Server IP address.

    • Let's Encrypt issued the certificate.

    • The certificate is within its validity period.

    • The browser trusts the certificate chain.

    Note

    Browser interfaces vary. Depending on the browser, certificate and connection details may appear under a lock, tune, shield, or site information icon.

Step 2: Verify the certificate in the Admin Web UI

  1. Sign in to the Admin Web UI.

  2. Navigate to Certificate Management.

  3. Select the Web Server Certificate tab.

  4. Confirm that the expected certificate appears.

  5. Select See full certificate details, if needed.

  6. Verify:

    • Subject.

    • Issuer.

    • Expiration date.

Step 3: Verify the certificate with the Web API

  1. Connect to the console and get root privileges.

  2. Verify via apicall:

    sacli --method POST --url 'api/certificate/info' --value "{\"certificate\": \"$(sacli ConfigQuery|grep cs.cert|cut -d '"' -f 4)\"}" apicall

    • Example output:

      {"serial":"534506998025996180192364413873987588486223","common_name":null,"algorithm":"secp384r1","not_before":"2026-07-26T14:41:47Z","not_after":"2026-08-02T06:41:46Z","self_signed":false,"sha256fp":"c7:86:0a:26:f4:89:55:d0:1a:14:73:8f:94:ce:8a:91:d0:50:17:d4:8b:cf:e9:a5:fc:ea:89:54:5e:d0:09:5f","subject":[],"issuer":["CN=YE2","O=Let's Encrypt","C=US"],"subj_alt_names":["IP:&lt;ACCESS_SERVER_IP&gt;"],"ca":false}

  3. Confirm that:

    • self_signed is false.

    • The issuer is Let's Encrypt.

    • The certificate is within its validity period.

    • subj_alt_names contains the expected IP address.

Step 4: (Optional) Verify the Subject Alternative Name with OpenSSL

  1. Verify with OpenSSL:

    sacli ConfigQuery|grep cs.cert|cut -d '"' -f 4|sed 's/\\n/\n/g'|openssl x509 -noout -ext subjectAltName

    • Example output:

      X509v3 Subject Alternative Name: critical
    IP Address:<ACCESS_SERVER_IP>

  2. Confirm the IP address appears under SubjectAltName.

Expected result: The Admin Web UI and Client Web UI present a browser-trusted Let’s Encrypt certificate for the configured IP address.

Automatic renewal

After ACME is configured, Access Server manages automatic certificate renewal.

For FQDN certificates

Access Server begins renewal after 60 days for the 90-day certificate.

To maintain successful renewal:

  1. Keep the FQDN pointed to the correct Access Server IP address.

  2. Keep the required ACME validation path available.

  3. Don’t replace the ACME-managed certificate manually.

  4. Review Access Server logs if the certificate approaches expiration without renewing.

For IP address certificates

Access Server begins renewal after 3 days because the shortlived certificate is valid for only 160 hours.

To maintain successful renewal:

  1. Keep the certified public IP address assigned to Access Server.

  2. Ensure the ACME validation requirements remain satisfied.

  3. Don’t disable the ACME client.

  4. Monitor certificate expiration closely if you change networking, firewalls, or public IP addresses.

Troubleshooting

The certificate request fails

  1. Confirm that Access Server can reach the ACME service.

  2. Confirm that the configured FQDN or IP address is correct.

  3. Confirm that the appropriate validation traffic can reach Access Server.

  4. Confirm that the ACME account was registered successfully.

  5. Review the output from the api/acme/request-certificate Web API call.

  6. Review the Access Server logs for ACME-related errors.

The browser still displays a certificate warning

For an FQDN certificate:

  1. Open Access Server using the configured hostname rather than its IP address.

  2. Verify that the hostname appears in the certificate Subject Alternative Name.

  3. Confirm that the certificate is within its validity period.

  4. Confirm that the certificate isn’t self-signed.

For an IP address certificate:

  1. Open Access Server using the exact IP address included in the certificate.

  2. Verify that the IP address appears in the certificate Subject Alternative Name.

  3. Confirm that the short-lived certificate hasn’t expired.

  4. Confirm that automatic renewal has completed successfully.

See also

In this section:

Access Server's web server used by the administrator to configure the VPN server.

Access Server's web server used by clients to download OpenVPN Connect and configuration profiles.