--- title: "Federated Robot Accounts" description: "Let CI/CD pipelines and Kubernetes workloads authenticate to Container Registry with short-lived JWTs from a provider you trust, instead of robot account secrets you have to store and rotate." date: 2026-09-21 lastmod: 2026-10-21 canonical: "https://container-registry.com/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/" source: "https://container-registry.com/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/index.md" harbor_version: "2.16" agent_instructions: "This is the markdown representation of https://container-registry.com/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/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 Robot Accounts *Let CI/CD pipelines and Kubernetes workloads authenticate to Container Registry with short-lived JWTs from a provider you trust, instead of robot account secrets you have to store and rotate.* Federated Robot Accounts ================================= A federated robot account is a robot account that signs in with a token issued by somebody else. Your CI system or your Kubernetes cluster already hands every job and every pod a short-lived JSON Web Token that says which job or which pod it is. Connect that issuer to Container Registry once, and those tokens become registry credentials. No shared secret exists on either side. The ordinary alternative is a robot account secret: Container Registry generates it, you copy it into a CI variable or a Kubernetes pull secret, and from then on it is your job to keep it out of logs, out of forks, and on a rotation schedule. A federated robot account has no secret to copy, so none of that applies. A token lives for minutes, belongs to one workload, and expires whether or not anyone remembers it. ## The Three Pieces | Piece | Who sets it up | What it does | |---|---|---| | A connected federated identity provider | System administrator, once per issuer and audience | Tells Container Registry which issuer to trust, and which audience value tokens must carry | | A federated robot account | System administrator, once per workload or group of workloads | Carries the permissions, and the claim rules that decide which tokens become this account | | A workload that presents its token | Whoever owns the pipeline or the cluster | Sends the token as the password on an ordinary registry login | ## How a Pull Works 1. The workload asks its own platform for a token. A CI job asks the CI system, a pod's node asks the cluster API server. 2. The platform returns a short-lived JWT that names the job, the repository or the service account. 3. The workload signs in to Container Registry with the token as the password. The account is identified by the token's claims, so the username is not what selects it. 4. Container Registry picks the connected provider whose issuer and audience the token carries. 5. It verifies the signature against the keys that provider publishes, and the token's expiry. 6. It matches the token's remaining claims against the claim rules on each federated robot account. 7. The matching account's permissions decide what happens next. Steps 4 to 6 are the whole feature. Everything before them is the platform you already run. ## What Has to Line Up Three strings, and almost every failed setup is one of them: - **The issuer.** Whatever the token's `iss` claim says, character for character, has to be the issuer on the connected provider. - **The audience.** The `aud` claim is an agreed identifier, usually the registry hostname. The same value has to appear wherever the workload asks for its token and on the connected provider. - **The claim values.** The claim rules on the robot account are compared to the token's claims as exact strings. A rule that matches nothing means no robot account is found, which reads as an authentication failure. ## When Not to Use It Federated robot accounts are for machine-to-machine traffic. A person signing in to the web interface uses [user authentication](/docs/2.16/administration-manual/authentication-management/user-authentication/index.md) instead. A client that cannot obtain a token from a trusted issuer, a laptop or a standalone build box, still needs a [system robot account](/docs/2.16/administration-manual/authentication-management/system-robot-accounts/index.md) with a secret. [Connect a Federated Identity Provider](/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/connect-a-federated-identity-provider/index.md) — Register the issuer whose tokens Container Registry will trust [Create a Federated Robot Account](/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/create-a-federated-robot-account/index.md) — Give a workload permissions through claim rules, with no secret to store [Kubernetes Workloads](/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/kubernetes-workloads/index.md) — Pull images on a cluster with no imagePullSecrets [Troubleshooting Federated Robot Accounts](/docs/2.16/administration-manual/authentication-management/federated-robot-accounts/troubleshooting-federated-robot-accounts/index.md) — Why a token was rejected, in the order worth checking