Federated Identity Provider for Workload Authentication

Federated identity provider authentication allows CI/CD pipelines and Kubernetes workloads to authenticate to Container Registry using short-lived JWTs instead of long-lived static robot account secrets. Rather than distributing and rotating static credentials, your workloads present a JWT issued by a trusted external identity provider; Container Registry validates the token against that provider’s published JWKS endpoint and grants access accordingly.

This authentication mechanism is intended for machine-to-machine use cases — automated pipelines, workload identity, and service accounts — not for interactive human login.

How It Works

When a workload authenticates:

1. The workload obtains a short-lived JWT from its identity provider (for example, a Kubernetes service account token, a GitHub Actions OIDC token, or a similar workload identity token).
2. The workload presents the JWT to Container Registry as its credential.
3. Container Registry fetches the provider’s JWKS (JSON Web Key Set) to validate the token’s signature and claims.
4. If validation succeeds, Container Registry maps the token’s claims to a robot account and grants the associated permissions.

Because tokens are short-lived, there are no long-lived secrets to leak or rotate manually.

Prerequisites

Before configuring a federated identity provider in Container Registry, ensure the following are in place:

• You have system administrator access to the Container Registry instance.
• You have an external identity provider that issues JWTs and exposes a JWKS endpoint accessible from the Container Registry instance.
• You have identified the claim in the JWT that will be used to map the token to a robot account (for example, a sub or repository claim).
• The identity provider’s JWKS endpoint is reachable over HTTPS from the Container Registry host.

JWKS Key Caching and Rotation

Container Registry caches the JWKS fetched from the provider endpoint to avoid latency on every authentication request. When your identity provider rotates its signing keys:

1. Publish the new key in the JWKS endpoint alongside the existing key (dual-key publication). Container Registry will continue to validate tokens signed with the old key while the cache is refreshed.
2. Allow sufficient time for the cache to expire and Container Registry to fetch the updated JWKS. During this window both old and new keys are accepted.
3. Once the cache has refreshed and all in-flight tokens signed by the old key have expired, you may remove the old key from the JWKS endpoint.

Rotating keys without a dual-key publication period will cause authentication failures for tokens signed by the new key until the cache refreshes.

Configuration

Federated identity provider settings are managed via the Container Registry API or, where available, the administration UI.

Enable Federated Identity Provider Authentication

1. In the left navigation pane, select Administration.
2. Click Identity Provider, then New Identity Provider or select an existing one to edit.
3. Fill in the federated identity provider fields as described in the Configuration section above.
4. Click Save.

Authenticating a Workload (End-User Tutorial)

Once federated identity is configured, workloads authenticate using their JWT as a password, with the mapped robot account name as the username.

With Docker CLI:

docker login <registry-hostname> \
  --username <robot-account-name> \
  --password "$(cat /path/to/workload-token)"

With a pipeline (example — adapt to your CI system):

Most CI/CD systems that support workload identity federation expose the JWT via an environment variable or a file. Pass that value as the password in your registry login step. Refer to your CI/CD provider’s documentation for how to obtain the workload JWT within a pipeline job.

The robot account referenced in the login must already exist in Container Registry and must have the permissions required for the pipeline’s operations (push, pull, etc.). If it does not exist yet, create it following the instructions in this article for system robots or this article for project-scoped robots.

Troubleshooting

Token rejected with “invalid signature”

The JWKS cache may not yet contain the key used to sign the token. This typically occurs immediately after a key rotation. Wait for the cache to refresh and retry. If the problem persists, verify that the JWKS URI is reachable from the Container Registry host and that the correct key ID (kid) is present in the published JWKS.

Token rejected with “invalid issuer” or “invalid audience”

The iss or aud claim in the presented JWT does not match the values configured in the federated identity provider settings. Check that the issuer and audience fields in Container Registry match exactly what your identity provider includes in issued tokens.

Token rejected with “token expired”

Short-lived tokens must be obtained immediately before use. Ensure the workload is fetching a fresh token for each authentication attempt rather than caching a token across multiple jobs or requests.

Robot account not found

The claim value used for mapping does not correspond to any robot account in Container Registry. Verify the claim mapping configuration and confirm that a robot account with a matching name exists and has not been disabled or deleted.

JWKS endpoint unreachable

Container Registry logs a fetch error and falls back to the cached key set. If the cache has expired and the endpoint is unreachable, all federated authentication attempts will fail. Ensure network connectivity and TLS trust between Container Registry and the identity provider’s JWKS endpoint.