Accept CI/CD ID tokens at the token exchange endpoint

What does this MR do and why?

POST /api/v4/token_exchange now accepts a CI/CD ID token as the credential, so the token a job publishes with carries its build metadata (gitlab.job: project, commit, pipeline and job). Behind the token_exchange_ci_id_token feature flag, checked against the job's project and off by default.

  • The ID token is addressed to the exchange. It must carry exactly one aud: the exchange URL, $CI_SERVER_URL/api/v4/token_exchange, the way every CI/CD ID token names its verifier. The target service comes from the audience parameter, which stays required for every credential.
  • Verification uses Authn::IamService::JwtValidationService: the instance's CI JWT signing key, the CI ID token issuer, exp, and the required claims.
  • Everything comes from the token, never the job record, so the IAM STS can perform the same exchange later. The minted token's TTL is capped at the ID token's exp.
  • Other credentials are unaffected. Only routes that declare ci_id_token_allowed accept an ID token, and only this endpoint does. A bearer value whose aud isn't the exchange goes to the existing handlers unchanged.
  • Composite identity users are refused. The ID token names only the service account, so exchanging it would act with the service account's full permissions. Those jobs keep using the job token, without build metadata.
  • ID tokens can't mint AutoFlow tokens. AutoFlow's Authn::TokenExchange::Audience entry sets job_token_allowed: false, and authorize_audience! applies that to any CI caller, which now includes an ID token.
  • Rate limits count per user. Rack::Attack identifies ID-token requests by user on any API request, as it does job tokens, so jobs behind one runner IP don't share the unauthenticated limit.
  • Two gates are wider than the endpoint, as for job tokens. On any API path, a valid ID token counts as authenticated for the Rack::Attack limiter and for API::Internal::Workhorse#request_authenticated?, which lets Workhorse buffer an upload body before Rails returns 401. Only the exchange accepts the ID token for authentication.
  • No extra log line. Once the ID token passes verification and the flag check, the request line in api_json.log carries meta.gl_project_id, meta.job_id and meta.pipeline_id, refusals included, and token_type: CiIdToken on success. The token itself is never logged.
Implementation notes
  • find_user_from_bearer_token is overridden in EE::Gitlab::Auth::AuthFinders. A bearer value meant for the exchange that fails verification gets 401 instead of falling through to other handlers.
  • resolve_access_token returns nil once an ID token has authenticated the request, the way find_personal_access_token already skips job tokens. A fresh authenticator that never ran the ID-token finder, such as the admin-mode check, raises instead. That keeps valid_access_token? false without hashing the JWT as an OAuth token and a PAT.
  • The verification JWKS is built with ruby-jwt's JWK class, keeping the kid that Gitlab::Ci::JwtBase signs with.
  • The JWKS, the unverified aud decode and the verification result are memoized per request, so Rack::Attack and the API share them and a rejected token logs one error line.
Known trade-offs
  • An ID token can be exchanged for any supported service until the follow-up lands. Per-service scoping moves to the target_audience claim (staging steps 2 and 3 in the audience note below), tracked in #639815. Today that costs nothing: the only other audience is AutoFlow, which refuses CI callers.
  • On Cells, an ID-token exchange from a non-legacy cell is refused. The ID token carries no routing claim, unlike a JWT job token, so the HTTP Router sends it to the legacy cell, which refuses it if each cell signs with its own CI key. The job falls back to CI_JOB_TOKEN. Tracked in gitlab-com/gl-infra/tenant-scale/cells-infrastructure/team#1065.
  • A leaked ID token can be exchanged until its exp. The job-token path refuses jobs that are no longer running. The ID-token path can't check that without reading the job record, so its window is the build timeout, which can be longer than the job's actual run time. There is no jti replay protection either. ADR-020 records both and leaves single-use jti tracking and sender binding to the IAM STS. The TTL cap limits only the minted token. Refusing ID tokens past a maximum age is proposed in #639814.
  • With the flag off, an ID token addressed to the exchange is still verified before the flag is checked, because the flag's actor is the project the token names. The response is 401 either way.

References

Screenshots or screen recordings

Not applicable: API-only change with no UI.

How to set up and validate locally

  1. Enable the feature flag in the Rails console:

    Feature.enable(:token_exchange_ci_id_token)
  2. In the Rails console, mint an ID token for a running build:

    build = Ci::Build.running.last # or create one by running a pipeline
    Gitlab::Ci::JwtV2.for_build(build, aud: "#{Gitlab.config.gitlab.url}/api/v4/token_exchange")
  3. Exchange it:

    curl --request POST --header "Authorization: Bearer <id_token>" \
      --data "audience=gitlab-artifact-registry" \
      "http://gdk.test:3000/api/v4/token_exchange"
  4. Decode the returned token and check that aud contains gitlab-artifact-registry and gitlab.job carries the build's project, commit, pipeline and job IDs.

  5. Repeat without audience (400), with an ID token whose aud is gitlab-artifact-registry (401), and with the flag disabled (401).

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

This change touches authentication, so it needs AppSec review. AppSec also needs to confirm the exchange URL as the ID token aud, with target_audience carrying the service in the follow-up.

Edited by Bojan Marjanovic

Merge request reports

Loading
Loading