Resource Indicators for OAuth 2.0Ping Identitybrian.d.campbell@gmail.comYubicove7jtb@ve7jtb.comArm Limitedhannes.tschofenig@gmx.net
Security
OAuth Working GroupOAuthResourceAudience
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.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by
the Internet Engineering Steering Group (IESG). Further
information on Internet Standards is available in Section 2 of
RFC 7841.
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
.
Copyright Notice
Copyright (c) 2020 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
() 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 Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
Table of Contents
. Introduction
. Requirements Notation and Conventions
. Terminology
. Resource Parameter
. Authorization Request
. Access Token Request
. Security Considerations
. Privacy Considerations
. IANA Considerations
. OAuth Parameters Registration
. OAuth Extensions Error Registration
. References
. Normative References
. Informative References
Acknowledgements
Authors' Addresses
Introduction
Several years of deployment and implementation experience with the OAuth 2.0
Authorization Framework
has uncovered a need (in some circumstances, such as an authorization server
servicing a significant number of diverse resources) for the client to
explicitly signal to the authorization server where it intends to use the
access token it is requesting.
Knowing the protected resource (a.k.a. resource server, application, API, etc.) that will process the access token enables the authorization server to construct the token
as necessary for that entity. Properly encrypting the token (or content within the token) to a particular resource, for example,
requires knowing which resource will receive and decrypt the token. Furthermore, various resources oftentimes have
different requirements with respect to the data contained in (or referenced by) the token, and knowing the resource
where the client intends to use the
token allows the authorization server to mint the token accordingly.
Specific knowledge of the intended recipient(s) of the access token also helps facilitate improved
security characteristics of the token itself.
Bearer tokens, currently the most commonly utilized type of OAuth access token,
allow any party in possession of a token to get access to the associated resources.
To prevent misuse, several important security assumptions must hold, one of which is that
an access token must only be valid for use at a
specific protected resource and for a specific scope of access.
, for example,
prescribes including the token's intended recipients within the token to prevent token redirect.
When the authorization server is informed of
the resource that will process the access token, it can restrict the intended audience of that token
to the given resource such that the token cannot be used successfully at other resources.
OAuth scope, from , is sometimes overloaded to convey the location or identity
of the protected resource, however, doing so isn't always feasible or
desirable. Scope is typically about what access is being requested rather
than where that access will be redeemed (e.g., email,
admin:org, user_photos, channels:read, and
channels:write are a small sample of scope values in use in the
wild that convey only the type of access and not the location or identity).
In some circumstances and for some deployments, a means for the client to signal to the authorization server where it
intends to use the access token it's requesting
is important and useful. A number of implementations and deployments of OAuth 2.0 have already employed proprietary parameters
toward that end.
Going forward, this specification aspires to provide a standardized and interoperable alternative to the proprietary approaches.
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.
Terminology
This specification uses the terms "access token", "refresh token",
"authorization server", "resource server", "authorization endpoint",
"authorization request", "authorization response", "token endpoint",
"grant type", "access token request", "access token response", and
"client" defined by The OAuth 2.0 Authorization Framework .
Resource Parameter
In requests to the authorization server, a client MAY
indicate the protected resource (a.k.a. resource server, application,
API, etc.) to which it is requesting access by including the following
parameter in the request.
resource
Indicates the target service or resource to which access is being
requested. Its value MUST be an absolute URI, as
specified by . The URI MUST NOT include a fragment
component. It SHOULD NOT include a query component, but
it is recognized that there are cases that make a query component a
useful and necessary part of the resource parameter, such as when one
or more query parameters are used to scope requests to an application.
The resource parameter URI value is an identifier
representing the identity of the resource, which MAY be
a locator that corresponds to a network-addressable location where the
target resource is hosted. Multiple resource parameters
MAY be used to indicate that the requested token is
intended to be used at multiple resources.
The parameter value identifies a resource to which the client is
requesting access. The parameter can carry the location of a
protected resource, typically as an https URL or a more abstract
identifier. This enables the authorization server to apply policy as
appropriate for the resource, such as determining the type and content
of tokens to be issued, if and how tokens are encrypted, and applying
appropriate audience restrictions.
The client SHOULD provide the most specific URI that it
can for the complete API or set of resources it intends to access.
In practice, a client will know a base URI for the application or resource that it interacts with, which
is appropriate to use as the value of the resource parameter.
The client SHOULD use the base URI of the API as the resource parameter
value unless specific knowledge of the resource dictates otherwise.
For example, the value https://api.example.com/ would be used
for a resource that is the exclusive application on that host; however,
if the resource is one of many applications on that host, something like
https://api.example.com/app/ would be used as a more specific
value.
Another example is when an API has multiple endpoints, e.g., when
System for Cross-domain Identity Management (SCIM) has
endpoints such as https://apps.example.com/scim/Users,
https://apps.example.com/scim/Groups, and
https://apps.example.com/scim/Schemas. The client would use
https://apps.example.com/scim/ as the resource so that the issued
access token is valid for all the endpoints of the SCIM API.
The following 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. It can also be used to inform the client that
it has requested an invalid combination of resource and scope.
invalid_target
The requested resource is invalid, missing, unknown, or malformed.
The authorization server SHOULD audience-restrict
issued access tokens to the resource(s) indicated by the
resource parameter. Audience restrictions can be
communicated in JSON Web Tokens with the aud claim and the top-level
member of the same name provides the audience restriction information
in a Token Introspection response. The authorization server may use
the exact resource value as the audience or it may map from
that value to a more general URI or abstract identifier for the given
resource.
Authorization Request
When the resource parameter is used in an authorization
request to the authorization endpoint, it indicates the identity of
the protected resource(s) to which access is being requested. When an
access token will be returned directly from the authorization endpoint
via the implicit flow (OAuth 2.0), the requested resource is applicable
to that access token. In the code flow (OAuth 2.0) where an
intermediate representation of the authorization grant (the
authorization code) is returned from the authorization endpoint, the
requested resource is applicable to the full authorization grant.
For an authorization request sent as a JSON Web Token (JWT), such as
when using the 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.
If the client omits the resource parameter when requesting
authorization, the authorization server MAY process the
request with no specific resource or by using a predefined default
resource value.
Alternatively, the authorization server MAY require clients to specify the resource(s) they intend to
access and MAY fail requests that omit the parameter with an invalid_target error.
The authorization server might use this data to inform the user about the resources the client
is going to access on their behalf, to apply policy (e.g., refuse the request due to unknown resources),
and to determine the set of resources that can be used in subsequent
access token requests.
If the authorization server fails to parse the
provided value(s) or does not consider the resource(s) acceptable, it should reject the request with
an error response using the error code invalid_target as the value of the
error parameter and can provide additional
information regarding the reasons for the error using the
error_description.
An example of an authorization request where the client tells the authorization server that it wants an access token for use at
https://api.example.com/app/ is shown in below
(extra line breaks and indentation are for display purposes only).
Below in is an example of an authorization request
using the code response type
where the client is requesting access to the resource owner's contacts and calendar data at
https://cal.example.com/ and https://contacts.example.com/
(extra line breaks and indentation are for display purposes only).
Access Token Request
When the resource parameter is used on an access token request made to the token endpoint,
for all grant types, it indicates the target service or protected resource where the client intends to use
the requested access token.
The resource value(s) that is acceptable to an authorization server in fulfilling an access token request is
at its sole discretion based on local policy or configuration. In the case of a
refresh_token or authorization_code grant type request, such policy may limit the acceptable resources
to those that were originally granted by the resource owner
or a subset thereof.
In the authorization_code case where the requested resources
are a subset of the set of resources originally granted, the
authorization server will issue an access token based on that subset of
requested resources, whereas any refresh token that is returned is bound to
the full original grant.
When requesting a token, the client can indicate the desired target
service(s) where it intends to use that token by way of the
resource parameter and can indicate the desired scope of the
requested token using the scope parameter. The semantics of
such a request are that the client is asking for a token with the
requested scope that is usable at all the requested target services.
Effectively, the requested access rights of the token are the cartesian
product of all the scopes at all the target services. To the extent
possible, when issuing access tokens, the authorization server should
downscope the scope value associated with an access token to the value
the respective resource is able to process and needs to know. (Here,
"downscope" means give fewer permissions than originally authorized by
the resource owner.) This
further improves privacy as a list of scope values is an indication that
the resource owner uses the multiple various services listed;
downscoping a token to only that which is needed for a particular
service can limit the extent to which such information is revealed
across different services. As specified in , the authorization server must
indicate the access token's effective scope to the client in the
scope response parameter value when it differs from the scope
requested by the client.
Following from the code flow authorization request shown in ,
the below examples show an authorization_code grant type access token request ()
and response () where the client tells the authorization server that
it wants the access token for use at https://cal.example.com/
(extra line breaks and indentation are for display purposes only).
A subsequent access token request, using the refresh token, where the client tells the authorization server that
it wants an access token for use at
https://contacts.example.com/ is shown in below
with the response shown in
(extra line breaks and indentation are for display purposes only).
Security Considerations
An audience-restricted access token that is legitimately presented to a
resource cannot then be taken by that resource and presented elsewhere
for illegitimate access to other resources.
The resource
parameter enables a client to indicate the protected resources where the requested access
token will be used, which in turn enables the authorization server to apply the
appropriate audience restrictions to the token.
Some servers may host user content or be multi-tenant. In order 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 portion of the URI that identifies the
tenant, such as a path component. This will allow access tokens to be audience-restricted in a way that identifies the tenant
and prevents their use, due to an invalid audience, at resources owned by a different tenant.
Although multiple occurrences of the resource parameter
may be included in a token request, using only a single resource parameter
is encouraged.
If a bearer token has multiple intended recipients
(audiences), then 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.
Thus, a high degree of trust between the involved parties
is needed when using access tokens with multiple audiences. Furthermore, an authorization server may
be unwilling or unable to fulfill a token request with multiple resources.
Whenever feasible, the resource parameter
should correspond to the network-addressable location of the protected resource.
This makes it possible for the client to validate that the resource being requested controls the corresponding
network location, reducing the risk of malicious endpoints obtaining tokens meant for other resources.
If the resource parameter contains an abstract identifier, it is the client's
responsibility to validate out of band that any network endpoint to which tokens are sent are the intended audience for that identifier.
Privacy Considerations
In typical OAuth deployments the authorization sever is in a position to observe and track a significant
amount of user and client behavior. It is largely just inherent to the nature of OAuth, and this document
does little to affect that. In some cases, however, such as when access token introspection is not being
used, use of the resource parameter defined herein may allow for tracking behavior at a somewhat more
granular and specific level than would otherwise be possible in its absence.
IANA ConsiderationsOAuth 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
Change controller:
IESG
Specification document(s):
RFC 8707
OAuth Extensions Error Registration
This specification updates the following error in
the IANA "OAuth Extensions Error Registry"
established by .
Error name:
invalid_target
Error usage location:
implicit grant error response, token error response
Related protocol extension:
resource parameter
Change controller:
IESG
Specification document(s):
RFC 8707
ReferencesNormative ReferencesOAuth ParametersIANAKey words for use in RFCs to Indicate Requirement LevelsIn 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.Uniform Resource Identifier (URI): Generic SyntaxA 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 FrameworkThe 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]Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 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 ReferencesThe OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)The authorization request in OAuth 2.0 described in RFC 6749 utilizes query parameter serialization, which means that Authorization Request parameters are encoded in the URI of the request and sent through user agents such as web browsers. While it is easy to implement, it means that (a) the communication through the user agents are not integrity protected and thus the parameters can be tainted, and (b) the source of the communication is not authenticated. Because of these weaknesses, several attacks to the protocol have now been put forward. This document introduces the ability to send request parameters in a JSON Web Token (JWT) instead, which allows the request to be signed with JSON Web Signature (JWS) and encrypted with JSON Web Encryption (JWE) so that the integrity, source authentication and confidentiality property of the Authorization Request is attained. The request can be sent by value or by reference.Work in ProgressThe OAuth 2.0 Authorization Framework: Bearer Token UsageThis specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK]JSON Web Token (JWT)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.System for Cross-domain Identity Management: ProtocolThe System for Cross-domain Identity Management (SCIM) specification is an HTTP-based protocol that makes managing identities in multi-domain scenarios easier to support via a standardized service. Examples include, but are not limited to, enterprise-to-cloud service providers and inter-cloud scenarios. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. SCIM's intent is to reduce the cost and complexity of user management operations by providing a common user schema, an extension model, and a service protocol defined by this document.OAuth 2.0 Token IntrospectionThis specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.Acknowledgements
This specification was developed within the OAuth Working Group
under the chairmanship of
and with , , and
serving as Security Area Directors. Additionally, the following
individuals contributed ideas, feedback, and wording
that helped shape this specification:,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
and
.
Authors' AddressesPing Identitybrian.d.campbell@gmail.comYubicove7jtb@ve7jtb.comArm Limitedhannes.tschofenig@gmx.net