draft-ietf-oauth-resource-indicators-00.txt   draft-ietf-oauth-resource-indicators-01.txt 
OAuth Working Group B. Campbell OAuth Working Group B. Campbell
Internet-Draft J. Bradley Internet-Draft Ping Identity
Intended status: Standards Track Ping Identity Intended status: Standards Track J. Bradley
Expires: February 4, 2019 H. Tschofenig Expires: April 22, 2019 Yubico
H. Tschofenig
Arm Limited Arm Limited
August 3, 2018 October 19, 2018
Resource Indicators for OAuth 2.0 Resource Indicators for OAuth 2.0
draft-ietf-oauth-resource-indicators-00 draft-ietf-oauth-resource-indicators-01
Abstract Abstract
This straw-man specification defines an extension to The OAuth 2.0 An extension to the OAuth 2.0 Authorization Framework defining
Authorization Framework that enables the client and authorization request parameters that enable a client to explicitly signal to an
server to more explicitly to communicate about the protected authorization server about the location of the protected resource(s)
resource(s) to be accessed. to which it is requesting access.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 4, 2019. This Internet-Draft will expire on April 22, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 13 skipping to change at page 2, line 13
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.1. Requirements Notation and Conventions . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Resource Parameter . . . . . . . . . . . . . . . . . . . . . 3 2. Resource Parameter . . . . . . . . . . . . . . . . . . . . . 3
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 2.1. Authorization Request . . . . . . . . . . . . . . . . . . 5
3.1. OAuth Parameters Registration . . . . . . . . . . . . . . 5 2.2. Access Token Request . . . . . . . . . . . . . . . . . . 6
3.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 5 3. Security Considerations . . . . . . . . . . . . . . . . . . . 9
3.2. OAuth Extensions Error Registration . . . . . . . . . . . 6 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
3.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 4.1. OAuth Parameters Registration . . . . . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 4.2. OAuth Extensions Error Registration . . . . . . . . . . . 10
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. Normative References . . . . . . . . . . . . . . . . . . 7 5.1. Normative References . . . . . . . . . . . . . . . . . . 10
5.2. Informative References . . . . . . . . . . . . . . . . . 7 5.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11
Appendix B. Document History . . . . . . . . . . . . . . . . . . 8 Appendix B. Document History . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
Several years of deployment and implementation experience with OAuth Several years of deployment and implementation experience with The
2.0 [RFC6749] has uncovered a need, in some circumstances, for the OAuth 2.0 Authorization Framework [RFC6749] has uncovered a need, in
client to explicitly signal to the authorization sever where it some circumstances, for the client to explicitly signal to the
intends to use the access token it is requesting. authorization server where it intends to use the access token it is
requesting.
Knowing which resource server will process the access token enables Knowing the protected resource (a.k.a. resource server, application,
the authorization server to construct the token as necessary for that 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) entity. Properly encrypting the token (or content within the token)
to a particular resource server, for example, requires knowing which to a particular resource, for example, requires knowing which
resource server will receive and decrypt the token. Furthermore, resource will receive and decrypt the token. Furthermore, various
various resource servers oftentimes have different requirements with resources oftentimes have different requirements with respect to the
respect to the data contained in, or referenced by, the token and data contained in, or referenced by, the token and knowing the
knowing the resource server where the client intends to use the s resource where the client intends to use the token allows the the
token allows the the authorization server to mint the token authorization server to mint the token accordingly.
accordingly.
Specific knowledge of the intended recipient(s) of the access token Specific knowledge of the intended recipient(s) of the access token
also helps facilitate improved security characteristics of the token also helps facilitate improved security characteristics of the token
itself. Bearer tokens, currently the only defined type of OAuth itself. Bearer tokens, currently the most commonly utilized type of
access token, allow any party in possession of a token to get access OAuth access token, allow any party in possession of a token to get
to the associated resources. To prevent misuse, two important access to the associated resources. To prevent misuse, several
security assumptions must hold: bearer tokens must be protected from important security assumptions must hold, one of which is that an
disclosure in storage and in transit and the access token must only access token must only be valid for use at a specific protected
be valid for use at a specific resource server and for a specific resource and for a specific scope of access. Section 5.2 of
scope. When the authorization server is informed of the resource [RFC6750], for example, prescribes including the token's intended
server that will process the access token, it can restrict the recipients within the token to prevent token redirect. When the
intended audience of that token such that it cannot be used at other authorization server is informed of the resource that will process
resource servers. Section 5.2 of OAuth 2.0 Authorization Framework: the access token, it can restrict the intended audience of that token
Bearer Token Usage [RFC6750] prescribes including the token's to the given resource such that the token cannot be used successfully
intended recipients within the token to prevent token redirect. at other resources.
Scope, from Section 3.3 of OAuth 2.0 [RFC6749], sometimes is OAuth scope, from Section 3.3 of [RFC6749], is sometimes overloaded
overloaded to convey the location or identity of the resource server, to convey the location or identity of the protected resource,
however, doing so isn't always feasible or desirable. Scope is however, doing so isn't always feasible or desirable. Scope is
typically about what access is being requested rather than where that typically about what access is being requested rather than where that
access will be redeemed (e.g. "email", "user:follow", "user_photos", access will be redeemed (e.g. "email", "admin:org", "user_photos",
and "channels:read" are a small sample of scope values in use). "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).
A means for the client to signal to the authorization sever where it In some circumstances and for some deployments, a means for the
intends to use the access token it's requesting is important and client to signal to the authorization server where it intends to use
useful. A number of implementations and deployments of OAuth 2.0 the access token it's requesting is important and useful. A number
have already employed proprietary parameters toward that end. This of implementations and deployments of OAuth 2.0 have already employed
specification aims to provide a standardized and interoperable proprietary parameters toward that end. Going forward, this
alternative to the proprietary approaches going forward. specification aspires to provide a standardized and interoperable
alternative to the proprietary approaches.
1.1. Requirements Notation and Conventions 1.1. Requirements Notation and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC "OPTIONAL" in this document are to be interpreted as described in BCP
2119 [RFC2119]. 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
1.2. Terminology 1.2. Terminology
This specification uses the terms "access token", "refresh token", This specification uses the terms "access token", "refresh token",
"authorization server", "resource server", "authorization endpoint", "authorization server", "resource server", "authorization endpoint",
"authorization request", "authorization response", "token endpoint", "authorization request", "authorization response", "token endpoint",
"grant type", "access token request", "access token response", and "grant type", "access token request", "access token response", and
"client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. "client" defined by The OAuth 2.0 Authorization Framework [RFC6749].
2. Resource Parameter 2. Resource Parameter
The client may indicate the resource server(s) for which it is In requests to the authorization server, a client MAY indicate the
requesting an access token by including the following parameter in protected resource (a.k.a. resource server, application, API, etc.)
the request. to which it is requesting access by including the following parameter
in the request.
resource resource
OPTIONAL. The value of the "resource" parameter indicates a Indicates the location of the target service or resource where
resource server where the requested access token will be used. It access is being requested. Its value MUST be an absolute URI, as
MUST be an absolute URI, as specified by Section 4.3 of[RFC3986], specified by Section 4.3 of [RFC3986], which MAY include a query
and MUST NOT include a query or fragment component. If the component but MUST NOT include a fragment component. Multiple
authorization server fails to parse the provided value or does not "resource" parameters MAY be used to indicate that the requested
consider the resource server acceptable, it MUST reject the token is intended to be used at multiple resources.
request and provide an error response with the error code
"invalid_resource". Multiple "resource" parameters may be used to
indicate that the issued token is intended to be used at multiple
resource servers.
When an access token will be returned from the authorization The parameter value indicates the location of a protected resource,
endpoint, the "resource" parameter is used in the authorization typically as an https URL, where the client is requesting access.
request to the authorization endpoint as defined in Section 4.2.1 of This enables the authorization server to apply policy as appropriate
OAuth 2.0 [RFC6749]. An example of an authorization request where for the resource, such as determining the type and content of tokens
the client tells the authorization server that it wants a token for to be issued, if and how tokens are encrypted, and applying
use at "https://rs.example.com/" is shown in Figure 1 below. 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. And 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, 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
resource.
2.1. Authorization Request
When the "resource" parameter is used in an authorization request to
the authorization endpoint, it indicates the location 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]),
the requested resource is applicable to that access token. In the
code flow (Section 4.1 of OAuth 2.0 [RFC6749]) where an 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 authorization requests sent as a JWTs, such as when using JWT
Secured Authorization Request [I-D.ietf-oauth-jwsreq], 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 meet policy
decision (e.g. refuse the request due to unknown resources), and
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 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" and/or "error_uri" parameters.
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 GET /as/authorization.oauth2?response_type=token
&client_id=s6BhdRkqt3&state=laeb &client_id=example-client
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &state=XzZaJlcwYew1u0QBrRv_Gw
&resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb
&resource=https%3A%2F%2Fapi.example.com%2Fapp%2F HTTP/1.1
Host: authorization-server.example.com Host: authorization-server.example.com
Figure 1: Protected Resource Request Figure 1: Implicit Flow Authorization Request
When the access token is returned from the token endpoint, the Below in Figure 2 is an example of an authorization request using the
request parameter is included in the token request to the token "code" response type where the the client is requesting access to the
endpoint. Sections 4.1.1, 4.3.1, 4.4.2, 4.5 and 6 of OAuth 2.0 resource owner's contacts and calendar data at
[RFC6749] define requests to the token endpoint with different grant "https://cal.example.com/" and "https://contacts.example.com/" (extra
types. An example of a token request, using a refresh token, where line breaks and indentation are for display purposes only).
the client tells the authorization server that it wants a token for
use at "https://rs.example.com/" is shown in Figure 2 below. GET /as/authorization.oauth2?response_type=code
&client_id=s6BhdRkqt3
&state=tNwzQ87pC6llebpmac_IDeeq-mCR2wLDYljHUZUAWuI
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb
&scope=calendar%20contacts
&resource=https%3A%2F%2Fcal.example.com%2F
&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 location
of 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 adapt 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 scope values give an
indication of what services the resource owner uses and it improves
security as scope values may contain confidential data. 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 client.
Following from the code flow authorization request shown in Figure 2,
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).
POST /as/token.oauth2 HTTP/1.1
Host: authorization-server.example.com
Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb
&code=10esc29BWC2qZB0acc9v8zAv9ltc2pko105tQauZ
&resource=https%3A%2F%2Fcal.example.com%2F
Figure 3: Access Token Request
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6Ijc3In0.eyJpc3MiOi
JodHRwOi8vYXV0aG9yaXphdGlvbi1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWI
iOiJfX2JfYyIsImV4cCI6MTU4ODQyMDgwMCwic2NvcGUiOiJjYWxlbmRhciIs
ImF1ZCI6Imh0dHBzOi8vY2FsLmV4YW1wbGUuY29tLyJ9.nNWJ2dXSxaDRdMUK
lzs-cYIj8MDoM6Gy7pf_sKrLGsAFf1C2bDhB60DQfW1DZL5npdko1_Mmk5sUf
zkiQNVpYw",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"4LTC8lb0acc6Oy4esc1Nk9BWC0imAwH7kic16BDC2",
"scope":"calendar"
}
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 POST /as/token.oauth2 HTTP/1.1
Host: authorization-server.example.com Host: authorization-server.example.com
Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token grant_type=refresh_token
&refresh_token=4LTC8lb0acc6Oy4esc1Nk9BWC0imAwH &refresh_token=4LTC8lb0acc6Oy4esc1Nk9BWC0imAwH7kic16BDC2
&resource=https%3A%2F%2Frs.example.com%2F &resource=https%3A%2F%2Fcontacts.example.com%2Fapp%2F
Figure 2: Protected Resource Request Figure 5: Access Token Request
The "resource" parameter indicates the physical location of resource HTTP/1.1 200 OK
server, typically as an https URL, where the client intends to use Content-Type: application/json
the requested access token. This enables the authorization server to Cache-Control: no-cache, no-store
apply policy as appropriate for the resource, such as determining the
type and content of the token to be issued, if and how the token is
to be encrypted, and applying appropriate audience restrictions to
the token.
The client SHOULD provide the most specific URI that it can for the {
set of resources or API it intends to access. In practice a client "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6Ijc3In0.eyJpc3MiOi
will know a base URI for the resource server application that it JodHRwOi8vYXV0aG9yaXphdGlvbi1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWI
interacts with, which is appropriate to use as the value of the iOiJfX2JfYyIsImV4cCI6MTU4ODQyMDgyNiwic2NvcGUiOiJjb250YWN0cyIs
"resource" parameter. The client SHOULD use the base URI for the API ImF1ZCI6Imh0dHBzOi8vY29udGFjdHMuZXhhbXBsZS5jb20vIn0.5f4yhqazc
unless specific knowledge of resource server dictates the client use OSlJw4y94KPeWNEFQqj2cfeO8x4hr3YbHtIl3nQXnBMw5wREY5O1YbZED-GfH
a shorter path. For example, the value "https://rs.example.com/" UowfmtNaA5EikYAw",
would be used for a resource server that is the exclusive application "token_type":"Bearer",
on that host, however, if the resource server is one of many "expires_in":3600,
applications on that host, something like "https://rs.example.com/ "scope":"contacts"
application/" would be used. Another example, for an API like SCIM }
[RFC7644] that has multiple endpoints such as
"https://rs.example.com/scim/Users", "https://rs.example.com/scim/
Groups", and "https://rs.example.com/scim/Schemas" The client should
use "https://rs.example.com/scim/" as the resource so that the issued
access token is valid for all the endpoints of the SCIM API.
The authorization server SHOULD audience restrict the access token to Figure 6: Access Token Response
the resource server(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 resource
server.
The requested resource pertains to the access token that is the 3. Security Considerations
expected result of the request and not to the underlying access
granted by the resource owner.
3. IANA Considerations An access token that is audience restricted to a protected resource
that obtains that token legitimately cannot be used to access
resources on behalf of the resource owner at other protected
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.
3.1. OAuth Parameters Registration Some servers may host user content or be multi-tenant. In order to
avoid attacks that might confuse a client into sending an access
token to a resource that is user controlled or is owned by a
different tenant, it is important to use a specific resource URI
including a path component. This will cause any access token issued
for accessing the user controlled resource to have a invalid audience
if replayed against the legitimate resource API.
Although multiple occurrences of the "resource" parameter may be
included in a request, using only a single "resource" parameter is
encouraged. A bearer token that has multiple intended recipients
(audiences) can be used by any one of those recipients at any other.
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.
4. IANA Considerations
4.1. OAuth Parameters Registration
This specification registers the following value in the IANA "OAuth This specification registers the following value in the IANA "OAuth
Parameters" registry [IANA.OAuth.Parameters] established by Parameters" registry [IANA.OAuth.Parameters] established by
[RFC6749]. [RFC6749].
3.1.1. Registry Contents
o Parameter name: resource o Parameter name: resource
o Parameter usage location: authorization request, token request o Parameter usage location: authorization request, token request
[[TODO: draft-ietf-oauth-token-exchange will have already
registered this for 'token request' and this draft has a more
generalized usage and needs to somehow either update that
registration or do a partial registration and reference]]
o Change controller: IESG o Change controller: IESG
o Specification document(s): Section 2 of [[ this specification ]] o Specification document(s): [[ this specification ]]
3.2. OAuth Extensions Error Registration 4.2. OAuth Extensions Error Registration
This specification registers the following error in the IANA "OAuth This specification registers the following error in the IANA "OAuth
Extensions Error Registry" [IANA.OAuth.Parameters] established by Extensions Error Registry" [IANA.OAuth.Parameters] established by
[RFC6749]. [RFC6749].
3.2.1. Registry Contents o Error name: invalid_target
o Error name: invalid_resource
o Error usage location: implicit grant error response, token error o Error usage location: implicit grant error response, token error
response response [[TODO: draft-ietf-oauth-token-exchange will have already
registered this for 'token error response' and this draft has a
more generalized usage and needs to somehow either update that
registration or do a partial registration and reference]]
o Related protocol extension: resource parameter o Related protocol extension: resource parameter
o Change controller: IESG o Change controller: IESG
o Specification document(s): Section 2 of [[ this specification ]] o Specification document(s): [[ this specification ]]
4. Security Considerations
An access token that is audience restricted to a resource server,
which obtains the token legitimately, cannot be used to access
resources on behalf of the resource owner at other resource servers.
The "resource" parameter enables a client to indicate the resource
server 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 Resource servers may host user content or be multi-tenant. In
order to avoid attacks that might confuse a client into sending a AT
to a user controlled resource it is important to use the a specific
resource URI including path and not use just a host with no path.
This will cause any AT issued for accessing the user controlled
resource to have a invalid audience if replayed against the
legitimate resource API.
Although multiple occurrences of the "resource" parameter may be
included in a request, using only a single "resource" parameter is
encouraged. A bearer token that has multiple intended recipients
(audiences) can be used by any one of those recipients at any other.
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.
[[TODO: I continue to question the value of allowing multiple
resources vs the functional and security complexity that comes with
doing so. Writing the preceding paragraph just underscores that
concern. So just noting it here.]]
5. References 5. References
5.1. Normative References 5.1. Normative References
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
<http://www.iana.org/assignments/oauth-parameters>. <http://www.iana.org/assignments/oauth-parameters>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
skipping to change at page 7, line 27 skipping to change at page 11, line 14
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[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>.
5.2. Informative References 5.2. Informative References
[I-D.draft-tschofenig-oauth-audience] [I-D.ietf-oauth-jwsreq]
Tschofenig, H., "OAuth 2.0: Audience Information", draft- Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization
tschofenig-oauth-audience (work in progress), February Framework: JWT Secured Authorization Request (JAR)",
2013. draft-ietf-oauth-jwsreq-16 (work in progress), April 2018.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012, DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>. <https://www.rfc-editor.org/info/rfc6750>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
skipping to change at page 8, line 7 skipping to change at page 11, line 45
and C. Mortimore, "System for Cross-domain Identity and C. Mortimore, "System for Cross-domain Identity
Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, Management: Protocol", RFC 7644, DOI 10.17487/RFC7644,
September 2015, <https://www.rfc-editor.org/info/rfc7644>. September 2015, <https://www.rfc-editor.org/info/rfc7644>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015, RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/info/rfc7662>. <https://www.rfc-editor.org/info/rfc7662>.
Appendix A. Acknowledgements Appendix A. Acknowledgements
The following individuals contributed to discussions relating to and This specification was developed within the OAuth Working Group under
giving rise to this draft specification: the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with
Eric Rescorla and Benjamin Kaduk serving as Security Area Directors.
Additionally, the following individuals contributed ideas, feedback,
and wording that helped shape this specification:
George Fletcher, Hans Zandbelt, Justin Richer, Michael Jones, Nat Sergey Beryozkin, William Denniss, Vladimir Dzhuvinov, George
Sakimura, Phil Hunt, Sergey Beryozkin, and Anthony "no go" Nadalin. Fletcher, Dick Hardt, Phil Hunt, Michael Jones, Torsten Lodderstedt,
Anthony Nadalin, Justin Richer, Nat Sakimura, Filip Skokan, and Hans
Zandbelt.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-00 draft-ietf-oauth-resource-indicators-01
o 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.
o Change the "invalid_resource" error to "invalid_target" to align
with draft-ietf-oauth-token-exchange, which has some overlap in
functionality.
o Allow the "resource" parameter value to have a query component
(aligning with draft-ietf-oauth-token-exchange).
o Moved the Security Considerations section to before the IANA
Considerations.
o Other editorial updates.
o Rework the Acknowledgements section.
o Use RFC 8174 boilerplate.
draft-ietf-oauth-resource-indicators-00
o First version of the working group document. A replica of draft- o First version of the working group document. A replica of draft-
campbell-oauth-resource-indicators-02. campbell-oauth-resource-indicators-02.
draft-campbell-oauth-resource-indicators-02
o No changes.
draft-campbell-oauth-resource-indicators-01
o Move Hannes Tschofenig, who wrote https://tools.ietf.org/html/
draft-tschofenig-oauth-audience in '13, from Acknowledgements to
Authors.
o Added IANA Considerations to register the "resource" parameter and
"invalid_resource" error code.
draft-campbell-oauth-resource-indicators-00
o Initial draft to define a resource parameter for OAuth 2.0.
Authors' Addresses Authors' Addresses
Brian Campbell Brian Campbell
Ping Identity Ping Identity
Email: brian.d.campbell@gmail.com Email: brian.d.campbell@gmail.com
John Bradley John Bradley
Ping Identity Yubico
Email: ve7jtb@ve7jtb.com Email: ve7jtb@ve7jtb.com
Hannes Tschofenig Hannes Tschofenig
Arm Limited Arm Limited
Email: hannes.tschofenig@gmx.net Email: hannes.tschofenig@gmx.net
 End of changes. 42 change blocks. 
180 lines changed or deleted 372 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/