# 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

```json
{
  "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**:

```json
{ "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.

## Related

- [Add an identity provider](add-an-identity-provider.md)
- [Set a trust policy](set-a-trust-policy.md)
- [Deploy from GitHub Actions without a stored key](deploy-from-github-actions.md)
- [Revoke role sessions](revoke-role-sessions.md)
