Federated Robot Accounts
Federated robot accounts allow 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, you connect a trusted federated identity provider; your workloads present a JWT issued by that provider, and Container Registry validates the token against the provider’s published JWKS endpoint and grants access accordingly.
Federated robot accounts are 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:
- 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).
- The workload presents the JWT to Container Registry as its credential.
- Container Registry fetches the provider’s JWKS (JSON Web Key Set) to validate the token’s signature and claims.
- If validation succeeds, Container Registry maps the token’s claims to a federated robot account and grants the associated permissions.
Because tokens are short-lived, there are no long-lived secrets to leak or rotate manually.
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:
- 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.
- 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.
- 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.
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 federated robot account (for example, a
suborrepositoryclaim). - The identity provider’s JWKS endpoint is reachable over HTTPS from the Container Registry host.
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 (required) | The issuer URL. It must equal the iss claim of incoming JWTs. It cannot be changed after creation. |
| Audience (required) | The value the aud claim of incoming JWTs must carry. It cannot be changed once set. |
| Claim Mapping | Claim rules that resolve which federated robot account a token authenticates as. iss and aud are fields of the provider, not claim rules: a claim rule on either is rejected with 400. |
Both Issuer and Audience are required. A federated identity provider is identified by the combination of its issuer and audience, which must be unique across system and project level. Several providers may share an issuer URL if their audiences differ.
Connect a Federated Identity Provider
- In the left navigation pane, select Administration.
- Click Federated Robot Accounts, then New Identity Provider or select an existing one to edit.
- Fill in the federated identity provider fields as described in the Configuration section above.
- Click Save.
Authenticating a Workload
For the end-user workflow of authenticating a workload as a federated robot account — the Docker CLI and pipeline login steps — see Authenticating a Workload with a Federated Robot Account.
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.
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.