draft-ietf-oauth-device-flow-02.txt   draft-ietf-oauth-device-flow-03.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: January 9, 2017 ForgeRock Expires: January 19, 2017 ForgeRock
J. Bradley J. Bradley
Ping Identity Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
July 8, 2016 July 18, 2016
OAuth 2.0 Device Flow OAuth 2.0 Device Flow
draft-ietf-oauth-device-flow-02 draft-ietf-oauth-device-flow-03
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 January 9, 2017. This Internet-Draft will expire on January 19, 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 25 skipping to change at page 2, line 25
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. Device Authorization Request . . . . . . . . . . . . . . 4 3.1. Device Authorization Request . . . . . . . . . . . . . . 4
3.2. Device Authorization Response . . . . . . . . . . . . . . 5 3.2. Device Authorization Response . . . . . . . . . . . . . . 5
3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 6 3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 6
3.4. Device Token Request . . . . . . . . . . . . . . . . . . 6 3.4. Device Token Request . . . . . . . . . . . . . . . . . . 6
3.5. Device Token Response . . . . . . . . . . . . . . . . . . 7 3.5. Device Token Response . . . . . . . . . . . . . . . . . . 7
4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
5. Normative References . . . . . . . . . . . . . . . . . . . . 8 4.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 8
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8
Appendix B. Document History . . . . . . . . . . . . . . . . . . 8 4.2. OAuth Extensions Error Registration . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 4.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6. Normative References . . . . . . . . . . . . . . . . . . . . 9
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9
Appendix B. Document History . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
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 6, line 50 skipping to change at page 6, line 50
minimum interval provided by the authorization server via the minimum interval provided by the authorization server via the
"interval" parameter (if provided). "interval" parameter (if provided).
The client makes a request to the token endpoint by sending the The client makes a request to the token endpoint by sending the
following parameters using the "application/x-www-form-urlencoded" following parameters using the "application/x-www-form-urlencoded"
format per Appendix B with a character encoding of UTF-8 in the HTTP format per Appendix B with a character encoding of UTF-8 in the HTTP
request entity-body: request entity-body:
grant_type grant_type
REQUIRED. Value MUST be set to "device_code". REQUIRED. Value MUST be set to "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
breaks are for display purposes only): breaks are for display purposes only):
skipping to change at page 7, line 15 skipping to change at page 7, line 18
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
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
grant_type=device_code&device_code=pxDoJ3Bt9WVMTXfDATLkxJ9u grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=pxDoJ3Bt9WVMTXfDATLkxJ9u
&client_id=459691054427 &client_id=459691054427
Note that unlike the Access Token Request for the authorization_code Note that unlike the Access Token Request for the authorization_code
grant type defined in Section 4.1.3 of [RFC6749] the "redirect_uri" grant type defined in Section 4.1.3 of [RFC6749] the "redirect_uri"
parameter is NOT REQUIRED as part of this request. parameter is NOT REQUIRED as part of this request.
If the client was issued client credentials (or assigned other If the client was issued client credentials (or assigned other
authentication requirements), the client MUST authenticate with the authentication requirements), the client MUST authenticate with the
authorization server as described in Section 3.2.1 of [RFC6749]. authorization server as described in Section 3.2.1 of [RFC6749].
3.5. Device Token Response 3.5. Device Token Response
skipping to change at page 8, line 17 skipping to change at page 8, line 19
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 code "authorization_pending" and "slow_down" are considered The error code "authorization_pending" and "slow_down" are considered
soft errors. The the client should continue to poll when receiving soft errors. The the client should continue to poll when receiving
"authorization_pending" errors, reducing the interval if a "authorization_pending" errors, reducing the interval 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.
4. Security Considerations 4. IANA Considerations
4.1. OAuth URI Registration
This specification registers the following values in the IANA "OAuth
URI" registry [IANA.OAuth.Parameters] established by [RFC6755].
4.1.1. Registry Contents
o URN: urn:ietf:params:oauth:grant-type:device_code
o Common Name: Device flow grant type for OAuth 2.0
o Change controller: IESG
o Specification Document: Section 3.1 of [[ this specification ]]
4.2. OAuth Extensions Error Registration
This specification registers the following values in the IANA "OAuth
Extensions Error Registry" registry [IANA.OAuth.Parameters]
established by [RFC6749].
4.2.1. Registry Contents
o Error name: authorization_pending
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 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: expired_token
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 ]]
5. Security Considerations
TBD TBD
5. Normative References 6. Normative References
[IANA.OAuth.Parameters]
IANA, "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
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>.
[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,
<http://www.rfc-editor.org/info/rfc6749>. <http://www.rfc-editor.org/info/rfc6749>.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<http://www.rfc-editor.org/info/rfc6755>.
Appendix A. Acknowledgements Appendix A. Acknowledgements
The -00 version of this document was based on draft-recordon-oauth- The -00 version of this document was based on draft-recordon-oauth-
v2-device edited by David Recordon and Brent Goldman. The content of v2-device edited by David Recordon and Brent Goldman. The content of
that document was initially part of the OAuth 2.0 protocol that document was initially part of the OAuth 2.0 protocol
specification but was later removed due to the lack of sufficient specification but was later removed due to the lack of sufficient
deployment expertise at that time. We would therefore also like to deployment expertise at that time. We would therefore also like to
thank the OAuth working group for their work on the initial content thank the OAuth working group for their work on the initial content
of this specification through 2010. of this specification through 2010.
 End of changes. 12 change blocks. 
17 lines changed or deleted 71 lines changed or added

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