Use your own TLS certificates

Estimated reading time: 2 minutes

All UCP services are exposed using HTTPS, to ensure all communications between clients and UCP are encrypted. By default, this is done using self-signed TLS certificates that are not trusted by client tools like web browsers. So when you try to access UCP, your browser warns that it doesn’t trust UCP or that UCP has an invalid certificate.

invalid certificate

The same happens with other client tools.

$ curl https://ucp.example.org

SSL certificate problem: Invalid certificate chain

You can configure UCP to use your own TLS certificates, so that it is automatically trusted by your browser and client tools.

To ensure minimal impact to your business, you should plan for this change to happen outside business peak hours. Your applications will continue running normally, but existing UCP client certificates will become invalid, so users will have to download new ones to access UCP from the CLI.

Configure UCP to use your own TLS certificates and keys

In the UCP web UI, log in with administrator credentials and navigate to the Admin Settings page.

In the left pane, click Certificates.

Upload your certificates and keys:

  • A ca.pem file with the root CA (Certificate Authority) public certificate.
  • A cert.pem file with the TLS certificate for your domain and any intermediate public certificates, in this order.
  • A key.pem file with TLS private key. Make sure it is not encrypted with a password. Encrypted keys should have ENCRYPTED in the first line.

After replacing the TLS certificates, your users will not be able to authenticate with their old client certificate bundles. Ask your users to access the UCP web UI and download new client certificate bundles.

As of UCP v3.2, the Certificates page includes a new text field, Client CA, that allows you to paste or upload one or more custom root CA certificates which the UCP Controller will use to verify the authenticity of client certificates issued by your corporate or trusted third-party CAs. Note that your custom root certificates will be appended to UCP’s internal root CA certificates.

Finally, click Save for the changes to take effect.

If you deployed Docker Trusted Registry, you’ll also need to reconfigure it to trust the new UCP TLS certificates. Learn how to configure DTR.

Where to go next

Universal Control Plane, UCP, certificate, authentication, tls