--- title: "Federated Identity Provider for Workload Authentication" date: 2026-05-21 lastmod: 2026-06-08 canonical: "https://container-registry.com/docs/administration-manual/federated-identity-provider-for-workload-authentication/" source: "https://container-registry.com/docs/administration-manual/federated-identity-provider-for-workload-authentication/index.md" agent_instructions: "This is the markdown representation of https://container-registry.com/docs/administration-manual/federated-identity-provider-for-workload-authentication/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt." --- > Agent-friendly representation of . Site index: . # 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. | Field | Description | |---|---| | **Name** | A label to identify this federated identity provider configuration. | | **Discovery URL** | A valid OpenID Configuration URL. The standard is `/.well-known/openid-configuration`. Returns a JSON metadata document detailing endpoints (authorization, token), public keys, and supported algorithms. | | **Manual mode** | You can enable manual mode to skip remote validation and use provided JWKS instead. | | **JWKS URI** | The URL of the identity provider's JSON Web Key Set endpoint. Container Registry fetches public keys from this endpoint to verify incoming JWTs. | | **Issuer (`iss`)** | The expected issuer claim value in incoming JWTs. Tokens with a non-matching issuer are rejected. | | **Audience (`aud`)** | The expected audience claim value. Tokens not addressed to this audience are rejected. | | **Claim Mapping** | The JWT claim used to resolve which robot account the token authenticates as. | ### 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](#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:** ```bash docker login \ --username \ --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](/docs/administration-manual/system-robot-accounts/index.md) for system robots or this [article](/docs/user-manual/projects/configuration/robot-accounts/index.md) 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.