< draft-ietf-oauth-device-flow-06.txt   draft-ietf-oauth-device-flow-07.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: December 2, 2017 Ping Identity Expires: May 3, 2018 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
May 31, 2017 October 30, 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-06 draft-ietf-oauth-device-flow-07
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 37 skipping to change at page 1, line 37
user's secondary device. user's secondary device.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 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 December 2, 2017. This Internet-Draft will expire on May 3, 2018.
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 (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
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 Interaction . . . . . . . . . . . . . . . . . . . . 7 3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7
3.3.1. Optimization for Non-textual Verification URIs . . . 8 3.3.1. Non-textual Verification URI Optimization . . . . . . 8
3.4. Device Access Token Request . . . . . . . . . . . . . . . 8 3.4. Device Access Token Request . . . . . . . . . . . . . . . 9
3.5. Device Access Token Response . . . . . . . . . . . . . . 9 3.5. Device Access Token Response . . . . . . . . . . . . . . 10
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 10 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 11
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11
5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 11 5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 11
5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 11 5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 11
5.4. Non-confidential Clients . . . . . . . . . . . . . . . . 11 5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 12
5.5. Non-Visual Code Transmission . . . . . . . . . . . . . . 12 5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 12
5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 12
6. Usability Considerations . . . . . . . . . . . . . . . . . . 12 6. Usability Considerations . . . . . . . . . . . . . . . . . . 12
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 12 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 13
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 12 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 13
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 13 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
7.2. OAuth Extensions Error Registration . . . . . . . . . . . 13 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 14
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 14 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 14
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
8. Normative References . . . . . . . . . . . . . . . . . . . . 14 8. Normative References . . . . . . . . . . . . . . . . . . . . 15
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15
Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17
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,
such as a smartphone. such as a smartphone.
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 OAuth 2.0 follow the practices specified in OAuth 2.0 for Native Apps OAuth 2.0
for Native Apps [I-D.ietf-oauth-native-apps]. for Native Apps [RFC8252].
The only requirements to use this flow are that the device is The only requirements to use this flow are that the device is
connected to the Internet, and able to make outbound HTTPS requests, connected to the Internet, and able to make outbound HTTPS requests,
be able to display or otherwise communicate a URI and code sequence be able to display or otherwise communicate a URI and code sequence
to the user, and that the user has a secondary device (e.g., personal to the user, and that the user has a secondary device (e.g., personal
computer or smartphone) from which to process the request. There is computer or smartphone) from which to process the request. There is
no requirement for two-way communication between the OAuth client and no requirement for two-way communication between the OAuth client and
the user-agent, enabling a broad range of use-cases. the user-agent, enabling a broad range of use-cases.
Instead of interacting with the end-user's user-agent, the client Instead of interacting with the end-user's user-agent, the client
skipping to change at page 5, line 6 skipping to change at page 5, line 6
order to grant access. order to grant access.
(D) The authorization server authenticates the end-user (via the (D) The authorization server authenticates the end-user (via the
user-agent) and prompts the end-user to grant the client's access user-agent) and prompts the end-user to grant the client's access
request. If the end-user agrees to the client's access request, request. If the end-user agrees to the client's access request,
the end-user enters the end-user code provided by the client. The the end-user enters the end-user code provided by the client. The
authorization server validates the end-user code provided by the authorization server validates the end-user code provided by the
end-user. end-user.
(E) While the end-user authorizes (or denies) the client's request (E) While the end-user authorizes (or denies) the client's request
(D), the client repeatedly polls the authorization server to find (step D), the client repeatedly polls the authorization server to
out if the end-user completed the end-user authorization step. find out if the end-user completed the end-user authorization
The client includes the verification code and its client step. The client includes the verification code and its client
identifier. identifier.
(F) Assuming the end-user granted access, the authorization server (F) Assuming the end-user granted access, the authorization server
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
skipping to change at page 6, line 35 skipping to change at page 6, line 35
following parameters: following parameters:
device_code device_code
REQUIRED. The device 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
users will be asked to manually type it into their user-agent. will be asked to manually type it into their user-agent.
verification_uri_complete
OPTIONAL. A verification URI that includes the "user_code" (or
other information with the same function as the "user_code"),
designed for non-textual transmission.
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",
"expires_in" : 1800, "verification_uri_complete":"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 7, line 49 skipping to change at page 7, line 50
session. The authorization server prompts the end-user to identify session. The authorization server prompts the end-user to identify
the device authorization session by entering the "user_code" provided the device authorization session by entering the "user_code" provided
by the client. The authorization server should then inform the user by the client. The authorization server should then inform the user
about the action they are undertaking, and ask them to approve or about the action they are undertaking, and ask them to approve or
deny the request. Once the user interaction is complete, the server deny the request. Once the user interaction is complete, the server
informs the user to return to their device. informs the user to return to their device.
During the user interaction, the device continuously polls the token 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. The "device_code" is not intended for the end-user and
MUST NOT be displayed or communicated.
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.
3.3.1. Optimization for Non-textual Verification URIs It is NOT RECOMMENDED for authorization servers to include the user
code in the verification URI ("verification_uri"), as this increases
Clients MAY present the verification URI in a non-textual manner the length and complexity of the URI that the user must type. The
using any method that results in the browser being opened with the next section documents user interaction with
URI, such as with QR codes, or NFC, to save the user typing the URI. "verification_uri_complete", which is designed to carry this
For usability reasons, it is RECOMMENDED for clients to still display information.
the unmodified verification URI for users not able to use such a
shortcut.
To optimize the user interaction for such non-textual verification 3.3.1. Non-textual Verification URI Optimization
URI transmission, clients MAY include the user code as part of the
verification URI using the URI parameter "user_code".
An example verification URI with the user code included: When "verification_uri_complete" is included in the Authorization
Response (Section 3.2), clients MAY present this URI in a non-textual
manner using any method that results in the browser being opened with
the URI, such as with QR codes or NFC, to save the user typing the
URI.
https://example.com/device?user_code=WDJB-MJHT For usability reasons, it is RECOMMENDED for clients to still display
the textual verification URI ("verification_uri") for users not able
to use such a shortcut. Clients MUST still display the "user_code",
as the authorization server may still require the user to confirm it
to disambiguate devices, or as a remote phishing mitigation (See
Section 5.3).
When the user code is included in the verification URI in this way, +-------------------------------------------------+
it is considered as a hint to the authorization server to enable | |
potential optimizations. The authorization server MAY use this hint | Using a browser on another +------------+ |
to optimize the user interaction (such as by removing the need for | device, visit: |[_].. . [_]| |
the user to type the code), it MAY also ignore it completely. The | https://example.com/device | . .. . .| |
client MUST still display the user code textually, for authorization | | . . . ....| |
servers that require users to input the user code manually, or | |. . . . | |
otherwise use the user code as part of a visual confirmation step. | And enter the code: |[_]. ... . | |
| WDJB-MJHT +------------+ |
| |
+-------------------------------------------------+
This optimization is intended for non-textual transmission of the Figure 3: Example User Instruction With QR Code Representation of the
verification URI, it is NOT RECOMMENDED to include the user code in Complete Verification URI
verification URIs shown textually, as this increases the length and
complexity of the URI that the user must type.
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
skipping to change at page 9, line 28 skipping to change at page 9, line 40
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8 &device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
&client_id=459691054427 &client_id=459691054427
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].
Note that there are security implications of statically distributed Note that there are security implications of statically distributed
client credentials, see Section 5.4. client credentials, see Section 5.5.
The response to this request is defined in Section 3.5. Unlike other The response to this request is defined in Section 3.5. Unlike other
OAuth grant types, it is expected for the client to try the Access OAuth grant types, it is expected for the client to try the Access
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
skipping to change at page 10, line 25 skipping to change at page 10, line 42
"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 standard OAuth error "invalid_grant". Clients MAY then
choose to start a new device authorization session. 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). If no interval was provided, the client
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
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. Such completed the action before initiating the token request. Such
behavior is, however, outside the scope of this specification. behavior is, however, outside the scope of this specification.
skipping to change at page 11, line 47 skipping to change at page 12, line 15
is being displayed on the device they are setting up. is being displayed on the device they are setting up.
The user code needs to have a long enough lifetime to be useable The user code needs to have a long enough lifetime to be useable
(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.4. Non-confidential Clients 5.4. Session Spying
While the device is pending authorization, it may be possible for a
malicious user to spy on the device user interface and hijack the
session by completing the authorization faster than the user that
initiated it. Devices SHOULD take into account the operating
environment when considering how to communicate the code to the user
to reduce the chances it will be observed by a malicious user.
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.9 of
[I-D.ietf-oauth-native-apps] apply. [RFC8252] apply.
5.5. 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
close proximity. E.g., users who can see, or hear the device, or close proximity. E.g., users who can see, or hear the device, or
within range of a short-range wireless signal. within range of a short-range wireless signal.
skipping to change at page 12, line 35 skipping to change at page 13, line 17
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 vowels to avoid randomly creation valid 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, is "WDJB-MJHT". 20^8: "WDJB-MJHT".
Pure numeric codes are also a good choice for usability, especially
for clients targeting locales where A-Z character keyboards are not
used, through their length needs to be longer to maintain a high
entropy.
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
Devices and authorization servers MAY negotiate an alternative code Devices and authorization servers MAY negotiate an alternative code
transmission and user interaction method in addition to the one transmission and user interaction method in addition to the one
described in Section 3.3. Such an alternative user interaction flow described in Section 3.3. Such an alternative user interaction flow
could obviate the need for a browser and manual input of the code, could obviate the need for a browser and manual input of the code,
for example, by using Bluetooth to transmit the code to the for example, by using Bluetooth to transmit the code to the
authorization server's companion app. Such interaction methods can authorization server's companion app. Such interaction methods can
utilize this protocol, as ultimately, the user just needs to identify utilize this protocol, as ultimately, the user just needs to identify
the authorization session to the authorization server; however, user the authorization session to the authorization server; however, user
interaction other than via the "verification_uri" is outside the interaction other than via the verification URI is outside the scope
scope of this specification. 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
skipping to change at page 14, line 25 skipping to change at page 15, line 19
o Change controller: IESG o Change controller: IESG
o Specification Document: Section 4 of [[ this specification ]] o Specification Document: Section 4 of [[ this specification ]]
8. Normative References 8. Normative References
[I-D.ietf-oauth-discovery] [I-D.ietf-oauth-discovery]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", draft-ietf-oauth- Authorization Server Metadata", draft-ietf-oauth-
discovery-05 (work in progress), January 2017. discovery-05 (work in progress), January 2017.
[I-D.ietf-oauth-native-apps]
Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
draft-ietf-oauth-native-apps-07 (work in progress),
January 2017.
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
<http://www.iana.org/assignments/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>. <https://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>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<http://www.rfc-editor.org/info/rfc6755>. <https://www.rfc-editor.org/info/rfc6755>.
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013, DOI 10.17487/RFC6819, January 2013,
<http://www.rfc-editor.org/info/rfc6819>. <https://www.rfc-editor.org/info/rfc6819>.
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>.
Appendix A. Acknowledgements Appendix A. Acknowledgements
The -00 version of this document was based on draft-recordon-oauth- The starting point for this document was the Internet-Draft draft-
v2-device edited by David Recordon and Brent Goldman. The content of recordon-oauth-v2-device, authored by David Recordon and Brent
that document was initially part of the OAuth 2.0 protocol Goldman, which itself was based on content in draft versions of the
specification but was later removed due to the lack of sufficient OAuth 2.0 protocol specification removed prior to publication due to
deployment expertise at that time. We would therefore also like to a then lack of sufficient deployment expertise. Thank you to the
thank the OAuth working group for their work on the initial content OAuth working group members who worked on this specification through
of this specification through 2010. 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, Simon Moffatt, Brian Campbell, James Manger, and Justin Myrseth, Simon Moffatt, Brian Campbell, James Manger, Justin Richer,
Richer. Ken Wang, Steven E. Wright, Nat Sakimura, and Torsten Lodderstedt.
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 ]]
-07
o Replaced the "user_code" URI parameter optimization with
verification_uri_complete following the IETF99 working group
discussion.
o Added security consideration about spying.
o Required that device_code not be shown.
o Added text regarding a minimum polling interval.
-06 -06
o Clarified usage of the "user_code" URI parameter optimization o Clarified usage of the "user_code" URI parameter optimization
following the IETF98 working group discussion. following the IETF98 working group discussion.
-05 -05
o response_type parameter removed from authorization request. o response_type parameter removed from authorization request.
o Added option for clients to include the user_code on the o Added option for clients to include the user_code on the
verification URI. verification URI.
 End of changes. 39 change blocks. 
93 lines changed or deleted 132 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/