# Deploy with an OIDC token

Let a GitHub-syntax job prove which repository, branch and environment it runs for, and trade that for temporary credentials instead of a stored key.

A job with `permissions: id-token: write` can ask for an OpenID Connect token as on GitHub: the
request URL and token are in its environment as `ACTIONS_ID_TOKEN_REQUEST_URL` and
`ACTIONS_ID_TOKEN_REQUEST_TOKEN`, so `core.getIDToken()` and actions built on it work unchanged.
CI signs the token with its own issuer, `https://<console host>/ci/api/oidc` (discovery at
`/.well-known/openid-configuration` under it, keys at `/jwks`). Any relying party can trust it:
Deutsche Cloud's IAM, or a cloud or vault of your own.

## Prerequisites

- A workflow under `.github/workflows/`; the native format has no OIDC tokens.
- A role whose trust policy admits the repository, and the CI identity provider in IAM (see
  [Deploy from GitHub Actions without a stored key](/docs/iam/guide/deploy-from-github-actions)).

## Ask for the token

```yaml
permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: dcloud/configure-credentials@v1
        with:
          role-to-assume: rn:ews::org-EXAMPLE1234:iam:role/3f0c9a52-5d0e-4c1a-9d39-0b8a3e0f6a11
      - run: dcloud ci runs list "$REPO_ID"
```

`dcloud/configure-credentials` trades the job's token for temporary credentials of the role (15 to
60 minutes, 60 by default), exports `DCLOUD_ACCESS_KEY` and `DCLOUD_API_URL` for later steps, and
signs Docker in to your organization's registry. `dcloud/…` actions are served by Deutsche Cloud on
its hosted machines, never looked up on GitHub; `ews/…` names the same actions. On your own runners
and runner pools they do not run (the job fails with "`uses: dcloud/configure-credentials@v1`:
Deutsche Cloud actions do not run on self-hosted runners yet"): ask for the token with
`core.getIDToken()` or `curl` there instead.

## Result

The token carries GitHub's claims. Its `sub` is:

| The job                 | `sub`                                                                      |
| ----------------------- | -------------------------------------------------------------------------- |
| has an environment      | `repo:<organization>/<repository>:environment:<name>`                      |
| runs for a pull request | `repo:<organization>/<repository>:pull_request`                            |
| otherwise               | `repo:<organization>/<repository>:ref:<ref>`, e.g. `…:ref:refs/heads/main` |

`runner_environment` is `ews-hosted` on the hosted machines and `self-hosted` on your runners and
runner pools.

- `403` "This job does not have `permissions: id-token: write`."
- `403` "No token: …" for a job of an environment that refuses its ref, is not approved yet, was
  rejected or expired, or whose wait timer has not run out; the rest of the message says which.
- `403` "The run is no longer running" once the run has ended, and on your runners "The job is not
  running" for a job that is not running.
- `400` "Invalid audience" for an `audience` with spaces or control characters, or over 256
  characters. Without one, the audience is the console's origin.
- `429` "Too many token requests" past 120 requests a minute in one run.

Every token issued is recorded in the audit log as `ci:CreateIdToken`, with the run, the job and
the `sub`; so is a refusal for a missing `id-token: write` or an environment that is not ready. The action is not granted by any policy: the job's `permissions:` and
the environment's rules decide.

## Related

- [Deploy from GitHub Actions without a stored key](/docs/iam/guide/deploy-from-github-actions)
- [Protect a deployment with an environment](protect-a-deployment.md)
