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 theaudienceparameter, 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_allowedaccept an ID token, and only this endpoint does. A bearer value whoseaudisn'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::Audienceentry setsjob_token_allowed: false, andauthorize_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 returns401. 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.logcarriesmeta.gl_project_id,meta.job_idandmeta.pipeline_id, refusals included, andtoken_type: CiIdTokenon success. The token itself is never logged.
Implementation notes
find_user_from_bearer_tokenis overridden inEE::Gitlab::Auth::AuthFinders. A bearer value meant for the exchange that fails verification gets401instead of falling through to other handlers.resolve_access_tokenreturnsnilonce an ID token has authenticated the request, the wayfind_personal_access_tokenalready skips job tokens. A fresh authenticator that never ran the ID-token finder, such as the admin-mode check, raises instead. That keepsvalid_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 thekidthatGitlab::Ci::JwtBasesigns with. - The JWKS, the unverified
auddecode 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_audienceclaim (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 nojtireplay protection either. ADR-020 records both and leaves single-usejtitracking 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
401either way.
References
- Resolves #633754
- Parent: #629690
- Audience design: #633754 (comment 4199618274)
- Feature flag rollout: #638630
- Follow-up, one lifetime ceiling for every issuance surface: #639382
- AR ADR-020: Token issuance R1
- Earlier attempt, reverted because it read the job record: !256927 (merged), revert !258494 (merged)
Screenshots or screen recordings
Not applicable: API-only change with no UI.
How to set up and validate locally
-
Enable the feature flag in the Rails console:
Feature.enable(:token_exchange_ci_id_token) -
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") -
Exchange it:
curl --request POST --header "Authorization: Bearer <id_token>" \ --data "audience=gitlab-artifact-registry" \ "http://gdk.test:3000/api/v4/token_exchange" -
Decode the returned
tokenand check thataudcontainsgitlab-artifact-registryandgitlab.jobcarries the build's project, commit, pipeline and job IDs. -
Repeat without
audience(400), with an ID token whoseaudisgitlab-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.