< draft-ietf-oauth-resource-indicators-01.txt   draft-ietf-oauth-resource-indicators-02.txt >
OAuth Working Group B. Campbell OAuth Working Group B. Campbell
Internet-Draft Ping Identity Internet-Draft Ping Identity
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: April 22, 2019 Yubico Expires: August 1, 2019 Yubico
H. Tschofenig H. Tschofenig
Arm Limited Arm Limited
October 19, 2018 January 28, 2019
Resource Indicators for OAuth 2.0 Resource Indicators for OAuth 2.0
draft-ietf-oauth-resource-indicators-01 draft-ietf-oauth-resource-indicators-02
Abstract Abstract
An extension to the OAuth 2.0 Authorization Framework defining An extension to the OAuth 2.0 Authorization Framework defining
request parameters that enable a client to explicitly signal to an request parameters that enable a client to explicitly signal to an
authorization server about the location of the protected resource(s) authorization server about the identity of the protected resource(s)
to which it is requesting access. 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 April 22, 2019. This Internet-Draft will expire on August 1, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
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
skipping to change at page 3, line 19 skipping to change at page 3, line 19
to the given resource such that the token cannot be used successfully to the given resource such that the token cannot be used successfully
at other resources. at other resources.
OAuth scope, from Section 3.3 of [RFC6749], is sometimes overloaded OAuth scope, from Section 3.3 of [RFC6749], is sometimes overloaded
to convey the location or identity of the protected resource, 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", "admin:org", "user_photos", access will be redeemed (e.g. "email", "admin:org", "user_photos",
"channels:read", and "channels:write" are a small sample of scope "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 values in use in the wild that convey only the type of access and not
the location). the location or identity).
In some circumstances and for some deployments, a means for the In some circumstances and for some deployments, a means for the
client to signal to the authorization server where it intends to use client to signal to the authorization server where it intends to use
the access token it's requesting is important and useful. A number the access token it's requesting is important and useful. A number
of implementations and deployments of OAuth 2.0 have already employed of implementations and deployments of OAuth 2.0 have already employed
proprietary parameters toward that end. Going forward, this proprietary parameters toward that end. Going forward, this
specification aspires to provide a standardized and interoperable specification aspires to provide a standardized and interoperable
alternative to the proprietary approaches. alternative to the proprietary approaches.
1.1. Requirements Notation and Conventions 1.1. Requirements Notation and Conventions
skipping to change at page 4, line 6 skipping to change at page 4, line 6
"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
In requests to the authorization server, a client MAY indicate the In requests to the authorization server, a client MAY indicate the
protected resource (a.k.a. resource server, application, API, etc.) protected resource (a.k.a. resource server, application, API, etc.)
to which it is requesting access by including the following parameter to which it is requesting access by including the following parameter
in the request. in the request.
resource resource
Indicates the location of the target service or resource where Indicates the target service or resource at which access is being
access is being requested. Its value MUST be an absolute URI, as requested. Its value MUST be an absolute URI, as specified by
specified by Section 4.3 of [RFC3986], which MAY include a query Section 4.3 of [RFC3986], which MAY include a query component but
component but MUST NOT include a fragment component. Multiple MUST NOT include a fragment component. The "resource" parameter
"resource" parameters MAY be used to indicate that the requested URI value is an identifier representing the identity of the
token is intended to be used at multiple resources. 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 indicates the location of a protected resource, The parameter value identifies a resource to which the client is
typically as an https URL, where the client is requesting access. requesting access. The parameter can carry the location of a
This enables the authorization server to apply policy as appropriate protected resource, typically as an https URL, or a more abstract
for the resource, such as determining the type and content of tokens identifier. This enables the authorization server to apply policy as
to be issued, if and how tokens are encrypted, and applying appropriate for the resource, such as determining the type and
appropriate audience restrictions. 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 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 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 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 interacts with, which is appropriate to use as the value of the
"resource" parameter. The client SHOULD use the base URI of the API "resource" parameter. The client SHOULD use the base URI of the API
as the "resource" parameter value unless specific knowledge of the as the "resource" parameter value unless specific knowledge of the
resource dictates otherwise. For example, the value resource dictates otherwise. For example, the value
"https://api.example.com/" would be used for a resource that is the "https://api.example.com/" would be used for a resource that is the
exclusive application on that host, however, if the resource is one exclusive application on that host, however, if the resource is one
skipping to change at page 4, line 49 skipping to change at page 5, line 4
indicate problems with the requested resource(s) in response to an indicate problems with the requested resource(s) in response to an
authorization request or access token request. And can also be used authorization request or access token request. And can also be used
to inform the client that it has requested an invalid combination of to inform the client that it has requested an invalid combination of
resource and scope. resource and scope.
invalid_target invalid_target
The requested resource is invalid, unknown, or malformed. The requested resource is invalid, unknown, or malformed.
The authorization server SHOULD audience restrict issued access The authorization server SHOULD audience restrict issued access
tokens to the resource(s) indicated by the "resource" parameter. tokens to the resource(s) indicated by the "resource" parameter.
Audience restrictions can be communicated in JSON Web Tokens Audience restrictions can be communicated in JSON Web Tokens
[RFC7519] with the "aud" claim and the top-level member of the same [RFC7519] with the "aud" claim and the top-level member of the same
name provides the audience restriction information in a Token name provides the audience restriction information in a Token
Introspection [RFC7662] response. The authorization server may use Introspection [RFC7662] response. The authorization server may use
the exact "resource" value as the audience or it may map from that 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 value to a more general URI or abstract identifier for the given
resource. resource.
2.1. Authorization Request 2.1. Authorization Request
When the "resource" parameter is used in an authorization request to When the "resource" parameter is used in an authorization request to
the authorization endpoint, it indicates the location of the the authorization endpoint, it indicates the identity of the
protected resource(s) to which access is being requested. When an protected resource(s) to which access is being requested. When an
access token will be returned directly from the authorization access token will be returned directly from the authorization
endpoint via the implicit flow (Section 4.2 of OAuth 2.0 [RFC6749]), endpoint via the implicit flow (Section 4.2 of OAuth 2.0 [RFC6749]),
the requested resource is applicable to that access token. In the the requested resource is applicable to that access token. In the
code flow (Section 4.1 of OAuth 2.0 [RFC6749]) where an an code flow (Section 4.1 of OAuth 2.0 [RFC6749]) where an an
intermediate representation of the authorization grant (the intermediate representation of the authorization grant (the
authorization code) is returned from the authorization endpoint, the authorization code) is returned from the authorization endpoint, the
requested resource is applicable to the full authorization grant. requested resource is applicable to the full authorization grant.
For authorization requests sent as a JWTs, such as when using JWT For authorization requests sent as a JWTs, such as when using JWT
skipping to change at page 6, line 34 skipping to change at page 6, line 36
&scope=calendar%20contacts &scope=calendar%20contacts
&resource=https%3A%2F%2Fcal.example.com%2F &resource=https%3A%2F%2Fcal.example.com%2F
&resource=https%3A%2F%2Fcontacts.example.com%2F HTTP/1.1 &resource=https%3A%2F%2Fcontacts.example.com%2F HTTP/1.1
Host: authorization-server.example.com Host: authorization-server.example.com
Figure 2: Code Flow Authorization Request Figure 2: Code Flow Authorization Request
2.2. Access Token Request 2.2. Access Token Request
When the "resource" parameter is used on an access token request made When the "resource" parameter is used on an access token request made
to the token endpoint, for all grant types, it indicates the location to the token endpoint, for all grant types, it indicates the target
of the target service or protected resource where the client intends service or protected resource where the client intends to use the
to use the requested access token. requested access token.
The resource value(s) that are acceptable to an authorization server The resource value(s) that are acceptable to an authorization server
in fulfilling an access token request are at its sole discretion in fulfilling an access token request are at its sole discretion
based on local policy or configuration. In the case of a based on local policy or configuration. In the case of a
"refresh_token" or "authorization_code" grant type request, such "refresh_token" or "authorization_code" grant type request, such
policy may limit the acceptable resources to those that were policy may limit the acceptable resources to those that were
originally granted by the resource owner or a subset thereof. In the originally granted by the resource owner or a subset thereof. In the
"authorization_code" case where the requested resources are a subset "authorization_code" case where the requested resources are a subset
of the set of resources originally granted, the authorization server of the set of resources originally granted, the authorization server
will issue an access token based on that subset of requested will issue an access token based on that subset of requested
skipping to change at page 10, line 5 skipping to change at page 9, line 50
Although multiple occurrences of the "resource" parameter may be Although multiple occurrences of the "resource" parameter may be
included in a request, using only a single "resource" parameter is included in a request, using only a single "resource" parameter is
encouraged. A bearer token that has multiple intended recipients encouraged. A bearer token that has multiple intended recipients
(audiences) can be used by any one of those recipients at any other. (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 Thus, a high degree of trust between the involved parties is needed
when using access tokens with multiple audiences. Furthermore an when using access tokens with multiple audiences. Furthermore an
authorization server may be unwilling or unable to fulfill a token authorization server may be unwilling or unable to fulfill a token
request with multiple resources. 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. IANA Considerations 4. IANA Considerations
4.1. OAuth Parameters Registration 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].
o Parameter name: resource o Parameter name: resource
o Parameter usage location: authorization request, token request o Parameter usage location: authorization request, token request
skipping to change at page 11, line 48 skipping to change at page 12, line 4
[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
This specification was developed within the OAuth Working Group under This specification was developed within the OAuth Working Group under
the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with
Eric Rescorla and Benjamin Kaduk serving as Security Area Directors. Eric Rescorla and Benjamin Kaduk serving as Security Area Directors.
Additionally, the following individuals contributed ideas, feedback, Additionally, the following individuals contributed ideas, feedback,
and wording that helped shape this specification: and wording that helped shape this specification:
Sergey Beryozkin, William Denniss, Vladimir Dzhuvinov, George Vittorio Bertocci, Sergey Beryozkin, William Denniss, Vladimir
Fletcher, Dick Hardt, Phil Hunt, Michael Jones, Torsten Lodderstedt, Dzhuvinov, George Fletcher, Dick Hardt, Phil Hunt, Michael Jones,
Anthony Nadalin, Justin Richer, Nat Sakimura, Filip Skokan, and Hans Torsten Lodderstedt, Anthony Nadalin, Justin Richer, Nat Sakimura,
Zandbelt. 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 ]]
draft-ietf-oauth-resource-indicators-02
o 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.
draft-ietf-oauth-resource-indicators-01 draft-ietf-oauth-resource-indicators-01
o Significant rework of the main section of the document attempting o Significant rework of the main section of the document attempting
to clarify a number of things that came up at, around and after to clarify a number of things that came up at, around and after
IETF 102 and the call for adoption. IETF 102 and the call for adoption.
o Change the "invalid_resource" error to "invalid_target" to align o Change the "invalid_resource" error to "invalid_target" to align
with draft-ietf-oauth-token-exchange, which has some overlap in with draft-ietf-oauth-token-exchange, which has some overlap in
functionality. functionality.
o Allow the "resource" parameter value to have a query component o Allow the "resource" parameter value to have a query component
(aligning with draft-ietf-oauth-token-exchange). (aligning with draft-ietf-oauth-token-exchange).
 End of changes. 16 change blocks. 
27 lines changed or deleted 49 lines changed or added

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