]> Okta

panva.ip@gmail.com

Security Web Authorization Protocol OAuth Resource Audience This document defines the resource parameter for OAuth 2.0 access token responses, enabling an authorization server to indicate to the client the resource(s) which an issued access token is for. It updates "Resource Indicators for OAuth 2.0" (RFC 8707). 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 "Resource Indicators for OAuth 2.0" defines the resource request parameter for use in authorization requests and access token requests, enabling a client to signal the target protected resource(s) to an authorization server. However, it does not define a corresponding response parameter that would allow the authorization server to communicate back to the client which resource(s) the issued access token is actually for. Without a response parameter, a client cannot reliably determine the effective resource(s) of an issued access token when the authorization server restricts the token to a subset of the requested resources, or when it applies a default resource policy in cases where the client did not include the resource parameter in its request. This document addresses that gap by defining the resource parameter for use in access token responses.

Requirements Notation and Conventions 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.

Access Token Response Resource Parameter In access token responses, the resource parameter is represented as a JSON array of strings, unlike the repeated form-encoded or query parameter used in requests defined in . The resource parameter defined for an access token response () is used to indicate to the client the resource(s) which an issued access token is for.

resource:

OPTIONAL, if identical to the resource value(s) requested by the client; otherwise, REQUIRED. Its value is a JSON array of strings, where each string is an absolute URI as specified by , identifying a protected resource for which the access token is valid. The array MUST contain at least one value.

[[TODO: (#1) Should the response use resource (a JSON string) when a single resource is indicated and resources (a JSON array of strings) when multiple are indicated instead?]] The resource response parameter serves a similar role to the scope response parameter defined in : it informs the client when the resource(s) associated with the issued access token differ from what the client requested. This can occur when the authorization server restricts the token to a subset of the requested resources, or when the authorization server applies a default resource policy in cases where the client did not include the resource parameter in its request. If the client requested access to multiple resources but the authorization server issues an access token that is restricted to a subset of those resources, the authorization server MUST include the resource parameter in the response to inform the client of the effective resource(s). The client can then make additional token requests for the remaining resources as needed.

Scope or Policy Determined Resources In some deployments, certain scope values are inherently associated with specific protected resources. For example, the openid scope in OpenID Connect is tightly coupled to the UserInfo endpoint, and authorization servers may define scope values that are only meaningful at a particular resource. When an authorization server issues an access token for a resource that it determined based on requested scope values or its own default policy, rather than from an explicit resource request parameter, the authorization server SHOULD use the resource's designated Resource Identifier as the resource response parameter value. If no Resource Identifier is defined for the resource, the authorization server SHOULD use the exact URL of the protected resource instead. The value used SHOULD be one that the client can recognize and correlate with the intended protected resource (e.g., the UserInfo endpoint URL for an OpenID Provider when the openid scope is requested). Since such a resource value was not explicitly requested by the client, the resource response parameter is REQUIRED in this case per the condition defined in . The following is a non-normative example of a token endpoint response where the authorization server indicates that the issued access token is valid for use at https://cal.example.com/.

Access Token Response with Resource

The following is a non-normative example of a token endpoint response where the authorization server, acting as an OpenID Provider, issues an access token for the UserInfo endpoint based on the openid scope value that was requested by the client. The authorization server uses the userinfo_endpoint URL from its discovery metadata as the resource value.

Access Token Response with Scope-Determined Resource

Security Considerations This document inherits the security considerations of . Knowledge of the resource(s) for which an access token is valid does not introduce new security concerns for the client. The resource response parameter merely makes explicit information that the client either already requested or that the authorization server determined based on its policy.

Privacy Considerations The resource response parameter conveys information about the resource(s) associated with an access token back to the client. Since the client either requested these resources or they were determined by authorization server policy, no new privacy-sensitive information is disclosed by this parameter.

IANA Considerations

OAuth Parameters Registration This specification updates the following value in the IANA "OAuth Parameters" registry established by .

Parameter name:

resource

Parameter usage location:

authorization request, token request, token response

Change controller:

IETF

Specification document(s):

and of this document

References Normative References 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] 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. IANA 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 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.

Acknowledgments The original "Resource Indicators for OAuth 2.0" specification was authored by Brian Campbell, John Bradley, and Hannes Tschofenig.

Document History draft-skokan-oauth-resource-response-02

• Added guidance on scope or policy determined resource values

draft-skokan-oauth-resource-response-01 draft-skokan-oauth-resource-response-00

• Initial draft defining the resource access token response parameter