Internal certificates

Prev Next

This section discusses the Certificate Authority (CA), appliance certificates, and managing issued certificates.


Certificate Authority

The security of an AppGate ZTNA Collective is initially based on a 10-year, self-signed root CA certificate. The Controller acts as the CA for the Collective, issuing certificates that establish trusted communications between appliances and between clients and appliances.

Use the Certificate Authority page (System > Certificate Authority) to manage CA certificates. The page displays the following at the top:

  • Time left on Current CA. The number of days remaining on the current CA certificate.

  • Next CA status. The status of the next CA certificate.

The lower half of the page contains the Current CA and Next CA tabs.

Current CA

The Current CA tab displays details of the current CA certificate, including the organization, validity dates, and any name constraints the certificate contains.

The tab also displays the CA fingerprint. The client profile uses this fingerprint to verify the authenticity of the Controller. Select the copy icon to copy the fingerprint if needed.

Select the Actions button to access the following options:

  • Download CRL File. Downloads the CRL file.

  • Download Certificate. Downloads the CA certificate. This may be required when running remote scripts, such as with sdpctl. The certificate is also available for direct download at https://mycontroller.com:8443/ui/global-settings/ca.

For more information, see Upgrading an appliance with sdpctl and Device and client controls.

Next CA

Generate the next CA certificate well before the current certificate expires. Use the next CA in parallel with the current CA until distribution to all clients and appliances is complete.

Select the Actions button to access the following options:

  • Generate. Creates a new internal CA certificate. Set the certificate's subject and validity period (up to 20 years). Use this option to set an appropriate validity period for your deployment.

  • Upload. Uploads an externally generated CA certificate. Create and upload a P12 file, enter the password if the file is password-protected, and optionally enable CRL. Generating the internal CA certificate is the preferred approach.

During the transitional phase, the system distributes the next CA certificate to each client when it connects. The client receives the next CA certificate only at sign-in or when its claims token is renewed. Allow sufficient time for all clients to connect at least once before activating the next CA. Appliances in the Collective follow the same distribution process, but distribution is nearly immediate. New client profiles generated after this point include the next CA certificate automatically.

NOTE

Write access to TrustedCertificatePath is required when using the headless client.

During the transitional phase, you can also copy the next CA fingerprint and download the next CA certificate, in the same way as the current CA certificate.

To activate the next CA, you must first add a replacement license. For more information, see Licenses and the Activating the next CA certificate section below.


Downloading the current CA certificate

Download the current CA certificate from the Current CA tab. Use the certificate for the following purposes:

  • Adding it to the local certificate stores on administrators' devices when a trusted certificate is not in use, which reduces browser warnings for administrative access.

  • Supporting the following components: the admin UI, sdpctl, and auto-scaling.

Certificate Revocation List

When you upload your own CA certificate, you can enable the Certificate Revocation List (CRL). The Controller cannot act as the CRL distribution point because SPA protects it and it is not readily accessible from outside the Collective.

When CRL is enabled, specify a remote CRL Distribution Point URL. This is typically an HTTP web server configured to deliver content of type application/pkix-crl. AppGate ZTNA clients and appliances use this URL to check for revoked certificates.

After you activate the next CA, a Download CRL button becomes available. Use this button to download the CRL and upload it manually to the remote CRL distribution point.

When CRL is enabled and unavailable, the appliance enters a Warning state. The system checks the CRL every hour. To update the CRL immediately, run:

sudo cz-config update-crl

When CRL is enabled, the Issued Certificates page appears under Usage > Issued Certificates. From this page, you can revoke one or more certificates as needed.

NOTE

Use CRL only in advanced use cases. CRL introduces a single point of failure that can completely disable an AppGate ZTNA Collective.

License update

The system license is tied to the CA certificate. When you activate the next CA certificate, the existing license expires. During this transitional phase, obtain a replacement license from AppGate Support.

The replacement license uses a new request code—for example, 164186314c5_v2. For more information, see Licenses.


Distributing the next CA certificate

AppGate ZTNA includes built-in support for CA transitions that are transparent to users. After you add the next CA certificate, it coexists with the current CA certificate for as long as needed during the transitional phase.

The system distributes the next CA certificate to each client when it connects. The client receives the next CA certificate only at sign-in or when its claims token is renewed. Allow sufficient time for all clients to connect at least once before activating the next CA.

Appliances in the Collective follow the same process, but distribution is nearly immediate. New client profiles generated after this point include the next CA certificate automatically.

Use the LogServer to identify clients that have not yet connected. Before doing so, verify that the log retention period is longer than the planned transitional period.

To identify clients that have not yet received the next CA certificate in OpenSearch:

  1. Select Visualize from the menu.

  2. Use the saved visualization Last next Controller CA Certificate generation to identify when the next CA certificate was generated.

  3. Use the saved visualization Last authentication date per distinguished name to view the last authentication date for each client.

  4. To identify device IDs, go to the onboarded devices screen in the admin UI and search by full distinguished name or device ID.

List of distinguished names with corresponding timestamps and organizational units.


Activating the next CA certificate

When you are ready to replace the current CA certificate, activate the next Controller CA certificate. The replacement license is applied automatically at this time.

When activation occurs, the following happens:

Admin UI

  • The admin UI disconnects.

  • A page refresh is required. Accept the new certificate before signing in again.

Peers

  • Peers must be connected to the Controller.

  • The Controller health-checks each peer using the next appliance certificate thumbprint.

  • The Controller instructs each peer to switch certificates, moving the next appliance certificate to the current appliance certificate, and then applies the configuration.

Clients

  • The next Controller CA certificate becomes the current Controller CA certificate.

  • Clients renew their VPN certificate, which causes a brief disconnection.

NOTE

Devices and users that have not received the next Controller CA certificate will not complete the CA switch successfully. On their next sign-in attempt, they receive an "Invalid certificate" error. Recovery requires manually clearing the certificate store and deploying an updated client profile. For more information, see Client Deployment and Management.


Appliance certificates

Hostname settings

Each appliance is identified by its Appliance Hostname/IP in System Settings.

NOTE

Use the Interfaces field to add additional interfaces (eth1, eth2, eth3, and so on) if needed. These interfaces typically correspond to additional NICs connected to internal networks.

When you first configure an appliance, the system automatically includes its hostname, IP address, and DNS names in the appliance certificate. Use Extra Hostnames in Certificate to add additional hostname aliases. This supports TLS connections to other hosts, such as when a load balancer is deployed in front of appliances.

If you change any hostname or IP address details in the appliance configuration, you must renew the appliance certificate. In some cases, the system triggers renewal automatically when you commit the change. In other cases, the system prompts you to renew manually.

Client hostname

The Client Hostname/IP field in Secure Tunnel Settings defines the name passed to the client during sign-in, which the client uses to connect to Gateways. This field is not the hostname setting for the appliance itself. The system populates this field automatically with the appliance hostname, but you can override it if needed.

Saving changes does not affect active client sessions. If you change the Client Hostname/IP on an active appliance, renew the appliance certificate manually after saving. Until you renew the certificate, new client connections to the Gateway may fail.

Certificate renewal

New appliances receive certificates valid for approximately two years and three months. Renewing certificates before expiration is critical for Controllers. If a Controller certificate expires, the trust model across the entire Collective fails. When an appliance certificate is due to expire within 30 days, the appliance health check status changes to Warning. Sign in to the admin UI regularly to monitor this condition.

Auto-renewal

To reduce the risk of expired Controller certificates, the system automatically renews expiring appliance certificates 24 hours before expiration. This process causes minor service disruption.

Manual renewal

To manually renew an appliance certificate after saving configuration changes:

  1. On the Appliances page, select Renew Certificate.

  2. Select OK to confirm.

During renewal, the appliance deactivates temporarily. The Appliances page may show the appliance as Not Activated for a short period. No administrative action is required during this time. After renewal completes, the appliance status returns to Activated.

Active client connections drop during renewal but reconnect automatically when renewal completes. In high-availability deployments, the system typically fails users over to alternate Gateways.


Managing issued certificates

The Issued Certificates page (Usage > Issued Certificates) is visible only when you upload a new CA certificate with CRL enabled. When enabled, Controllers track all issued certificates.

Revoking and downloading certificates

Use the action button—the three dots icon (Three circular shapes stacked vertically on a dark background, selected to access a menu.) to the right of each line item—to access the following options:

  • Revoke Certificate. Revokes the client certificate. You cannot revoke appliance certificates directly. To revoke an appliance certificate, renew it or deactivate the appliance.

  • Download Certificate. Downloads the certificate.

To revoke or download multiple certificates at once, select the checkbox next to each certificate and then select the action. For more information about bul00k actions, see the Admin UI section.