--- title: "Authenticating a Workload with a Federated Robot Account" description: "Authenticate a CI/CD pipeline or Kubernetes workload to Container Registry as a federated robot account with a short-lived JWT instead of a stored secret." date: 2026-08-13 lastmod: 2026-10-20 canonical: "https://container-registry.com/docs/2.16/user-manual/images/authenticating-a-workload-with-a-federated-robot-account/" source: "https://container-registry.com/docs/2.16/user-manual/images/authenticating-a-workload-with-a-federated-robot-account/index.md" harbor_version: "2.16" agent_instructions: "This is the markdown representation of https://container-registry.com/docs/2.16/user-manual/images/authenticating-a-workload-with-a-federated-robot-account/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: . # Authenticating a Workload with a Federated Robot Account 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, your workloads present a JWT issued by a trusted federated identity provider. Federated robot accounts are intended for machine-to-machine use cases — automated pipelines, workload identity, and service accounts — not for interactive human login. > **Note:** The federated robot accounts feature must first be configured by a system administrator, who connects the federated identity provider. For the setup and configuration steps, see [Federated Robot Accounts](/docs/2.16/administration-manual/authentication-management/system-robot-accounts/federated-robot-accounts/index.md). ## Prerequisites The federated robot account the token maps to 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/2.16/administration-manual/authentication-management/system-robot-accounts/manage-system-robot-accounts/index.md) for system robots or this [article](/docs/2.16/user-manual/projects/configuration/project-robot-accounts/index.md) for project-scoped robots. ## Authenticating a Workload Once a federated identity provider is connected, workloads authenticate as the mapped federated robot account, using their JWT as the password. The username is not read: Container Registry resolves the federated robot account from the token's claims, so any non-empty username works. Passing the robot account name keeps logs and scripts readable. **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. ## 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.