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