Skip to main content

TLS Certificates

TLS Certificates are digital credentials used to present and prove the identity of a system during a TLS handshake. In USP, TLS Certificates are essential for establishing secure, authenticated communication between trusted components.

TLS Certificates are used in two main contexts:

  • Mutual TLS (mTLS) authentication between the USP Manager and USP Server.
  • Presented by external LDAP servers during inbound authentication, where the USP Server validates the server's identity using a CA Certificate.
info

For more detailed information on TLS Certificates beyond what is covered on this page, refer to Certificates.

Before You Begin​

TLS Certificates in mTLS Authentication​

USP uses TLS Certificates on both ends of the mTLS connection between the USP Manager and USP Server. Each component presents its own TLS Certificate to prove its identity to the other during the handshake.

ComponentRole of TLS CertificateWhere It's Added
USP ManagerPresented to the USP Server to prove the Manager's identity.Selected in the Proxy Server configuration in the USP Admin UI or via the USP REST API.
USP ServerPresented to the USP Manager to prove the Server's identity.Referenced in the web.tls.cert field of the USP Server's .hcl configuration file. The corresponding private key is set in web.tls.key.
info

Each TLS Certificate must be paired with a corresponding Private Key, which is used during the handshake to prove ownership of the certificate.

TLS Certificates in LDAP Server Validation​

When LDAP is used as a Rule's Inbound Authentication Source, the USP Server connects to an external LDAP server, and it might be over a TLS-secured connection. In this case, the LDAP server has to present its own TLS Certificate.

The USP Server does not present a TLS Certificate of its own, but it must be able to validate the LDAP server's certificate using a CA Certificate (configured in the LDAP Connection).

ComponentRole of TLS CertificateWhere It's Presented
LDAP server (external component, not USP's)Presented to the USP Server during the TLS handshake to prove its identity.Delivered by the LDAP server during connection initialization. Not configured in USP.

TLS Certificate Administration via USP Admin UI​

Adding a TLS Certificate​

To add a TLS Certificate, follow these steps:

  1. From the Sidebar, click Authentication > Certificates.
  2. Click TLS Certificates.
  3. Click Add TLS Certificate.
  4. Complete the details for the new TLS Certificate using the Field Descriptions table as a guide.
warning

Once saved, the TLS Certificate's Private Key cannot be viewed again.

  1. Click Save.

Field Descriptions​

NameDescriptionSpecificationsRequired
NameThe name of the TLS Certificate.
  • Must be unique.
  • Must follow the Standard Naming Pattern.
Yes
DescriptionThe description of the TLS Certificate.No
CertificateThe TLS Certificate content.Must be in PEM format.Yes
Private KeyThe Private Key for the TLS Certificate.Yes

Editing a TLS Certificate​

warning

When editing a TLS Certificate, the TLS Certificate and Private Key fields appear empty, but the original values remain stored unless deliberately overwritten. This is intentional, as the USP Manager does not allow updating only one of these fields. To make changes, you must edit both the certificate and its corresponding private key.

To edit a TLS Certificate, follow these steps:

  1. From the Sidebar, click Authentication > Keys.
  2. Click TLS Certificates.
  3. Click the Name of the TLS Certificate you want to edit.
  4. Click the Edit button above the TLS Certificate details.
  5. Edit the details of the TLS Certificate using the Field Descriptions table as a guide.
  6. Click Save.
warning

If you modify a TLS Certificate that is currently in use by a USP Server instance, the changes will not take effect until you manually apply the updated configuration by pushing it to the server. To apply the changes:

  1. Navigate to Monitoring > Status.
  2. Click the Name of the associated USP Server instance.
  3. Go to the Configuration tab.
  4. Review the pending changes in the Updated Configuration column.
  5. If the changes are correct, click Push Configuration.

TLS Certificate Metadata​

TLS Certificate details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

NameDescription
IDUniversally Unique Identifier of this TLS Certificate.
EnabledA Boolean value indicating the status of the TLS Certificate. The only possible value is true.
CertificateThe TLS Certificate content.
Created AtDate and time this TLS Certificate was created.
Updated AtDate and time this TLS Certificate was last updated.

Deleting a TLS Certificate​

To delete a TLS Certificate, follow these steps:

  1. From the Sidebar, click Authentication > Keys.
  2. Click TLS Certificates.
  3. Click the Name of the TLS Certificate you want to delete.
  4. Click the Delete button above the TLS Certificate details.
  5. You will be asked to confirm the deletion. Click Delete.
warning

USP Manager prevents deletion of a TLS Certificate if it is currently referenced by a Configuration Item.

Additionally, if the TLS Certificate is used by a USP Server instance, the updated configuration must be manually applied. To apply the changes:

  1. Navigate to Monitoring > Status.
  2. Click the Name of the associated USP Server instance.
  3. Go to the Configuration tab.
  4. Review the pending changes in the Candidate Configuration - Preview section.
  5. If the changes are correct, click Push Configuration.

The changes do not take effect on the server until this step is completed.