< draft-ietf-oauth-device-flow-13.txt		draft-ietf-oauth-device-flow-14.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: April 22, 2019 Ping Identity		Expires: July 20, 2019 Ping Identity
	M. Jones		M. Jones
	Microsoft		Microsoft
	H. Tschofenig		H. Tschofenig
	ARM Limited		ARM Limited
	October 19, 2018		January 16, 2019
	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-13		draft-ietf-oauth-device-flow-14
	Abstract		Abstract
	This OAuth 2.0 authorization flow is designed for devices that either		This OAuth 2.0 authorization flow is designed for devices that either
	lack a browser to perform a user-agent based OAuth flow, or are		lack a browser to perform a user-agent based OAuth flow, or are
	input-constrained to the extent that requiring the user to input a		input-constrained to the extent that requiring the user to input a
	lot of text (like their credentials to authenticate with the		lot of text (like their credentials to authenticate with the
	authorization server) is impractical. It enables OAuth clients on		authorization server) is impractical. It enables OAuth clients on
	such devices (like smart TVs, media consoles, digital picture frames,		such devices (like smart TVs, media consoles, digital picture frames,
	and printers) to obtain user authorization to access protected		and printers) to obtain user authorization to access protected
	skipping to change at page 1, line 43 ¶		skipping to change at page 1, line 43 ¶
	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 July 20, 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 2, line 34 ¶		skipping to change at page 2, line 34 ¶
	3.4. Device Access Token Request . . . . . . . . . . . . . . . 9		3.4. Device Access Token Request . . . . . . . . . . . . . . . 9
	3.5. Device Access Token Response . . . . . . . . . . . . . . 10		3.5. Device Access Token Response . . . . . . . . . . . . . . 10
	4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12		4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 12		5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
	5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12		5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12
	5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13		5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13
	5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13		5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13
	5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13		5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13
	5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14		5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14
	5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14		5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14
	5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 14		5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 15
	6. Usability Considerations . . . . . . . . . . . . . . . . . . 14		6. Usability Considerations . . . . . . . . . . . . . . . . . . 15
	6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15		6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15
	6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16		6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16
	7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
	7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16		7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16
	7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16		7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
	7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 16		7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 17
	7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16		7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
	7.3. OAuth Extensions Error Registration . . . . . . . . . . . 16		7.3. OAuth Extensions Error Registration . . . . . . . . . . . 17
	7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17		7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
	7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 17		7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 18
	7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17		7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
	8. Normative References . . . . . . . . . . . . . . . . . . . . 17		8. Normative References . . . . . . . . . . . . . . . . . . . . 18
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 18		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
	Appendix B. Document History . . . . . . . . . . . . . . . . . . 19		Appendix B. Document History . . . . . . . . . . . . . . . . . . 19
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
	1. Introduction		1. Introduction
	This OAuth 2.0 [RFC6749] protocol flow for browserless and input-		This OAuth 2.0 [RFC6749] protocol extension known as the "device
	constrained devices, often referred to as the device flow, enables		flow" enables OAuth clients to request user authorization from
	OAuth clients to request user authorization from applications on		applications on devices that have limited input capabilities or lack
	devices that have an Internet connection, but don't have an easy		a suitable browser. Such devices include those smart TVs, media
	input method (such as a smart TV, media console, picture frame, or		console, picture frames and printers which lack an easy input method
	printer), or lack a suitable browser for a more traditional OAuth		or suitable browser required for a more traditional OAuth flow. This
	flow. This authorization flow instructs the user to perform the		authorization flow instructs the user to perform the authorization
	authorization request on a secondary device, such as a smartphone.		request on a secondary device, such as a smartphone which does have
			the requisite input and browser capabilities for an OAuth flow.
	The device flow is not intended to replace browser-based OAuth in		The device flow is not intended to replace browser-based OAuth in
	native apps on capable devices (like smartphones). Those apps should		native apps on capable devices (like smartphones). Those apps should
	follow the practices specified in OAuth 2.0 for Native Apps		follow the practices specified in OAuth 2.0 for Native Apps
	[RFC8252].		[RFC8252].
	The operating requirements to be able to use this authorization flow		The operating requirements to be able to use this authorization flow
	are:		are:
	(1) The device is already connected to the Internet.		(1) The device is already connected to the Internet.
	skipping to change at page 6, line 35 ¶		skipping to change at page 6, line 35 ¶
	All requests from the device MUST use the Transport Layer Security		All requests from the device MUST use the Transport Layer Security
	(TLS) [RFC8446] protocol and implement the best practices of BCP 195		(TLS) [RFC8446] protocol and implement the best practices of BCP 195
	[RFC7525].		[RFC7525].
	Parameters sent without a value MUST be treated as if they were		Parameters sent without a value MUST be treated as if they were
	omitted from the request. The authorization server MUST ignore		omitted from the request. The authorization server MUST ignore
	unrecognized request parameters. Request and response parameters		unrecognized request parameters. Request and response parameters
	MUST NOT be included more than once.		MUST NOT be included more than once.
	Due to the polling nature of this protocol, to avoid unneeded		Due to the polling nature of this protocol, care is needed to avoid
			overloading the capacity of the token endpoint. To avoid unneeded
	requests on the token endpoint, the client SHOULD only commence a		requests on the token endpoint, the client SHOULD only commence a
	device authorization request when prompted by the user, and not		device authorization request when prompted by the user, and not
	automatically such as when the app starts.		automatically such as when the app starts or when the previous
			authorization session expires or fails.
	3.2. Device Authorization Response		3.2. Device Authorization Response
	In response, the authorization server generates a unique device		In response, the authorization server generates a unique device
	verification code and an end-user code that are valid for a limited		verification code and an end-user code that are valid for a limited
	time and includes them in the HTTP response body using the		time and includes them in the HTTP response body using the
	"application/json" format [RFC8259] with a 200 (OK) status code. The		"application/json" format [RFC8259] with a 200 (OK) status code. The
	response contains the following parameters:		response contains the following parameters:
	device_code		device_code
	skipping to change at page 11, line 40 ¶		skipping to change at page 11, line 40 ¶
	session has concluded. The client MAY commence a new Device		session has concluded. The client MAY commence a new Device
	Authorization Request but SHOULD wait for user interaction before		Authorization Request but SHOULD wait for user interaction before
	restarting to avoid unnecessary polling.		restarting to avoid unnecessary polling.
	A client receiving an error response as defined in Section 5.2 of		A client receiving an error response as defined in Section 5.2 of
	[RFC6749] MUST stop polling and SHOULD react accordingly, for		[RFC6749] MUST stop polling and SHOULD react accordingly, for
	example, by displaying an error to the user, except for the error		example, by displaying an error to the user, except for the error
	codes "authorization_pending" and "slow_down" which are processed as		codes "authorization_pending" and "slow_down" which are processed as
	described above.		described above.
			On encountering a connection timeout, clients MUST unilaterally
			reduce their polling frequency before retrying. The use of an
			exponential backoff algorithm to achieve this, such as by doubling
			the polling interval on each such connection timeout, is RECOMMENDED.
	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
	on a TV that can only make outbound requests. If a return channel		on a TV that can only make outbound requests. If a return channel
	were to exist for the chosen user interaction interface, then the		were to exist for the chosen user interaction interface, then the
	device MAY wait until notified on that channel that the user has		device MAY wait until notified on that channel that the user has
	completed the action before initiating the token request (as an		completed the action before initiating the token request (as an
	alternative to polling). Such behavior is, however, outside the		alternative to polling). Such behavior is, however, outside the
	scope of this specification.		scope of this specification.
	skipping to change at page 14, line 20 ¶		skipping to change at page 14, line 24 ¶
	(allowing the user to retrieve their secondary device, navigate to		(allowing the user to retrieve their secondary device, navigate to
	the verification URI, login, etc.), but should be sufficiently short		the verification URI, login, etc.), but should be sufficiently short
	to limit the usability of a code obtained for phishing. This doesn't		to limit the usability of a code obtained for phishing. This doesn't
	prevent a phisher presenting a fresh token, particularly in the case		prevent a phisher presenting a fresh token, particularly in the case
	they are interacting with the user in real time, but it does limit		they are interacting with the user in real time, but it does limit
	the viability of codes sent over email or SMS.		the viability of codes sent over email or SMS.
	5.5. Session Spying		5.5. Session Spying
	While the device is pending authorization, it may be possible for a		While the device is pending authorization, it may be possible for a
	malicious user to spy on the device user interface and hijack the		malicious user to physically spy on the device user interface (by
	session by completing the authorization faster than the user that		viewing the screen on which it's displayed, for example) and hijack
			the 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.6. Non-confidential Clients		5.6. Non-confidential Clients
	Most device clients are incapable of being confidential clients, as		Device clients are generally incapable of maintaining the
	secrets that are statically included as part of an app distributed to		confidentiality of their credentials, as users in possession of the
	multiple users cannot be considered confidential. For such clients,		device can reverse engineer it and extract the credentials.
	the recommendations of Section 5.3.1 of [RFC6819] and Section 8.5 of		Therefore, unless additional measures are taken, they should be
	[RFC8252] apply.		treated as public clients (as defined by Section 2.1 of OAuth 2.0)
			susceptible to impersonation. The security considerations of
			Section 5.3.1 of [RFC6819] and Sections 8.5 and 8.6 of [RFC8252]
			apply to such clients.
			The user may also be able to obtain the device_code and/or other
			OAuth bearer tokens issued to their client, which would allow them to
			use their own authorization grant directly by impersonating the
			client. Given that the user in possession of the client credentials
			can already impersonate the client and create a new authorization
			grant (with a new device_code), this doesn't represent a separate
			impersonation vector.
	5.7. Non-Visual Code Transmission		5.7. 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
	close proximity. E.g., users who can see, or hear the device.		close proximity. E.g., users who can see, or hear the device.
	skipping to change at page 19, line 25 ¶		skipping to change at page 19, line 46 ¶
	Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin		Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin
	Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt,		Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt,
	James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin		James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin
	Richer, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Ken Wang,		Richer, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Ken Wang,
	and Steven E. Wright.		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 ]]
	-13		-14
			o Added more normative text on polling behavior.
			o Added discussion on risk of user retrieving their own device_code.
			o Editorial improvements.
			-13
	o Added a longer discussion about entropy, proposed by Benjamin		o Added a longer discussion about entropy, proposed by Benjamin
	Kaduk.		Kaduk.
	o Added device_code to OAuth IANA registry.		o Added device_code to OAuth IANA registry.
	o Expanded explanation of "case insensitive".		o Expanded explanation of "case insensitive".
	o Added security section on Device Code Brute Forcing.		o Added security section on Device Code Brute Forcing.
	o application/x-www-form-urlencoded normativly referenced.		o application/x-www-form-urlencoded normativly referenced.
	o Editatorial improvements.		o Editorial improvements.
	-12		-12
	o Set a default polling interval to 5s explicitly.		o Set a default polling interval to 5s explicitly.
	o Defined the slow_down behavior that it should increase the current		o Defined the slow_down behavior that it should increase the current
	interval by 5s.		interval by 5s.
	o expires_in now REQUIRED		o expires_in now REQUIRED
	o Other changes in response to review feedback.		o Other changes in response to review feedback.
	-11		-11
End of changes. 17 change blocks.
	33 lines changed or deleted		58 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/