In many organizations, authenticating to systems with a username and password combination is either restricted or outright prohibited. CLI client certificate-based authentication the web user interface (web UI). MSR also works with UCP’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.
Operation |
Benefit |
|---|---|
MKE browser authenticaton |
MKE client bundles enable communication between a local Docker client and UCP without the need of a username and password. You can also import client certificates in the UCP 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.
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.
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.
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.
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)"
Import the PKCS12 file into the browser or Keychain Access if you’re running macOS.
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.
Instructions on how to import a certificate into a web browser vary according to your platform, OS, preferred browser, and browser version:
For pulling and pushing images to your MSR (with client certificate
authentication method enabled) without performing a docker login, do
the following:
Create a directory for your MSR public address or FQDN (Fully Qualified Domain Name) within your operating system’s TLS certificate directory.
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.
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
Restart the Docker daemon for the changes to take effect.
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.
MSR provides the Notary service for using Docker Content Trust (DCT) out of the box.
Implementation |
Settings |
|---|---|
Sign with |
Copy |
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. |
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.
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.
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"
}
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.
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.
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.
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"