From 64605ad294b1f4512d9f9a3fa49b3ba14cd8e9a1 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sat, 14 Nov 2026 23:24:29 -0700 Subject: [PATCH 1/7] feat: add the settings of the CI OIDC token exchange, off by default [P-ENG-132] The director's `POST /oidc/token` gives a CI job a record key for 6 hours in exchange for the OIDC token of its CI provider. It is off unless `OIDC_TOKEN_EXCHANGE_ENABLED=true`. The director reads its settings from `.env` (`env_file`), so no compose file changes. - `.env.example` lists `OIDC_TOKEN_EXCHANGE_ENABLED`, `OIDC_TOKEN_AUDIENCE` and `OIDC_TRUST_FORWARDED_FOR`, commented out. - `docs/configuration.md` has a section with the three variables and what the exchange needs: outbound access to the CI providers, the audience, the indexes the scheduler creates, and the limits. - `docs/quickstart.md` points to it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE --- docs/configuration.md | 19 +++++++++++++++++++ docs/quickstart.md | 4 ++++ on-prem/.env.example | 19 +++++++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index 1b2574a..fc4b3c5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -118,6 +118,25 @@ In testing, an `api` container with 2 CPUs and 2 GB answered about 2 agent inves - One render thread runs at a time, so more CPUs make quick reads faster but not animations. - Past capacity, trace requests answer `503` with `Retry-After: 5`, and agents retry. +### CI OIDC Token Exchange (Optional) + +A CI job can get a record key from the OIDC token its CI provider gives it, so no record key is stored as a CI secret. The reporters ask for a key this way only when no record key is set. The key is valid for 6 hours, is limited to the one project the job names, and the reporter revokes it when the job ends. An organization admin adds a trust policy for each repository or owner in the dashboard; a job without a matching policy is refused. + +The exchange is off. Set `OIDC_TOKEN_EXCHANGE_ENABLED=true` in `.env` and run `docker compose up -d` once the requirements below are met. It needs the images of a release that includes the exchange. + +| Variable | Type | Default | Description | +|----------|------|---------|-------------| +| `OIDC_TOKEN_EXCHANGE_ENABLED` | bool | _(unset)_ | Turn the exchange on. Off, `POST /oidc/token` answers 404. On with no valid `OIDC_TOKEN_AUDIENCE`, it answers 503 | +| `OIDC_TOKEN_AUDIENCE` | string | _(empty)_ | The public URL of the director, the one reporters use as `CURRENTS_API_URL`, such as `https://currents-record.example.com`. Only its origin counts: scheme, host and port, no path. A token is accepted only when its audience is this origin | +| `OIDC_TRUST_FORWARDED_FOR` | bool | _(unset)_ | Count the exchange's requests per client address by the last entry of `X-Forwarded-For`. Set it to `true` only when a proxy in front of the director appends the client's address to that header and passes on none that the caller wrote. Otherwise a caller writes the header and gets a new count for each request, so the limit does nothing. Unset, the limit counts the address of the connection, which behind a proxy is the proxy's: every caller then shares 120 requests a minute. Check what your proxy writes before setting it | + +Requirements: + +- **Network.** The director checks a token with the CI provider's public signing keys, which it fetches over https through the provider's OpenID Connect discovery document. It needs outbound access to the providers you use: GitHub Actions (`token.actions.githubusercontent.com`), GitLab.com (`gitlab.com`), CircleCI (`oidc.circleci.com`), Buildkite (`agent.buildkite.com`) and Bitbucket Pipelines (`api.bitbucket.org`). It does not work on an install without internet access, and tokens from self-hosted GitLab and GitHub Enterprise are not accepted. +- **Audience.** The reporters ask the CI provider for a token whose audience is the origin of `CURRENTS_API_URL`, the director URL the reporter is configured with. GitHub Actions jobs get this automatically. On other providers the job names the audience, such as `aud` in a GitLab CI `id_tokens` entry. Set `OIDC_TOKEN_AUDIENCE` to the same origin. +- **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange are removed 6 hours after they are issued. +- **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests. + ### AI Explanations and Chat (Optional) The `ai-queue-worker` service runs the AI tasks (test explanations, chat) from the `ai-bmq` queue. `webhooks` does not run AI tasks. diff --git a/docs/quickstart.md b/docs/quickstart.md index 4619fe1..d5ce64b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -170,6 +170,10 @@ SSO_SAML_ISSUER=currents-onprem:your-org See [Enable SAML SSO](./sso-saml.md) for the full walkthrough. +### CI OIDC token exchange (optional) + +To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to your director URL. It is off by default, needs the director to reach the CI providers over the internet, and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). + See [Configuration Reference](./configuration.md) for all available options. ## Step 4: Start Services diff --git a/on-prem/.env.example b/on-prem/.env.example index dcefb6c..88040c4 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -184,6 +184,25 @@ OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED=true # OAUTH_RATE_LIMIT_AUTHORIZE_MAX=30 # OAUTH_RATE_LIMIT_USERINFO_MAX=60 +# ============================================================================= +# CI OIDC token exchange (Optional) +# ============================================================================= +# Lets a CI job get a record key, valid for 6 hours, in exchange for the OIDC +# token its CI provider gives it, so no record key is stored as a CI secret. +# Off unless OIDC_TOKEN_EXCHANGE_ENABLED=true. The director must reach the CI +# provider's public OIDC endpoints over https (GitHub Actions, GitLab.com, +# CircleCI, Buildkite, Bitbucket Pipelines), so it does not work without +# internet access, with self-hosted GitLab or with GitHub Enterprise. Read +# docs/configuration.md before turning it on. +# OIDC_TOKEN_EXCHANGE_ENABLED=true +# The public URL of the director that reporters use as CURRENTS_API_URL. A token +# is accepted only when its audience is this origin. +# OIDC_TOKEN_AUDIENCE=${CURRENTS_RECORD_API_URL} +# Only behind a proxy that appends the client address to X-Forwarded-For and +# passes on none that the caller wrote. Unset, the limit per address counts the +# address of the connection. +# OIDC_TRUST_FORWARDED_FOR=true + # ============================================================================= # AI explanations and chat (Optional) # ============================================================================= From 1f2b8687aa5b3db063540241a7b7cb24c0730d81 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sat, 14 Nov 2026 23:32:03 -0700 Subject: [PATCH 2/7] docs: make the OIDC audience a name the admin chooses [P-ENG-132] The audience of the CI OIDC token is a fixed string, not a URL: Currents cloud uses `currents:record-key`, and an install uses a name of its own, such as `currents:record-key:acme`. `OIDC_TOKEN_AUDIENCE` is required when the exchange is on and has no default, and the CI jobs set the same value as `CURRENTS_OIDC_AUDIENCE`. The docs no longer say that an install needs no client setting. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE --- docs/configuration.md | 6 +++--- docs/quickstart.md | 2 +- on-prem/.env.example | 8 +++++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index fc4b3c5..7736bca 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -126,14 +126,14 @@ The exchange is off. Set `OIDC_TOKEN_EXCHANGE_ENABLED=true` in `.env` and run `d | Variable | Type | Default | Description | |----------|------|---------|-------------| -| `OIDC_TOKEN_EXCHANGE_ENABLED` | bool | _(unset)_ | Turn the exchange on. Off, `POST /oidc/token` answers 404. On with no valid `OIDC_TOKEN_AUDIENCE`, it answers 503 | -| `OIDC_TOKEN_AUDIENCE` | string | _(empty)_ | The public URL of the director, the one reporters use as `CURRENTS_API_URL`, such as `https://currents-record.example.com`. Only its origin counts: scheme, host and port, no path. A token is accepted only when its audience is this origin | +| `OIDC_TOKEN_EXCHANGE_ENABLED` | bool | _(unset)_ | Turn the exchange on. Off, `POST /oidc/token` answers 404. On with no `OIDC_TOKEN_AUDIENCE`, it answers 503 | +| `OIDC_TOKEN_AUDIENCE` | string | _(empty)_ | **Required when the exchange is on.** A name you choose for this install, such as `currents:record-key:acme`. It is not a URL, so a change of DNS does not affect it. A token is accepted only when its audience is exactly this string. Set the same value as `CURRENTS_OIDC_AUDIENCE` in the CI jobs. Do not use `currents:record-key`, the name Currents cloud uses: a token made for the cloud would then be accepted here. A token made for another install is refused | | `OIDC_TRUST_FORWARDED_FOR` | bool | _(unset)_ | Count the exchange's requests per client address by the last entry of `X-Forwarded-For`. Set it to `true` only when a proxy in front of the director appends the client's address to that header and passes on none that the caller wrote. Otherwise a caller writes the header and gets a new count for each request, so the limit does nothing. Unset, the limit counts the address of the connection, which behind a proxy is the proxy's: every caller then shares 120 requests a minute. Check what your proxy writes before setting it | Requirements: - **Network.** The director checks a token with the CI provider's public signing keys, which it fetches over https through the provider's OpenID Connect discovery document. It needs outbound access to the providers you use: GitHub Actions (`token.actions.githubusercontent.com`), GitLab.com (`gitlab.com`), CircleCI (`oidc.circleci.com`), Buildkite (`agent.buildkite.com`) and Bitbucket Pipelines (`api.bitbucket.org`). It does not work on an install without internet access, and tokens from self-hosted GitLab and GitHub Enterprise are not accepted. -- **Audience.** The reporters ask the CI provider for a token whose audience is the origin of `CURRENTS_API_URL`, the director URL the reporter is configured with. GitHub Actions jobs get this automatically. On other providers the job names the audience, such as `aud` in a GitLab CI `id_tokens` entry. Set `OIDC_TOKEN_AUDIENCE` to the same origin. +- **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. Reporters ask the CI provider for a token with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses. Set `CURRENTS_OIDC_AUDIENCE` to your name in every CI job that records to this install. On providers where the job names the audience itself (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines), use the same name there. - **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange are removed 6 hours after they are issued. - **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests. diff --git a/docs/quickstart.md b/docs/quickstart.md index d5ce64b..3f3fc5b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -172,7 +172,7 @@ See [Enable SAML SSO](./sso-saml.md) for the full walkthrough. ### CI OIDC token exchange (optional) -To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to your director URL. It is off by default, needs the director to reach the CI providers over the internet, and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). +To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to a name you choose, such as `currents:record-key:`, and set the same name as `CURRENTS_OIDC_AUDIENCE` in the CI jobs. It is off by default, needs the director to reach the CI providers over the internet, and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). See [Configuration Reference](./configuration.md) for all available options. diff --git a/on-prem/.env.example b/on-prem/.env.example index 88040c4..9c5f99f 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -195,9 +195,11 @@ OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED=true # internet access, with self-hosted GitLab or with GitHub Enterprise. Read # docs/configuration.md before turning it on. # OIDC_TOKEN_EXCHANGE_ENABLED=true -# The public URL of the director that reporters use as CURRENTS_API_URL. A token -# is accepted only when its audience is this origin. -# OIDC_TOKEN_AUDIENCE=${CURRENTS_RECORD_API_URL} +# Required when the exchange is on, with no default: a name you choose for this +# install, such as currents:record-key:acme. It is not a URL. A token is accepted +# only when its audience is exactly this string, so set the same value as +# CURRENTS_OIDC_AUDIENCE in the CI jobs. +# OIDC_TOKEN_AUDIENCE=currents:record-key: # Only behind a proxy that appends the client address to X-Forwarded-For and # passes on none that the caller wrote. Unset, the limit per address counts the # address of the connection. From 6d2d1b8dff2dd4d6c5461106672390d26e221a98 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sat, 14 Nov 2026 23:34:38 -0700 Subject: [PATCH 3/7] docs: say where the OIDC audience is set, per CI provider [P-ENG-132] The reporter uses `CURRENTS_OIDC_AUDIENCE` only to request the token on GitHub Actions, and to show it in its missing-key hint. When the job supplies the token (GitLab CI, CircleCI, Buildkite, Bitbucket Pipelines), the audience is whatever the job asked its provider for, so the job uses the install's name there. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE --- docs/configuration.md | 4 ++-- docs/quickstart.md | 2 +- on-prem/.env.example | 5 +++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 7736bca..7513241 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -127,13 +127,13 @@ The exchange is off. Set `OIDC_TOKEN_EXCHANGE_ENABLED=true` in `.env` and run `d | Variable | Type | Default | Description | |----------|------|---------|-------------| | `OIDC_TOKEN_EXCHANGE_ENABLED` | bool | _(unset)_ | Turn the exchange on. Off, `POST /oidc/token` answers 404. On with no `OIDC_TOKEN_AUDIENCE`, it answers 503 | -| `OIDC_TOKEN_AUDIENCE` | string | _(empty)_ | **Required when the exchange is on.** A name you choose for this install, such as `currents:record-key:acme`. It is not a URL, so a change of DNS does not affect it. A token is accepted only when its audience is exactly this string. Set the same value as `CURRENTS_OIDC_AUDIENCE` in the CI jobs. Do not use `currents:record-key`, the name Currents cloud uses: a token made for the cloud would then be accepted here. A token made for another install is refused | +| `OIDC_TOKEN_AUDIENCE` | string | _(empty)_ | **Required when the exchange is on.** A name you choose for this install, such as `currents:record-key:acme`. It is not a URL, so a change of DNS does not affect it. A token is accepted only when its audience is exactly this string. The CI jobs have to ask for a token with this audience, see Requirements. Do not use `currents:record-key`, the name Currents cloud uses: a token made for the cloud would then be accepted here. A token made for another install is refused | | `OIDC_TRUST_FORWARDED_FOR` | bool | _(unset)_ | Count the exchange's requests per client address by the last entry of `X-Forwarded-For`. Set it to `true` only when a proxy in front of the director appends the client's address to that header and passes on none that the caller wrote. Otherwise a caller writes the header and gets a new count for each request, so the limit does nothing. Unset, the limit counts the address of the connection, which behind a proxy is the proxy's: every caller then shares 120 requests a minute. Check what your proxy writes before setting it | Requirements: - **Network.** The director checks a token with the CI provider's public signing keys, which it fetches over https through the provider's OpenID Connect discovery document. It needs outbound access to the providers you use: GitHub Actions (`token.actions.githubusercontent.com`), GitLab.com (`gitlab.com`), CircleCI (`oidc.circleci.com`), Buildkite (`agent.buildkite.com`) and Bitbucket Pipelines (`api.bitbucket.org`). It does not work on an install without internet access, and tokens from self-hosted GitLab and GitHub Enterprise are not accepted. -- **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. Reporters ask the CI provider for a token with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses. Set `CURRENTS_OIDC_AUDIENCE` to your name in every CI job that records to this install. On providers where the job names the audience itself (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines), use the same name there. +- **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. On GitHub Actions the reporter requests the token itself, with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses: set it to your name in those jobs. On the other providers the job supplies the token, so the audience is whatever the job asks the provider for (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines): use your name there. The hint the reporter prints when it has neither a record key nor a token shows `CURRENTS_OIDC_AUDIENCE` when it is set. - **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange are removed 6 hours after they are issued. - **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests. diff --git a/docs/quickstart.md b/docs/quickstart.md index 3f3fc5b..3044485 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -172,7 +172,7 @@ See [Enable SAML SSO](./sso-saml.md) for the full walkthrough. ### CI OIDC token exchange (optional) -To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to a name you choose, such as `currents:record-key:`, and set the same name as `CURRENTS_OIDC_AUDIENCE` in the CI jobs. It is off by default, needs the director to reach the CI providers over the internet, and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). +To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to a name you choose, such as `currents:record-key:`, and ask for the same name as the audience in the CI jobs. It is off by default, needs the director to reach the CI providers over the internet, and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). See [Configuration Reference](./configuration.md) for all available options. diff --git a/on-prem/.env.example b/on-prem/.env.example index 9c5f99f..00ef00e 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -197,8 +197,9 @@ OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED=true # OIDC_TOKEN_EXCHANGE_ENABLED=true # Required when the exchange is on, with no default: a name you choose for this # install, such as currents:record-key:acme. It is not a URL. A token is accepted -# only when its audience is exactly this string, so set the same value as -# CURRENTS_OIDC_AUDIENCE in the CI jobs. +# only when its audience is exactly this string. CI jobs ask for it: GitHub +# Actions jobs set CURRENTS_OIDC_AUDIENCE to it, and on other providers the job +# names it as the audience of its token. # OIDC_TOKEN_AUDIENCE=currents:record-key: # Only behind a proxy that appends the client address to X-Forwarded-For and # passes on none that the caller wrote. Unset, the limit per address counts the From b6c95d6f922f6cd790002d04b4d18db6c2cdbfbe Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sat, 14 Nov 2026 23:35:50 -0700 Subject: [PATCH 4/7] docs: say that the key of the OIDC exchange works for the whole organization [P-ENG-132] The project a job names only selects the organization and its trust policy. The key it gets works for the whole organization for 6 hours, so the docs no longer say that it is limited to that project. Keys expire after six hours, and MongoDB's TTL cleanup removes their documents later. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE --- docs/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 7513241..ad73d48 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -120,7 +120,7 @@ In testing, an `api` container with 2 CPUs and 2 GB answered about 2 agent inves ### CI OIDC Token Exchange (Optional) -A CI job can get a record key from the OIDC token its CI provider gives it, so no record key is stored as a CI secret. The reporters ask for a key this way only when no record key is set. The key is valid for 6 hours, is limited to the one project the job names, and the reporter revokes it when the job ends. An organization admin adds a trust policy for each repository or owner in the dashboard; a job without a matching policy is refused. +A CI job can get a record key from the OIDC token its CI provider gives it, so no record key is stored as a CI secret. The reporters ask for a key this way only when no record key is set. The key is valid for 6 hours and works for the whole organization that owns the project the job names (the project only picks the organization and its trust policy), and the reporter revokes it when the job ends. An organization admin adds a trust policy for each repository or owner in the dashboard; a job without a matching policy is refused. The exchange is off. Set `OIDC_TOKEN_EXCHANGE_ENABLED=true` in `.env` and run `docker compose up -d` once the requirements below are met. It needs the images of a release that includes the exchange. @@ -134,7 +134,7 @@ Requirements: - **Network.** The director checks a token with the CI provider's public signing keys, which it fetches over https through the provider's OpenID Connect discovery document. It needs outbound access to the providers you use: GitHub Actions (`token.actions.githubusercontent.com`), GitLab.com (`gitlab.com`), CircleCI (`oidc.circleci.com`), Buildkite (`agent.buildkite.com`) and Bitbucket Pipelines (`api.bitbucket.org`). It does not work on an install without internet access, and tokens from self-hosted GitLab and GitHub Enterprise are not accepted. - **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. On GitHub Actions the reporter requests the token itself, with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses: set it to your name in those jobs. On the other providers the job supplies the token, so the audience is whatever the job asks the provider for (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines): use your name there. The hint the reporter prints when it has neither a record key nor a token shows `CURRENTS_OIDC_AUDIENCE` when it is set. -- **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange are removed 6 hours after they are issued. +- **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange expire after six hours, and MongoDB's TTL cleanup removes their documents later. - **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests. ### AI Explanations and Chat (Optional) From d2ec9e21c872e9cb10de1de63549357cf439a5eb Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sun, 15 Nov 2026 00:37:27 -0700 Subject: [PATCH 5/7] docs: add OIDC_EXTRA_ISSUERS for self-managed GitLab and GitHub Enterprise [P-ENG-132] The director and the API read OIDC_EXTRA_ISSUERS, a list of provider=issuer entries. Add it to .env.example and the configuration reference, say that the director must reach the listed hosts, and show how to mount an internal CA with NODE_EXTRA_CA_CERTS. The notes that said tokens from self-hosted GitLab and GitHub Enterprise are not accepted now say they work with the setting. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_011baD3jW7wFPFbKF1o7FCeC --- docs/configuration.md | 16 +++++++++++++++- docs/quickstart.md | 2 +- on-prem/.env.example | 15 +++++++++++++-- 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index ad73d48..810942c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -128,11 +128,25 @@ The exchange is off. Set `OIDC_TOKEN_EXCHANGE_ENABLED=true` in `.env` and run `d |----------|------|---------|-------------| | `OIDC_TOKEN_EXCHANGE_ENABLED` | bool | _(unset)_ | Turn the exchange on. Off, `POST /oidc/token` answers 404. On with no `OIDC_TOKEN_AUDIENCE`, it answers 503 | | `OIDC_TOKEN_AUDIENCE` | string | _(empty)_ | **Required when the exchange is on.** A name you choose for this install, such as `currents:record-key:acme`. It is not a URL, so a change of DNS does not affect it. A token is accepted only when its audience is exactly this string. The CI jobs have to ask for a token with this audience, see Requirements. Do not use `currents:record-key`, the name Currents cloud uses: a token made for the cloud would then be accepted here. A token made for another install is refused | +| `OIDC_EXTRA_ISSUERS` | string | _(empty)_ | Self-managed GitLab and GitHub Enterprise Server instances whose jobs may exchange tokens, besides the cloud providers. Comma-separated `provider=issuer` entries, for example `gitlab=https://gitlab.acme.internal,github=https://ghes.acme.internal/_services/token`. The director and the API read it, and both refuse to start with an invalid value. Unset: cloud providers only. See Requirements | | `OIDC_TRUST_FORWARDED_FOR` | bool | _(unset)_ | Count the exchange's requests per client address by the last entry of `X-Forwarded-For`. Set it to `true` only when a proxy in front of the director appends the client's address to that header and passes on none that the caller wrote. Otherwise a caller writes the header and gets a new count for each request, so the limit does nothing. Unset, the limit counts the address of the connection, which behind a proxy is the proxy's: every caller then shares 120 requests a minute. Check what your proxy writes before setting it | Requirements: -- **Network.** The director checks a token with the CI provider's public signing keys, which it fetches over https through the provider's OpenID Connect discovery document. It needs outbound access to the providers you use: GitHub Actions (`token.actions.githubusercontent.com`), GitLab.com (`gitlab.com`), CircleCI (`oidc.circleci.com`), Buildkite (`agent.buildkite.com`) and Bitbucket Pipelines (`api.bitbucket.org`). It does not work on an install without internet access, and tokens from self-hosted GitLab and GitHub Enterprise are not accepted. +- **Network.** The director checks a token with the CI provider's public signing keys, which it fetches over https through the provider's OpenID Connect discovery document. It needs outbound access to the providers you use: GitHub Actions (`token.actions.githubusercontent.com`), GitLab.com (`gitlab.com`), CircleCI (`oidc.circleci.com`), Buildkite (`agent.buildkite.com`) and Bitbucket Pipelines (`api.bitbucket.org`). It does not work on an install without internet access, unless the only issuers are self-hosted ones you list in `OIDC_EXTRA_ISSUERS`. For each listed instance the director needs outbound https access to its host, which can be private or internal; only the listed hosts are fetched. +- **Self-managed GitLab and GitHub Enterprise Server.** Tokens from these are accepted when you list their issuers in `OIDC_EXTRA_ISSUERS`: `gitlab=` followed by the URL of the GitLab instance, and `github=` followed by `https:///_services/token` for GitHub Enterprise Server. The issuer is compared with the `iss` claim of the token as an exact string. Write each as `https`, with the host in lowercase, no default port, and no user, password, trailing slash, query or fragment. An issuer of a cloud provider, an issuer listed twice, an unknown provider and more than 20 entries are refused. The director and the API do not start with an entry they cannot use, so check `docker compose logs director api` after you change it. The `.env` file reaches both services, so you set it once. A trust policy stores the issuer it was made for and matches only tokens of that issuer, because a self-hosted instance chooses its own owner and project IDs, which can equal IDs on GitLab.com or github.com. The dashboard form for adding a policy for a listed issuer is not available yet. This part needs the images of a release that includes self-hosted issuers. +- **Internal certificate authority.** When a listed instance uses a certificate from your own authority, give the director that authority with `NODE_EXTRA_CA_CERTS`, the path of a PEM file inside the container. Only the director fetches signing keys, so only it needs the file. Put the file on the host and mount it into the director, for example in a `docker-compose.override.yml` next to `docker-compose.yml`, which `docker compose` reads on its own: + + ```yaml + services: + director: + environment: + NODE_EXTRA_CA_CERTS: /certs/internal-ca.pem + volumes: + - ./certs/internal-ca.pem:/certs/internal-ca.pem:ro + ``` + + Node.js adds the file to its built-in authorities; it does not replace them. If you start the stack with `-f`, add the same lines to a file you pass with `-f`. - **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. On GitHub Actions the reporter requests the token itself, with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses: set it to your name in those jobs. On the other providers the job supplies the token, so the audience is whatever the job asks the provider for (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines): use your name there. The hint the reporter prints when it has neither a record key nor a token shows `CURRENTS_OIDC_AUDIENCE` when it is set. - **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange expire after six hours, and MongoDB's TTL cleanup removes their documents later. - **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests. diff --git a/docs/quickstart.md b/docs/quickstart.md index 3044485..2aacd32 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -172,7 +172,7 @@ See [Enable SAML SSO](./sso-saml.md) for the full walkthrough. ### CI OIDC token exchange (optional) -To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to a name you choose, such as `currents:record-key:`, and ask for the same name as the audience in the CI jobs. It is off by default, needs the director to reach the CI providers over the internet, and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). +To let CI jobs get a record key from the OIDC token their CI provider issues, instead of storing a record key as a CI secret, set `OIDC_TOKEN_EXCHANGE_ENABLED=true` and `OIDC_TOKEN_AUDIENCE` to a name you choose, such as `currents:record-key:`, and ask for the same name as the audience in the CI jobs. It is off by default, needs the director to reach the CI providers over the internet (or the self-managed GitLab and GitHub Enterprise Server instances you list in `OIDC_EXTRA_ISSUERS`), and has requirements to read first: see [CI OIDC Token Exchange](./configuration.md#ci-oidc-token-exchange-optional). See [Configuration Reference](./configuration.md) for all available options. diff --git a/on-prem/.env.example b/on-prem/.env.example index 00ef00e..0fdb38f 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -192,8 +192,9 @@ OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED=true # Off unless OIDC_TOKEN_EXCHANGE_ENABLED=true. The director must reach the CI # provider's public OIDC endpoints over https (GitHub Actions, GitLab.com, # CircleCI, Buildkite, Bitbucket Pipelines), so it does not work without -# internet access, with self-hosted GitLab or with GitHub Enterprise. Read -# docs/configuration.md before turning it on. +# internet access. Self-managed GitLab and GitHub Enterprise Server work when +# you list them in OIDC_EXTRA_ISSUERS. Read docs/configuration.md before +# turning it on. # OIDC_TOKEN_EXCHANGE_ENABLED=true # Required when the exchange is on, with no default: a name you choose for this # install, such as currents:record-key:acme. It is not a URL. A token is accepted @@ -201,6 +202,16 @@ OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED=true # Actions jobs set CURRENTS_OIDC_AUDIENCE to it, and on other providers the job # names it as the audience of its token. # OIDC_TOKEN_AUDIENCE=currents:record-key: +# Self-managed GitLab and GitHub Enterprise Server instances whose jobs may +# exchange tokens: comma-separated provider=issuer entries, at most 20, read by +# the director and the API. A GitLab issuer is the URL of the instance, a GitHub +# Enterprise Server issuer is https:///_services/token. Each is https, in +# lowercase, with no trailing slash, query or fragment. An invalid value stops +# both services at start. Unset: only the cloud providers. The director must +# reach each listed host. For a certificate from an internal CA, mount the CA +# file into the director and set NODE_EXTRA_CA_CERTS there: see +# docs/configuration.md. +# OIDC_EXTRA_ISSUERS=gitlab=https://gitlab.acme.internal,github=https://ghes.acme.internal/_services/token # Only behind a proxy that appends the client address to X-Forwarded-For and # passes on none that the caller wrote. Unset, the limit per address counts the # address of the connection. From fdebb337bd1489096f257792e2d5ed8c9cae3986 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sun, 15 Nov 2026 00:47:50 -0700 Subject: [PATCH 6/7] docs: list the recordKeyHash index and say only the host is lowercase [P-ENG-132] The scheduler now builds the unique partial index on recordKeyHash, so the note that on-prem looks keys up by hash without an index is gone. In an issuer only the host is lowercase; the path keeps its case. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_011baD3jW7wFPFbKF1o7FCeC --- docs/configuration.md | 2 +- on-prem/.env.example | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 810942c..8915737 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -148,7 +148,7 @@ Requirements: Node.js adds the file to its built-in authorities; it does not replace them. If you start the stack with `-f`, add the same lines to a file you pass with `-f`. - **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. On GitHub Actions the reporter requests the token itself, with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses: set it to your name in those jobs. On the other providers the job supplies the token, so the audience is whatever the job asks the provider for (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines): use your name there. The hint the reporter prints when it has neither a record key nor a token shows `CURRENTS_OIDC_AUDIENCE` when it is set. -- **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a TTL index on `recordKeys.expiresAt` that removes expired keys, and a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy. There is nothing to build by hand. Record keys are looked up by hash without an index on-prem, which is fast while the collection is small; keys from the exchange expire after six hours, and MongoDB's TTL cleanup removes their documents later. +- **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a unique partial index on `recordKeys.recordKeyHash`, which finds a record key by its hash; a TTL index on `recordKeys.expiresAt` that removes expired keys; a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy; and the unique index of the `oidcTrustPolicies` collection, which the exchange reads through. There is nothing to build by hand. Keys from the exchange expire after six hours, and MongoDB's TTL cleanup removes their documents later. - **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests. ### AI Explanations and Chat (Optional) diff --git a/on-prem/.env.example b/on-prem/.env.example index 0fdb38f..1fa0733 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -205,8 +205,8 @@ OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED=true # Self-managed GitLab and GitHub Enterprise Server instances whose jobs may # exchange tokens: comma-separated provider=issuer entries, at most 20, read by # the director and the API. A GitLab issuer is the URL of the instance, a GitHub -# Enterprise Server issuer is https:///_services/token. Each is https, in -# lowercase, with no trailing slash, query or fragment. An invalid value stops +# Enterprise Server issuer is https:///_services/token. Each is https, +# with the host in lowercase and no trailing slash, query or fragment. An invalid value stops # both services at start. Unset: only the cloud providers. The director must # reach each listed host. For a certificate from an internal CA, mount the CA # file into the director and set NODE_EXTRA_CA_CERTS there: see From 27dcdf74ce58a50304d735eac76db1a4e5d82c30 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sun, 15 Nov 2026 15:25:02 -0700 Subject: [PATCH 7/7] docs: name the oidcAudience option and --oidc-audience next to CURRENTS_OIDC_AUDIENCE [P-ENG-132] Checked the OIDC_EXTRA_ISSUERS rules, NODE_EXTRA_CA_CERTS and the required audience against the currents code; this is the only difference. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_011baD3jW7wFPFbKF1o7FCeC --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8915737..af6c78d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -147,7 +147,7 @@ Requirements: ``` Node.js adds the file to its built-in authorities; it does not replace them. If you start the stack with `-f`, add the same lines to a file you pass with `-f`. -- **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. On GitHub Actions the reporter requests the token itself, with the audience in `CURRENTS_OIDC_AUDIENCE`, which defaults to `currents:record-key`, the name Currents cloud uses: set it to your name in those jobs. On the other providers the job supplies the token, so the audience is whatever the job asks the provider for (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines): use your name there. The hint the reporter prints when it has neither a record key nor a token shows `CURRENTS_OIDC_AUDIENCE` when it is set. +- **Audience.** There is no default. Pick a name for your install, such as `currents:record-key:`, and set it as `OIDC_TOKEN_AUDIENCE`. On GitHub Actions the reporter requests the token itself, with the audience in `CURRENTS_OIDC_AUDIENCE` (or the `oidcAudience` option of `@currents/playwright`, or `--oidc-audience` of the `currents` CLI, which win over the variable), which defaults to `currents:record-key`, the name Currents cloud uses: set it to your name in those jobs. On the other providers the job supplies the token, so the audience is whatever the job asks the provider for (`aud` in a GitLab CI `id_tokens` entry, and the commands on CircleCI, Buildkite and Bitbucket Pipelines): use your name there. The hint the reporter prints when it has neither a record key nor a token shows `CURRENTS_OIDC_AUDIENCE` when it is set. - **Indexes.** The scheduler creates the indexes the exchange needs when it starts, with the other indexes the release declares: a unique partial index on `recordKeys.recordKeyHash`, which finds a record key by its hash; a TTL index on `recordKeys.expiresAt` that removes expired keys; a partial index on `recordKeys.issuedFor.policyId` that finds the keys of a removed trust policy; and the unique index of the `oidcTrustPolicies` collection, which the exchange reads through. There is nothing to build by hand. Keys from the exchange expire after six hours, and MongoDB's TTL cleanup removes their documents later. - **Limits.** The director counts at most 120 requests a minute from one address before it checks a token, and at most 600 keys a minute for one organization. When Redis is down it refuses the requests.