]> Independent

public@karlmcguinness.com

Okta

aaron@parecki.com https://www.okta.com

Security Web Authorization Protocol OAuth 2.0 Token Exchange Identity Chaining Resource Indicators Cross-Domain Authorization This specification defines a method for OAuth 2.0 clients to discover the set of available target services (audiences, resources, and scopes) for a given subject token when performing OAuth 2.0 Token Exchange. The discovery endpoint accepts any subject token type registered in the OAuth Token Type Registry and returns values that are valid inputs to subsequent Token Exchange requests, supporting advanced use cases such as identity chaining and cross-domain delegation. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction OAuth 2.0 Token Exchange enables a client to present a token issued in one security domain to an Authorization Server and securely trade it for a new token issued for another domain. The exchanged token is minted with the target server’s token requirements, including its own audience, resource indicators, and scopes, so it becomes valid and enforceable for the desired downstream service. This enables controlled cross-domain access, removes the confused-deputy problem by ensuring tokens are explicitly targeted to the correct service, and avoids requiring direct trust between the original token issuer and the target service. Authorization Servers may be capable of issuing tokens to multiple services for a given subject token and client, but the client must already know which values it may request. Today, this knowledge is typically provided through static configuration, proprietary APIs, or informal documentation, leading to brittle integrations and unnecessary Token Exchange failures, particularly when subjects are authorized to access only a subset of available services. This specification defines the OAuth 2.0 Token Exchange Target Service Discovery Endpoint, a standardized mechanism that enables clients to dynamically discover the set of available Token Exchange targets (audiences, resources, and scopes) for a given subject token. The authorization server evaluates both the subject token and the client's permissions and returns only the values the client is authorized to request. This extension is especially valuable in scenarios requiring identity chaining and cross-domain authorization:

• Progressive token exchange across service boundaries, such as multi-tier microservices architectures and delegated flows where tokens must be exchanged with narrower or transformed permissions at each hop. In these scenarios, discovery is critical because the set of available downstream services and their required permissions vary based on the subject token's context and the client's authorization. The permission narrowing at each service hop means that static configuration cannot accommodate these per-subject and per-client variations, leading to integration failures when clients attempt token exchanges for services the subject is not authorized to access.
• Cross-boundary deployments where downstream services exist in separate administrative, organizational, or cloud domains requiring strict control over token issuance and acceptance. Unlike progressive token exchange which focuses on permission transformation within a single domain, this scenario addresses the challenge of discovering available target services across distinct trust boundaries where authorization policies are independently managed. Discovery is essential here because authorization policies and available target services change dynamically across these boundaries, and static configuration cannot reflect real-time policy decisions or account for varying permissions across different administrative domains.
• Single Sign-On (SSO) to API flows, such as those enabled by the Identity Assertion Authorization Grant (ID-JAG) , where a client needs to seamlessly connect to cross-domain resources and act on behalf of the user to access APIs

This specification provides the following benefits:

• Dynamic Discovery: Eliminates static configuration requirements by enabling clients to discover available target services at runtime, reducing integration failures and improving developer experience.
• Standardization: Provides a standardized discovery mechanism, replacing proprietary APIs and improving interoperability across OAuth 2.0 implementations.
• Real-Time Authorization: Returns target services based on real-time policy evaluation, client permissions, and subject token context, ensuring accurate and up-to-date authorization information. This enables per-subject and per-client results, which is essential when the set of available target services varies by user or client. Static configurations cannot accommodate these per-subject or per-client variations.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Token Exchange Target Service Discovery Endpoint This specification defines a new endpoint for OAuth 2.0 Authorization Servers that enables clients to discover the set of available target services (audiences, resources, and scopes) for a given subject token when performing OAuth 2.0 Token Exchange . The endpoint is identified by the Authorization Server metadata parameter token_exchange_target_service_discovery_endpoint, as defined in Section 7.

Endpoint Request The client makes a request to the token exchange target service discovery endpoint by sending an HTTP POST request to the endpoint URL. The client MUST use TLS as specified in Section 1.6 of . The endpoint URL MUST be obtained from the Authorization Server's metadata document using the token_exchange_target_service_discovery_endpoint parameter. The endpoint URL is an absolute URL as defined by . The client sends the parameters using the application/x-www-form-urlencoded format per Appendix B of . Character encoding MUST be UTF-8 as specified in Appendix B of . If a parameter is included more than once in the request, the authorization server MUST return an error response with the error code invalid_request as described in Section 2.2.

Request Parameters The following parameters are used in the request:

subject_token

REQUIRED. The subject token used as input to discovery. The token type is indicated by the subject_token_type parameter.

subject_token_type

REQUIRED. A string value containing a URI, as described in Section 5 of , that indicates the type of the subject_token parameter. This identifier MUST be a valid URI, as defined in , and SHOULD be registered in the "OAuth Token Type Registry" as defined in Section 5.1 of .

The client MAY include additional parameters as defined by extensions and the authorization server MUST ignore unknown parameters. Client authentication MAY be required by the authorization server. The means of client authentication are defined by the authorization server and MAY include any method supported by the authorization server, including those defined in Section 2.3 of . If client authentication is required by the authorization server but not provided in the request, the authorization server MUST return an error response with the error code invalid_client as described in Section 2.2.

Subject Token Processing The authorization server MUST process the subject_token parameter according to the following rules:

1. The authorization server MUST validate that the subject_token and subject_token_type parameters are not empty strings. If either parameter is an empty string, the authorization server MUST return an error response with the error code invalid_request as described in Section 2.2.
2. The authorization server MUST validate that the subject_token_type parameter is a valid URI per the URI validation requirements specified in Section 2.1.2. If the format is invalid (e.g., not a valid absolute URI or URN), the authorization server MUST return an error response with the error code invalid_request as described in Section 2.2.
3. The authorization server MUST determine whether it supports the indicated token type. This determination is an implementation decision and MAY be based on the authorization server's capabilities, the subject_token value, the authenticated client, or any combination thereof. If the subject_token_type is not supported by the authorization server for the given context, the authorization server MUST return an error response with the error code unsupported_token_type as described in Section 2.2.
4. The authorization server MUST validate the subject_token according to the rules for the indicated token type. The validation process MUST verify:
   • The token is properly formatted for the indicated token type
   • The token's signature (if applicable) is valid and can be verified using the appropriate cryptographic keys
   • The token was issued by a trusted issuer
   • The token has not expired
   • The token has not been revoked
   • The token is associated with the authenticated client, if client authentication is required
5. If the subject_token is invalid for any reason (e.g., malformed, expired, revoked, or does not match the subject_token_type), the authorization server MUST return an error response with the error code invalid_request as described in Section 2.2.
6. The authorization server MUST evaluate the subject_token in conjunction with the authenticated client's permissions to determine which target services are available for discovery. The specific authorization policy evaluation mechanism is implementation-specific and MAY be based on scopes, claims, resource-based access control, or other authorization models. When constructing the response, the authorization server MUST omit any target service objects or fields that would contain empty strings, as specified in Section 2.1.2.

Request Example The following is an example of a discovery request:

Endpoint Response The authorization server validates the request and returns a response with the discovery results. The response MUST use the application/json media type as specified in . The Content-Type header of the response MUST be set to application/json. The authorization server MAY include HTTP cache validators (such as ETag or Last-Modified headers) and expiration times (such as Cache-Control or Expires headers) in the response to enable conditional requests by the client, as specified in Section 13 of .

Successful Response If the request is valid and authorized, the authorization server returns a JSON array of available token exchange targets. Each element in the array represents a target service that the client is authorized to request in a subsequent token exchange operation. Each target service object contains the following fields:

audience

REQUIRED. A string value containing an absolute URI indicating an available audience value for token exchange, as defined in Section 2.1 of . Empty strings are not supported and the response MUST contain an URI. If the audience value is a URI but not a URL (e.g., a URN) and does not provide a location, the authorization server SHOULD return a resource field that contains a location.

resource

OPTIONAL. A string value containing an absolute URI, or an array of string values each containing a URI, indicating available resource indicator values, as defined in Section 2 of . In JSON, URI values are represented as strings. Empty strings are not supported. If present as a string, the string MUST contain a non-empty URI. If present as an array, the array MUST contain at least one non-empty URI string and MUST NOT be empty. If no resources are available for a target service, this field MUST be omitted from the response rather than including an empty string, empty array, or null value.

scope

OPTIONAL. A string value containing a space-delimited list of OAuth 2.0 scope values, as defined in Section 3.3 of , that are available for this target service. Each individual scope value in the list MUST conform to the scope syntax defined in Section 3.3 of . Empty strings are not supported. If the field is present, the string MUST contain at least one non-empty scope value. If no scopes are available for a target service, this field MUST be omitted from the response rather than including an empty string. The authorization server determines which scopes to return based on its authorization policy evaluation, which is implementation-specific. The scopes returned SHOULD be those that would be authorized in a subsequent token exchange request per Section 2.2 of .

supported_token_types

OPTIONAL. An array of strings indicating the token types that may be requested for this target service in a subsequent token exchange operation. Each string MUST be a valid absolute URI, as defined in . Empty strings are not supported; array elements MUST contain non-empty URI strings. If the array would be empty or contain only empty strings, this field MUST be omitted from the response. If omitted, the client may use any token type supported by the authorization server.

Multiple target service objects for the same audience MAY be returned with different resource(s) and scopes. The combination of audience and resource (the entire set of resources, when present) MUST be unique within the target service array. That is, no two objects in the array may have both the same audience value and the same set of resource values (when comparing arrays, the order of elements does not matter, but the complete set must match). If no target services are available for the given subject token and client, the authorization server returns an empty array [].

Response Example The following is an example of a successful discovery response:

Error Response If the request failed, the authorization server returns an error response as defined in Section 5.2 of . The response MUST use the application/json media type, and the Content-Type header MUST be set to application/json. The HTTP status code MUST be set according to the error code, as specified below and in Section 5.2 of . The following error codes may be returned:

invalid_request

The request is missing a required parameter, includes an invalid parameter value (such as an invalid URI format for subject_token_type or an empty string for subject_token or subject_token_type), includes a parameter more than once, or is otherwise malformed. This error code is also returned when the provided subject token is invalid, expired, revoked, or does not match the subject token type, or when another error condition occurred during token validation. The HTTP status code MUST be 400 (Bad Request).

invalid_client

Client authentication failed (e.g., unknown client, no client authentication included when required, or unsupported authentication method). This error code MUST be returned when client authentication is required by the authorization server but not provided in the request. The HTTP status code MUST be 401 (Unauthorized).

unauthorized_client

The authenticated client is not authorized to use this discovery endpoint. The HTTP status code MUST be 403 (Forbidden).

unsupported_token_type

The authorization server does not support the subject token type indicated by the subject_token_type parameter. The HTTP status code MUST be 400 (Bad Request).

invalid_scope

The request includes an invalid scope parameter. The HTTP status code MUST be 400 (Bad Request).

server_error

The authorization server encountered an unexpected condition that prevented it from fulfilling the request. The HTTP status code MUST be 500 (Internal Server Error).

temporarily_unavailable

The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The HTTP status code MUST be 503 (Service Unavailable).

Error Response Example The following is an example of an error response:

Example This example demonstrates a complete cross-domain identity chaining workflow using the token exchange target service discovery endpoint.

Step 1: Discover Target Services The client begins with a subject access token issued by Domain A and calls the target service discovery endpoint to learn which target services are available.

Discovery Request

Discovery Response From this response, the client learns that it may request a token exchange for the audience https://api.domainB.example with the resources https://api.domainB.example/orders and https://api.domainB.example/inventory and the scopes orders.read and inventory.read. The client also learns that JWT bearer tokens are supported for this target service.

Step 2: Discover Token Types (Optional) If the discovery response does not include supported_token_types, or if the client needs to verify token type support, the client may query the Authorization Server Metadata of Domain B to determine which token types are supported for the target service.

Metadata Request

Metadata Response This confirms that Domain B supports JWT bearer tokens as a requested token type.

Step 3: Perform Token Exchange The client now performs a token exchange with Domain A's token endpoint, requesting a JWT for Domain B using the values discovered in the previous steps.

Token Exchange Request

Token Exchange Response The client now holds a Domain B-scoped JWT token that can be used to access the target service, derived from Domain A's access token through the token exchange process.

Authorization Server Metadata This specification defines the following authorization server metadata parameter to enable clients to discover the token exchange target service discovery endpoint:

token_exchange_target_service_discovery_endpoint

URL of the token exchange target service discovery endpoint. This URL MUST use the https scheme. The authorization server SHOULD publish this metadata value.

The following is a non-normative example of the metadata:

Security Considerations

Subject Token Validation The authorization server MUST validate the subject token provided in the request. The validation process MUST verify that:

• The subject token is valid and not expired
• The subject token type matches the subject_token_type parameter
• The subject token is associated with the authenticated client (if client authentication is required)
• The subject token has not been revoked

If any validation fails, the authorization server MUST return an invalid_request error as described in Section 2.2.

Client Authentication The authorization server SHOULD require client authentication for the discovery endpoint to prevent unauthorized access to authorization information. The authorization server MUST support at least one of the client authentication methods defined in Section 2.3 of . If client authentication is required but not provided, the authorization server MUST return an error response with the error code invalid_client as described in Section 2.2.

Authorization Policy Enforcement The authorization server MUST evaluate both the subject token and the client's permissions when determining which target services to return. The server MUST only return target services that the client is authorized to request in a subsequent token exchange operation. The specific authorization policy evaluation mechanism is implementation-specific and MAY be based on scopes, claims, resource-based access control, attribute-based access control, or other authorization models supported by the authorization server.

Information Disclosure The discovery endpoint reveals information about which target services are available for a given subject token and client. This information could be used by an attacker to enumerate authorization relationships. To mitigate this risk:

• The authorization server SHOULD require client authentication
• The authorization server SHOULD apply rate limiting to prevent enumeration attacks
• The authorization server MAY return different results based on the authenticated client to limit information disclosure
• The authorization server SHOULD log access to the discovery endpoint for security monitoring

Token Confidentiality The subject token is transmitted in the request. The authorization server MUST require the use of TLS as specified in Section 1.6 of to protect the token in transit.

Error Handling The authorization server MUST NOT provide detailed error messages that could aid an attacker in understanding the authorization server's internal state or policies. Error responses SHOULD be generic and not reveal specific information about why a request failed beyond what is necessary for the client to correct the request.

Privacy Considerations The discovery endpoint returns information about authorization relationships between subjects, clients, and target services. This information may be considered privacy-sensitive, as it reveals:

• Which target services a subject is authorized to access
• The scope of permissions available for each target service
• The existence of authorization relationships

To protect privacy:

• The authorization server SHOULD only return information that the authenticated client is authorized to know
• The authorization server SHOULD apply the principle of least privilege when determining which target services to return
• The authorization server SHOULD log access to the discovery endpoint in accordance with applicable privacy regulations
• The authorization server MAY provide mechanisms for subjects to control or limit the information returned by the discovery endpoint

IANA Considerations

OAuth Authorization Server Metadata Registry This specification registers the following value in the IANA "OAuth Authorization Server Metadata" registry established by . Metadata Name: token_exchange_target_service_discovery_endpoint Metadata Description: URL of the token exchange target service discovery endpoint Change Controller: IESG Specification Document(s): [[ this document ]]

References Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document specifies an extension to the OAuth 2.0 Authorization Framework defining request parameters that enable a client to explicitly signal to an authorization server about the identity of the protected resource(s) to which it is requesting access. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References HTTP has been in use by the World-Wide Web global information initiative since 1990. This specification defines the protocol referred to as "HTTP/1.1", and is an update to RFC 2068. [STANDARDS-TRACK] SPIRL SPIRL MITRE NSA-CCSS Ping Identity This specification defines a mechanism to preserve identity and authorization information across trust domains that use the OAuth 2.0 Framework. Discussion Venues This note is to be removed before publishing as an RFC. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Source for this draft and an issue tracker can be found at https://github.com/oauth-wg/oauth-identity-chaining.

Acknowledgments TODO acknowledge.