OAuth Working Group

Internet Engineering Task Force (IETF)                       B. Campbell
Request for Comments: 0000                                 Ping Identity
Intended status:
Category: Standards Track                                     J. Bradley
Expires: March 14, 2020
ISSN: 2070-1721                                                   Yubico
                                                           H. Tschofenig
                                                             Arm Limited
                                                      September 11,
                                                            October 2019

                   Resource Indicators for OAuth 2.0


   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 Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list  It represents the consensus of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid the IETF community.  It has
   received public review and has been approved for a maximum publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of six months RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be updated, replaced, or obsoleted by other documents obtained 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 March 14, 2020.

Copyright Notice

   Copyright (c) 2019 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 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

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Notation and Conventions . . . . . . . . . .   3
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Resource Parameter  . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Authorization Request . . . . . . . . . . . . . . . . . .   5
     2.2.  Access Token Request  . . . . . . . . . . . . . . . . . .   6
   3.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   4.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  10
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
     5.1.  OAuth Parameters Registration . . . . . . . . . . . . . .  10
     5.2.  OAuth Extensions Error Registration . . . . . . . . . . .  10
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .  11
     6.2.  Informative References  . . . . . . . . . . . . . . . . .  11
   Appendix A.
   Acknowledgements . . . . . . . . . . . . . . . . . .  12
   Appendix B.  Document History . . . . . . . . . . . . . . . . . .  12
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  14

1.  Introduction

   Several years of deployment and implementation experience with the
   OAuth 2.0 Authorization Framework [RFC6749] 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. (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.  Section 5.2 of
   [RFC6750], 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 Section 3.3 of [RFC6749], 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.

1.1.  Requirements Notation and Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "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.

1.2.  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 [RFC6749].

2.  Resource Parameter

   In requests to the authorization server, a client MAY indicate the
   protected resource (a.k.a. (a.k.a., resource server, application, API, etc.)
   to which it is requesting access by including the following parameter
   in the request.

      Indicates the target service or resource to which access is being
      requested.  Its value MUST be an absolute URI, as specified by
      Section 4.3 of [RFC3986].  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
      query parameter(s) 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, for an API like SCIM [RFC7644] that has
   multiple 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.

      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
   [RFC7519] with the "aud" claim and the top-level member of the same
   name provides the audience restriction information in a Token
   Introspection [RFC7662] 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

2.1.  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 (Section 4.2 of OAuth 2.0 [RFC6749]), [OAuth 2.0]), the
   requested resource is applicable to that access token.  In the code
   flow (Section 4.1 of OAuth 2.0 [RFC6749]) [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 JWT Secured Authorization Request [I-D.ietf-oauth-jwsreq], [JWT-SAR], 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 pre-defined 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 her 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

   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 Figure 1 below (extra line
   breaks and indentation are for display purposes only).

     GET /as/authorization.oauth2?response_type=token
        &resource=https%3A%2F%2Fapi.example.com%2Fapp%2F HTTP/1.1
     Host: authorization-server.example.com

               Figure 1: Implicit Flow Authorization Request

   Below in Figure 2 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).

     GET /as/authorization.oauth2?response_type=code
        &resource=https%3A%2F%2Fcontacts.example.com%2F HTTP/1.1
     Host: authorization-server.example.com

                 Figure 2: Code Flow Authorization Request

2.2.  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 are acceptable to an authorization server
   in fulfilling an access token request are 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 while 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.  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
   Section 5.1 of [RFC6749], 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

   Following from the code flow authorization request shown in Figure 2,
   the below examples show an "authorization_code" grant type access
   token request (Figure 3) and response (Figure 4) 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).

     POST /as/token.oauth2 HTTP/1.1
     Host: authorization-server.example.com
     Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ
     Content-Type: application/x-www-form-urlencoded


                       Figure 3: Access Token Request

      HTTP/1.1 200 OK
      Content-Type: application/json
      Cache-Control: no-cache, no-store


                      Figure 4: Access Token Response

   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 Figure 5 below
   with the response shown in Figure 6 (extra line breaks and
   indentation are for display purposes only).

     POST /as/token.oauth2 HTTP/1.1
     Host: authorization-server.example.com
     Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ
     Content-Type: application/x-www-form-urlencoded


                       Figure 5: Access Token Request

      HTTP/1.1 200 OK
      Content-Type: application/json
      Cache-Control: no-cache, no-store


                      Figure 6: Access Token Response

3.  Security Considerations

   An audience-restricted access token, 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 prevent 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.  A bearer token that has multiple intended recipients
   (audiences) indicating that the token is valid at more than one
   protected resource can be used by any one of those protected
   resources to access any of the other protected resources.  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.

4.  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.

5.  IANA Considerations

5.1.  OAuth Parameters Registration

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


   *  Parameter name: resource
   *  Parameter usage location: authorization request, token request
   *  Change controller: IESG
   *  Specification document(s): [[ this specification ]] RFC 0000

5.2.  OAuth Extensions Error Registration

   This specification updates the following error in the IANA "OAuth
   Extensions Error Registry" [IANA.OAuth.Parameters] established by


   *  Error name: invalid_target
   *  Error usage location: implicit grant error response, token error
   *  Related protocol extension: resource parameter
   *  Change controller: IESG
   *  Specification document(s): [[ this specification ]] RFC 0000

6.  References

6.1.  Normative References

              IANA, "OAuth Parameters",

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,

   [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,

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

6.2.  Informative References


   [JWT-SAR]  Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization
              Framework: JWT Secured Authorization Request (JAR)",
              draft-ietf-oauth-jwsreq-19 (work Work
              in progress), Progress, Internet-Draft, draft-ietf-oauth-jwsreq-19,
              10 June 2019. 2019,

   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750,
              DOI 10.17487/RFC6750, October 2012,

   [RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,

   [RFC7644]  Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E.,
              and C. Mortimore, "System for Cross-domain Identity
              Management: Protocol", RFC 7644, DOI 10.17487/RFC7644,
              September 2015, <https://www.rfc-editor.org/info/rfc7644>.

   [RFC7662]  Richer, J., Ed., "OAuth 2.0 Token Introspection",
              RFC 7662, DOI 10.17487/RFC7662, October 2015,

Appendix A.


   This specification was developed within the OAuth Working Group under
   the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with
   Eric Rescorla, Benjamin Kaduk and Roman Danyliw serving as Security
   Area Directors.  Additionally, the following individuals contributed
   ideas, feedback, and wording that helped shape this specification:

   Vittorio Bertocci, Sergey Beryozkin, Roman Danyliw, William Denniss,
   Vladimir Dzhuvinov, George Fletcher, Dick Hardt, Phil Hunt, Michael
   Jones, Benjamin Kaduk, Barry Leiba, Torsten Lodderstedt, Anthony
   Nadalin, Justin Richer, Adam Roach, Nat Sakimura, Rifaat Shekh-Yusef,
   Filip Skokan, Eric Vyncke, and Hans Zandbelt.

Appendix B.  Document History

   [[ to be removed by the RFC Editor before publication as an RFC ]]



   *  One last update from IESG evaluation comments



   *  One more update from IESG evaluation comments



   *  Expand JWT acronym on first use per Genart last call review.
   *  Updates from IESG evaluation comments.



   *  Remove specific mention of error_uri, which is rarely (if ever)
      used and seems to only confuse things for readers of extensions
      like this one.



   *  Editorial updates from AD review that were overlooked in -03.



   *  Editorial updates from AD review.
   *  Update draft-ietf-oauth-jwsreq ref to -19.
   *  Update the IANA requests to say they update the registries.



   *  Clarify that the value of the "resource" parameter is a URI which
      can be an abstract identifier for the target resource and doesn't
      necessarily have to correspond to a network addressable location.



   *  Significant rework of the main section of the document attempting
      to clarify a number of things that came up at, around and after
      IETF 102 and the call for adoption.
   *  Change the "invalid_resource" error to "invalid_target" to align
      with draft-ietf-oauth-token-exchange, which has some overlap in
   *  Allow the "resource" parameter value to have a query component
      (aligning with draft-ietf-oauth-token-exchange).
   *  Moved the Security Considerations section to before the IANA
   *  Other editorial updates.
   *  Rework the Acknowledgements section.
   *  Use RFC 8174 boilerplate.



   *  First version of the working group document.  A replica of draft-



   *  No changes.



   *  Move Hannes Tschofenig, who wrote https://tools.ietf.org/html/
      draft-tschofenig-oauth-audience in '13, from Acknowledgements to
   *  Added IANA Considerations to register the "resource" parameter and
      "invalid_resource" error code.



   *  Initial draft to define a resource parameter for OAuth 2.0.

Authors' Addresses

   Brian Campbell
   Ping Identity

   Email: brian.d.campbell@gmail.com

   John Bradley

   Email: ve7jtb@ve7jtb.com

   Hannes Tschofenig
   Arm Limited

   Email: hannes.tschofenig@gmx.net