Skip to main content

TLS certificates

To let agents and users connect to OpenLM Platform over HTTPS, set up the TLS certificate correctly. The main actors communicating with OpenLM Platform are the field agents (Broker, Workstation Agent, and Directory Synchronization Agent (DSA)) and users accessing the web UI. All of them connect through a single HTTPS endpoint. The TLS certificate provided during deployment is what makes this work. If the certificate is set up incorrectly, agents can't establish the encrypted HTTPS connection and can't communicate with the system.

Requirements​

The certificate must meet the following requirements.

Use PEM-encoded certificate and key files​

Supply the certificate and its private key as separate PEM files (the text format beginning -----BEGIN CERTIFICATE-----). The key file must hold the leaf private key only, never a CA private key. Convert binary formats such as PFX/PKCS#12 or DER first:

openssl pkcs12 -in cert.pfx -clcerts -nokeys -out tls.crt
openssl pkcs12 -in cert.pfx -nocerts -nodes -out tls.key

To verify that the certificate and key are a matching pair, run these commands. The two outputs must be identical:

openssl x509 -noout -modulus -in tls.crt | md5sum
openssl rsa  -noout -modulus -in tls.key | md5sum

Match the certificate to your domain​

The certificate Common Name (CN) or Subject Alternative Name (SAN) must match the fully qualified domain name (FQDN) configured during deployment (for example, openlm.yourcompany.com). This is the domain that all agents and web UI users connect to.

Trust the certificate on every agent machine​

Every machine running a Broker, Workstation Agent, or DSA must trust the certificate. If the certificate is issued by a public CA (like Let's Encrypt or DigiCert), this usually works by default.

If the certificate is issued by an internal or private CA, install the CA's root and intermediate certificates in the OS trust store of each agent machine. Without this, agents refuse to connect.

Trust the certificate inside the Kubernetes cluster​

The microservices must trust the certificate too. This is essential because OpenLM Platform uses an IdentityServer for authentication, and every microservice validates JWT tokens by calling back to the issuer at https://<your-fqdn>/identity. If the certificate is not trusted inside the cluster, services can't reach the identity issuer, JWT validation fails, and users can't sign in.

For a certificate from a private CA, every microservice mounts the full chain (root and intermediate CA certificates):

  • On Platform as VM, from a ConfigMap named custom-ca-cert with the data key custom-ca-cert.crt, which the installer creates.
  • On the other paths, from a secret, through global.deploymentCerts in the OpenLM Platform values. See Trust a private CA inside the cluster.

Configure the certificate​

To configure the certificate, follow the steps for your deployment path.

Platform as VM does this for you

On a Platform as VM deployment, don't create these objects by hand. Place the PEM certificate and key at the paths set by tls_cert_path and tls_key_path in config.yaml (by default /etc/openlm/certs/tls.crt and /etc/openlm/certs/tls.key), and the installer creates both the openlm-lb-cert secret and the custom-ca-cert ConfigMap from them.

For a private or self-signed CA, concatenate the whole chain into the certificate file, with the leaf first, then the intermediates, then the root CA. To rotate the certificate, replace the files and run ./entrypoint.sh. Manual edits to the secret or ConfigMap are overwritten from those file paths on every installer run.

The manual steps in the following sections apply to the AWS, Azure, and on-premises machines paths.

Kubernetes TLS secret​

Load your certificate and private key as a Kubernetes secret in the openlm namespace:

kubectl create secret tls openlm-lb-cert \
  --key your-domain.key \
  --cert your-domain.crt \
  -n openlm

Trust a private CA inside the cluster​

If your certificate comes from a private CA, mount the CA chain into the microservices with global.deploymentCerts in the OpenLM Platform values. The chart then mounts one key of a secret as a file in every microservice. The following example points it at the TLS secret, whose certificate file must then hold the whole chain: the leaf first, then the intermediates, then the root CA.

global:
  deploymentCerts:
    enabled: true
    name: openlm-lb-cert
    secretKeyName: tls.crt
    secretFileName: custom-ca-cert.crt
    containerMountPath: /usr/local/share/ca-certificates/custom-ca-cert.crt

If you are unsure which certificates the chain needs, go to a website on the same domain in a browser and export the certificate chain.

On Red Hat OpenShift, the routes serve the router's certificate, not openlm-lb-cert. Put the CA chain of the certificate the router serves for your FQDN into a secret, and point deploymentCerts at that secret. See Red Hat OpenShift.

If your certificate is from a public CA, the microservices trust it already, and you don't need deploymentCerts.

Self-signed or custom CA certificates​

If you are using a self-signed certificate or a certificate issued by a custom (internal) CA, provide the full certificate chain in every place where the certificate is used:

  • The Kubernetes TLS secret (openlm-lb-cert) must contain the full chain, not only the leaf certificate.
  • The CA chain mounted into the microservices (the custom-ca-cert ConfigMap on Platform as VM, global.deploymentCerts on the other paths) must include the root and all intermediate CA certificates.
  • The OS trust store on every agent machine and user workstation must have the root CA installed.

Providing only the leaf certificate without the full chain is one of the most common causes of TLS errors. If any link in the chain is missing in any of these locations, the connection fails.

Troubleshooting​

The following entries cover the most common certificate problems.

Check certificate trust first

Untrusted or incomplete certificate chains are the most common cause of agent connection failures. If agents can't reach OpenLM Platform after deployment, check certificate trust and chain completeness first.

Why do agents fail to connect?​

Verify that the CA root certificate is installed in the OS trust store on the agent machine. On Windows, check the Trusted Root Certification Authorities store. On Linux, check /etc/pki/ca-trust/ or /usr/local/share/ca-certificates/.

Why does the browser show a "not secure" warning for OpenLM Platform?​

The certificate does not match the domain, is expired, or the CA is not trusted by the browser.

Why can't users sign in, or why do services show authentication errors?​

The CA chain inside the cluster is likely missing or incomplete: the custom-ca-cert ConfigMap on Platform as VM, or the secret behind global.deploymentCerts on the other paths. Each service must trust the certificate to validate JWT tokens against the identity issuer (https://<your-fqdn>/identity). Verify that the chain is complete and redeploy.

Checklist​

Last updated on by Maria Gilca

The documentation team might draft this page using a large language model. A technical writer reviews every page and verifies it against the product before publishing it. A human makes the final decision.