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
- 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.
- The platform returns a short-lived JWT that names the job, the repository or the service account.
- 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.
- Container Registry picks the connected provider whose issuer and audience the token carries.
- It verifies the signature against the keys that provider publishes, and the token’s expiry.
- It matches the token’s remaining claims against the claim rules on each federated robot account.
- 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
issclaim says, character for character, has to be the issuer on the connected provider. - The audience. The
audclaim 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 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 with a secret.