< 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.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/