In many organizations, authenticating to systems with a username and password combination is either restricted or outright prohibited. With Docker Enterprise 3.0, UCP’s CLI client certificate-based authentication has been extended to the web user interface (web UI). DTR has also been enhanced to work 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 UCP and issued by an external certificate authority (CA) — for authentication.
| O pera tion | Benefit |
|---|---|
| `UCP bro wser auth enti cati on < #ucp --dt r-br owse r-au then tica tion >`__ | Previously, UCP client bundles enabled communication between a local Docker client and UCP without the need of a username and password. Importing your client certificates into the browser extends this capability to the UCP web UI. |
| `DTR bro wser auth enti cati on < #ucp --dt r-br owse r-au then tica tion >`__ | You can bypass the login page for the DTR web UI when you use TLS client certificates as a DTR authentication method. |
`I mage p ulls and pu shes to DTR
mage -pul ls-a nd-p ushe s-to -dtr >`__ |
You can update Docker engine with a client certificate for
image pulls and pushes to DTR without the need for
docker login. |
`I mage sig ning
mage -sig ning >`__ |
You can use client certificates to sign images that you push to DTR. Depending on which you configure to talk to DTR, the certificate files need to be located in certain directories. Alternatively, you can enable system-wide trust of your custom root certificates. |
| `DTR API acc ess <#dt r-ap i-ac cess >`__ | You can use TLS client certificates in lieu of your user credentials to access the DTR API. |
| `No tary CLI op erat ions with DTR <#no tary -cli -ope rati ons- with -dtr >`__ | You can set your DTR as the remote trust server location and pass the certificate flags directly to the Notary CLI to access your DTR repositories. |
docker push and docker pull operations for all users of
the same machine.The following instructions apply to UCP and DTR administrators. For non-admin users, 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 UCP and DTR, follow the steps below.
Add your organization’s root CA certificates via the UCP web UI or the CLI installation command. For testing purposes, you can download an admin client bundle from UCP and convert the client certificates to ``pkcs12` <#convert-your-client-certificates-to-a-PKCS12-file>`__
Download UCP’s ca.pem from https://<ucp-url>/ca either in the
browser or via curl. When using curl, redirect the response
output to a file. curl -sk https://<ucp-url>/ca -o ca.pem
Enable client certificate authentication for DTR. If previously installed, reconfigure DTR with your UCP hostname’s root CA certificate. This will be your organization’s root certificate(s) appended to UCP’s internal root CA certificates.
docker run --rm -it docker/dtr:2.7.0 reconfigure --debug --ucp-url \
<ucp-url> --ucp-username <ucp_admin_user> --ucp-password \ <ucp_admin_password> --enable-client-cert-auth
--client-cert-auth-ca "$(cat ca.pem)"
See DTR installation and DTR reconfiguration CLI reference pages for an explanation of the different options.
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. As a general rule, refer to one of the following how-to articles: - Firefox: https://www.sslsupportdesk.com/how-to-import-a-certificate-into-firefox/ - Chrome: https://www.comodo.com/support/products/authentication_certs/setup/win_chrome.php - Internet Explorer: https://www.comodo.com/support/products/authentication_certs/setup/ie7.php
For pulling and pushing images to your DTR (with client certificate
authentication method enabled) without performing a docker login, do
the following:
Create a directory for your DTR 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 DTR without
doing a docker login. Note that the filenames must match.
Obtain the CA certificate from your DTR server, ca.crt from
https://<dtrurl>/ca, and copy ca.crt to your operating
system’s TLS certificate directory so that your machine’s Docker
Engine will trust DTR. 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 DTR server certificate to /etc/ca-certs and running
update-ca-certificates.
curl curl -k https://<dtr>/ca -o ca.crt
On Ubuntu `bash cp ca.crt /etc/ca-certs
Restart the Docker daemon for the changes to take effect. See Configure your host for different ways to restart the Docker daemon.
You have the option to add your DTR 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 DTR public address changes.
DTR provides the Notary service for using Docker Content Trust (DCT) out of the box.
Implementation | Component Pairing | Settings |
|---|---|---|
Sign with docker trust sign |
| Copy ca.crt from https://<dtr-external-url>/ca to:
|
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://<dtr-external-url>/ca to /<home_directory>/.docker/tls/ on Linux and macOS. docker push will sign your images. |
Sign images that UCP can trust |
| Configure UCP to run only signed images. See Sign an image for detailed steps. |
With curl, you can interact with the DTR API by passing a public
certificate and private key pair instead of your DTR username and
password/authentication token.
curl --cert cert.pem --key key.pem -X GET \
"https://<dtr-external-url>/api/v0/repositories?pageSize=10&count=false" \
-H "accept:application/json"
In the above example, cert.pem contains the public certificate and
key.pem contains the private key. For non-admin users, you can
generate a client bundle from UCP or contact your administrator for your
public and private key pair.
For Mac-specific quirks, see curl on certain macOS versions.
For establishing mutual trust between the Notary client and your trusted
registry (DTR) using the Notary CLI, place your TLS client certificates
in <home_directory>/.docker/tls/<dtr-external-url>/ as
client.cert and client.key. Note that 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.
Self-signed DTR server certificate
Also place
ca.crtin<home_directory>/.docker/tls/<dtr-external-url>/when you’re using a self-signed server certificate for DTR.
Hit your DTR’s basic_info endpoint via curl:
curl --cert cert.pem --key key.pem -X GET "https://<dtr-external-url>/basic_info"
If successfully configured, you should see TLSClientCertificate
listed as the AuthnMethod in the JSON 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 DTR to Docker Engine’s list of insecure registries as a workaround. This has the side effect of disabling the use of TLS certificates.
Error response from daemon: Get https://35.165.223.150/v2/: x509: certificate is valid for 172.17.0.1, not 35.165.223.150
--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 DTR
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://<dtr-external-url>/api/v0/repositories?pageSize=10&count=false" \
-H "accept:application/json"