< draft-ietf-oauth-device-flow-04.txt   draft-ietf-oauth-device-flow-05.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: August 31, 2017 Ping Identity Expires: September 14, 2017 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
February 27, 2017 March 13, 2017
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-04 draft-ietf-oauth-device-flow-05
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 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 August 31, 2017. This Internet-Draft will expire on September 14, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 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 28 skipping to change at page 2, line 28
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Device Authorization Request . . . . . . . . . . . . . . 5 3.1. Device Authorization Request . . . . . . . . . . . . . . 5
3.2. Device Authorization Response . . . . . . . . . . . . . . 6 3.2. Device Authorization Response . . . . . . . . . . . . . . 6
3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 7 3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 7
3.4. Device Access Token Request . . . . . . . . . . . . . . . 7 3.4. Device Access Token Request . . . . . . . . . . . . . . . 8
3.5. Device Access Token Response . . . . . . . . . . . . . . 8 3.5. Device Access Token Response . . . . . . . . . . . . . . 9
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 9 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 10 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 10
5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 10 5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 10
5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 10 5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 10
5.4. Non-confidential Clients . . . . . . . . . . . . . . . . 10 5.4. Non-confidential Clients . . . . . . . . . . . . . . . . 11
5.5. Non-Visual Code Transmission . . . . . . . . . . . . . . 10 5.5. Non-Visual Code Transmission . . . . . . . . . . . . . . 11
6. Usability Considerations . . . . . . . . . . . . . . . . . . 11 6. Usability Considerations . . . . . . . . . . . . . . . . . . 11
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 11 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 11
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 12
7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 11 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 12
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12
7.2. OAuth Extensions Error Registration . . . . . . . . . . . 12 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 12
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12
7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 12 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 13
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 13
8. Normative References . . . . . . . . . . . . . . . . . . . . 12 8. Normative References . . . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14
Appendix B. Document History . . . . . . . . . . . . . . . . . . 13 Appendix B. Document History . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
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
the user to perform the authorization request on a secondary device, the user to perform the authorization request on a secondary device,
skipping to change at page 5, line 22 skipping to change at page 5, line 22
validates the verification code provided by the client and validates the verification code provided by the client and
responds back with the access token. responds back with the access token.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119]. [RFC2119].
Device Endpoint: Device Authorization Endpoint:
The authorization server's endpoint capable of issuing The authorization server's endpoint capable of issuing device
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 server, 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. Protocol 3. Protocol
3.1. Device Authorization Request 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 authorization endpoint. The client constructs the
adding the following parameters to the request: request with the following parameters, encoded with the "application/
x-www-form-urlencoded" content type:
response_type
REQUIRED. The parameter value MUST be set to "device_code".
client_id client_id
REQUIRED. The client identifier as described in Section 2.2 of REQUIRED. The client identifier as described in Section 2.2 of
[RFC6749]. [RFC6749].
scope scope
OPTIONAL. The scope of the access request as described by OPTIONAL. The scope of the access request as described by
Section 3.3 of [RFC6749]. Section 3.3 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 /device_authorization 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=459691054427 client_id=459691054427
Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters
MUST NOT be included more than once.
3.2. Device Authorization Response 3.2. Device Authorization Response
In response, the authorization server generates a verification code In response, the authorization server generates a device verification
and an end-user code and includes them in the HTTP response body code and an end-user code that are valid for a limited time, and
using the "application/json" format with a 200 (OK) status code. The includes them in the HTTP response body using the "application/json"
response contains the following parameters: format with a 200 (OK) status code. The response contains the
following parameters:
device_code device_code
REQUIRED. The verification code. REQUIRED. The device verification code.
user_code user_code
REQUIRED. The end-user verification code. REQUIRED. The end-user verification code.
verification_uri verification_uri
REQUIRED. The end-user verification URI on the authorization REQUIRED. The end-user verification URI on the authorization
server. The URI should be short and easy to remember as end- server. The URI should be short and easy to remember as end-
users will be asked to manually type it into their user-agent. users will be asked to manually type it into their user-agent.
expires_in expires_in
OPTIONAL. The duration in seconds of the verification code OPTIONAL. The lifetime in seconds of the "device_code" and
lifetime. "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
skipping to change at page 7, line 21 skipping to change at page 7, line 33
on their mobile phone), and enter the user code. on their mobile phone), and enter the user code.
The end-user navigates to the "verification_uri" and authenticates The end-user navigates to the "verification_uri" and authenticates
with the authorization server. The authorization server prompts the with the authorization server. The authorization server prompts the
end-user to identify the device authorization session by entering the end-user to identify the device authorization session by entering the
"user_code" provided by the client. The authorization server should "user_code" provided by the client. The authorization server should
then inform the user about the action they are undertaking, and ask then inform the user about the action they are undertaking, and ask
them to approve or deny the request. Once the user interaction is them to approve or deny the request. Once the user interaction is
complete, the server informs the user to return to their device. complete, the server informs the user to return to their device.
During this user interaction, the device continuously polls the token Clients MAY additionally present the verification URI in a non-
textual manner using any method that results in a the browser being
opened with the URI, like QR codes, or NFC, to save the user typing
the URI. For such shortcuts, the client MAY include the user code
with the parameter "user_code" on the verification URI, as a hint for
the authorization server. The server MAY accept this hint, and skip
the user code input step, however the client MUST still display the
user code, as the server MAY also ignore the hint or require visual
confirmation. Clients SHOULD still display the unmodified
verification URI for users not able to use such a shortcut.
During the user interaction, the device continuously polls the token
endpoint with the "device_code", as detailed in Section 3.4, until endpoint with the "device_code", as detailed in Section 3.4, until
the user completes the interaction, the code expires, or another the user completes the interaction, the code expires, or another
error occurs. error occurs.
Authorization servers supporting this specification MUST implement a Authorization servers supporting this specification MUST implement a
user interaction sequence that starts with the user navigating to user interaction sequence that starts with the user navigating to
"verification_uri" and continues with them supplying the "user_code" "verification_uri" and continues with them supplying the "user_code"
at some stage during the interaction. Other than that, the exact at some stage during the interaction. Other than that, the exact
sequence and implementation of the user interaction is up to the sequence and implementation of the user interaction is up to the
authorization server, and is out of scope of this specification. authorization server, and is out of scope of this specification.
Devices and authorization servers MAY negotiate an alternative code
transmission and user interaction method in addition to the one
described here. Such an alternative user interaction flow could
obviate the need for a browser and manual input of the code, for
example, by using Bluetooth to transmit the code to the authorization
server's companion app. Such interaction methods can utilize this
protocol, as ultimately, the user just needs to identify the
authorization session to the authorization server, however user
interaction other than via the "verification_uri" is outside the
scope of this specification.
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 "urn:ietf:params:oauth:grant-
skipping to change at page 9, line 23 skipping to change at page 9, line 36
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
with the standard OAuth error "invalid_grant". Clients MAY then
choose to 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). Response (see Section 3.2).
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
skipping to change at page 11, line 27 skipping to change at page 11, line 41
For many users, their nearest Internet-connected device will be their For many users, their nearest Internet-connected device will be their
mobile phone, and typically these devices offer input methods that mobile phone, and typically these devices offer input methods that
are more time consuming than a computer keyboard to change the case are more time consuming than a computer keyboard to change the case
or input numbers. To improve usability (improving entry speed, and or input numbers. To improve usability (improving entry speed, and
reducing retries), these limitations should be taken into account reducing retries), these limitations should be taken into account
when selecting the user-code character set. when selecting the user-code character set.
One way to improve input speed is to restrict the character set to One way to improve input speed is to restrict the character set to
case-insensitive A-Z characters, with no digits. These characters case-insensitive A-Z characters, with no digits. These characters
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 the I and O characters due to potential keys. Further removing vowels to avoid randomly creation valid words
confusion with numbers results in the base-24 character set: results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes
"ABCDEFGHJKLMNPQRSTUVWXYZ". Dashes or other punctuation may be or other punctuation may be included for readability.
included for readability.
An example user code following this guideline, with 24^8 bits of An example user code following this guideline, with an entropy of
entropy, is "WDJB-MJHT". 20^8, is "WDJB-MJHT".
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
Devices and authorization servers MAY negotiate an alternative code
transmission and user interaction method in addition to the one
described in Section 3.3. Such an alternative user interaction flow
could obviate the need for a browser and manual input of the code,
for example, by using Bluetooth to transmit the code to the
authorization server's companion app. Such interaction methods can
utilize this protocol, as ultimately, the user just needs to identify
the authorization session to the authorization server; however, user
interaction other than via the "verification_uri" is outside the
scope of this specification.
7. IANA Considerations 7. IANA Considerations
7.1. OAuth URI Registration 7.1. OAuth URI Registration
This specification registers the following values in the IANA "OAuth This specification registers the following values in the IANA "OAuth
URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. URI" registry [IANA.OAuth.Parameters] established by [RFC6755].
7.1.1. Registry Contents 7.1.1. Registry Contents
o URN: urn:ietf:params:oauth:grant-type:device_code o URN: urn:ietf:params:oauth:grant-type:device_code
skipping to change at page 13, line 46 skipping to change at page 14, line 24
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.
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 Roshni Chandrashekhar, Marius Scurtescu, Breno de Medeiros, Stein
Myrseth, and Simon Moffatt. Myrseth, Simon Moffatt, Brian Campbell, James Manger, and Justin
Richer.
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 ]]
-05
o response_type parameter removed from authorization request.
o Added option for clients to include the user_code on the
verification URI.
o Clarified token expiry, and other nits.
-04 -04
o Security & Usability sections. OAuth Discovery Metadata. o Security & Usability sections. OAuth Discovery Metadata.
-03 -03
o device_code is now a URN. Added IANA Considerations o device_code is now a URN. Added IANA Considerations
-02 -02
o Added token request & response specification. o Added token request & response specification.
 End of changes. 24 change blocks. 
54 lines changed or deleted 84 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/