Authenticating a Workload with Federated Identity

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.

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

Note: Federated identity provider authentication must first be configured by a system administrator. For the setup and configuration steps, see Federated Identity Provider for Workload Authentication.

Prerequisites

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.

Authenticating a Workload

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.

Troubleshooting

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.

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.