Web identity federation

How a workload such as a CI job trades its own OIDC token for short-lived credentials of an IAM role, and what is checked on the way.

Last updated 18 November 2026View as Markdown

Instead of storing an access key in a CI system, a job presents the OIDC token its platform issues to it. Deutsche Cloud checks the token, checks the role's trust policy, and answers with a temporary access key that acts as the role.

Part What it is
Identity provider An OIDC issuer registered in your organization, with the audiences its tokens may carry
Role The policies the credentials carry. A session acts with the role's policies and nothing else
Trust policy The document on the role that says which provider's tokens, with which claims, may assume it
Session One exchange: a temporary access key, live for 15 minutes to one hour, listed on the role's page

Token checks

Check Rule
Provider The token's iss names an identity provider of the role's organization, exactly
Signature RS256 or ES256, by a key the issuer publishes, named by the token's kid
aud Contains one of the provider's audiences
exp, nbf Honoured with 60 seconds of clock skew
iat Present and not in the future; exp at most one hour after iat
Size At most 8 KiB

The signing keys of Deutsche Cloud CI's own issuer are read from the platform, never fetched over the network. Other issuers' keys are fetched from their public https:// address.

Trust policies

{
  "Version": "2024-01-01",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Federated": "rn:ews::org-EXAMPLE1234:iam:oidc-provider/<provider id>" },
      "Condition": {
        "StringEquals": { "repository": "my-org/my-app" },
        "StringLike": { "sub": "repo:my-org/my-app:environment:*" }
      }
    }
  ]
}
Field Values
Version 2024-01-01, exactly
Statement 1 to 20 statements
Effect Allow or Deny. A matching Deny refuses, whatever else allows
Principal.Federated The resource name of an identity provider in your organization
Operators StringEquals, and StringLike (* any run of characters, ? one character). Both case-sensitive
Claims sub, aud, repository, repository_id, repository_owner, repository_owner_id, ref, ref_type, environment, job_workflow_ref, workflow_ref, event_name, actor, actor_id

A statement applies when its provider is the token's and every claim it names matches. A claim with a list of values matches when any one does. A claim the token does not carry never matches.

Every Allow must pin the workload, or the policy is refused when saved. It needs at least one of:

  • a repository condition whose owner (my-org/) is written out before any wildcard;
  • for GitHub Actions, a sub that starts repo:<owner>/ or repo:<owner>@<owner id>/ before any wildcard, or a numeric repository_id or repository_owner_id without wildcards;
  • for other issuers, a sub with at least three characters, one a letter or digit, before any wildcard.

repo:my-org/* and repo:my-org@1001/* are accepted; repo:* and repo:*@1001/*@5005:… are not, because a branch name may contain @ and /.

GitHub repository renames

GitHub writes a token's sub in one of two formats, depending on the repository's OIDC subject settings:

Format Example sub
classic repo:my-org/my-app:ref:refs/heads/main
immutable subjects repo:my-org@1001/my-app@5005:ref:refs/heads/main

Both contain the names, so a sub condition stops matching when the repository or its owner is renamed, or the repository moves. To keep a role working through that, pin repository_id plus ref or environment, and leave sub out. This is what the console's template writes when you match by ID:

{ "StringEquals": { "repository_id": "5005", "ref": "refs/heads/main" } }

A repository ID stays the same through a rename and through a transfer to another owner; to refuse the role after a transfer, also pin repository_owner_id. ref matches every job on that branch, including jobs that run in a GitHub environment, which a classic branch sub does not.

Deutsche Cloud CI

Jobs on Deutsche Cloud's runners get tokens from https://<console host>/ci/api/oidc, with GitHub's claim names. Their sub is repo:<organization slug>/<repository>: followed by ref:<ref>, environment:<name> or pull_request. One role can trust both issuers with one statement for each.

Limits

  • A session lasts 900 to 3600 seconds, 3600 by default.
  • Exchanges are limited to 30 a minute from one address and 60 a minute for one role.
  • Deleting an identity provider stops new exchanges with its tokens; credentials already issued stay valid until they expire.
Did this page help you?