| Internet-Draft | Resource Token Response Parameter | July 2025 |
| McGuinness & Hanson | Expires 20 January 2026 | [Page] |
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]).¶
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.¶
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 (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.¶
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.¶
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.¶
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/" } ```¶
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.¶
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.¶
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:¶
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.¶
This document registers the following value in the OAuth Parameters registry established by [RFC6749].¶
| Name | Description | Specification |
|---|---|---|
| resource | Resource to which the access token applies | This document |
This proposal builds on prior work in OAuth 2.0 extensibility and security analysis, particularly [RFC8707] and [RFC9207].¶
-00¶
Initial revision¶