Resource Indicators for OAuth 2.0
Extracted elements (24)
Downscoping access tokens to only what is needed for a particular service limits the extent to which user behavior information (the list of services a resource owner uses) is revealed across different services, improving privacy.
Knowing the intended recipient(s) of the access token enables the authorization server to restrict the token's audience so that it cannot be successfully used at other resources, addressing the token redirect attack vector described in RFC 6750 Section 5.2.
OAuth scope is sometimes overloaded to convey the location or identity of the protected resource, but doing so isn't always feasible or desirable — scope values typically convey only the type of access (e.g., 'email', 'channels:read'), not the location. This extension provides a dedicated parameter for resource identity to separate these concerns.
The semantics of requesting a token with both 'resource' and 'scope' parameters are that the client is asking for a token with the requested scope that is usable at all the requested target services — effectively the cartesian product of all scopes at all target services.
This specification provides a standardized and interoperable alternative to proprietary parameters that a number of existing OAuth 2.0 implementations and deployments already employ to signal resource identity to authorization servers.
For refresh_token or authorization_code grant type requests, the authorization server policy may limit acceptable resources to those originally granted or a subset thereof. When a subset is requested, the issued access token is scoped to that subset while any refresh token returned is bound to the full original grant.
If the client omits the 'resource' parameter when requesting authorization, the authorization server MAY process the request with no specific resource or using a predefined default resource value, or MAY require clients to specify resources and fail requests that omit the parameter with an 'invalid_target' error.
The authorization server SHOULD audience-restrict issued access tokens to the resource(s) indicated by the 'resource' parameter. Audience restrictions can be communicated in JWTs via the 'aud' claim.
The client SHOULD provide the most specific URI it can for the complete API or set of resources it intends to access, and SHOULD use the base URI of the API as the 'resource' parameter value unless specific knowledge of the resource dictates otherwise.
The 'resource' parameter URI SHOULD NOT include a query component, though query parameters are recognized as useful and necessary in some cases for scoping requests to an application.
The 'resource' parameter URI value MUST be an absolute URI as specified by Section 4.3 of RFC 3986, and the URI MUST NOT include a fragment component.
To the extent possible, when issuing access tokens, the authorization server should downscope the scope value to what the respective resource is able to process and needs to know. As specified in RFC 6749 Section 5.1, the authorization server must indicate the access token's effective scope when it differs from the scope requested.
When the 'resource' parameter is used in an authorization request for the code flow, the requested resource is applicable to the full authorization grant, not just the access token returned from the authorization endpoint.
When the 'resource' parameter is used on an access token request for all grant types, it indicates the target service or protected resource where the client intends to use the requested access token. The acceptable resource values are at the authorization server's sole discretion.
In some cases, such as when access token introspection is not being used, use of the 'resource' parameter may allow tracking client and user behavior at a more granular and specific level than would otherwise be possible without it, as the resource URI reveals the specific services accessed.
For an authorization request sent as a JWT (e.g., JWT Secured Authorization Request), a single 'resource' parameter value is represented as a JSON string while multiple values are represented as an array of strings.
The 'invalid_target' error code is provided for an authorization server to indicate problems with the requested resource(s) in response to an authorization request or access token request, and can also be used to inform the client that it has requested an invalid combination of resource and scope.
The 'resource' parameter indicates the target service or resource to which access is being requested. Its value MUST be an absolute URI per RFC 3986, MUST NOT include a fragment component, and SHOULD NOT include a query component. Multiple 'resource' parameters MAY be used to indicate that the requested token is intended to be used at multiple resources.
This specification registers the 'invalid_target' error code in the IANA 'OAuth Extensions Error Registry', for use in implicit grant error responses and token error responses, related to the resource parameter extension.
This specification registers the 'resource' parameter in the IANA 'OAuth Parameters' registry (established by RFC 6749), for use in authorization requests and token requests, with IESG as change controller.
An audience-restricted access token legitimately presented to a resource cannot be taken by that resource and presented elsewhere for illegitimate access to other resources. The 'resource' parameter enables the authorization server to apply appropriate audience restrictions to prevent this token redirect attack.
For multi-tenant servers, to avoid attacks where one tenant uses an access token to illegitimately access resources owned by a different tenant, it is important to use a specific resource URI including any path component that identifies the tenant, allowing audience restrictions to identify the tenant and prevent cross-tenant misuse.
Using only a single 'resource' parameter is encouraged. If a bearer token has multiple intended recipients (audiences), the token is valid at more than one protected resource and can be used by any one of those resources to access any of the others, requiring a high degree of trust between involved parties.
Whenever feasible, the 'resource' parameter should correspond to the network-addressable location of the protected resource, enabling the client to validate that the resource being requested controls that network location. If using an abstract identifier, the client is responsible for out-of-band validation that network endpoints receiving tokens are the intended audience.