A fresh Docker installation defaults to public interactions with Docker Hub. Logging in lets you access your private content and benefit from less restrictive Docker API rate limits.
In this guide, we’ll show how to login to the Docker CLI, covering both Docker Hub authentication and your own private registries. We’ll also look at some of the common issues with Docker’s credential storage.
Logging Into Docker Hub
Logging into Docker Hub lets the Docker CLI access private content that’s accessible to your account. It’ll also give you the higher rate limit threshold of 200 image pulls per six hours, instead of the 100 pulls per six hours offered to unauthenticated clients.
Use the docker login command to supply your credentials and authenticate with the server:
$ docker login Username: Password:
You’ll be prompted to enter your username and password interactively. Docker will try to login to Docker Hub using the credentials. You’ll see Login Succeeded if the details are accepted. Docker will store the issued authentication token in your .docker/config.json file.
$ docker login Login Succeeded
Access Tokens for 2FA Logins
Docker Hub accounts with two-factor authentication enabled need to use an access token instead of a password. Using Docker Hub’s web UI, click your profile icon in the top-right and choose “Account Settings” from the menu. Use the left sidebar to switch to the “Security” tab.
Click the blue “New Access Token” button to create a Personal Access Token. Take care to note down the token key that’s displayed as you won’t be able to recover it in the future. Use this token instead of your regular password when you run docker login back in the CLI.
Non-Interactive Logins
You can supply your username and password as command-line flags:
$ docker login --username demo --password example
This is useful when you’re logging in programmatically or as part of a CI pipeline. To increase security, use the --password-stdin flag to instruct Docker to read your password from STDIN. This lets you pipe in a password file, preventing plain text from being captured in your shell history and CI job logs.
$ cat password.txt | docker login --username demo --password-stdin
Logging Into Private Registries
docker login also lets you login to self-hosted registries. Supply your registry’s hostname and port as the command’s first argument. 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 registries. You can be logged into multiple registries simultaneously – repeat the docker login command as many times as you need.
Manually Adding Credentials
Sometimes you might want to manually login to a registry by adding an existing authentication token to Docker’s config file. This can be useful in CI environments where you’d like to provide a pre-obtained token as a pipeline variable.
You can add auth tokens yourself by editing your .docker/config.json file. Add a new key for your registry within the auths field at the top of the file. Provide an object as the key’s value; this object needs a single auth property that contains your token. Here’s an example for the registry.example.com registry:
{
"auths": {
"registry.example.com": {
"auth": "aWxtaW9ud..."
}
}
}
You can add a Docker Hub token by using https://index.docker.io/v1/ as the registry URL.
Multiple Accounts For One Registry
A significant limitation of the authentication mechanism is its requirement that registries map one-to-one with user accounts. It’s not natively possible to be simultaneously logged in to multiple users at the same registry. This is often desirable when you’re using a private registry that separates permission across into projects or teams.
You can mitigate the issue by splitting your credentials into several config files. The Docker CLI uses the --config flag or DOCKER_CONFIG environment variable to determine the file to load 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 # Pull 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’ve got many projects to work with, you could use a shell alias or function to rewrite docker to a command that automatically selects the right config 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 get to handle credential store, get, and erase commands issued by Docker in response to CLI operations.
You can associate a registry with a particular helper utility using the credHelpers field in your config file:
{
"credHelpers": {
"registry.example.com": "pass"
}
}
This example uses the pass credential helper to store credentials for registry.example.com into Pass instead of the config file. The Pass helper is provided as part of Docker’s docker-credential-helpers bundle that also includes integrations with macOS’ keychain, Windows’ Credentials Manager, and the D-Bus secret service.
Logging Out
You can log out by either manually deleting the registry’s section from your .docker/config.json file or using the docker logout command.
$ docker logout
Like docker login, logouts target Docker Hub by default. You can logout of a private registry by passing its hostname as the command’s only argument:
$ docker logout registry.example.com
Common Problems
Most Docker authentication issues stem from missing or invalid credentials. If you’ve previously logged in but authentication isn’t working, try logging out and back in again:
$ docker logout # OR $ docker logout registry.example.com $ docker login # OR $ docker login registry.example.com
Consistently rejected credentials could indicate a problem with your registry account. In the case of Docker Hub, check you’ve followed the guidance above to use a Personal Access Token instead of a password with 2FA-protected accounts.
Confusion can also occur when you’ve got multiple Docker config files. Check you’re using the --config flag or DOCKER_CONFIG environment variable to load the correct one each time you push and pull your images.
Summary
Getting the Docker CLI connected to your Docker Hub account or a private registry is usually best handled by the docker login command. You can supply credentials interactively, as flags, or via a piped-in password file. Make sure you use a Personal Access Token instead of your password if you have two-factor authentication enabled.
Although there’s seamless support for authenticating to multiple registries, working with several accounts from one registry is more cumbersome. Try to use separate config files where possible or configure your registry with specially scoped user accounts appropriate for each of your environments.
