You can upload third-party certificates bundled with a private key for use in several places in AppGate ZTNA. When a third-party certificate is due to expire within 30 days (90 days for the external root CA certificate), the appliance health check is set to Warning. Sign in to the admin UI regularly to monitor certificate expiration.
The following table describes where third-party certificates are used and how to add them:
Use case | Where to add the PKCS#12 file | Description |
|---|---|---|
Admin/API access | Admin/API TLS Connection settings in Controllers and LogServers. | Admin and API access uses a unique admin hostname with a self-signed root certificate, which causes browsers to display a warning. To remove the warning, upload a PKCS#12 file containing a certificate for the unique admin hostname signed by a trusted CA, along with the private key. |
URL user access | Tunneling settings in System > Sites. | The URL access feature operates as a reverse proxy for client traffic. The appliance requires a PKCS#12 file to terminate HTTPS connections, decrypt traffic, apply URL filtering, and reestablish an outbound HTTPS connection to the protected hosts. URL access supports multiple PKCS#12 files, each containing a certificate for a protected host signed by a trusted CA, along with the private key. A wildcard certificate is an alternative to multiple certificates, but limit its scope due to the security implications if the certificate is compromised. |
Portal client | HTTPS Settings when configuring a Portal. | The Portal requires a fully qualified domain name (FQDN) for the Portal hostname, where users sign in using a web client. Users are also redirected to this hostname when they access a protected host URL directly. Upload a PKCS#12 file containing a certificate for the Portal hostname signed by a trusted CA, along with the private key. |
Portal user access | User Access Settings when configuring a Portal. | The Portal operates as a reverse proxy for user traffic. It terminates HTTPS connections, decrypts traffic, and reestablishes an outbound HTTPS connection to the protected hosts. The Portal supports multiple PKCS#12 files, each containing a certificate for a protected host signed by a trusted CA, along with the private key. A wildcard certificate is an alternative to multiple certificates, but limit its scope due to the security implications if the certificate is compromised. |
Metrics forwarding | Prometheus Exporter Settings when configuring a Metrics Aggregator. | Metrics scraping requires a PKCS#12 file containing a certificate for the appliance hostname signed by a trusted CA, along with the private key, to terminate the inbound HTTPS connection used to scrape metrics. |
External root CA | The Certificate Authority page (System > Certificate Authority). | The initial Controller in a Collective creates a CA certificate with a 10-year lifetime. Generate the next CA certificate well before the current one expires. You can also upload an externally generated root certificate as the next CA certificate, but generating the internal CA certificate is preferable. |
Using an externally-signed certificate
For connections that terminate on the appliance, a specific hostname is required. A wildcard certificate and private key covering that hostname may already exist — package them into a PKCS#12 file and export the file to each appliance that requires it. If you have concerns about private key exposure, generate a new private key directly on the appliance and use it with a certificate covering only that hostname.
The PKCS#12 file must meet the following requirements:
Include all relevant intermediate certificates so the certificate chain can be verified. For self-signed certificates, include the full chain up to the root CA.
Do not encrypt the private key (no passphrase).
Add certificates to the PKCS#12 file in order: web server certificate, intermediate certificate, and so on, ending with the root CA.
Wildcard certificates are supported.
Creating the certificate
The following example shows one way to create a PKCS#12 file for use with AppGate ZTNA using OpenSSL. You can use alternate parameters or tools. If you are not familiar with certificate signing, have someone experienced handle this process.
You need SSH terminal access. You can run these commands on your own device or on the appliance. Plan the process to minimize exposure of the private key.
Create a private key:
openssl genrsa -out /mnt/state/pki/my-appliance.pem 2048Create a certificate signing request (CSR) using the private key:
openssl req -new -sha256 -key /mnt/state/pki/my-appliance.pem -out /mnt/state/pki/my-appliance.csrTo view the CSR, run:
openssl req -text -noout -in /mnt/state/pki/my-appliance.csrSend the CSR file
/mnt/state/pki/my-appliance.csrto the appropriate certificate authority (CA). The CSR is a public file. The CA uses it to generate a signed certificate and returns a.crtfile.
Using the certificate
When you receive the signed certificate, combine it with the private key into a PKCS#12 file before uploading it to the appliance. Handle the private key carefully throughout this process.
Create the PKCS #12 file:
openssl pkcs12 -export -out my-appliance.pfx -inkey my-appliance.pem -in my-appliance.crtUpload the PKCS#12 file using the admin UI.