Skip to content

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

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

agoldis wants to merge 8 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) as chart values, off by default:

Value Default Sets on the director
currents.oidcTokenExchange.enabled false OIDC_TOKEN_EXCHANGE_ENABLED=true
currents.oidcTokenExchange.audience "" OIDC_TOKEN_AUDIENCE. Required when enabled is true, no default: templating fails while it is empty. A name you choose, such as currents:record-key:acme, not a URL. The CI jobs set the same value as CURRENTS_OIDC_AUDIENCE
currents.oidcTokenExchange.trustForwardedFor false OIDC_TRUST_FORWARDED_FOR=true. Only for a proxy or load balancer 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

| currents.oidcTokenExchange.extraIssuers | [] | OIDC_EXTRA_ISSUERS on the director and the server: self-managed GitLab and GitHub Enterprise Server instances whose jobs may exchange tokens, as provider=issuer entries (a list, or a comma-separated string), at most 20. Rendered whenever the list is not empty, whether or not enabled is true, because the server reads it too. An entry that is not github= or gitlab= with an https:// issuer fails templating; the services check the other rules at start and refuse to start with an invalid value |

Nothing is rendered while enabled is false, whatever the other two are, except extraIssuers below. Docs: a new section in docs/eks/quickstart.md, docs/configuration.md regenerated with ./scripts/build-docs.sh, and an entry under [Unreleased] in CHANGELOG.md.

The audience is a fixed name, not a URL, so a DNS change never affects it (Andrew's decision): Currents cloud uses currents:record-key, and an install picks its own. The docs say not to pick currents:record-key itself, because a token made for the cloud would then be accepted.

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 extraIssuers: the director pods 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 the director.env, director.volumes and director.volumeMounts values for it.

Release. The extraIssuers part needs images of a currents release that contains currents#5011 (the director accepts the issuers) and currents#5012 (the server 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

Tested

  • helm lint with ci/lint-values.yaml, without the exchange and with it on with an audience: passes.
  • helm template: off, no OIDC_* variable; on with an audience, OIDC_TOKEN_EXCHANGE_ENABLED and OIDC_TOKEN_AUDIENCE with that value; on with no audience, an empty one or one of only spaces (the director trims it), rendering fails with a message that says what to set; spaces around a valid name are trimmed; OIDC_TRUST_FORWARDED_FOR only when trustForwardedFor is true; nothing when enabled is false with the others set. Only the director deployment gets them.
  • extraIssuers (rendered with helm template): empty, no OIDC_EXTRA_ISSUERS; a list of two entries, and a comma-separated string, render OIDC_EXTRA_ISSUERS with the entries joined by commas on the director and the server deployments and nowhere else; with enabled true and an audience it renders next to the other variables; bitbucket=https://x and gitlab=http://x fail templating with a message that gives an example. helm lint passes, and helm-docs leaves docs/configuration.md clean.
  • ./scripts/build-docs.sh leaves nothing uncommitted. Not run: ct install, which needs the cluster of the CI job.

🤖 Generated with Claude Code

https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE

…-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`.

- `currents.oidcTokenExchange.enabled` (false), `audience` (empty: the URL of
  `domains.recordApiHost`) and `trustForwardedFor` (false) set
  `OIDC_TOKEN_EXCHANGE_ENABLED`, `OIDC_TOKEN_AUDIENCE` and
  `OIDC_TRUST_FORWARDED_FOR` on the director. Nothing is rendered while
  `enabled` is false, whatever the other two are.
- `docs/eks/quickstart.md` has a section on the network access it needs, the
  audience, client addresses and the indexes the scheduler creates;
  `docs/configuration.md` is regenerated; the changelog lists the values.

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

Add optional Helm chart settings for CI OIDC token exchange, allowing the director to issue six-hour record keys while keeping the feature disabled by default. Configure director and server environment variables, validate audiences and self-managed issuers, and document deployment, networking, security, and upgrade requirements.

Topics

TopicDetails
Deployment Documentation Document how to enable CI OIDC exchange, configure audiences and self-managed issuers, provide network and certificate requirements, and understand rate limits, indexes, and release prerequisites.
Modified files (3)
  • CHANGELOG.md
  • docs/configuration.md
  • docs/eks/quickstart.md
Latest Contributors(2)
UserCommitDate
agoldis@gmail.comdocs: name the oidcAud...November 15, 2026
agoldis@users.noreply....docs: say that the key...November 15, 2026
CI OIDC Exchange Configure the chart to render OIDC_TOKEN_EXCHANGE_ENABLED, OIDC_TOKEN_AUDIENCE, OIDC_TRUST_FORWARDED_FOR, and OIDC_EXTRA_ISSUERS for the appropriate deployments, including validation and safe defaults.
Modified files (4)
  • charts/currents/templates/_common.tpl
  • charts/currents/templates/director/deployment.yaml
  • charts/currents/templates/server/deployment.yaml
  • charts/currents/values.yaml
Latest Contributors(2)
UserCommitDate
agoldis@gmail.comfeat: add currents.oid...November 15, 2026
agoldis@users.noreply....fix: treat an audience...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 7 commits November 14, 2026 23:32
…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`.

- `currents.oidcTokenExchange.audience` has no default. Templating fails with a
  message that says what to set when `enabled` is true and it is empty. It
  no longer falls back to the URL of `domains.recordApiHost`.
- The docs and the changelog say to pick a name, to set the same value as
  `CURRENTS_OIDC_AUDIENCE` in the CI jobs, and not to use `currents:record-key`.

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
The director trims `OIDC_TOKEN_AUDIENCE`, so a value of only spaces passed the
chart's `required` check and left the exchange answering that it is not
configured. The chart now trims the audience before checking it, and renders
the trimmed value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011baD3hG81A9qbFYrSn1ysE
…tLab and GHES [P-ENG-132]

The director and the server read OIDC_EXTRA_ISSUERS, a list of
provider=issuer entries. The chart renders it on both when the list is not
empty, and fails templating for an entry that is not github= or gitlab= with an
https issuer. Document the network access to the listed hosts and
NODE_EXTRA_CA_CERTS for an internal CA, and change the notes that said
self-hosted GitLab and GitHub Enterprise are not supported.

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