Web Authorization Protocol K. McGuinness Internet-Draft Independent Intended status: Standards Track J. Hanson Expires: 20 January 2026 Keycard Labs 19 July 2025 OAuth 2.0 Resource Parameter in Access Token Response draft-mcguinness-resource-token-resp-latest Abstract 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 ([RFC8707]). About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://mcguinness.github.io/draft-mcguinness-resource-token-resp/ draft-mcguinness-resource-token-resp.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft- mcguinness-resource-token-resp/. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/. Source for this draft and an issue tracker can be found at https://github.com/mcguinness/draft-mcguinness-resource-token-resp. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 20 January 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction 2. Conventions and Terminology 3. Resource Parameter in Token Response 3.1. Syntax 3.2. Semantics 4. Client Processing 5. Security Considerations 6. Privacy Considerations 7. IANA Considerations 7.1. OAuth Access Token Response Parameters Registry 8. Normative References Acknowledgments Document History Authors' Addresses 1. 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 [RFC8707] specification introduced a resource request parameter that allows clients to indicate the resource server for which the token is intended. However, the current specification does not require the authorization server to return any confirmation of the resource to which the access token applies. 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. This document introduces a new parameter, resource, to be returned in the token response, so the client can validate that the issued token corresponds to the intended resource. 2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Resource Parameter in Token Response 3.1. Syntax Authorization servers that support this specification MAY include the resource parameter in successful access token responses, as defined in Section 5.1 of [RFC6749]. The value of the resource parameter MUST be an absolute URI (as defined in [RFC3986]) that identifies the resource server for which the token is valid. ```json HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "Bearer", "expires_in": 3600, "resource": "https://api.example.com/" } ``` 3.2. Semantics * If the client included one or more resource parameters in the request per [RFC8707], the resource value in the response MUST reflect the accepted or selected resource. * If the authorization server selected a default resource, it SHOULD return that selected resource in the resource parameter. * If the token is not bound to a specific resource or the concept does not apply, the resource parameter SHOULD be omitted. 4. Client Processing Clients that support this extension: * SHOULD compare the returned resource URI 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. 5. 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; * 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 [RFC9207]. 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. 6. 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. 7. IANA Considerations This document registers the following value in the OAuth Parameters registry established by [RFC6749]. 7.1. OAuth Access Token Response Parameters Registry +==========+=======================+===============+ | Name | Description | Specification | +==========+=======================+===============+ | resource | Resource to which the | This document | | | access token applies | | +----------+-----------------------+---------------+ Table 1 8. Normative References [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, . [RFC9728] Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . [RFC9207] Meyer zu Selhausen, K. and D. Fett, "OAuth 2.0 Authorization Server Issuer Identification", RFC 9207, DOI 10.17487/RFC9207, March 2022, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Acknowledgments This proposal builds on prior work in OAuth 2.0 extensibility and security analysis, particularly [RFC8707] and [RFC9207]. Document History -00 * Initial revision Authors' Addresses Karl McGuinness Independent Email: public@karlmcguinness.com Jared Hanson Keycard Labs Email: jared@keycard.ai URI: https://keycard.ai