< draft-ietf-oauth-device-flow-01.txt		draft-ietf-oauth-device-flow-02.txt >
	OAuth W. Denniss		OAuth W. Denniss
	Internet-Draft Google		Internet-Draft Google
	Intended status: Standards Track S. Myrseth		Intended status: Standards Track S. Myrseth
	Expires: September 4, 2016 ForgeRock		Expires: January 9, 2017 ForgeRock
	J. Bradley		J. Bradley
	Ping Identity		Ping Identity
	M. Jones		M. Jones
	Microsoft		Microsoft
	H. Tschofenig		H. Tschofenig
	ARM Limited		ARM Limited
	March 3, 2016		July 8, 2016
	OAuth 2.0 Device Flow		OAuth 2.0 Device Flow
	draft-ietf-oauth-device-flow-01		draft-ietf-oauth-device-flow-02
	Abstract		Abstract
	The device flow is suitable for OAuth 2.0 clients executing on		The device flow is suitable for OAuth 2.0 clients executing on
	devices that do not have an easy data-entry method (e.g., game		devices that do not have an easy data-entry method (e.g., game
	consoles, TVs, picture frames, and media hubs), but where the end-		consoles, TVs, picture frames, and media hubs), but where the end-
	user has separate access to a user-agent on another computer or		user has separate access to a user-agent on another computer or
	device (e.g., desktop computer, a laptop, a smart phone, or a		device (e.g., desktop computer, a laptop, a smart phone, or a
	tablet).		tablet).
	skipping to change at page 1, line 42 ¶		skipping to change at page 1, line 42 ¶
	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 http://datatracker.ietf.org/drafts/current/.		Drafts is at http://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 September 4, 2016.		This Internet-Draft will expire on January 9, 2017.
	Copyright Notice		Copyright Notice
	Copyright (c) 2016 IETF Trust and the persons identified as the		Copyright (c) 2016 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
	(http://trustee.ietf.org/license-info) in effect on the date of		(http://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 20 ¶		skipping to change at page 2, line 20 ¶
	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
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4		3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4
	3.1. Client Requests Authorization . . . . . . . . . . . . . . 4		3.1. Device Authorization Request . . . . . . . . . . . . . . 4
	3.2. Client Requests Access Token . . . . . . . . . . . . . . 6		3.2. Device Authorization Response . . . . . . . . . . . . . . 5
	3.3. Additional Error Responses . . . . . . . . . . . . . . . 6		3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 6
	4. Security Considerations . . . . . . . . . . . . . . . . . . . 7		3.4. Device Token Request . . . . . . . . . . . . . . . . . . 6
	5. Normative References . . . . . . . . . . . . . . . . . . . . 7		3.5. Device Token Response . . . . . . . . . . . . . . . . . . 7
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7		4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	Appendix B. Document History . . . . . . . . . . . . . . . . . . 7		5. Normative References . . . . . . . . . . . . . . . . . . . . 8
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8
			Appendix B. Document History . . . . . . . . . . . . . . . . . . 8
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
	1. Introduction		1. Introduction
	The device flow is suitable for clients executing on devices that do		The device flow is suitable for clients executing on devices that do
	not have an easy data-entry method and where the client is incapable		not have an easy data-entry method and where the client is incapable
	of receiving incoming requests from the authorization server		of receiving incoming requests from the authorization server
	(incapable of acting as an HTTP server).		(incapable of acting as an HTTP server).
	Instead of interacting with the end-user's user-agent, the client		Instead of interacting with the end-user's user-agent, the client
	instructs the end-user to use another computer or device and connect		instructs the end-user to use another computer or device and connect
	skipping to change at page 3, line 14 ¶		skipping to change at page 3, line 14 ¶
	+----------+ +----------------+		+----------+ +----------------+
	| |>---(A)-- Client Identifier --->| |		| |>---(A)-- Client Identifier --->| |
	| | | |		| | | |
	| |<---(B)-- Verification Code, --<| |		| |<---(B)-- Verification Code, --<| |
	| | User Code, | |		| | User Code, | |
	| | & Verification URI | |		| | & Verification URI | |
	| Device | | |		| Device | | |
	| Client | Client Identifier & | |		| Client | Client Identifier & | |
	| |>---(E)-- Verification Code --->| |		| |>---(E)-- Verification Code --->| |
	| | ... | |		| | polling... | |
	| |>---(E)---> | |		| |>---(E)-- Verification Code --->| |
	| | | Authorization |		| | | Authorization |
	| |<---(F)-- Access Token --------<| Server |		| |<---(F)-- Access Token --------<| Server |
	+----------+ (w/ Optional Refresh Token) | |		+----------+ (w/ Optional Refresh Token) | |
	v | |		v | |
	: | |		: | |
	(C) User Code & Verification URI | |		(C) User Code & Verification URI | |
	: | |		: | |
	v | |		v | |
	+----------+ | |		+----------+ | |
	| End-user | | |		| End-user | | |
	skipping to change at page 4, line 34 ¶		skipping to change at page 4, line 34 ¶
	The authorization server's endpoint capable of issuing		The authorization server's endpoint capable of issuing
	verification codes, user codes, and verification URLs.		verification codes, user codes, and verification URLs.
	Device Verification Code:		Device Verification Code:
	A short-lived token representing an authorization session.		A short-lived token representing an authorization session.
	End-User Verification Code:		End-User Verification Code:
	A short-lived token which the device displays to the end user, is		A short-lived token which the device displays to the end user, is
	entered by the end-user on the authorization sever, and is thus		entered by the end-user on the authorization server, and is thus
	used to bind the device to the end-user.		used to bind the device to the end-user.
	3. Specification		3. Specification
	3.1. Client Requests Authorization		3.1. Device Authorization Request
	The client initiates the flow by requesting a set of verification		The client initiates the flow by requesting a set of verification
	codes from the authorization server by making an HTTP "POST" request		codes from the authorization server by making an HTTP "POST" request
	to the device endpoint. The client constructs a request URI by		to the device endpoint. The client constructs a request URI by
	adding the following parameters to the request:		adding the following parameters to the request:
	response_type:		response_type:
	REQUIRED. The parameter value MUST be set to "device_code".		REQUIRED. The parameter value MUST be set to "device_code".
	skipping to change at page 5, line 22 ¶		skipping to change at page 5, line 22 ¶
	For example, the client makes the following HTTPS request (line		For example, the client makes the following HTTPS request (line
	breaks are for display purposes only):		breaks are for display purposes only):
	POST /token HTTP/1.1		POST /token HTTP/1.1
	Host: server.example.com		Host: server.example.com
	Content-Type: application/x-www-form-urlencoded		Content-Type: application/x-www-form-urlencoded
	response_type=device_code&client_id=s6BhdRkqt3		response_type=device_code&client_id=s6BhdRkqt3
			3.2. Device Authorization Response
	In response, the authorization server generates a verification code		In response, the authorization server generates a verification code
	and an end-user code and includes them in the HTTP response body		and an end-user code and includes them in the HTTP response body
	using the "application/json" format with a 200 status code (OK). The		using the "application/json" format with a 200 status code (OK). The
	response contains the following parameters:		response contains the following parameters:
	device_code		device_code
	REQUIRED. The verification code.		REQUIRED. The verification code.
	user_code		user_code
	skipping to change at page 6, line 16 ¶		skipping to change at page 6, line 18 ¶
	Content-Type: application/json		Content-Type: application/json
	Cache-Control: no-store		Cache-Control: no-store
	{		{
	"device_code":"74tq5miHKB",		"device_code":"74tq5miHKB",
	"user_code":"94248",		"user_code":"94248",
	"verification_uri":"http://www.example.com/device",		"verification_uri":"http://www.example.com/device",
	"interval"=5		"interval"=5
	}		}
	The client displays the end-user code and the end-user verification		3.3. User Instruction
	URI to the end-user, and instructs the end-user to visit the URI
	using a user-agent and enter the end-user code.		After receiving a successful Authorization Response, the client
			displays the end-user code and the end-user verification URI to the
			end-user, and instructs the end-user to visit the URI using a user-
			agent and enter the end-user code.
	The end-user manually types the provided verification URI and		The end-user manually types the provided verification URI and
	authenticates with the authorization server. The authorization		authenticates with the authorization server. The authorization
	server prompts the end-user to authorize the client's request by		server prompts the end-user to authorize the client's request by
	entering the end-user code provided by the client. Once the end-user		entering the end-user code provided by the client. Once the end-user
	approves or denies the request, the authorization server informs the		approves or denies the request, the authorization server informs the
	end-user to return to the device for further instructions.		end-user to return to the device for further instructions.
	3.2. Client Requests Access Token		3.4. Device Token Request
	Since the client is unable to receive incoming requests from the		As the user is authorizing the request on secondary device which may
	authorization server, it polls the authorization server repeatedly		not have a way to communicate to the original device, the client
	until the end-user grants or denies the request, or the verification		polls the token endpoint until the end-user grants or denies the
	code expires.		request, or the device code expires.
	The client makes the following request at an arbitrary but reasonable		The client polls at reasonable interval which MUST NOT exceed the
	interval which MUST NOT exceed the minimum interval rate provided by		minimum interval provided by the authorization server via the
	the authorization server (if present via the "interval" parameter).		"interval" parameter (if provided).
	Alternatively, the client MAY provide a user interface for the end-
	user to manually inform it when authorization was granted.
	The client requests an access token by making an HTTP "POST" request		The client makes a request to the token endpoint by sending the
	to the token endpoint as described in Section 4.1.1 of [RFC6749] .		following parameters using the "application/x-www-form-urlencoded"
	The "redirect_uri" parameter is NOT REQUIRED as part of this request.		format per Appendix B with a character encoding of UTF-8 in the HTTP
			request entity-body:
	3.3. Additional Error Responses		grant_type
	The following error responses are defined in addition to those within		REQUIRED. Value MUST be set to "device_code".
	Section 4.2.2.1. of [RFC6749]:
			device_code
			REQUIRED. The device verification code, "device_code" from the
			Device Authorization Response, defined in Section 3.2.
			client_id
			REQUIRED, if the client is not authenticating with the
			authorization server as described in Section 3.2.1. of [RFC6749]
			For example, the client makes the following HTTPS request (line
			breaks are for display purposes only):
			POST /token HTTP/1.1
			Host: server.example.com
			Content-Type: application/x-www-form-urlencoded
			grant_type=device_code&device_code=pxDoJ3Bt9WVMTXfDATLkxJ9u
			&client_id=459691054427
			Note that unlike the Access Token Request for the authorization_code
			grant type defined in Section 4.1.3 of [RFC6749] the "redirect_uri"
			parameter is NOT REQUIRED as part of this request.
			If the client was issued client credentials (or assigned other
			authentication requirements), the client MUST authenticate with the
			authorization server as described in Section 3.2.1 of [RFC6749].
			3.5. Device Token Response
			If the user has approved the grant, the token endpoint responds with
			a success response defined in Section 5.1 of [RFC6749] otherwise, it
			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],
			the following error codes are specific for the device flow:
	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 visited the authorization server and entered their		yet visited the authorization server and entered their
	verification code.		verification code.
	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
			The device_code has expired. The client will need to make a new
			Device Authorization Request.
			The error code "authorization_pending" and "slow_down" are considered
			soft errors. The the client should continue to poll when receiving
			"authorization_pending" errors, reducing the interval if a
			"slow_down" error is received. Other error codes are considered hard
			errors, the client should stop polling and react accordingly, for
			example, by displaying an error to the user.
	4. Security Considerations		4. Security Considerations
	TBD		TBD
	5. Normative References		5. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<http://www.rfc-editor.org/info/rfc2119>.		<http://www.rfc-editor.org/info/rfc2119>.
End of changes. 18 change blocks.
	35 lines changed or deleted		89 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/