We set up a secure docker registry. Now we want to add authentication to this registry to prevent any unauthorized user from pushing any image to our registry. This will not be a role-based authentication we will set up Basic Authentication.
👉 Let’s create a directory named auth using the mkdir command. Here's how you can do it:
localhost:~$ mkdir auth
This command will create a directory named auth in the current location. You can navigate to this directory using cd auth if needed.
👉 Install htpasswd if it's not already available.
- For Debian-based systems (like Ubuntu):
sudo apt-get update
sudo apt-get install apache2-utils
- For Red Hat-based systems (like CentOS):
sudo yum install httpd-tools
- For macOS (using Homebrew):
brew install httpd
👉 After installing htpasswd, you can proceed with creating the password file as mentioned earlier:
localhost:~$ htpasswd -bnB megha password > auth/htpasswd
The command you provided will create a password file named htpasswd in the auth directory and store the username "megha" along with the hashed password in that file. Here's a breakdown of the command:
htpasswd: The command to create or update an Apache-style password file.-bnB: Flags for htpasswd.-bspecifies that the password should be given on the command line (not interactively), and-nprevents updating the password file (useful for creating a new file).megha: The username you want to add to the password file.
password: The password you want to associate with the username "megha".>: Redirects the output of the command to a file.auth/htpasswd: The path and filename where the password file should be saved (in this case, it's saved in theauthdirectory with the namehtpasswd).
👉 To view the contents of the htpasswd file, you can use the following command:
localhost:~$ cat auth/htpasswd
localhost:~$ ZDnhKI5nQvqNCFA94hY5e.rnIMD4KpTDkwMkA9jPVMe0g8wH06U7G
👉 To run a Docker registry container with basic authentication using the htpasswd file you created, you can use a command :
localhost:~$ docker container run -d -p 5000:5000 --restart=always --name registry_basic \
-v /path/to/htpasswdfile:/auth/htpasswd \
-v "$(pwd)"/certs:/certs \
-e "REGISTRY_AUTH=htpasswd" \
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
-e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
registry:2
Here’s a breakdown of the command:
docker container run: Starts a new Docker container.-d: Runs the container in detached mode (background).-p 5000:5000: Maps port 5000 on the host to port 5000 inside the container for accessing the registry.--restart=always: Restarts the container automatically if it stops or crashes.--name registry_basic: Names the container as "registry_basic".-v /path/to/htpasswdfile:/auth/htpasswd: Mounts thehtpasswdfile into the container at/auth/htpasswd.-v "$(pwd)"/certs:/certs: Mounts the TLS/SSL certificates (domain.crtanddomain.key) from the local directorycertsinto the container at/certs.-e "REGISTRY_AUTH=htpasswd": Sets the authentication method to htpasswd.-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm": Defines the authentication realm (displayed when users are prompted for credentials).-e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd": Specifies the path to thehtpasswdfile inside the container.-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt: Specifies the path to the TLS certificate inside the container.-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key: Specifies the path to the TLS private key inside the container.registry:2: Specifies the Docker registry image (version 2) to use.
👉To list the running Docker containers and see the container named “registry_basic” that you just started.
localhost:~$ docker container ls
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
00c5f5104add registry "/entrypoint.sh /etc…" 7 seconds ago Up 2 seconds 0.0.0.0:5000->5000/tcp registry_basic
👉 Now we try to push an image to this container registry .
If you try to push an image to a Docker registry that requires basic authentication without providing the required username and password, you will indeed receive an error indicating that authentication is required.
localhost:~$ docker image push repo.docker.local:5000/redis
Using default tag: latest
The push refers to repository [repo.docker.local:5000/redis]
262de04acb7e: Preparing
45f6df634253: Preparing
e46136075591: Preparing
11f991845040: Preparing
dd1ebb1f5319: Preparing
814bff734324: Preparing
no basic auth credentials
The error message “no basic auth credentials” indicates that Docker is trying to push an image to the repository at repo.docker.local:5000/redis but it's not providing the necessary basic authentication credentials.
To resolve this issue, you need to log in to the Docker registry with your username and password before pushing the image.
.
👉 Log in to the Docker registry using the docker login command. Replace repo.docker.local:5000 with the actual URL of your Docker registry:
localhost:~$ docker login repo.docker.local:5000
Username: megha
Password:
WARNING! Your password will be stored unencrypted in /home/megha/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded
localhost:~$
👉 After successful login, retry pushing the image to the registry:
localhost:~$ docker push repo.docker.local:5000/redis
Using default tag: latest
The push refers to repository [repo.docker.local:5000/redis]
262de04acb7e: Pushed
45f6df634253: Pushed
e46136075591: Pushed
11f991845040: Pushed
dd1ebb1f5319: Pushed
814bff734324: Pushed
latest: digest: sha256:1bd57e1a42b99ae53412b582784d0362fa8205243ce5f289cb4f76de2907cb97 size: 1574
localhost:~$
Once you’ve logged in and provided the correct credentials, Docker should be able to authenticate with the registry and push the image successfully.
👉 To log out from a Docker registry, you can use the docker logout command.
localhost:~$ docker logout repo.docker.local:5000
Removing login credentials for repo.docker.local:5000
localhost:~$