Docker registry authentication

Publish Date: March 27, 2023

Docker Registry Authentication

Recently, I wrote an article on Private Docker registry setup, where we configured a Docker registry for private use. By default, this private Docker registry doesn’t require any authentication so it literally allows everyone to pull or push Docker images. This is not a very much secure setup till now. In this post, you will learn how to secure a private Docker registry.

Setup Authentication

If you remember from my previous post, we used nginx web server as a reveres proxy with out private Docker registry. We will now integrate a basic authentication, which will require a username and password before anyone can push/pull a Docker image to/from our private registry. To do this, we will use htpasswd, which is a part of apache2-utils package. Install the package using these commands:

sudo apt update
sudo apt install apache2-utils -y

Installing apache2-utils package

This command will install apache2-utils package. Now create a directory docker_auth with this command:

sudo mkdir docker_auth
sudo htpasswd -Bc docker_auth/registry.password surender

Adding an authenticated user with htpasswd command

This command adds a new user with htpasswd command. The -B option forces htpasswd to use a secure bcrypt encryption and -c is used to create a new file. To add more users to this file, just run the same command without -c option as shown below:

sudo htpasswd -B docker_auth/registry.password mark

Restart Docker Registry

We make sure you stop and remove your old registry container  with the help of sudo docker stop registry && sudo docker rm registry command and launch a new private docker registry with the following command:

sudo docker run --detach \
--restart=always \
--name registry \
--publish 5000:5000 \
--mount type=volume,source=docker_repo,target=/docker_repo \
--mount type=bind,source=$(pwd)/docker_auth,target=/docker_auth \
--env REGISTRY_AUTH=htpasswd \
--env REGISTRY_AUTH_HTPASSWD_PATH=/docker_auth/registry.password \

Running private docker registry with authentication parameters

This command launches a new registry container with authentication parameters passed as environment variables.

Using Authentication

Once your new registry container is up and running, you can use the docker login command for Docker authentication as shown below:

docker login https://registry.testlab.local

Error response from daemon: login attempt to http://registry.testlab.local/v2/ failed with status: 401 Unauthorized

As you can see in the screenshot, if we enter a wrong password, we get the following error:

Error response from daemon: login attempt to http://registry.testlab.local/v2/ failed with status: 401 Unauthorized

When a right password is entered, you will see a Login Succeeded message. After successful login, you will be able to use docker pull or docker push commands normally. That’s it. Your private Docker registry now requires authentication so only the authorized people can pull or push Docker images.

Please note that the method of docker login is not very secure and stores your credentials in .docker/config.json file. You can use a credential helper to learn more about this in detail.

Microsoft Certified | Cisco Certified

Leave a Reply