Registry authentication — basic, token, OIDC

Registries support three authentication schemes:

• Basic auth — username and password, sent over HTTPS.
• Bearer token — a short-lived, scope-limited token issued by an auth service, passed as Authorization: Bearer ....
• OIDC — delegated authentication, where the registry trusts an external identity provider rather than holding a password itself.

In practice they are not alternatives. Basic credentials are usually what you exchange for a bearer token, and OIDC changes what you present at that exchange. Understanding the sequence is what lets you diagnose a 401 correctly.

Basic auth, and where the credential goes

docker login registry.example.com
# Username: deployer
# Password:

The fix is a credential helper

A credential helper is a small external program the Docker CLI calls instead of writing the credential itself. The plaintext never touches config.json.

{
"credsStore": "pass"
}

Per-registry helpers are also supported, which matters when one registry authenticates through a cloud IAM helper and another through a local keyring:

{
"credsStore": "pass",
"credHelpers": {
  "registry.example.com": "secretservice"
}
}

On Linux the two common helpers are docker-credential-pass, which stores secrets in a GPG-backed pass store, and docker-credential-secretservice, which uses the D-Bus Secret Service (GNOME Keyring and equivalents). Both are separate binaries you install onto PATH; neither ships with the Docker CLI.

jq '.auths | map_values(has("auth"))' ~/.docker/config.json

{
"registry.example.com": false
}

That is a verification that can fail, which is the point. “I configured a credential helper” is a claim; an empty auth field is evidence.

Never pass a password on the command line

docker login -u deployer -p "$DEPLOYER_PASSWORD" registry.example.com

This is the pattern every CI example uses and it is wrong in two ways: the value appears in the process list for as long as the command runs, and in the shell history of anyone who runs it interactively. Docker warns about it at runtime.

$ docker login -u deployer -p REDACTED registry.example.com

WARNING! Using --password via the CLI is insecure. Use --password-stdin.

Use standard input instead. The documentation’s justification is exact: “Using STDIN prevents the password from ending up in the shell’s history, or log-files.”

printf '%s' "$DEPLOYER_TOKEN" \
| docker login registry.example.com --username deployer --password-stdin

Login Succeeded

Bearer tokens

Bearer tokens are the mechanism doing most of the work, and they are invisible because docker login handles them.

The client presents its basic credential to an auth service, which returns a token scoped to a specific action on a specific repository — repository:library/nginx:pull, for example. That token, not the password, is what accompanies the manifest and blob requests. It is short-lived; the exact lifetime is set by the registry operator, and clients simply request a new one when the old one is refused.

Two operational consequences follow from the scoping:

• A leaked token is bounded. It grants the actions named in its scope, on the repositories named in its scope, until it expires. A leaked password is not bounded at all — it mints new tokens.
• A 401 on a push with a working pull is normal. The token was issued with pull scope because that is what the client asked for. The fix is a credential with push permission, not a network investigation.

OIDC and workload identity

OIDC moves the trust decision out of the registry. The registry stops holding a password and instead validates a token issued by an identity provider it trusts.

This is worth doing for three reasons that have nothing to do with cryptography:

• Single sign-on for humans, so a departure revokes registry access as a side effect of revoking the account.
• Workload identity for machines — a CI job or a Kubernetes service account presents an ephemeral, automatically rotated token rather than a long-lived password somebody pasted into a secret store years ago.
• Auditing. The IdP logs the authentication with the real identity attached, rather than the registry logging twelve pipelines all presenting svc-ci.

The third one is usually the argument that lands, because “who pushed this image” is a question every incident eventually asks.

Service accounts, not people

For anything automated, the credential must belong to a robot:

• Scoped. Read-only for deploy hosts; push only for the CI job that publishes. A deploy host that can push is a deploy host that can poison the registry after one compromise.
• Per-consumer. One credential per pipeline, not one shared across the estate. Shared credentials cannot be rotated without a synchronised outage and cannot be attributed in an audit log.
• Named for its purpose. svc-ci-publish tells the next operator what breaks if they disable it. deployer2 does not.

Personal credentials in automation fail in a specific and predictable way: someone leaves, the account is disabled on their last day, and a pipeline nobody associated with that person stops working at the next run.

Rotation without an outage

1. Issue the new credential alongside the old one. Both valid.
2. Verify the new one works against the registry directly, before distributing it: a docker login plus a pull of a known digest from a scratch host.
3. Distribute it to every consumer — secret manager, CI variables, host config, Kubernetes pull secrets, the pull-through cache.
4. Prove no consumer is still using the old one. This is the step people skip, and it is the only one that makes the next step safe.
5. Disable the old credential — do not delete it yet.
6. Wait one full cycle of your slowest consumer (a nightly job, a weekly DR test) before deleting.

Step 4 needs evidence, and where you get it depends on the registry. Harbor, Quay, GitLab and the cloud registries all record the authenticating identity in an access log; a Distribution registry behind a reverse proxy records it in the proxy’s access log. Filter for the old identity and confirm the last entry predates your distribution step.

LOGFILE=/var/log/nginx/registry-access.log
OLD_USER=deployer

grep -F "$OLD_USER" "$LOGFILE" | tail -5 || echo 'no recent use'

no recent use

Knowledge check