A new Docker installation uses public interactions with Docker Hub by default. Logging in allows you to access your private content and benefit from less restrictive Docker API speed limits.
In this guide, we’ll show how to log into the Docker CLI, covering both Docker Hub authentication and your own private records. We’ll also look at some of the common issues with storing Docker credentials.
Logging
into Docker Hub
Logging into Docker Hub allows the Docker CLI to access private content accessible to your account. It will also give you the higher rate limit threshold of 200 image extracts per six hours, instead of the 100 extracts per six hours offered to unauthenticated clients.
Use the docker login command
to provide your credentials and authenticate with the server: $ docker login
Username: Password:
You will be asked to enter your username and password interactively. Docker will attempt to log in to Docker Hub with the credentials. You’ll see Successful sign-in if the details are accepted. Docker will store the issued authentication token in the .docker/config.json file.
$ docker login Login Successful access tokens
for 2FA logins
Docker Hub accounts with two-factor authentication enabled must use an access token instead of a password. Using the Docker Hub web UI, click your profile icon at the top right and choose “Account Settings” from the menu. Use the left sidebar to switch to the “Security” tab.
<img src="https://www.howtogeek.com/wp-content/uploads/csit/2022/03/4a788ba4.png" alt="Docker
Hub access token creation image” />
Click the blue “New Access Token” button to create a personal access token. Be careful to write down the token key that is displayed, as you will not be able to retrieve it in the future. Use this token instead of your normal password when you run docker login again in the CLI.
Non-interactive logins
You can provide your user name and password as command-line prompts:
$ docker login -username demo -password
example This is useful when you log in programmatically or as part of a CI pipeline. To increase security, use the -password-stdin flag to instruct Docker to read the STDIN password. This allows you to pipe a password file, preventing plain text from being captured in shell history and CI job logs.
$ cat password.txt | docker login -username demo -password-stdin
Logging
into private records
docker login also allows you to log in to self-hosted records. Provide the registry host name and port as the first argument to the command. Docker Hub is always used when no argument is given.
$ docker login registry.example.com Username: Password:
You can still use the -username, -password, and -password-stdin flags when working with custom records. You can log in to multiple records simultaneously: repeat the docker login command as many times as you need.
Add credentials
manually
Sometimes, you might want to manually log in to a registry by adding an existing authentication token to the Docker configuration file. This can be useful in CI environments where you want to provide a previously obtained token as a pipeline variable.
You can add authentication tokens yourself by editing their .docker/config.json file. Add a new key for your record inside the auths field at the top of the file. Provide an object as the key value; This object needs a single Auth property that contains the token. Here’s an example for the registry.example.com registry:
You can add a Docker Hub token using https://index.docker.io/v1/ as the registry URL
.
Multiple accounts for one record A
significant limitation of the authentication mechanism is its requirement that records be mapped one-to-one with user accounts. It is not possible to log on simultaneously with multiple users in the same registry. This is usually desirable when using a private record that separates permissions on projects or teams.
You can mitigate the problem by splitting your credentials into multiple configuration files. The Docker CLI uses the -config flag or DOCKER_CONFIG environment variable to determine which file to upload for each invocation.
# Authenticate as user-1$ docker -config ~/docker/user-1.conf login registry.example.com -username user-1 -password foobar # Authenticate as user-2$ docker -config ~/docker/user-2.conf login registry.example.com -username user-2 -password foobar # Extract an image from registry.example.com as user-1$ docker -config ~/docker/user-1.conf pull my-team/my-project:latest # Push an image to registry.example.com as user-2$ docker -config ~/docker/user-2.conf push my-team/my-project:latest When you
have many projects to work with, you can use an alias or shell function to rewrite Docker in a command that automatically selects the correct configuration file for your working directory. alias
docker=”docker -config ~/docker/$(basename $PWD).conf $1″
Credential Helpers
Docker stores your credentials insecurely in ~/.docker/config.json by default. You can add more protection by integrating a credential helper utility. Enabled helpers can handle credential storage, get and delete commands issued by Docker in response to CLI operations.
You can associate a record with a particular helper utility by using the credHelpers field
in the configuration file:
This example uses the pass credential helper to store the registry.example.com credentials in Pass instead of the configuration file. The Pass helper is provided as part of Docker’s docker-credential-helpers package that also includes integrations with macOS Keychain, Windows Credential Manager, and D-Bus Secret Service.
Sign
out You can log out
You can log out by manually deleting the registry section of the .docker/config.json file or by using the docker logout command.
$ docker
logout Like docker login, logouts are directed to Docker Hub by default. You can log out of a private record by passing its hostname as the only argument to the command:
$ docker logout registry.example.com
Common Issues
Most Docker authentication issues stem from missing or invalid credentials. If you have logged in before but authentication does not work, try logging out and logging back in:
$ docker logout # OR $ docker logout registry.example.com $ docker login # OR $ docker login registry.example.com
Systematically declined credentials could indicate a problem with your registration account. For Docker Hub, verify that you’ve followed the instructions above to use a personal access token instead of a password with accounts protected by 2FA.
Confusion can also occur when you have multiple Docker configuration files. Check that you are using the -config flag or DOCKER_CONFIG environment variable to load the correct one every time you push and extract your images.
Summary
Getting the Docker
CLI connected to your Docker Hub account or a private registry is usually best handled using the docker login command. You can provide credentials interactively, as flags, or through a pipelined password file. Be sure to use a personal access token instead of your password if you have two-factor authentication enabled.
Although there is perfect support for authenticating to multiple records, working with multiple accounts in one registry is more cumbersome. Try to use separate configuration files whenever possible, or configure the registry with specially defined user accounts appropriate for each of your environments.