Docker Login Error: x509: certificate signed by unknown authority

We recently set up a custom Docker Registry, using the VMware Harbor solution. The NGINX endpoint was secured using a TLS certificate from DigiCert. When we ran the docker login command, to authenticate to this registry, we were receiving a very common error message:

x509: certificate signed by unknown authority

The crux of the issue appears to be that the Docker Engine isn’t checking the trusted root certificate authorities on the local system. Instead, it requires you to specify the root CA to trust.

On a Windows 10 computer, we inspected the TLS certificate in Google Chrome, to determine which root certificate authority (CA) our TLS certificate chained up to.

Our particular TLS certificate was signed by the DigiCert High Assurance EV Root CA. This root CA certificate is valid until November 9th, 2031, and has the thumbprint: ‎5f b7 ee 06 33 e2 59 db ad 0c 4c 9a e6 d3 8f 1a 61 c7 dc 25. We were attempting to login to the private Docker Registry from an Ubuntu 14.04 LTS Docker Host. On this Linux distribution, the trusted root CA certificates are located in the /etc/ssl/certs directory. To fix the problem, we needed to explicitly instruct the Docker Engine to trust the appropriate root CA certificate.

DigitCert TLS Certificate Chain

The Docker CLI recognizes a special environment variable called REGISTRY_HTTP_TLS_CERTIFICATE. This environment variable should have a value of the filesystem path to the trusted root CA certificate. In our scenario, given the particular root CA certificate that our certificate was issued from, we ran the following command:

export REGISTRY_HTTP_TLS_CERTIFICATE=/etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem

After configuring this environment variable, we were able to successfully run docker login against our TLS-secured VMware Harbor Docker Registry.

There are many different threads referencing this problem on the Docker GitHub project and various software development blogs.