Docker Hub two-factor authentication changes the CLI credential contract

Enabling two-factor authentication on an account also changes how its unattended tools authenticate. Docker Hub's October 21 release notes introduce a two-factor authentication beta and require personal access tokens for Docker CLI login once the setting is enabled. An account password that previously worked in a script is therefore no longer the supported CLI credential for that account.

The earlier personal access token announcement supplies the complementary mechanism. A token can replace the password at the CLI prompt, and an account can manage several tokens independently. The September addition now provides the noninteractive authentication path needed alongside October's account-security setting.

I care about this distinction because Docker's useful artifact is an image that can move between machines. The registry credentials used by those machines should have their own management boundary. A human account's second factor and a build worker's token solve different parts of that requirement.

The change is visible at login

The release notes place the beta setting under Security in account settings. They also give a direct CLI consequence, a personal access token must replace the password. That is a behavior change for tools already using the account, not just an additional screen during browser sign-in.

An unattended job cannot be assumed to answer a human's second-factor prompt. Hub's documented response is to give the CLI a different secret type through the existing login flow. The resulting separation lets the account require a second factor for its human interaction while preserving a credential suitable for automated registry operations.

That does not make a token a second factor supplied on every pull or push. The token is the credential accepted by the CLI login path. The distinction prevents an inaccurate security description in which enabling two-factor authentication somehow makes every stored automation secret require the owner's active participation.

The interactive command remains familiar, with the token entered when prompted for the password.

docker login --username YOUR_DOCKER_ID

The username still identifies the account. Hub changes which credential it accepts for that account's CLI authentication after two-factor authentication is enabled. A successful browser login therefore does not establish that a script retaining the old password has the credential it now needs.

Token creation and token consumption are separate operations

The launch announcement explains that each token value is shown only when created. An account owner must retain it in an appropriate credential store or supply it to its intended consumer then. Losing the value requires deleting that token and creating another. The management interface can identify a token without redisplaying its secret.

That lifecycle fits a dedicated integration. The account owner creates a token for the consumer, the consumer uses it for login, and the account owner can revoke it later. Creating a different token for another consumer allows the first one to be removed without replacing both credentials.

The practical benefit depends on preserving that association. If every build worker receives the same token, a revocation still affects all those workers. Multiple-token support supplies the ability to separate their lifecycles, but it cannot infer which consumer an operator intended to isolate.

The 19.03.1 CLI documentation documents --password-stdin for noninteractive secret input. This keeps a supplied credential out of the command's argument text. A token used instead of a password can follow that same input path, with the integration's secret-delivery mechanism providing standard input.

Input handling does not settle storage. After login, Docker's credential configuration determines where the client retains the secret. The same guide documents external helpers and a configuration-file fallback. An account-security change at Hub cannot by itself change the helper installed on a build worker.

Account recovery remains part of the authentication design

The October release notes warn that losing both the authentication device and the recovery code may make account recovery impossible. That warning identifies two distinct recovery resources whose simultaneous loss matters. A setup process that confirms the second factor but leaves no accessible recovery code has not accounted for the failure described in the notes.

Recovery is not the same operation as issuing a replacement integration token. A token can be deleted and recreated through account management when that management access is available. The recovery warning concerns losing the means to regain the account itself. These operations involve different authority, even though both are presented near the Security settings.

It is useful to keep their inventories separate. The token list describes credentials issued to integrations. The recovery material describes a route back to human account access when the regular authentication device is unavailable. Counting tokens does not establish that recovery material has been retained, and retaining a recovery code does not identify which integration uses a particular token.

My preference is to keep this account material outside the image artifact. The build or deployment system needs authority to access the registry, while the application image needs its runtime contents. Combining those lifecycles would make distributing the application also distribute an authentication dependency that belongs to its surrounding tools.

The local credential store still matters

The contemporary CLI guide describes external helper programs selected through credsStore or registry-specific credHelpers. Those programs store and retrieve credentials for the client. If no suitable helper is present, the documented fallback retains credentials in base64 form in the configuration file. The remote account setting does not alter that local fallback.

The guide also distinguishes deleting local credentials with logout from the token management operations at Hub. A local cleanup removes what that client retains. Revocation changes whether the remote service will accept the credential wherever copies exist. That difference becomes more useful once separate integrations have separately revocable tokens.

For the beta introduced today, the supported arrangement is explicit. Enable the account's second factor, retain its recovery material, and use personal access tokens through the CLI's existing login mechanism. Each integration can have an independent credential lifecycle, while local helper configuration continues to determine how its client stores that credential.