Shanea Leven

Designing Docker Hub Two-Factor Authentication

Shanea Leven

We recognize the central role that Docker Hub plays in modern application development and are working on many enhancements around security and content. In this blog post we will share how we are implementing two-factor authentication (2FA). 

Using Time-Based One-Time Password (TOTP) Authentication

Two-factor authentication increases the security of your accounts by requiring two different forms of validation. This helps ensure that you are the rightful account owner. For Docker Hub, that means providing something you know (your username and a strong password) and something you have in your possession. Since Docker Hub is used by millions of developers and organizations for storing and sharing content – sometimes company intellectual property – we chose to use one of the more secure models for 2FA: software token (TOTP) authentication. 

TOTP authentication is more secure than SMS-based 2FA, which has many attack vectors and vulnerabilities. TOTP requires a little more upfront setup, but once enabled, it is just as simple (if not simpler) than text message-based verification. It requires the use of an authenticator application, of which there are many available. These can be apps downloaded to your mobile device (e.g. Google Authenticator or Microsoft Authenticator) or it can be a hardware key (e.g. YubiKey). To learn about these solutions: 

Enabling Two-Factor Authentication in Docker Hub

Two-factor authentication is enabled in your Docker Hub Account Settings, under the Security tab. 

The basis of TOTP is that you will need to share a one-time secret between Docker Hub and your authenticator app – either through a unique QR code or 32-character string. After this initial synchronization, your authenticator will run an algorithm to change the passcode at a preset interval (typically under a minute) so it is now a time-sensitive piece of information only you have access to – the second component of 2FA. Subsequent logins into Docker Hub will ask for this passcode in addition to your password.

As the initial synchronization is an important part of the TOTP process, it is also a piece of information that is very sensitive; you do not want someone else gaining access to this initial secret. As a result, we do not share the code after your initial synchronization has been confirmed. If you lose your mobile device or access to your authenticator app, you will not be able to login with 2FA. 

This is why it is critical to save your recovery code. You will need the recovery code that is presented when you enable 2FA the first time. Save it somewhere safe so you can recover your account when needed! 

One additional note: Many Docker users access their Hub account through the CLI. Once you’ve enabled 2FA, you will need to create a personal access token in order to log into your Hub account from the CLI. Traditional username and password combinations will not work once you have enabled 2FA. Personal access tokens can be created from the same Security tab under Account Settings.  

For detailed instructions on enabling and using 2FA during the beta, please refer to the following:

What’s Next for Docker Hub

We’d love for you to try the two-factor authentication beta in Docker Hub today and give us feedback at https://github.com/docker/hub-feedback/issues 

In addition to moving 2FA to general availability in the near future, we are also preparing to add support for further authentication controls:

  • WebAuthn support: This allows you to use a security key or supported browsers with WebAuthn support for 2FA
  • Mandatory enforcement of 2FA for an organization: This allows organization administrators to enforce 2FA for all of their members and provide methods for remediating anyone who is not in compliance

To learn more about Docker Hub: