Enable authentication using TLS client certificates

Enable authentication using TLS client certificates

In many organizations, authenticating to systems with a username and password combination is either restricted or outright prohibited. CLI client certificate-based authentication can be used to access the MKE and MSR web UIs. MSR also works with MKE’s internally generated client bundles for client certificate-based authentication. If you have an external public key infrastructure (PKI) system, you can manage user authentication using a pool of X.509 client certificates in lieu of usernames and passwords.


The following table outlines existing and added capabilities when using client certificates – both internal to MKE and issued by an external certificate authority (CA) – for authentication.



MKE browser authenticaton

MKE client bundles enable communication between a local Docker client and MKE without the need of a username and password. You can also import client certificates in the MKE web UI.

MSR browser authentication

You can bypass the login page for the MSR web UI when you use TLS client certificates as a MSR authentication method.

Image pulls and pushes to MSR

You can update MCR with a client certificate for image pulls and pushes to MSR without the need for docker login.

Image signing

You can use client certificates to sign images that you push to MSR. Depending on which you configure to talk to MSR, the certificate files need to be located in certain directories. Alternatively, you can enable system-wide trust of your custom root certificates.

MSR API access

You can use TLS client certificates in lieu of your user credentials to access the MSR API.

Notary CLI operations with MSR

You can set your MSR as the remote trust server location and pass the certificate flags directly to the Notary CLI to access your MSR repositories.


  • The security of client certificates issued by your organization’s PKI is outside of MKE’s control. MKE administrators are responsible for instructing their users on how to authenticate via client certificates.

  • Username and password authentication cannot be disabled.

  • If client certificates have been configured, they will be used for all docker push and docker pull operations for all users of the same machine.

  • MKE does not check certificate revocation lists (CRLs) or Online Certificate Status Protocol (OCSP) for revoked certificates.

MKE / MSR browser authentication

You have to be an admistrator to follow these instructions. If you are not an admin, contact your administrator for details on your PKI’s client certificate configuration.

To bypass the browser login pages and hide the logout buttons for both MKE and MSR, follow the steps below.

  1. Add your organization’s root CA certificates via the MKE web UI or the CLI.

    For testing purposes, you can download the client bundle from MKE and then convert the client certificates to pkcs12, as descrribed below.

  2. Download MKE’s ca.pem from https://<mke-url>/ca either in the browser or via curl. When using curl, redirect the response output to a file. curl -sk https://<mke-url>/ca -o ca.pem.

  3. Enable client certificate authentication for MSR. If previously installed, reconfigure MSR with your MKE hostname’s root CA certificate. This will be your organization’s root certificate(s) appended to MKE’s internal root CA certificates.

    docker run --rm -it mirantis/dtr:2.8.2 reconfigure --debug --ucp-url \
    <mke-url> --ucp-username <mke_admin_user> --ucp-password \ <mke_admin_password> --enable-client-cert-auth
    --client-cert-auth-ca "$(cat ca.pem)"
  4. Import the PKCS12 file into the browser or Keychain Access if you’re running macOS.

Client certificate to PKCS12 file conversion

From the command line, switch to the directory of your client bundle and run the following command to convert the client bundle public and private key pair to a .p12 file.

openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem

Create with a simple password, you will be prompted for it when you import the certificate into the browser or Mac’s Keychain Access.

PKCS12 file browser import

Instructions on how to import a certificate into a web browser vary according to your platform, OS, preferred browser, and browser version:

Image pulls and pushes to MSR

For pulling and pushing images to your MSR (with client certificate authentication method enabled) without performing a docker login, do the following:

  1. Create a directory for your MSR public address or FQDN (Fully Qualified Domain Name) within your operating system’s TLS certificate directory.

  2. As a superuser, copy the private key (client.pem) and certificate (client.cert) to the machine you are using for pulling and pushing to MSR without doing a docker login. Note that the filenames must match.

  3. Obtain the CA certificate from your MSR server, ca.crt from https://<dtrurl>/ca, and copy ca.crt to your operating system’s TLS certificate directory so that your machine’s MCR will trust MSR. For Linux, this is /etc/docker/certs.d/<dtrurl>/. On Docker for Mac, this is /<home_directory>/certs.d/<dtr_fqdn>/. This is a convenient alternative to, for Ubuntu as an example, adding the MSR server certificate to /etc/ca-certs and running update-ca-certificates. curl   curl -k https://<msr>/ca -o ca.crt On Ubuntu `bash  cp ca.crt /etc/ca-certs

  4. Restart the Docker daemon for the changes to take effect.

Add your MSR server CA certificate to system level

You have the option to add your MSR server CA certificate to your system’s trusted root certificate pool. This is MacOS Keychain or /etc/ca-certificates/ on Ubuntu. Note that you will have to remove the certificate if your MSR public address changes.

Image signing

MSR provides the Notary service for using Docker Content Trust (DCT) out of the box.



Sign with docker trust sign

Copy ca.crt from https://<msr-external-url>/ca to: /etc/docker/certs.d/ (Linux) <home_directory>/.docker/certs.d/ (mac)

Enforce signature or hash verification on the Docker client

export DOCKER_CONTENT_TRUST=1 to enable content trust on the Docker client. Copy ca.crt from https://<msr-external-url>/ca to /<home_directory>/.docker/tls/ on Linux and macOS. docker push will sign your images.

Sign images that MKE can trust

Configure MKE to run only signed images. See Sign an image for detailed steps.

MSR API access

With curl, you can interact with the MSR API by passing a public certificate and private key pair instead of your MSR username and password/authentication token. cert.pem contains the public certificate and key.pem contains the private key.

curl --cert cert.pem --key key.pem  -X GET \
"https://<msr-external-url>/api/v0/repositories?pageSize=10&count=false" \
-H "accept:application/json"

For non-admin users, you can generate a client bundle from MKE or contact your administrator for your public and private key pair. For Mac-specific information, see curl on certain macOS versions.

Notary CLI operations with MSR

For establishing mutual trust between the Notary client and your trusted registry (MSR) using the Notary CLI, place your TLS client certificates in <home_directory>/.docker/tls/<msr-external-url>/ as client.cert and client.key.

The filenames must match. Pass the FQDN or publicly accessible IP address of your registry along with the TLS client certificate options to the Notary client. To get started, see Use the Notary client for advanced users.


MSR authentication via client certificates

Discover your MSR’s basic_info endpoint via curl.

curl --cert cert.pem --key key.pem -X GET "https://<msr-external-url>/basic_info"

If successfully configured, you should see TLSClientCertificate listed as the AuthnMethod in the JSON response.

Example Response

"CurrentVersion": "2.7.0",
"User": {
"name": "admin",
"id": "30f53dd2-763b-430d-bafb-dfa361279b9c",
"fullName": "",
"isOrg": false,
"isAdmin": true,
"isActive": true,
"isImported": false
"IsAdmin": true,
"AuthnMethod": "TLSClientCertificate"

MSR as an insecure registry

Avoid adding MSR to Mirantis Container Runtime’s list of insecure registries as a workaround. This has the side effect of disabling the use of TLS certificates.

MSR server certificate errors

Example Error

  • On the web UI, make sure to add the IP address or the FQDN associated with your custom TLS certificate under System > General > Domains & Proxies.

  • From the command line interface, reconfigure MSR with the --dtr-external-url option and the associated PEM files for your certificate.

Intermediate certificates

For chain of trust which includes intermediate certificates, you may optionally add those certificates when installing or reconfiguring MSR with --enable-client-cert-auth and --client-cert-auth-ca. You can do so by combining all of the certificates into a single PEM file.

curl on certain macOS versions

Some versions of macOS include curl which only accepts .p12 files and specifically requires a ./ prefix in front of the file name if running curl from the same directory as the .p12 file:

curl --cert ./client.p12  -X GET \
"https://<msr-external-url>/api/v0/repositories?pageSize=10&count=false" \
-H "accept:application/json"