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.
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
repositorycondition whose owner (my-org/) is written out before any wildcard; - for GitHub Actions, a
subthat startsrepo:<owner>/orrepo:<owner>@<owner id>/before any wildcard, or a numericrepository_idorrepository_owner_idwithout wildcards; - for other issuers, a
subwith 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.