OAuth 2.0 Token Exchange
Extracted elements (24)
A refresh token will typically not be issued in a token exchange (trading one temporary credential for another), but MAY be issued for offline or user-not-present scenarios where the original credential may expire before the client no longer needs access.
Impersonation gives the acting principal all the rights of the subject and makes them indistinguishable from the subject; delegation preserves the actor's separate identity while explicitly noting they act on behalf of the subject. Both semantics are supported via the presence or absence of 'actor_token' and the 'act' claim in issued tokens.
The distinction between 'urn:ietf:params:oauth:token-type:access_token' and 'urn:ietf:params:oauth:token-type:jwt' is intentional: the former indicates an opaque OAuth access token (which may internally be a JWT), while the latter specifically indicates a JWT is being exchanged, typically in cross-domain use cases.
The response reuses the 'access_token' parameter from RFC 6749 Section 5.1 for historical reasons and to allow reuse of existing OAuth 2.0 token endpoint constructs; the issued token need not be an OAuth access token. The 'token_type' value 'N_A' is used when the issued token is not usable as an access token.
The token exchange act has no impact on the validity of the subject or actor tokens (absent one-time-use semantics), and does not create tight linkage between input and output tokens—renewal of the input token is not expected to be reflected in the output token. Token revocation propagation is deployment-specific, not a general STS protocol property.
The token exchange protocol is not itself RESTful because an STS doesn't lend itself well to a REST approach, but it does use communication patterns (HTTP POST, JSON) familiar to REST developers, avoiding the XML/SOAP complexity of WS-Trust.
The token exchange grant type is layered on top of OAuth 2.0's existing extension grant mechanism (RFC 6749 Section 4.5) and token endpoint, meaning existing OAuth infrastructure can support token exchange with minimal changes. The 'audience' and 'resource' parameters may be used together to indicate multiple target services with a mix of logical names and resource URIs.
For access control policy, consumers of a token MUST only consider the token's top-level claims and the current actor identified by the top-level 'act' claim. Nested (prior) 'act' claims are informational only and MUST NOT be used in access control decisions.
If the request or either token is invalid or unacceptable based on policy, the authorization server MUST construct an error response with the 'invalid_request' error code. If unable to issue a token for an indicated target, the 'invalid_target' error code SHOULD be used.
The 'actor_token_type' parameter is REQUIRED when 'actor_token' is present in the request but MUST NOT be included otherwise.
The authorization server MUST perform the appropriate validation procedures for the indicated token types of both the subject token and (if present) the actor token.
The 'grant_type' parameter MUST be 'urn:ietf:params:oauth:grant-type:token-exchange' to indicate a token exchange request. The 'subject_token' and 'subject_token_type' parameters are also REQUIRED in every token exchange request.
The 'scope' response parameter is OPTIONAL if the scope of the issued token is identical to the scope requested; otherwise it is REQUIRED.
The value of the 'resource' parameter MUST be an absolute URI per RFC 3986 Section 4.3, MAY include a query component, and MUST NOT include a fragment component. Multiple 'resource' parameters may be used to indicate multiple target resources.
Tokens may contain privacy-sensitive information and MUST only be transmitted over encrypted channels such as TLS. When disclosure of certain information to the client is undesirable, the token MUST be encrypted to its intended recipient. Deployments SHOULD minimize the data included in issued tokens, potentially using anonymous or pseudonymous identifiers.
A successful token exchange response returns 'access_token' (REQUIRED, the issued security token), 'issued_token_type' (REQUIRED, URI identifier for the issued token's type), 'token_type' (REQUIRED, e.g., 'Bearer' or 'N_A'), 'expires_in' (RECOMMENDED), and optionally 'scope' and 'refresh_token'.
The 'act' (actor) claim is a JSON object within a JWT that expresses delegation, identifying the acting party to whom authority has been delegated. Delegation chains are expressed by nesting 'act' claims; the outermost represents the current actor, with deeper nesting representing prior actors.
The 'may_act' claim is a JSON object in a JWT asserting that a specific party is authorized to become the actor and act on behalf of the JWT subject. It can be used by an authorization server to determine if the client or actor_token party is authorized to engage in delegation or impersonation.
The 'scope' JWT claim is a JSON string containing a space-separated list of scopes associated with the token, consistent with RFC 6749 Section 3.3 format. The 'client_id' JWT claim carries the OAuth 2.0 client identifier that requested the token.
Token exchange uses the extension grant type mechanism defined in Section 4.5 of RFC 6749. The client sends an HTTP POST to the token endpoint with 'application/x-www-form-urlencoded' encoding, using the grant type 'urn:ietf:params:oauth:grant-type:token-exchange'.
Token type identifiers are URIs. Defined types include: access_token, refresh_token, id_token (OpenID Connect), saml1 (base64url-encoded SAML 1.1 assertion), and saml2 (base64url-encoded SAML 2.0 assertion). The JWT type 'urn:ietf:params:oauth:token-type:jwt' is defined in RFC 7519.
IANA registers six URNs in the 'OAuth URI' subregistry: the token-exchange grant type and five token type URIs (access_token, refresh_token, id_token, saml1, saml2). Seven new OAuth Parameters are registered (audience, requested_token_type, subject_token, subject_token_type, actor_token, actor_token_type, issued_token_type). The 'N_A' access token type and four JWT claims (act, scope, client_id, may_act) are also registered.
Delegation and impersonation introduce unique security risks: any time one principal is delegated the rights of another, the potential for abuse exists. Use of the 'scope' claim, combined with limited token lifetimes, is recommended to mitigate abuse by restricting the contexts in which delegated rights can be exercised.
Omitting client authentication allows a compromised token to be leveraged via the STS into other tokens by anyone possessing it. Client authentication enables additional authorization checks by the STS as to which entities are permitted to impersonate or receive delegations from other entities.