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: A system administrator has to set this up first, by connecting the identity provider and creating the federated robot account your token will map to. See Federated Robot Accounts.

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 for system robots or this article 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. The Kubernetes credential provider sends jwt.

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 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 token’s claims do not satisfy the claim rules of any federated robot account under the provider. The username plays no part in this. Compare the rules with the decoded token, and confirm the account has not been disabled, has not expired and has not been deleted.

Issuer or audience mismatch

The iss or aud claim in the presented JWT does not match the Issuer and Audience of any connected federated identity provider. Both are compared as exact strings, scheme included: request the token for exactly the audience configured on the provider. If harbor-core logs trusted issuer <name> has no audience, the provider predates v2.15.12 and a system administrator has to set its audience once.