diff --git a/docs/configuration.md b/docs/configuration.md index 1b2574a..af6c78d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -118,6 +118,39 @@ 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 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. + +| 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. 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, 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` (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. + ### 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..2aacd32 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 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. ## Step 4: Start Services diff --git a/on-prem/.env.example b/on-prem/.env.example index dcefb6c..1fa0733 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -184,6 +184,39 @@ 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. 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 +# 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: +# 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, +# 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 +# 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. +# OIDC_TRUST_FORWARDED_FOR=true + # ============================================================================= # AI explanations and chat (Optional) # =============================================================================