How to login to Docker with a Docker Hub access token

Fix Docker’s incorrect username or password error

To fix Docker’s unauthorized: incorrect username or password error, you must obtain and log in with a Docker Hub access token. Your Docker Hub account password will not work.

To create a Docker Hub access token that will enable you to login to Docker on the command line, follow these steps:

1. Login to your account at hub.docker.com and navigate to Account Settings.
2. Click the Security menu link on the left.
3. Click the New Access Token button.
4. Give the Docker Hub Access Token a name and copy it.
5. Use the token when you login to Docker on the command line.

Why are Docker access tokens required?

Most online SaaS applications, including GitHub and GitLab, have moved away from password-based authentication in favor of access tokens.

Unlike passwords, if a token is compromised, a hacker does not gain total access to the user’s account. Instead, the hacker only obtains access to rights associated with that token.

Furthermore, a compromised access token can be revoked and deleted with no impact to any other tokens, and it does not force a change of the Docker Hub account’s primary password.

What are the benefits of authorizing with Docker access tokens?

The use of Docker access tokens provides organizations a variety of benefits, including the following:

• Enhanced security — various levels of granular security can be applied to a token.
• Revocable rights — as a Docker access token can be deleted at any point in time.
• Minimized password exposure — there is no need to share a DockerHub account’s primary password.
• User-level access controls — users can receive their own unique tokens with specific access rights.
• Automation and scalability — tokens are more easily managed in CI/CD build tools such as Jenkins, Gradle and GitHub Actions.

What are the drawbacks to token-based Docker access?

Docker access tokens indeed provide enhanced security, but they are also an extra, added layer of complexity that has the power to frustrate and push away new users.

Casual users, beginners and learners don’t palpably benefit from token-based access. Moreover, the additional steps do little more than cause confusion.

The option for Docker users to turn token-based access control on and off serves both enterprise users and newcomers to the platform. However, most vendors, including GitHub and BitBucket, make token-based access an all-or-nothing option.

That’s why, if you want to avoid the unauthorized: incorrect username or password error when you attempt to login to Docker on the command line, you must log into Docker Hub and generate a Docker access token for your account.

Docker security is an issue that goes beyond the creation of Docker Hub access tokens.