]> Independent

public@karlmcguinness.com

Okta

aaron@parecki.com https://aaronparecki.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 .

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 . 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. 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 .

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 , that indicates the type of the subject_token parameter. This identifier MUST be a valid URI, and SHOULD be registered in the "OAuth URI Registry" as established by .

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 and extensions. 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 .

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 .
2. The authorization server MUST validate that the subject_token_type parameter is a valid URI. 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 .
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 .
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 .
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 properties that would contain empty strings.

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 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 .

Successful Response If the request is valid and authorized, the authorization server returns a JSON object containing a supported_targets property with an 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 properties:

audience

REQUIRED. A string value containing an absolute URI indicating an available audience value for token exchange, as defined in . 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 property 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 . 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 property 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 , that are available for this target service. Each individual scope value in the list MUST conform to the scope syntax defined in . Empty strings are not supported. If the property is present, the string MUST contain at least one non-empty scope value. If no scopes are available for a target service, this property 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 .

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. 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 property MUST be omitted from the response. If omitted, the client may use any token type supported by the authorization server.

Extensions to this specification MAY define additional properties for the response object or for target service objects. Clients MUST ignore any properties they do not understand. 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 supported_targets array. That is, no two objects in the supported_targets 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 a JSON object with an empty supported_targets array: {"supported_targets": []}.

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 . The response MUST use the application/json media type, and the Content-Type header MUST be set to application/json. In addition to the error codes specified in , the following error codes may be returned:

unsupported_token_type

The authorization server does not support the subject token type indicated by the subject_token_type parameter.

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

Example This example demonstrates a complete cross-domain identity chaining workflow described in with the addition of 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 .

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 . 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 .

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 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. 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 The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document establishes an IETF URN Sub-namespace for use with OAuth-related specifications. This document is not an Internet Standards Track specification; it is published for informational purposes. Defakto Security Defakto Security 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 The authors would like to thank the following individuals who contributed ideas, feedback, and wording that helped shape this specification: Max Gerber

Document History -01

• Changed discovery response to an object for extensibility with supported_targets param
• Updated references

-00

• Initial revision