< draft-ietf-oauth-device-flow-09.txt		draft-ietf-oauth-device-flow-10.txt >
	OAuth W. Denniss		OAuth W. Denniss
	Internet-Draft Google		Internet-Draft Google
	Intended status: Standards Track J. Bradley		Intended status: Standards Track J. Bradley
	Expires: October 22, 2018 Ping Identity		Expires: December 3, 2018 Ping Identity
	M. Jones		M. Jones
	Microsoft		Microsoft
	H. Tschofenig		H. Tschofenig
	ARM Limited		ARM Limited
	April 20, 2018		June 01, 2018
	OAuth 2.0 Device Flow for Browserless and Input Constrained Devices		OAuth 2.0 Device Flow for Browserless and Input Constrained Devices
	draft-ietf-oauth-device-flow-09		draft-ietf-oauth-device-flow-10
	Abstract		Abstract
	This OAuth 2.0 authorization flow for browserless and input		This OAuth 2.0 authorization flow for browserless and input
	constrained devices, often referred to as the device flow, enables		constrained devices, often referred to as the device flow, enables
	OAuth clients to request user authorization from devices that have an		OAuth clients to request user authorization from devices that have an
	Internet connection, but don't have an easy input method (such as a		Internet connection, but don't have an easy input method (such as a
	smart TV, media console, picture frame, or printer), or lack a		smart TV, media console, picture frame, or printer), or lack a
	suitable browser for a more traditional OAuth flow. This		suitable browser for a more traditional OAuth flow. This
	authorization flow instructs the user to perform the authorization		authorization flow instructs the user to perform the authorization
	skipping to change at page 1, line 44 ¶		skipping to change at page 1, line 44 ¶
	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 October 22, 2018.		This Internet-Draft will expire on December 3, 2018.
	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 49 ¶		skipping to change at page 2, line 49 ¶
	6. Usability Considerations . . . . . . . . . . . . . . . . . . 13		6. Usability Considerations . . . . . . . . . . . . . . . . . . 13
	6.1. User Code Recommendations . . . . . . . . . . . . . . . . 13		6.1. User Code Recommendations . . . . . . . . . . . . . . . . 13
	6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14		6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14
	7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
	7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14		7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14
	7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14		7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
	7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15		7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15
	7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15		7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
	7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 15		7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 15
	7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15		7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
	8. Normative References . . . . . . . . . . . . . . . . . . . . 15		8. Normative References . . . . . . . . . . . . . . . . . . . . 16
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16
	Appendix B. Document History . . . . . . . . . . . . . . . . . . 16		Appendix B. Document History . . . . . . . . . . . . . . . . . . 17
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
	1. Introduction		1. Introduction
	This OAuth 2.0 protocol flow for browserless and input constrained		This OAuth 2.0 protocol flow for browserless and input constrained
	devices, often referred to as the device flow, enables OAuth clients		devices, often referred to as the device flow, enables OAuth clients
	to request user authorization from devices that have an internet		to request user authorization from devices that have an internet
	connection, but don't have an easy input method (such as a smart TV,		connection, but don't have an easy input method (such as a smart TV,
	media console, picture frame, or printer), or lack a suitable browser		media console, picture frame, or printer), or lack a suitable browser
	for a more traditional OAuth flow. This authorization flow instructs		for a more traditional OAuth flow. This authorization flow instructs
	skipping to change at page 7, line 5 ¶		skipping to change at page 7, line 5 ¶
	expires_in		expires_in
	OPTIONAL. The lifetime in seconds of the "device_code" and		OPTIONAL. The lifetime in seconds of the "device_code" and
	"user_code".		"user_code".
	interval		interval
	OPTIONAL. The minimum amount of time in seconds that the client		OPTIONAL. The minimum amount of time in seconds that the client
	SHOULD wait between polling requests to the token endpoint.		SHOULD wait between polling requests to the token endpoint.
	For example:		For example:
	HTTP/1.1 200 OK		HTTP/1.1 200 OK
	Content-Type: application/json		Content-Type: application/json
	Cache-Control: no-store		Cache-Control: no-store
	{		{
	"device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",		"device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
	"user_code":"WDJB-MJHT",		"user_code":"WDJB-MJHT",
	"verification_uri":"https://www.example.com/device",		"verification_uri":"https://www.example.com/device",
	"verification_uri_complete":"https://www.example.com/device?user_code=WDJB-MJHT",		"verification_uri_complete":
	"expires_in" : 1800,		"https://www.example.com/device?user_code=WDJB-MJHT",
	"interval": 5		"expires_in" : 1800,
	}		"interval": 5
			}
	3.3. User Interaction		3.3. User Interaction
	After receiving a successful Authorization Response, the client		After receiving a successful Authorization Response, the client
	displays or otherwise communicates the "user_code" and the		displays or otherwise communicates the "user_code" and the
	"verification_uri" to the end-user and instructs them to visit the		"verification_uri" to the end-user and instructs them to visit the
	URI in a user agent on a secondary device (for example, in a browser		URI in a user agent on a secondary device (for example, in a browser
	on their mobile phone), and enter the user code.		on their mobile phone), and enter the user code.
	+-----------------------------------------------+		+-----------------------------------------------+
	skipping to change at page 9, line 14 ¶		skipping to change at page 9, line 14 ¶
	3.4. Device Access Token Request		3.4. Device Access Token Request
	After displaying instructions to the user, the client makes an Access		After displaying instructions to the user, the client makes an Access
	Token Request to the token endpoint with a "grant_type" of		Token Request to the token endpoint with a "grant_type" of
	"urn:ietf:params:oauth:grant-type:device_code". This is an extension		"urn:ietf:params:oauth:grant-type:device_code". This is an extension
	grant type (as defined by Section 4.5 of [RFC6749]) with the		grant type (as defined by Section 4.5 of [RFC6749]) with the
	following parameters:		following parameters:
	grant_type		grant_type
	REQUIRED. Value MUST be set to "urn:ietf:params:oauth:grant-		REQUIRED. Value MUST be set to
	type:device_code".		"urn:ietf:params:oauth:grant-type:device_code".
	device_code		device_code
	REQUIRED. The device verification code, "device_code" from the		REQUIRED. The device verification code, "device_code" from the
	Device Authorization Response, defined in Section 3.2.		Device Authorization Response, defined in Section 3.2.
	client_id		client_id
	REQUIRED, if the client is not authenticating with the		REQUIRED, if the client is not authenticating with the
	authorization server as described in Section 3.2.1. of [RFC6749].		authorization server as described in Section 3.2.1. of [RFC6749].
	For example, the client makes the following HTTPS request (line		For example, the client makes the following HTTPS request (line
	skipping to change at page 10, line 12 ¶		skipping to change at page 10, line 12 ¶
	Token Request repeatedly in a polling fashion, based on the error		Token Request repeatedly in a polling fashion, based on the error
	code in the response.		code in the response.
	3.5. Device Access Token Response		3.5. Device Access Token Response
	If the user has approved the grant, the token endpoint responds with		If the user has approved the grant, the token endpoint responds with
	a success response defined in Section 5.1 of [RFC6749]; otherwise it		a success response defined in Section 5.1 of [RFC6749]; otherwise it
	responds with an error, as defined in Section 5.2 of [RFC6749].		responds with an error, as defined in Section 5.2 of [RFC6749].
	In addition to the error codes defined in Section 5.2 of [RFC6749],		In addition to the error codes defined in Section 5.2 of [RFC6749],
	the following error codes are specific for the device flow:		the following error codes are specified by the device flow for use in
			token endpoint responses:
	authorization_pending		authorization_pending
	The authorization request is still pending as the end-user hasn't		The authorization request is still pending as the end-user hasn't
	yet completed the user interaction steps (Section 3.3). The		yet completed the user interaction steps (Section 3.3). The
	client should repeat the Access Token Request to the token		client should repeat the Access Token Request to the token
	endpoint.		endpoint.
			access_denied
			The end-user denied the authorization request.
	slow_down		slow_down
	The client is polling too quickly and should back off at a		The client is polling too quickly and should back off at a
	reasonable rate.		reasonable rate.
	expired_token		expired_token
	The "device_code" has expired. The client will need to make a new		The "device_code" has expired. The client will need to make a new
	Device Authorization Request.		Device Authorization Request.
	The error codes "authorization_pending" and "slow_down" are		The error codes "authorization_pending" and "slow_down" are
	considered soft errors. The client should continue to poll the token		considered soft errors. The client should continue to poll the token
	endpoint by repeating the Device Token Request (Section 3.4) when		endpoint by repeating the Device Token Request (Section 3.4) when
	receiving soft errors, increasing the time between polls if a		receiving soft errors, increasing the time between polls if a
	"slow_down" error is received. Other error codes are considered hard		"slow_down" error is received. Other error codes are considered hard
	errors; the client should stop polling and react accordingly, for		errors; the client should stop polling and react accordingly, for
	example, by displaying an error to the user.		example, by displaying an error to the user.
	If the verification codes have expired, the server SHOULD respond		If the verification codes have expired, the server SHOULD respond
	with the standard OAuth error "invalid_grant". Clients MAY then		with the error code "expired_token". Clients MAY then choose to
	choose to start a new device authorization session.		start a new device authorization session.
	The interval at which the client polls MUST NOT be more frequent than		The interval at which the client polls MUST NOT be more frequent than
	the "interval" parameter returned in the Device Authorization		the "interval" parameter returned in the Device Authorization
	Response (see Section 3.2). If no interval was provided, the client		Response (see Section 3.2). If no interval was provided, the client
	MUST use a reasonable default polling interval.		MUST use a reasonable default polling interval.
	The assumption of this specification is that the secondary device the		The assumption of this specification is that the secondary device the
	user is authorizing the request on does not have a way to communicate		user is authorizing the request on does not have a way to communicate
	back to the OAuth client. Only a one-way channel is required to make		back to the OAuth client. Only a one-way channel is required to make
	this flow useful in many scenarios. For example, an HTML application		this flow useful in many scenarios. For example, an HTML application
	skipping to change at page 13, line 21 ¶		skipping to change at page 13, line 21 ¶
	session by completing the authorization faster than the user that		session by completing the authorization faster than the user that
	initiated it. Devices SHOULD take into account the operating		initiated it. Devices SHOULD take into account the operating
	environment when considering how to communicate the code to the user		environment when considering how to communicate the code to the user
	to reduce the chances it will be observed by a malicious user.		to reduce the chances it will be observed by a malicious user.
	5.5. Non-confidential Clients		5.5. Non-confidential Clients
	Most device clients are incapable of being confidential clients, as		Most device clients are incapable of being confidential clients, as
	secrets that are statically included as part of an app distributed to		secrets that are statically included as part of an app distributed to
	multiple users cannot be considered confidential. For such clients,		multiple users cannot be considered confidential. For such clients,
	the recommendations of Section 5.3.1 of [RFC6819] and Section 8.9 of		the recommendations of Section 5.3.1 of [RFC6819] and Section 8.5 of
	[RFC8252] apply.		[RFC8252] apply.
	5.6. Non-Visual Code Transmission		5.6. Non-Visual Code Transmission
	There is no requirement that the user code be displayed by the device		There is no requirement that the user code be displayed by the device
	visually. Other methods of one-way communication can potentially be		visually. Other methods of one-way communication can potentially be
	used, such as text-to-speech audio, or Bluetooth Low Energy. To		used, such as text-to-speech audio, or Bluetooth Low Energy. To
	mitigate an attack in which a malicious user can bootstrap their		mitigate an attack in which a malicious user can bootstrap their
	credentials on a device not in their control, it is RECOMMENDED that		credentials on a device not in their control, it is RECOMMENDED that
	any chosen communication channel only be accessible by people in		any chosen communication channel only be accessible by people in
	skipping to change at page 14, line 13 ¶		skipping to change at page 14, line 13 ¶
	can typically be entered on a mobile keyboard without using modifier		can typically be entered on a mobile keyboard without using modifier
	keys. Further removing vowels to avoid randomly creating words		keys. Further removing vowels to avoid randomly creating words
	results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes		results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes
	or other punctuation may be included for readability.		or other punctuation may be included for readability.
	An example user code following this guideline, with an entropy of		An example user code following this guideline, with an entropy of
	20^8: "WDJB-MJHT".		20^8: "WDJB-MJHT".
	Pure numeric codes are also a good choice for usability, especially		Pure numeric codes are also a good choice for usability, especially
	for clients targeting locales where A-Z character keyboards are not		for clients targeting locales where A-Z character keyboards are not
	used, through their length needs to be longer to maintain a high		used, though their length needs to be longer to maintain a high
	entropy.		entropy.
	An example numeric user code, with an entropy of 10^9: "019-450-730".		An example numeric user code, with an entropy of 10^9: "019-450-730".
	The server should ignore any characters like punctuation that are not		The server should ignore any characters like punctuation that are not
	in the user-code character set. Provided that the character set		in the user-code character set. Provided that the character set
	doesn't include characters of different case, the comparison should		doesn't include characters of different case, the comparison should
	be case insensitive.		be case insensitive.
	6.2. Non-Browser User Interaction		6.2. Non-Browser User Interaction
	skipping to change at page 15, line 19 ¶		skipping to change at page 15, line 19 ¶
	established by [RFC6749].		established by [RFC6749].
	7.2.1. Registry Contents		7.2.1. Registry Contents
	o Error name: authorization_pending		o Error name: authorization_pending
	o Error usage location: Token endpoint response		o Error usage location: Token endpoint response
	o Related protocol extension: [[ this specification ]]		o Related protocol extension: [[ this specification ]]
	o Change controller: IETF		o Change controller: IETF
	o Specification Document: Section 3.5 of [[ this specification ]]		o Specification Document: Section 3.5 of [[ this specification ]]
			o Error name: access_denied
			o Error usage location: Token endpoint response
			o Related protocol extension: [[ this specification ]]
			o Change controller: IETF
			o Specification Document: Section 3.5 of [[ this specification ]]
	o Error name: slow_down		o Error name: slow_down
	o Error usage location: Token endpoint response		o Error usage location: Token endpoint response
	o Related protocol extension: [[ this specification ]]		o Related protocol extension: [[ this specification ]]
	o Change controller: IETF		o Change controller: IETF
	o Specification Document: Section 3.5 of [[ this specification ]]		o Specification Document: Section 3.5 of [[ this specification ]]
	o Error name: expired_token		o Error name: expired_token
	o Error usage location: Token endpoint response		o Error usage location: Token endpoint response
	o Related protocol extension: [[ this specification ]]		o Related protocol extension: [[ this specification ]]
	o Change controller: IETF		o Change controller: IETF
	skipping to change at page 16, line 38 ¶		skipping to change at page 16, line 45 ¶
	BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,		BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
	<https://www.rfc-editor.org/info/rfc8252>.		<https://www.rfc-editor.org/info/rfc8252>.
	Appendix A. Acknowledgements		Appendix A. Acknowledgements
	The starting point for this document was the Internet-Draft draft-		The starting point for this document was the Internet-Draft draft-
	recordon-oauth-v2-device, authored by David Recordon and Brent		recordon-oauth-v2-device, authored by David Recordon and Brent
	Goldman, which itself was based on content in draft versions of the		Goldman, which itself was based on content in draft versions of the
	OAuth 2.0 protocol specification removed prior to publication due to		OAuth 2.0 protocol specification removed prior to publication due to
	a then lack of sufficient deployment expertise. Thank you to the		a then lack of sufficient deployment expertise. Thank you to the
	OAuth working group members who worked on this specification through		OAuth working group members who contributed to those earlier drafts.
	2010.
			This document was produced in the OAuth working group under the
			chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with
			Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as
			Security Area Directors.
	The following individuals contributed ideas, feedback, and wording		The following individuals contributed ideas, feedback, and wording
	that shaped and formed the final specification:		that shaped and formed the final specification:
	Roshni Chandrashekhar, Marius Scurtescu, Breno de Medeiros, Stein		Brian Campbell, Roshni Chandrashekhar, Eric Fazendin, Torsten
	Myrseth, Simon Moffatt, Brian Campbell, James Manger, Justin Richer,		Lodderstedt, James Manger, Breno de Medeiros, Simon Moffatt, Stein
	Ken Wang, Steven E. Wright, Nat Sakimura, and Torsten Lodderstedt.		Myrseth, Justin Richer, Nat Sakimura, Andrew Sciberras, Marius
			Scurtescu, Ken Wang, and Steven E. Wright.
	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 ]]
			-10
			o Added a missing definition of access_denied for use on the token
			endpoint.
			o Corrected text documenting which error code should be returned for
			expired tokens (it's "expired_token", not "invalid_grant").
			o Corrected section reference to RFC 8252 (the section numbers had
			changed after the initial reference was made).
			o Fixed line length of one diagram (was causing xml2rfc warnings).
			o Added line breaks so the URN grant_type is presented on an
			unbroken line.
			o Typos fixed and other stylistic improvements.
	-09		-09
	o Addressed review comments by Security Area Director Eric Rescorla		o Addressed review comments by Security Area Director Eric Rescorla
	about the potential of a confused deputy attack.		about the potential of a confused deputy attack.
	-08		-08
	o Expanded the User Code Brute Forcing section to include more		o Expanded the User Code Brute Forcing section to include more
	detail on this attack.		detail on this attack.
	-07		-07
End of changes. 19 change blocks.
	29 lines changed or deleted		59 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/