]> Independent

public@karlmcguinness.com

Keycard Labs

jared@keycard.ai https://keycard.ai

Security Web Authorization Protocol OAuth 2.0 Resource Indicators Authorization Server Token Response Mix-up Attack This specification defines a new parameter, resource, to be returned in OAuth 2.0 access token responses. It enables clients to confirm the intended protected resource (resource server) for the issued token. This mitigates ambiguity and certain classes of security vulnerabilities such as resource mix-up attacks, particularly in systems that use the Resource Indicators for OAuth 2.0 specification . 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 defines a framework in which clients request access tokens from authorization servers and present them to resource servers. In deployments where multiple resources (or APIs) are involved, the Resource Indicators for OAuth 2.0 specification introduced a resource request parameter that allows clients to indicate the protected resource for which the token is intended. However, does not require the authorization server to return any confirmation of the resource to which the access token applies (audience). When an authorization request includes one or more resource parameters, the authorization server can exhibit a range of behaviors depending on its capabilities and policy configuration. An authorization server MAY:

• Ignore the resource parameter (e.g., if it does not support ) and audience-restrict the issued access token to a default resource or set of resources.
• Accept and honor all requested resource values, audience-restricting the issued access token to the entire set of requested resources.
• Accept a subset of the requested resource values, audience-restricting the token accordingly.
• Override the requested resource values and issue a token audience-restricted to an authorization-server-defined set of resources, based on policy or client registration.
• Reject one or more requested resource values and return an OAuth 2.0 error response with the error code invalid_target as defined in .

This leads to ambiguity in the client's interpretation of the token's audience, potentially resulting in resource mix-up attacks or incorrect token usage such as:

1. A client requests an access token for Resource A.
2. The authorization server issues a token for Resource B (intentionally or due to configuration).
3. The client unknowingly sends the token to Resource A, which may mistakenly accept it or return a misleading error.
4. The client misuses a token for a different audience, causing a confidentiality or access control breach.

This document introduces a new parameter, resource, to be returned in the access token response, so the client can validate that the issued token corresponds to the intended resource.

Conventions and Terminology 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.

Terminology The terms "client", "authorization server", "resource server', "access token", "protected resource", "authorization request", "access token request", "access token response" is defined by the OAuth 2.0 Authorization Framework specification . The term "resource" is defined by the Resource Indicators for OAuth 2.0 specification . The term "StringOrURI" is defined by the JWT specification .

Resource Parameter in Token Response

Syntax Authorization servers that support this specification SHOULD include the resource parameter in successful access token responses, as defined in Section 5.1 of for a valid token request. The value of the resource parameter MUST be an array of case-sensitive strings, each containing a StringOrURI value that identifies the protected resource for which the token is valid. In the special case when the token is targeted to a single resource, the resource value MAY be a single case-sensitive string containing a StringOrURI value.

Semantics

• If the client included one or more resource parameters in the request per , the resource value in the response MUST reflect the accepted or selected resource(s).
• If the authorization server selected a default resource, it SHOULD return that selected resource in the resource parameter.
• If the requested resource is not valid for the client, user, or authorization server, then the authorization server SHOULD return an invalid_target OAuth error response code according to
• If the token is not bound to a specific resource or the concept does not apply, the resource parameter SHOULD be omitted.

Client Processing Clients that support this extension:

• SHOULD compare the returned resource URIs against the originally requested resource URI(s), if applicable.
• MUST treat mismatches as errors, unless the client is explicitly designed to handle token audience negotiation.
• MUST NOT use the token with a resource other than the one identified in the response.

Examples

Single Protected Resource

Authorization Request Client makes an authorization request for a protected resource using the URL as the resource indicator

Redirect User successfully authenticates and delegates access to the client for the requested resource and scopes

Token Request

Token Response Resource is confirmed and unambiguous.

Multiple Protected Resources

Authorization Request Client makes an authorization request for multiple protected resources using the URLs as the resource indicators

Redirect User successfully authenticates and delegates access to the client for the requested resource and scopes

Token Request Client exchanges the authorization code for an access token

Token Response Both resources are confirmed and unambiguous.

Default Resource

Authorization Request Client makes an authorization request without a resource indicator

Redirect User successfully authenticates and delegates access to the client for the requested scopes

Token Request

Token Response Default resource is confirmed and unambiguous.

Invalid Resource

Authorization Request

Error Redirect The server rejected the requested resource value (e.g authorization or policy violation, resource is not valid, etc).

Security Considerations The lack of confirmation about the audience of an access token introduces a security risk in OAuth deployments, particularly when:

• A client uses multiple authorization servers and resource servers
• A client dynamically discovers an authorization server and attempts to obtain an access token at runtime via a HTTP authorization challenge with OAuth 2.0 Protected Resource Metadata
• An attacker attempts a mix-up attack where a token intended for one resource is used at another;
• The authorization server ignores or overrides the requested resource without informing the client.

This specification addresses such issues by explicitly returning the resource URI in the token response, similar in spirit to the iss parameter defined in . Clients are advised to:

• Validate the resource parameter when present;
• Avoid use of access tokens with unverified or unintended resources;
• Treat absence of the resource parameter as a potential ambiguity if the client requires strict audience binding.

Privacy Considerations Returning the resource value may reveal some information about the protected resource. If the value is sensitive, the authorization server SHOULD assess whether the resource name can be safely disclosed to the client.

IANA Considerations This document registers the following value in the OAuth Parameters registry established by .

OAuth Access Token Response Parameters Registry

Name	Description	Specification
resource	Resource to which the access token applies	This document

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] 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 or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. 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 document specifies a new parameter called iss. This parameter is used to explicitly include the issuer identifier of the authorization server in the authorization response of an OAuth authorization flow. The iss parameter serves as an effective countermeasure to "mix-up attacks". 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] JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This document describes best current security practice for OAuth 2.0. It updates and extends the threat model and security advice given in RFCs 6749, 6750, and 6819 to incorporate practical experiences gathered since OAuth 2.0 was published and covers new threats relevant due to the broader application of OAuth 2.0. Further, it deprecates some modes of operation that are deemed less secure or even insecure. 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.

Additional Examples

Requesting a token for a dynamically discovered protected resource The following example details the need for the resource parameter when a client dynamically discovers an authorization server and obtains an access token using and Client attempts to access a protected a resource without a valid access token Client is challenged for authentication Client fetches the resource's OAuth 2.0 Protected Resource Metadata per to dynamically discover an authorization server that can issue an access token for the resource. Client discovers the Authorization Server configuration per Client makes an authorization request for the resource User successfully authenticates and delegates access to the client for the requested resource and scopes Client exchanges the authorization code for an access token Client obtains an access token for the resource Client verifies the requested a token explicitly bound to the discovered resource.

Acknowledgments This proposal builds on prior work in OAuth 2.0 extensibility and security analysis, particularly , , and .

Document History -00

• Initial revision