Image: Docker

On several occasions, I’ve run into instances where, when attempting to pull down images from Docker Hub, I was greeted with an authentication error. This issue came into being when Docker Hub changed its requirements for login, which was a necessary step forward in the constant threat of cybersecurity breaches.

However, that change left many users scratching their heads, unsure how to interact with the service. Fortunately, Docker Hub considered that and made it quite simple for users to authenticate, so they can pull down those images at will.

How do you take care of the authentication process? I’m going to show you.

SEE: The best programming languages to learn–and the worst (TechRepublic Premium)

What you’ll need

To make this work, you’ll need Docker up and running on a machine and a Docker Hub account.

How to create an access token

The first thing you must do is create a Docker access token. For this, log in to your Docker Hub account and click on your profile image in the top-right corner. Click Account Settings from the drop-down and then click Security in the left navigation. In the resulting window, click New Access Token (Figure A).

Figure A

Creating a Personal Access Token on Docker Hub.

When prompted, give the new token a name (Figure B).

Figure B

Giving the new Docker Hub personal access token a name.

Type a new name for the token and click Create.

When the new popup appears, make sure to copy the new access token to your clipboard by clicking Copy And Close (Figure C).

Figure C

Your new Docker Hub access token has been generated.

How to use your personal access token

Usually, you could just pull down an image with the command:

docker pull IMAGE

Where IMAGE is the name of the image you want to pull down. When you get an authentication error (which will prevent the image from downloading), you need to make Docker Hub aware of your username and access token.

Before you do this, you must issue the logout command in the Docker CLI. The reason for this is that Docker might have cached your previous login credentials and will fail to accept the new access token. This has tripped me up before and the only way around it is to first issue the command:

docker logout

Once you’ve successfully logged out, you can then log in with the command:

docker login --username USER

Where USER is your Docker Hub username.

You will then be prompted for your Docker Hub access token. Paste the token into the CLI prompt and you’ll be logged in to your Docker Hub account and should be able to pull down images at will.

Finally, if you’re still having issues, make sure you’re running the latest version of Docker on your system (be it Docker, docker-ce, etc). An out of date version of the Docker engine can cause problems with Docker Hub authentication.

Subscribe to TechRepublic’s How To Make Tech Work on YouTube for all the latest tech advice for business pros from Jack Wallen.