OCI registry tokens combine audience, scope, and the identity behind them
A container registry client often receives a bearer token from an authentication service after a challenge from the registry. The challenge names a service, such as a registry host, and a scope, such as a repository and a set of actions. The client exchanges its credentials for a token and presents that token to the registry.
The token format can make the authorization look like a single string. In practice, the registry checks the token's audience, issuer, signature, expiry, and access claims. The authentication service decides which access claims to issue based on the authenticated user or workload. A token with the right repository name but the wrong audience is not interchangeable with a token for another service.
Read the challenge as policy
The WWW-Authenticate response identifies the token realm and service and may include a scope. The client should request only the action it needs. A pull operation does not need push access, and a builder that publishes one image does not need access to every repository in the registry. The token service should issue access claims that are narrower than the client's request when the user has less authority.
Do not trust a scope string supplied by a client as proof that the granted token matches it. The registry must validate the token's access claims for the repository and action being requested. The authentication service must authenticate the requester before issuing access. A public read token service and a write-capable token service may share software, but they should not share the same authorization policy.
Record the service audience in client and server configuration. If multiple registries use the same token issuer, a token for one service should not be accepted by another. Use distinct signing keys or audience validation to keep the trust domains separate. Rotate the issuer keys through a process that both the registry and token service understand, and reject tokens signed by retired keys.
Treat pull-through caches as identities
A pull-through cache or registry mirror may fetch upstream content with its own credentials. That credential is a service identity, not a user token. Scope it to the upstream repositories and actions the mirror needs. Store it in the mirror's secret management path and keep it out of image builds and client configuration.
A mirror that can pull any public image can also become an origin for content a policy did not intend to allow. Apply allowlists for upstream registries and repositories, validate TLS, and record the upstream digest. If the mirror caches by tag, a mutable upstream tag can change the content returned to clients. Resolve to a digest and store the digest with the cached artifact.
Separate anonymous pull, authenticated pull, and push credentials. A build worker that only reads base images should not receive the push token. A deployment cluster should pull from the approved mirror with a workload identity or a short-lived credential, not a static personal token. The registry's authorization logs should let an operator identify the client identity behind a failed or unusual request.
Verify the artifact behind the token
A valid token allows an action on a repository. It does not establish that the image content is approved. Pin a manifest digest, verify its signature or provenance, and inspect the resulting configuration and layers. The registry can enforce immutable tags or retention, but signature policy and vulnerability policy belong to the deployment pipeline.
Use digest references in Kubernetes and deployment manifests where feasible. A tag can move while a digest identifies exact content. If an image index is used for multiple architectures, verify the index and the selected platform manifest against the expected policy. Do not confuse a successful pull with a clean vulnerability scan.
Test scope boundaries with separate credentials. Confirm that a pull token cannot push, that a token for one repository cannot read another, and that a token issued for one registry audience is rejected by a different registry. Test revocation by using the token after its identity has been disabled. Test an expired token and a token with an altered claim in a disposable lab.
Registry token systems are security boundaries made of short strings and configuration. The client needs to request the smallest scope, the issuer needs to authenticate the right identity, the registry needs to validate the audience and claims, and the deployment needs to verify the artifact. Each layer has a distinct job, and the chain is only as strong as the least specific one.
Top comments (0)