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).
When prompted, give the new token a name (Figure B).
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).
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:
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.
Subscribe to the Developer Insider Newsletter
From the hottest programming languages to commentary on the Linux OS, get the developer and open source news and tips you need to know. Delivered Tuesdays and Thursdays