ci-oidc.md Raw History Folder

CI: OIDC

ermite is an OpenID Connect provider for its jobs, like GitHub. A job exchanges a short-lived ID token for cloud or Vault credentials instead of storing a long-lived secret.

permissions:
  id-token: write

Works with core.getIDToken(), aws-actions/configure-aws-credentials, hashicorp/vault-action (method: jwt).

Requirements

A trusted run (see CI trust). Agent runs get no token.
id-token: write in permissions:.
ERMITE_SECRETS_KEY set on the server.

Otherwise the action fails as on GitHub without the permission.

Endpoints


Issuer	`<ERMITE_PUBLIC_URL>/-/oidc`
Discovery	`/-/oidc/.well-known/openid-configuration`
Keys	`/-/oidc/.well-known/jwks`

The relying party must reach the issuer. AWS, Azure and GCP need it on the public Internet; a private server works with a relying party on the same network, such as Vault.

Token

RS256, valid 5 minutes, GitHub's claims (sub, repository, ref, sha, job_workflow_ref, environment, …), runner_environment: self-hosted.
sub:
- repo:<owner>/<repo>:environment:<name> for a job with an environment
- repo:<owner>/<repo>:pull_request for pull_request and pull_request_target
- repo:<owner>/<repo>:ref:<ref> otherwise
Default aud: <ERMITE_PUBLIC_URL>/<owner>. getIDToken(audience) picks another.

Key rotation

ermite oidc rotate-key

The previous key stays in the JWKS for 24 hours.

Vault example

vault auth enable jwt
vault write auth/jwt/config \
  oidc_discovery_url="https://git.example.com/-/oidc" \
  bound_issuer="https://git.example.com/-/oidc"
vault write auth/jwt/role/deploy role_type=jwt user_claim=sub \
  bound_audiences="https://git.example.com/owner" \
  bound_claims_type=glob bound_claims='{"sub":"repo:owner/proj:ref:refs/heads/main"}' \
  policies=deploy ttl=10m

source

1# CI: OIDC
2
3ermite is an OpenID Connect provider for its jobs, like GitHub. A job exchanges a short-lived ID token for cloud or Vault credentials instead of storing a long-lived secret.
4
5```yaml
6permissions:
7  id-token: write
8```
9
10Works with `core.getIDToken()`, `aws-actions/configure-aws-credentials`, `hashicorp/vault-action` (`method: jwt`).
11
12## Requirements
13
14- A **trusted** run (see [CI trust](ci.md#trust)). Agent runs get no token.
15- `id-token: write` in `permissions:`.
16- `ERMITE_SECRETS_KEY` set on the server.
17
18Otherwise the action fails as on GitHub without the permission.
19
20## Endpoints
21
22| | |
23|---|---|
24| Issuer | `<ERMITE_PUBLIC_URL>/-/oidc` |
25| Discovery | `/-/oidc/.well-known/openid-configuration` |
26| Keys | `/-/oidc/.well-known/jwks` |
27
28The relying party must reach the issuer. AWS, Azure and GCP need it on the public Internet; a private server works with a relying party on the same network, such as Vault.
29
30## Token
31
32- RS256, valid 5 minutes, GitHub's claims (`sub`, `repository`, `ref`, `sha`, `job_workflow_ref`, `environment`, …), `runner_environment: self-hosted`.
33- `sub`:
34  - `repo:<owner>/<repo>:environment:<name>` for a job with an environment
35  - `repo:<owner>/<repo>:pull_request` for `pull_request` and `pull_request_target`
36  - `repo:<owner>/<repo>:ref:<ref>` otherwise
37- Default `aud`: `<ERMITE_PUBLIC_URL>/<owner>`. `getIDToken(audience)` picks another.
38
39## Key rotation
40
41```sh
42ermite oidc rotate-key
43```
44
45The previous key stays in the JWKS for 24 hours.
46
47## Vault example
48
49```sh
50vault auth enable jwt
51vault write auth/jwt/config \
52  oidc_discovery_url="https://git.example.com/-/oidc" \
53  bound_issuer="https://git.example.com/-/oidc"
54vault write auth/jwt/role/deploy role_type=jwt user_claim=sub \
55  bound_audiences="https://git.example.com/owner" \
56  bound_claims_type=glob bound_claims='{"sub":"repo:owner/proj:ref:refs/heads/main"}' \
57  policies=deploy ttl=10m
58```

ci-oidc.md RawHistoryFolder