oauth2.dev

urn:ietf:params:oauth:grant-type:token-exchange

IESG

Registry Context

This URI identifies an OAuth 2.0 token exchange request when used as the `grant_type` value at the token endpoint.

Technical Summary

RFC 8693 defines this value for the required `grant_type` parameter in a token exchange request. Token exchange uses the extension grant mechanism defined by RFC 6749, where an absolute URI is used as the `grant_type` value.

When Used

When a client requests a security token through OAuth 2.0 token exchange.

Normative Requirements

Clients

MUST NOT
2
  1. RFC 8693 - Section 2.1

    Include a fragment component in a `resource` URI..

    Condition: When including a `resource` parameter.

    [The resource URI] MUST NOT include a fragment component.

  2. RFC 8693 - Section 2.1

    Include `actor_token_type`..

    Condition: When `actor_token` is absent.

    [actor_token_type] MUST NOT be included otherwise.

MUST
1
  1. RFC 8693 - Section 2.1

    Provide each `resource` value as an absolute URI..

    Condition: When including a `resource` parameter.

    The value of the resource parameter MUST be an absolute URI.

REQUIRED
4
  1. RFC 8693 - Section 2.1

    Include the `grant_type` parameter with the value `urn:ietf:params:oauth:grant-type:token-exchange`..

    Condition: When making a token exchange request.

    grant_type REQUIRED. The value urn:ietf:params:oauth:grant-type:token-exchange indicates that a token exchange is being performed.

  2. RFC 8693 - Section 2.1

    Include a `subject_token` representing the identity of the party on whose behalf the request is made..

    Condition: When making a token exchange request.

    subject_token REQUIRED.

  3. RFC 8693 - Section 2.1

    Include `subject_token_type` identifying the type of the supplied subject token..

    Condition: When making a token exchange request.

    subject_token_type REQUIRED.

  4. RFC 8693 - Section 2.1

    Include `actor_token_type` identifying the type of the actor token..

    Condition: When `actor_token` is present.

    This is REQUIRED when the actor_token parameter is present in the request.

MAY
1
  1. RFC 8693 - Section 2.1

    Include a query component in a `resource` URI..

    Condition: When including a `resource` parameter.

    [The resource URI] MAY include a query component.

OPTIONAL
5
  1. RFC 8693 - Section 2.1

    Include one or more `resource` parameters identifying target services or resources..

    Condition: When the client needs to identify where it intends to use the requested token.

    resource OPTIONAL.

  2. RFC 8693 - Section 2.1

    Include one or more `audience` parameters identifying target services by logical name..

    Condition: When the client needs to identify intended audiences.

    audience OPTIONAL.

  3. RFC 8693 - Section 2.1

    Include a `scope` parameter containing space-delimited, case-sensitive scope values..

    Condition: When specifying the desired scope of the requested security token.

    scope OPTIONAL.

  4. RFC 8693 - Section 2.1

    Include `requested_token_type` to identify the desired type of security token..

    Condition: When requesting a particular token type.

    requested_token_type OPTIONAL.

  5. RFC 8693 - Section 2.1

    Include an `actor_token` representing the identity of an acting party..

    Condition: When an acting party is involved.

    actor_token OPTIONAL.

Authorization servers

MUST
1
  1. RFC 8693 - Section 2.1

    Perform the appropriate validation procedures for the indicated subject token type and, when present, the indicated actor token type..

    Condition: When processing a token exchange request.

    The authorization server MUST perform the appropriate validation procedures for the indicated token type and, if the actor token is present, also perform the appropriate validation procedures for its indicated token type.

Validation Guidance

error

Verify that `grant_type` is present and exactly equals `urn:ietf:params:oauth:grant-type:token-exchange`.

error

If `resource` is present, verify that every value is an absolute URI without a fragment component; a query component is permitted.

error

Verify that both `subject_token` and `subject_token_type` are present.

error

Verify that `actor_token_type` is present if and only if `actor_token` is present.

error

Validate the subject token according to its indicated type, and do the same for the actor token when supplied.

warning

Treat this value as an OAuth 2.0 extension grant URI used at the token endpoint, not as a token type identifier.

Security Notes

RFC 8693 - Section 2.1

Allowing unauthenticated token exchange can let anyone possessing a compromised token use the security token service to obtain other tokens. Client authentication enables additional authorization checks on impersonation and delegation.

Reference

Details

Entry Id
urn:ietf:params:oauth:grant-type:token-exchange
Urn
urn:ietf:params:oauth:grant-type:token-exchange
Common Name
Token exchange grant type for OAuth 2.0
Change Controller
IESG
Reference
RFC8693 - Section 2.1