12.16. OIDC token exchange
- Overview
- How it works
- Configuration
- Setting up Microsoft Entra ID
- Setting up GitHub Actions
- Making the request
- Troubleshooting
Overview
An application that calls the Cloud Pipeline API for its signed-in users needs a Cloud Pipeline token. Without this feature that means a long-lived token, issued once and copied into the application's configuration, often one token shared by all of its users — so the API cannot tell who is really acting.
The token exchange lets such an application trade a user's own access token, issued by the corporate identity provider, for a short-lived Cloud Pipeline token for that same user, as RFC 8693 describes. With it:
- the application stores no static token from Cloud Pipeline;
- every call is made as the real user, with that user's permissions, and is audited as that user;
- blocking a user in Cloud Pipeline takes effect within one token lifetime.
The exchange never creates a user. The user named by the identity provider's token has to exist in Cloud Pipeline already, and the exchange changes neither their groups nor their attributes.
Note: only JSON Web Tokens are accepted as the incoming token. An opaque access token, which would need the provider's introspection endpoint, is not supported.
How it works
1. User --- signs in ------------------------------> Identity provider
2. Application --- asks for a token, aud = Cloud Pipeline -> Identity provider
3. Application --- POST /restapi/oauth/token
subject_token = the user's token ------> Cloud Pipeline API
4. Cloud Pipeline --- fetches and caches the signing keys ---> Identity provider
5. Cloud Pipeline --- a short-lived platform token ----------> Application
6. Application --- Authorization: Bearer <platform token> -> Cloud Pipeline API, edge
Cloud Pipeline checks, in this order:
- the token is a signed JWT, and its
issnames a configured issuer. An issuer that is not configured is refused before anything is fetched over the network; - the signature, against that issuer's keys, using only the algorithms it allows;
audcontains one of the configured audiences, andexp,nbfandiatpass, with 60 seconds of clock skew allowed;- the token matches one of the issuer's configured clients;
- the user that client acts as exists, is not blocked, and none of their groups is blocked.
Only then is a token issued. If any check fails, the response says so in the terms RFC 6749 defines and nothing more — the reason is written to the API log instead, because the endpoint is reachable without a Cloud Pipeline token and an unknown caller must not be able to learn from it which check refused them.
Configuration
Turning it on
The exchange is off by default. Until it is enabled the endpoint is not registered at all, so a
request to it answers 404 rather than refusing — a deployment that has not set up an identity
provider is not listening on it.
It is enabled by an application property of the API service, not by a system preference, because it decides whether the route exists:
oidc.token.exchange.enabled=true
In a pipectl deployment that is the CP_API_OIDC_TOKEN_EXCHANGE_ENABLED environment variable of
the cp-api-srv service. The API has to be restarted for a change to take effect.
Preferences
Then two system preferences, both in the System group (see 12.10):
| Preference | Description |
|---|---|
system.oidc.token.exchange.issuers |
The identity providers whose tokens may be exchanged, and the callers trusted under each. Empty or unset means the exchange is not configured, and the endpoint refuses everything |
system.oidc.token.exchange.token.lifetime |
The longest life, in seconds, of a token the exchange issues. Default 3600. A cap: an issuer or a client may ask for less, and a larger value is reduced to this one |
The issuers preference holds a JSON list. An example:
[
{
"issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
"audiences": ["<Cloud Pipeline API client ID>"],
"algorithms": ["RS256"],
"maxTokenLifetime": 3600,
"clients": [
{
"id": "portal",
"rules": [
{ "claim": "azp", "operator": "EQUALS", "value": "<portal client ID>" }
],
"requiredScopes": ["access_as_user"],
"assumeStrategy": {
"type": "REQUESTED_USER",
"userClaim": "preferred_username",
"rolesToKeep": ["ROLE_USER"],
"maxTokenLifetime": 900
}
}
]
}
]
Issuer
| Field | Required | Description |
|---|---|---|
issuer |
yes | Matched against the token's iss, exactly, and used as the base for discovery. Must be an https URL |
jwks |
no | An inline JSON Web Key Set, for a deployment whose API cannot reach the provider |
jwksUri |
no | An explicit key set URL, which skips discovery. Must be an https URL |
audiences |
yes | The token's aud must contain one of these |
algorithms |
no | Accepted signing algorithms. Default RS256 and ES256. Only asymmetric algorithms are accepted; none and the HS* family are refused |
maxTokenLifetime |
no | The longest life, in seconds, of any token issued under this issuer |
clients |
yes | The callers trusted under this issuer |
The signing keys come from whichever of the three sources is configured:
jwks— used as it is, nothing is fetched. It cannot pick up a key rotation on its own, so it has to list every key the provider publishes and be updated whenever they change. A provider signs with its next key before retiring the old one, so a set holding one key breaks at the moment of rotation.jwksUri— fetched directly.- Discovery, used when neither is set — the configured
issuerplus/.well-known/openid-configuration, andjwks_uriis read from that document. The document's ownissueris checked against the configured one.
Setting both jwks and jwksUri is refused, so the choice is never left to chance. Prefer
discovery or jwksUri where the API can reach the provider: both pick up a key rotation by
themselves.
Note: give each deployment an audience of its own, such as its API URL. With a value shared between deployments, a token minted for one of them can be replayed at another.
Client
An issuer is not a caller. Every repository on github.com shares one issuer, and so does every application registered in one Entra ID tenant. A client is the unit that trust is actually expressed against.
| Field | Required | Description |
|---|---|---|
id |
yes | Names this client in the API log, so an administrator can tell which one a token was issued through. Unique within its issuer |
rules |
yes | The claim conditions identifying the caller. All of them must pass |
requiredScopes |
no | Scopes the token must carry, read from its scp claim or, failing that, scope. Either a space-separated string or a list is understood |
assumeStrategy |
yes | Which user this client acts as, and what its token may do |
Clients are tried in the order they are configured, and the first match wins. A narrower client has to be placed above a wider one that would also match, or it never fires. The matched client is named in the log line of every exchange, which is how a shadowed entry shows up.
Rules
Each rule is one condition on one claim:
{ "claim": "repository_id", "operator": "EQUALS", "value": "456789" }
| Operator | Meaning |
|---|---|
EQUALS |
The claim equals the value, case-sensitively. Claims are compared as text, so an identifier arriving as a JSON number matches a value written as a string |
CONTAINS |
The claim is a list and the value is one of its entries. A single value is not treated as a list of one |
LIKE |
The claim matches the value as a glob, where * stands for any run of characters and ? for exactly one. The whole claim has to match |
A claim the token does not carry never matches, whatever the operator. A claim holding an object
never matches either, and neither do the time claims exp, nbf and iat, which are not text.
Every client must carry at least one EQUALS condition. A provider shares its issuer between many
callers, so these conditions are the only boundary there is, and a client built out of patterns
alone is too easy to widen by accident. For the same reason, prefer claims holding an immutable
identifier over claims holding a name: a name can be released and taken by somebody else.
Assume strategy
| Field | Description |
|---|---|
type |
SPECIFIC_USER or REQUESTED_USER |
user |
The fixed user name. SPECIFIC_USER only |
userClaim |
The claim naming the user. REQUESTED_USER only |
allowedUsers |
The only users this client may act as. REQUESTED_USER only |
deniedUsers |
Users this client may never act as, applied after allowedUsers. REQUESTED_USER only |
rolesToKeep |
Keep only these roles out of the ones the user already holds. Groups are not affected |
rolesToDrop |
Remove these roles, applied after rolesToKeep |
maxTokenLifetime |
The longest life, in seconds, of a token issued through this client |
ignoreSubjectTokenLifetime |
Let the issued token outlive the provider's token. Off by default |
exchangeable |
Let the issued token be traded for another through Cloud Pipeline's own token endpoints. Off by default |
external |
Mark the issued token external, which limits data storage access to shared storages |
With SPECIFIC_USER the user is named in the configuration — for a CI job or another service
account, whose token names no person. With REQUESTED_USER the user comes from a claim of the
token; the claim is chosen by the configuration and never by the caller, so this is not
impersonation. The name is upper-cased before it is looked up, the same way a SAML login does it.
Both role lists can only narrow. They start from what the user already holds, so naming a role the user does not have does not grant it.
They apply to roles only. The user's groups are carried into the token untouched, so any permission granted through a group — which is how storage access is usually given — survives the narrowing. A permission granted to a role that was narrowed away is lost, as intended.
Note: narrowing the roles does not reach the Docker registry. Registry access is authorized by user name, and resolves the roles from the stored user rather than from the token, so an exchanged token used for
docker logincarries whatever roles its user holds in Cloud Pipeline. Where that matters, do not grant the user those roles in the first place.
The issued token's life is the smallest of: this client's maxTokenLifetime, the issuer's, the
system.oidc.token.exchange.token.lifetime preference, and what is left of the provider's token.
That last one is what ties the two together: ending a user's session at the provider ends their
Cloud Pipeline access within one token lifetime. Two settings give that up deliberately, and both
are off unless turned on:
ignoreSubjectTokenLifetimelets the issued token outlive the provider's. It exists for CI tokens, which are short by design — a GitHub Actions token expires minutes after it is issued, which would otherwise end a longpipe storage cpmidway — and which carry no revocable session to begin with.exchangeablelets the issued token be traded for another throughGET /restapi/user/token. Left off, that call is refused for an exchanged token, so its holder cannot turn a token good for minutes into one good for weeks. Turn it on only for a client that genuinely needs to mint platform tokens.
Setting up Microsoft Entra ID
Register Cloud Pipeline as the API, and each application as a client of it:
- Create an app registration for Cloud Pipeline — this is the resource. Note its
client ID: that GUID is what appears in the token's
aud. - Under Expose an API, set an Application ID URI such as
api://cloud-pipeline-prodand add a scope, for exampleaccess_as_user. - In the registration's manifest, set
"requestedAccessTokenVersion": 2. - For each calling application, add an API permission for the Cloud Pipeline API and that scope.
- Under Token configuration, make sure the token carries the claim naming the user.
Important: step 3 is not optional. An API-only registration issues version 1.0 tokens by default, and those have a different issuer (
https://sts.windows.net/<tenant-id>/), carryappidrather thanazp, and carry nopreferred_username— so none of the configuration above matches them. Only version 2.0 tokens, whose issuer ends in/v2.0, are supported.Note:
audholds the client ID of the Cloud Pipeline registration, a GUID. It does not hold the Application ID URI — that is what a calling application asks for as a scope.
Pick for userClaim whatever attribute the deployment's SAML login already uses as its NameID, so
the exchange identifies a user exactly as a normal login does. Microsoft calls preferred_username
mutable, so where the two differ, follow the NameID.
Setting up GitHub Actions
A CI job acts as a service account, not as a person, so use SPECIFIC_USER. Nothing has to be
registered at GitHub — the whole setup is on the Cloud Pipeline side.
[
{
"issuer": "https://token.actions.githubusercontent.com",
"audiences": ["https://<cp-host>/pipeline/restapi"],
"algorithms": ["RS256"],
"clients": [
{
"id": "github-prod-deploy",
"rules": [
{ "claim": "repository_id", "operator": "EQUALS", "value": "456789" },
{ "claim": "environment", "operator": "EQUALS", "value": "prod" }
],
"assumeStrategy": {
"type": "SPECIFIC_USER",
"user": "GITHUB_CI_DEPLOY",
"rolesToKeep": ["ROLE_USER"],
"maxTokenLifetime": 3600,
"ignoreSubjectTokenLifetime": true
}
}
]
}
]
Points worth knowing:
audprotects nothing here. Every repository on github.com shares one issuer, and a workflow chooses its own audience, so the claim conditions are the only boundary. Match onrepository_idrather thanrepository: a repository name can be released and taken by somebody else, an identifier cannot. Pin an environment or a branch as well, or anyone able to push a branch in that repository can obtain the token.ignoreSubjectTokenLifetimeis needed. A GitHub token expires minutes after it is issued, so without this the Cloud Pipeline token would expire with it and end a long step midway.- The runner has to reach the API. GitHub-hosted runners run on the public internet, so a
deployment with a private API needs a self-hosted runner inside the network. The API in turn
needs outbound HTTPS to GitHub to fetch the signing keys, unless an inline
jwksis configured.
A workflow step:
permissions:
id-token: write
steps:
- run: |
GH=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://<cp-host>/pipeline/restapi" | jq -r .value)
CP=$(curl -s https://<cp-host>/pipeline/restapi/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$GH" \
-d subject_token_type=urn:ietf:params:oauth:token-type:jwt | jq -r .access_token)
echo "::add-mask::$CP"
echo "API=https://<cp-host>/pipeline/restapi/" >> "$GITHUB_ENV"
echo "API_TOKEN=$CP" >> "$GITHUB_ENV"
Making the request
Form encoded, and no Cloud Pipeline token is needed:
POST /restapi/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<the user's access token>
subject_token_type=urn:ietf:params:oauth:token-type:access_token
requested_token_type=urn:ietf:params:oauth:token-type:jwt
subject_token_type may be either ...:token-type:access_token or ...:token-type:jwt;
requested_token_type is optional and may only be ...:token-type:jwt.
A successful response:
{
"access_token": "<platform token>",
"issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
"token_type": "Bearer",
"expires_in": 900
}
The token is an ordinary Cloud Pipeline token, so the API, the edge and pipe accept it as they
accept any other — with pipe, set it as API_TOKEN. There is no refresh token: when it expires,
exchange again.
A refused response carries the error code and nothing else:
{ "error": "invalid_grant" }
| Code | Status | Meaning |
|---|---|---|
unsupported_grant_type |
400 | grant_type is missing or is not the token exchange grant |
invalid_request |
400 | subject_token is missing, or a token type is missing or unsupported |
invalid_grant |
400 | The token was not accepted, or the user it names cannot be acted as |
unauthorized_client |
400 | The token is genuine, but no configured client matches it |
server_error |
500 | A fault on the Cloud Pipeline side |
The same subject token may be exchanged more than once, for application replicas or retries.
Troubleshooting
Because the response says so little by design, the API log is where the reason is. Every exchange is
logged with the issuer, the subject, the matched client, the resulting user, the token's jti and
the lifetime it was given.
| Symptom | Likely cause |
|---|---|
The endpoint answers 404 |
The exchange is not enabled. See Turning it on |
unauthorized_client for a token that looks right |
No client matched. A condition on a claim the token does not carry, or a client above this one matched first |
invalid_grant straight away |
The issuer is not configured, aud does not match, the token has expired, or the user does not exist in Cloud Pipeline |
| Every exchange fails after a provider key rotation | An inline jwks has gone stale. Prefer discovery or jwksUri |
| The issued token has more rights at the Docker registry than its roles suggest | Expected: registry access resolves roles from the stored user, not from the token. See the note above |
The issued token expires far sooner than maxTokenLifetime |
It is capped by what was left of the provider's token. For a CI client, set ignoreSubjectTokenLifetime |
GET /restapi/user/token is refused |
Expected: an exchanged token cannot mint another unless the client sets exchangeable |