Skip to content

feat: add the settings of the CI OIDC token exchange, off by default [P-ENG-132] - #46

Draft
agoldis wants to merge 7 commits into
mainfrom
agoldis/oidc-token-exchange-settings
Draft

agoldis wants to merge 7 commits into
mainfrom
agoldis/oidc-token-exchange-settings

Conversation

@agoldis

@agoldis agoldis commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Owner: @agoldis
Linear: P-ENG-132

Draft until the token exchange is live in SaaS, like the reporter PRs.

What

Adds the settings of the CI OIDC token exchange (POST /oidc/token on the director) to the compose setup. They are commented out in .env.example, so the exchange is off. The director and the API read .env through env_file, so no compose file changes.

Variable Default
OIDC_TOKEN_EXCHANGE_ENABLED unset (off) Turns the exchange on
OIDC_TOKEN_AUDIENCE unset Required when the exchange is on, no default. A name you choose, such as currents:record-key:acme, not a URL. The CI jobs set the same value as CURRENTS_OIDC_AUDIENCE
OIDC_EXTRA_ISSUERS unset (cloud providers only) Self-managed GitLab and GitHub Enterprise Server instances whose jobs may exchange tokens: comma-separated provider=issuer entries, at most 20. The director and the API read it, and both refuse to start with an invalid value
OIDC_TRUST_FORWARDED_FOR unset true only behind a proxy that appends the client address to X-Forwarded-For and passes on none the caller wrote. Otherwise a caller can fake its address and get around the limit per address

docs/configuration.md has a new section with the variables and the requirements, and docs/quickstart.md points to it.

Checked before writing

Indexes. On-prem builds them itself. The scheduler runs runMigrations({ syncIndexes: true }) at startup (packages/scheduler/src/init.ts), which creates every index the release declares. For recordKeys the release declares the unique partial index on recordKeyHash (the lookup by hash), the TTL index on expiresAt (expireAfterSeconds: 0) and the partial index on issuedFor.policyId, and for oidcTrustPolicies its unique index. So there is no manual step, and the docs list the four indexes. Keys from the exchange expire after six hours, and MongoDB's TTL cleanup removes their documents later. The next release's upgrade notes should list the new recordKeys indexes.

Reporter audience. The reporters' default audience is currents:record-key, and on GitHub Actions, where the reporter requests the token itself, they take another from CURRENTS_OIDC_AUDIENCE (the CLI also has --oidc-audience). The reporter also shows CURRENTS_OIDC_AUDIENCE in its missing-key hint when it is set. On GitLab CI, CircleCI, Buildkite and Bitbucket Pipelines the job supplies the token, so the audience is whatever the job asks its provider for. An install picks its own name, so on-prem does need a client setting: the docs say to use the install's name in each of those places, and not to pick currents:record-key itself, because a token made for the cloud would then be accepted. Reporters: currents-reporter#511, currents-playwright#1107.

Do not merge this before the server change and the reporter releases that use the fixed audience name.

Network. The director must reach the providers' public discovery and key endpoints over https: GitHub Actions, GitLab.com, CircleCI, Buildkite and Bitbucket Pipelines. Air-gapped installs are not supported. Self-managed GitLab and GitHub Enterprise Server are supported through OIDC_EXTRA_ISSUERS: the director must reach each listed host, which can be private or internal, and an issuer with a certificate from an internal CA needs NODE_EXTRA_CA_CERTS on the director. The docs show a docker-compose.override.yml that mounts the CA file.

Release. The OIDC_EXTRA_ISSUERS part needs images of a currents release that contains currents#5011 (the director accepts the issuers) and currents#5012 (the API reads the setting and stores a policy for a listed issuer). The dashboard form for such a policy follows in a later change. The rest of this PR needs the release with the exchange.

Related

Checklist

  • PR title is Changelog-friendly: (fix|feat|chore): title [CSR-xxx]
  • User-friendly and meaningful description of the changes
  • Documentation was updated

Not run: docker compose config on a changed file, because no compose file changed.

🤖 Generated with Claude Code

https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE

…[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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE
@baz-reviewer

baz-reviewer Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Review this PR on Baz

Baz Summary

Document the optional CI OIDC token exchange and its configuration for on-premise deployments, allowing CI jobs to obtain six-hour record keys without storing CI secrets. Explain audience, issuer, network, certificate, rate-limit, and index requirements across the configuration guide, quickstart, and environment template.

Latest Contributors(2)
UserCommitDate
agoldis@gmail.comdocs: name the oidcAud...November 15, 2026
agoldis@users.noreply....docs: say that the key...November 15, 2026


Skills  Activate Skill Maintainer to keep your skills up to date

Planner  This PR would have been improved with Baz Planner - Try it now

agoldis and others added 6 commits November 14, 2026 23:32
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE
…ization [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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE
…prise [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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3jW7wFPFbKF1o7FCeC
… [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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3jW7wFPFbKF1o7FCeC
…TS_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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3jW7wFPFbKF1o7FCeC

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant