# Deploy from GitHub Actions without a stored key

Let a GitHub Actions job exchange its own OIDC token for credentials of an IAM role that last at most one hour, so no access key is stored in the repository.

The job asks GitHub for an OIDC token, sends it to Deutsche Cloud, and gets back a temporary access
key acting as the role. Replace `org-EXAMPLE1234` with your organization's id and
role-id with the role's id.

## Prerequisites

- GitHub Actions registered as an identity provider (see
  [Add an identity provider](add-an-identity-provider.md)).
- A role, here ci-deployer, with the policies the job needs attached (see
  [Create a role](create-a-role.md)) and a trust policy that admits the repository and branch or
  environment (see [Set a trust policy](set-a-trust-policy.md)).
- To copy the workflow from the console, `iam:GetRole` on the role; without it the role's page
  answers "not found".
- The exchange itself needs no IAM permission: the role's trust policy decides.

## Add the workflow

1. Open the role, choose **Trust policy**, and copy the **GitHub Actions workflow** shown under the
   saved trust policy. It has the console address, the audience and the role's resource name
   filled in, and an `environment:` line when the trust policy pins a GitHub environment.
2. Put it in `.github/workflows/` of the repository. Its sign-in step is:

```yaml
permissions:
  id-token: write # lets the job request an OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      EWS_API_URL: https://console.example.com
      EWS_ROLE_RN: rn:ews::org-EXAMPLE1234:iam:role/role-id
      EWS_AUDIENCE: https://console.example.com
    steps:
      - name: Sign in to Deutsche Cloud (OIDC, no stored secret)
        run: |
          AUD=$(jq -rn --arg a "$EWS_AUDIENCE" '$a|@uri')
          OIDC_TOKEN=$(curl -sS --fail-with-body \
            -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUD" | jq -r .value)
          CREDS=$(curl -sS --fail-with-body -X POST \
            "$EWS_API_URL/iam/api/sts/assume-role-with-web-identity" \
            -H 'content-type: application/json' \
            -d "$(jq -n --arg role "$EWS_ROLE_RN" --arg token "$OIDC_TOKEN" \
                  '{roleRn: $role, webIdentityToken: $token}')") \
            || { echo "Deutsche Cloud refused the token: $CREDS" >&2; exit 1; }
          KEY_ID=$(jq -r .data.accessKeyId <<<"$CREDS")
          SECRET=$(jq -r .data.secretKey <<<"$CREDS")
          echo "::add-mask::$SECRET"
          echo "::add-mask::$KEY_ID:$SECRET"
          {
            echo "EWS_ACCESS_KEY=$KEY_ID:$SECRET"
            echo "EWS_ACCESS_KEY_ID=$KEY_ID"
            echo "EWS_SECRET_KEY=$SECRET"
          } >> "$GITHUB_ENV"
          echo "Signed in until $(jq -r .data.expiresAt <<<"$CREDS")"
```

## Result

For the rest of the job, `EWS_ACCESS_KEY` holds `<key id>:<secret>`, the variable the CLI reads,
and `EWS_ACCESS_KEY_ID` and `EWS_SECRET_KEY` hold the two halves, for example for `docker login`.
The credential works wherever an access key does and carries the role's policies. To deploy an app
with it, see [Deploy from GitHub Actions without a stored key](/docs/deploy/guide/deploy-from-github-actions-with-oidc).

## The exchange

`POST /iam/api/sts/assume-role-with-web-identity` takes no `Authorization` header: the token is the
credential.

```json
{
  "roleRn": "rn:ews::org-EXAMPLE1234:iam:role/<role id>",
  "webIdentityToken": "<OIDC token>",
  "durationSeconds": 3600,
  "sessionName": "gha-1234-1"
}
```

- `durationSeconds` is 900 to 3600; without it the credential lasts 3600 seconds.
- `sessionName` is 2 to 64 characters of `A-Z a-z 0-9 _ + = , . @ -`; without it, a GitHub token's
  session is named `gha-<run id>-<run attempt>`.

The answer's `data` holds `accessKeyId`, `secretKey`, `accessKey` (`<key id>:<secret>`),
`expiresAt`, `orgId`, `orgSlug`, `roleRn`, `sessionName` and `subject` (the token's `sub`).

Every exchange for a role that exists, allowed or refused, is recorded in the audit log as
`iam:AssumeRoleWithWebIdentity` on the role. Once the token's signature and claims are checked,
the entry carries its repository, ref, environment, workflow and run id; a token refused before
that carries only the reason and, when it has one, its issuer. A malformed request body, a 429,
and a role that does not exist are not recorded.

## On Deutsche Cloud's own runners

Jobs that run on Deutsche Cloud CI get tokens from Deutsche Cloud's own issuer with GitHub's claim names.
Register **Deutsche Cloud CI** as an identity provider and add a statement for it to the same trust
policy, so one role serves both. For a repository imported or mirrored from GitHub,
`dcloud iam roles trust-ci` adds those statements from the ones that trust GitHub Actions (see
[Set a trust policy](set-a-trust-policy.md)). There, `uses: dcloud/configure-credentials@v1` with
`role-to-assume: <role RN>` does the exchange and signs Docker in to the container registry.

## If the exchange is refused

- 403 `AccessDenied: not authorized to assume this role with this token`: no trust policy, no
  statement matches the token's claims, a `Deny` matches, or the role does not exist. A job in a
  GitHub environment carries `environment:` in its `sub`, not `ref:`.
- 400 `InvalidIdentityToken: token audience is not accepted by this provider`: the job requested
  an audience the provider does not list.
- 400 `InvalidIdentityToken: no identity provider is registered for this issuer`.
- 400 `InvalidIdentityToken: token has expired`, or another `InvalidIdentityToken: …` reason.
- 400 `roleRn: roleRn must look like rn:…::<org-id>:iam:role/<role-id>`.
- 429 `Too many requests`: more than 30 exchanges a minute from one address, or 60 a minute for one
  role.

## Related

- [Web identity federation](web-identity-federation.md)
- [Revoke role sessions](revoke-role-sessions.md)
- [Deploy from GitHub Actions without a stored key](/docs/deploy/guide/deploy-from-github-actions-with-oidc)
  in the Apps guide
