< draft-ietf-oauth-device-flow-12.txt   draft-ietf-oauth-device-flow-13.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: February 2, 2019 Ping Identity Expires: April 22, 2019 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
August 1, 2018 October 19, 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-12 draft-ietf-oauth-device-flow-13
Abstract Abstract
This OAuth 2.0 authorization flow for browserless and input- This OAuth 2.0 authorization flow is designed for devices that either
constrained devices, often referred to as the device flow, enables lack a browser to perform a user-agent based OAuth flow, or are
OAuth clients to request user authorization from devices that have an input-constrained to the extent that requiring the user to input a
Internet connection, but don't have an easy input method (such as a lot of text (like their credentials to authenticate with the
smart TV, media console, picture frame, or printer), or lack a authorization server) is impractical. It enables OAuth clients on
suitable browser for a more traditional OAuth flow. This such devices (like smart TVs, media consoles, digital picture frames,
authorization flow instructs the user to perform the authorization and printers) to obtain user authorization to access protected
request on a secondary device, such as a smartphone. There is no resources without using an on-device user-agent, provided that they
requirement for communication between the constrained device and the have an Internet connection.
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 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 February 2, 2019. This Internet-Draft will expire on April 22, 2019.
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 28 skipping to change at page 2, line 23
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. Non-textual Verification URI Optimization . . . . . . 8 3.3.1. Non-textual Verification URI Optimization . . . . . . 9
3.4. Device Access Token Request . . . . . . . . . . . . . . . 9 3.4. Device Access Token Request . . . . . . . . . . . . . . . 9
3.5. Device Access Token Response . . . . . . . . . . . . . . 10 3.5. Device Access Token Response . . . . . . . . . . . . . . 10
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 11 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12
5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12
5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 12 5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13
5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 12 5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13
5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 13 5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13
5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 13 5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14
5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 13 5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14
6. Usability Considerations . . . . . . . . . . . . . . . . . . 13 5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 14
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 14 6. Usability Considerations . . . . . . . . . . . . . . . . . . 14
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16
7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 15 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16
7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 16
7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 16 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 7.3. OAuth Extensions Error Registration . . . . . . . . . . . 16
8. Normative References . . . . . . . . . . . . . . . . . . . . 16 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 17
Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 8. Normative References . . . . . . . . . . . . . . . . . . . . 17
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 18
Appendix B. Document History . . . . . . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
1. Introduction 1. Introduction
This OAuth 2.0 [RFC6749] protocol flow for browserless and input- This OAuth 2.0 [RFC6749] protocol 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 applications on
internet connection, but don't have an easy input method (such as a devices that have an Internet connection, but don't have an easy
smart TV, media console, picture frame, or printer), or lack a input method (such as a smart TV, media console, picture frame, or
suitable browser for a more traditional OAuth flow. This printer), or lack a suitable browser for a more traditional OAuth
authorization flow instructs the user to perform the authorization flow. This authorization flow instructs the user to perform the
request on a secondary device, such as a smartphone. authorization request on a secondary device, 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 follow the practices specified in OAuth 2.0 for Native Apps
[RFC8252]. [RFC8252].
The only requirements to use this flow are that the device is The operating requirements to be able to use this authorization flow
connected to the Internet, and able to make outbound HTTPS requests, are:
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 (1) The device is already connected to the Internet.
computer or smartphone) from which to process the request. There is
no requirement for two-way communication between the OAuth client and (2) The device is able to make outbound HTTPS requests.
the user-agent, enabling a broad range of use-cases.
(3) The device is able to display or otherwise communicate a URI and
code sequence to the user.
(4) The user has a secondary device (e.g., personal computer or
smartphone) from which they can process the request.
As the device flow does not require two-way communication between the
OAuth client and the user-agent (unlike other OAuth 2 flows), it
supports several use cases that cannot be served by those other
approaches.
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
to the authorization server to approve the access request. Since the to the authorization server to approve the access request. Since the
client cannot receive incoming requests, it polls the authorization client cannot receive incoming requests, it polls the authorization
server repeatedly until the end user completes the approval process. server repeatedly until the end user completes the approval process.
The device typically chooses the set of authorization servers to
support (i.e., its own authorization server, or those by providers it
has relationships with). It is not uncommon for the device
application to support only a single authorization server, such as
with a TV application for a specific media provider that supports
only that media provider's authorization server. The user may not
have an established relationship yet with that authorization
provider, though one can potentially be set up during the
authorization flow.
+----------+ +----------------+ +----------+ +----------------+
| |>---(A)-- Client Identifier --->| | | |>---(A)-- Client Identifier --->| |
| | | | | | | |
| |<---(B)-- Verification Code, --<| | | |<---(B)-- Verification Code, --<| |
| | User Code, | | | | User Code, | |
| | & Verification URI | | | | & Verification URI | |
| Device | | | | Device | | |
| Client | Client Identifier & | | | Client | Client Identifier & | |
| |>---(E)-- Verification Code --->| | | |>---(E)-- Verification Code --->| |
| | polling... | | | | polling... | |
skipping to change at page 5, line 45 skipping to change at page 5, line 48
This specification defines a new OAuth endpoint, the device This specification defines a new OAuth endpoint, the device
authorization endpoint. This is separate from the OAuth authorization endpoint. This is separate from the OAuth
authorization endpoint defined in [RFC6749] with which the user authorization endpoint defined in [RFC6749] with which the user
interacts with via a user-agent (i.e., a browser). By comparison, interacts with via a user-agent (i.e., a browser). By comparison,
when using the device authorization endpoint, the OAuth client on the when using the device authorization endpoint, the OAuth client on the
device interacts with the authorization server directly without device interacts with the authorization server directly without
presenting the request in a user-agent, and the end user authorizes presenting the request in a user-agent, and the end user authorizes
the request on a separate device. This interaction is defined as the request on a separate device. This interaction is defined as
follows. follows.
The client initiates the flow by requesting a set of verification The client initiates the authorization flow by requesting a set of
codes from the authorization server by making an HTTP "POST" request verification codes from the authorization server by making an HTTP
to the device authorization endpoint. "POST" request to the device authorization endpoint.
All requests from the device MUST use the Transport Layer Security
(TLS) [RFC5246] protocol and implement the best practices of
[RFC7525].
The client constructs the request with the following parameters, The client constructs the request with the following parameters, sent
encoded with the "application/x-www-form-urlencoded" content type: as the body of the request, encoded with the "application/x-www-form-
urlencoded" encoding algorithm defined by Section 4.10.22.6 of
[HTML5]:
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:
breaks are for display purposes only):
POST /device_authorization 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
client_id=459691054427 client_id=459691054427
All requests from the device MUST use the Transport Layer Security
(TLS) [RFC8446] protocol and implement the best practices of BCP 195
[RFC7525].
Parameters sent without a value MUST be treated as if they were Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters unrecognized request parameters. Request and response parameters
MUST NOT be included more than once. MUST NOT be included more than once.
Due to the polling nature of this protocol, to avoid unneeded Due to the polling nature of this protocol, to avoid unneeded
requests on the token endpoint, the client SHOULD only commence a requests on the token endpoint, the client SHOULD only commence a
device authorization request when prompted by the user, and not device authorization request when prompted by the user, and not
automatically such as when the app starts. automatically such as when the app starts.
3.2. Device Authorization Response 3.2. Device Authorization Response
In response, the authorization server generates a device verification In response, the authorization server generates a unique device
code and an end-user code that are valid for a limited time and verification code and an end-user code that are valid for a limited
includes them in the HTTP response body using the "application/json" time and includes them in the HTTP response body using the
format [RFC8259] with a 200 (OK) status code. The response contains "application/json" format [RFC8259] with a 200 (OK) status code. The
the following parameters: response contains the 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 users server. The URI should be short and easy to remember as end users
skipping to change at page 7, line 26 skipping to change at page 7, line 31
SHOULD wait between polling requests to the token endpoint. If no SHOULD wait between polling requests to the token endpoint. If no
value is provided, clients MUST use 5 as the default. value is provided, clients MUST use 5 as the default.
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": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
"user_code":"WDJB-MJHT", "user_code": "WDJB-MJHT",
"verification_uri":"https://www.example.com/device", "verification_uri": "https://example.com/device",
"verification_uri_complete": "verification_uri_complete":
"https://www.example.com/device?user_code=WDJB-MJHT", "https://example.com/device?user_code=WDJB-MJHT",
"expires_in" : 1800, "expires_in": 1800,
"interval": 5 "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 8, line 19 skipping to change at page 8, line 19
| | | |
| And enter the code: | | And enter the code: |
| WDJB-MJHT | | WDJB-MJHT |
| | | |
+-----------------------------------------------+ +-----------------------------------------------+
Figure 2: Example User Instruction Figure 2: Example User Instruction
The authorizing user navigates to the "verification_uri" and The authorizing user navigates to the "verification_uri" and
authenticates with the authorization server in a secure TLS-protected authenticates with the authorization server in a secure TLS-protected
([RFC5246]) session. The authorization server prompts the end user ([RFC8446]) session. The authorization server prompts the end user
to identify the device authorization session by entering the 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 MAY inform the user to return to their device. complete, the server MAY inform 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. The "device_code" is not intended for the end user error occurs. The "device_code" is not intended for the end user
directly, and thus should not be displayed during the interaction to directly, and thus should not be displayed during the interaction to
avoid confusing the end user. avoid confusing the end user.
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, for example, the authorization server may
enable new users to sign up for an account during the authorization
flow, or add additional security verification steps.
It is NOT RECOMMENDED for authorization servers to include the user It is NOT RECOMMENDED for authorization servers to include the user
code in the verification URI ("verification_uri"), as this increases code in the verification URI ("verification_uri"), as this increases
the length and complexity of the URI that the user must type. The the length and complexity of the URI that the user must type. While
next section documents user interaction with the user must still type the same number of characters with the
"verification_uri_complete", which is designed to carry this user_code separated, once they successfully navigate to the
information. verification_uri, any errors in entering the code can be highlighted
by the authorization server to improve the user experience. The next
section documents user interaction with "verification_uri_complete",
which is designed to carry both pieces of information.
3.3.1. Non-textual Verification URI Optimization 3.3.1. Non-textual Verification URI Optimization
When "verification_uri_complete" is included in the Authorization When "verification_uri_complete" is included in the Authorization
Response (Section 3.2), clients MAY present this URI in a non-textual 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 manner using any method that results in the browser being opened with
the URI, such as with QR (Quick Response) codes or NFC (Near Field the URI, such as with QR (Quick Response) codes or NFC (Near Field
Communication), to save the user typing the URI. Communication), to save the user typing the URI.
For usability reasons, it is RECOMMENDED for clients to still display For usability reasons, it is RECOMMENDED for clients to still display
the textual verification URI ("verification_uri") for users not able the textual verification URI ("verification_uri") for users not able
to use such a shortcut. Clients MUST still display the "user_code", to use such a shortcut. Clients MUST still display the "user_code",
as the authorization server may still require the user to confirm it as the authorization server will require the user to confirm it to
to disambiguate devices, or as a remote phishing mitigation (See disambiguate devices, or as a remote phishing mitigation (See
Section 5.3). Section 5.4).
If the user starts the user interaction by browsing to
"verification_uri_complete", then the user interaction described in
Section 3.3 is still followed, but with the optimization that the
user does not need to type the "user_code". The server SHOULD
display the "user_code" to the user and ask them to verify that it
matches the "user_code" being displayed on the device, to confirm
they are authorizing the correct device. As before, in addition to
taking steps to confirm the identity of the device, the user should
also be afforded the choice to approve or deny the authorization
request.
+-------------------------------------------------+ +-------------------------------------------------+
| | | |
| Scan the QR code, or using +------------+ | | Scan the QR code, or using +------------+ |
| a browser on another device, |[_].. . [_]| | | a browser on another device, |[_].. . [_]| |
| visit: | . .. . .| | | visit: | . .. . .| |
| https://example.com/device | . . . ....| | | https://example.com/device | . . . ....| |
| |. . . . | | | |. . . . | |
| And enter the code: |[_]. ... . | | | And enter the code: |[_]. ... . | |
| WDJB-MJHT +------------+ | | WDJB-MJHT +------------+ |
| | | |
+-------------------------------------------------+ +-------------------------------------------------+
Figure 3: Example User Instruction with QR Code Representation of the Figure 3: Example User Instruction with QR Code Representation of the
Complete Verification URI Complete Verification URI
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 (as defined by Section 3.2 of
[RFC6749]) 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]) created by this
following parameters: specification, with the following parameters:
grant_type grant_type
REQUIRED. Value MUST be set to REQUIRED. Value MUST be set to
"urn:ietf:params:oauth:grant-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
skipping to change at page 10, line 10 skipping to change at page 10, line 28
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=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8 &device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
&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.5. client credentials, see Section 5.6.
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 11, line 14 skipping to change at page 11, line 37
expired_token expired_token
The "device_code" has expired and the device flow authorization The "device_code" has expired and the device flow authorization
session has concluded. The client MAY commence a new Device session has concluded. The client MAY commence a new Device
Authorization Request but SHOULD wait for user interaction before Authorization Request but SHOULD wait for user interaction before
restarting to avoid unnecessary polling. restarting to avoid unnecessary polling.
A client receiving an error response as defined in Section 5.2 of A client receiving an error response as defined in Section 5.2 of
[RFC6749] MUST stop polling and SHOULD react accordingly, for [RFC6749] MUST stop polling and SHOULD react accordingly, for
example, by displaying an error to the user, except for the error example, by displaying an error to the user, except for the error
codes "authorization_pending" and "slow_down" which are be processed codes "authorization_pending" and "slow_down" which are processed as
as described above. described above.
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 (as an completed the action before initiating the token request (as an
alternative to polling). Such behavior is, however, outside the alternative to polling). Such behavior is, however, outside the
skipping to change at page 11, line 46 skipping to change at page 12, line 23
5. Security Considerations 5. Security Considerations
5.1. User Code Brute Forcing 5.1. User Code Brute Forcing
Since the user code is typed by the user, shorter codes are more Since the user code is typed by the user, shorter codes are more
desirable for usability reasons. This means the entropy is typically desirable for usability reasons. This means the entropy is typically
less than would be used for the device code or other OAuth bearer less than would be used for the device code or other OAuth bearer
token types where the code length does not impact usability. It is token types where the code length does not impact usability. It is
therefore recommended that the server rate-limit user code attempts. therefore recommended that the server rate-limit user code attempts.
The user code SHOULD have enough entropy that when combined with rate The user code SHOULD have enough entropy that when combined with rate
limiting and other mitigations makes a brute-force attack infeasible. limiting and other mitigations makes a brute-force attack infeasible.
For example, it's generally held that 128-bit symmetric keys for
encryption are seen as good enough today because an attacker has to
put in 2^96 work to have a 2^-32 chance of guessing correctly via
brute force. The rate limiting and finite lifetime on the user code
places an artificial limit on the amount of work an attacker can
"do", so if, for instance, one uses a 8-character base-20 user code
(with roughly 34.5 bits of entropy), the rate-limiting interval and
validity period would need to only allow 5 attempts in order to get
the same 2^-32 probability of success by random guessing.
A successful brute forcing of the user code would enable the attacker A successful brute forcing of the user code would enable the attacker
to authenticate with their own credentials and make an authorization to authenticate with their own credentials and make an authorization
grant to the device. This is the opposite scenario to an OAuth grant to the device. This is the opposite scenario to an OAuth
bearer token being brute forced, whereby the attacker gains control bearer token being brute forced, whereby the attacker gains control
of the victim's authorization grant. Such attacks may not always of the victim's authorization grant. Such attacks may not always
make economic sense, for example for a video app the device owner may make economic sense, for example for a video app the device owner may
then be able to purchase movies using the attacker's account, though then be able to purchase movies using the attacker's account, though
a privacy risk would still remain and thus is important to protect a privacy risk would still remain and thus is important to protect
against. Furthermore, some uses of the device flow give the granting against. Furthermore, some uses of the device flow give the granting
account the ability to perform actions such as controlling the account the ability to perform actions such as controlling the
device, which needs to be protected. device, which needs to be protected.
The precise length of the user code and the entropy contained within The precise length of the user code and the entropy contained within
is at the discretion of the authorization server, which needs to is at the discretion of the authorization server, which needs to
consider the sensitivity of their specific protected resources, the consider the sensitivity of their specific protected resources, the
practicality of the code length from a usability standpoint, and any practicality of the code length from a usability standpoint, and any
mitigations that are in place such as rate-limiting, when determining mitigations that are in place such as rate-limiting, when determining
the user code format. the user code format.
5.2. Device Trustworthiness 5.2. Device Code Brute Forcing
An attacker who guesses the device code would be able to potentially
obtain the authorization code once the user completes the flow. As
the device code is not displayed to the user and thus there are
usability considerations on the length, a very high entropy code
SHOULD be used.
5.3. Device Trustworthiness
Unlike other native application OAuth 2.0 flows, the device Unlike other native application OAuth 2.0 flows, the device
requesting the authorization is not the same as the device that the requesting the authorization is not the same as the device that the
user grants access from. Thus, signals from the approving user's user grants access from. Thus, signals from the approving user's
session and device are not relevant to the trustworthiness of the session and device are not relevant to the trustworthiness of the
client device. client device.
Note that if an authorization server used with this flow is Note that if an authorization server used with this flow is
malicious, then it could man-in-the-middle the backchannel flow to malicious, then it could man-in-the-middle the backchannel flow to
another authorization server. In this scenario, the man-in-the- another authorization server. In this scenario, the man-in-the-
middle is not completely hidden from sight, as the end user would end middle is not completely hidden from sight, as the end user would end
up on the authorization page of the wrong service, giving them an up on the authorization page of the wrong service, giving them an
opportunity to notice that the authorization being requested is opportunity to notice that the URL in the browser's address bar is
wrong. For this to be possible, the device manufacturer must either wrong. For this to be possible, the device manufacturer must either
directly be the attacker, shipping a device intended to perform the directly be the attacker, shipping a device intended to perform the
man-in-the-middle attack, or be using an authorization server that is man-in-the-middle attack, or be using an authorization server that is
controlled by an attacker, possibly because the attacker compromised controlled by an attacker, possibly because the attacker compromised
the authorization server used by the device. In part, the person the authorization server used by the device. In part, the person
purchasing the device is counting on it and its business partners to purchasing the device is counting on it and its business partners to
be trustworthy. be trustworthy.
5.3. Remote Phishing 5.4. Remote Phishing
It is possible for the device flow to be initiated on a device in an It is possible for the device flow to be initiated on a device in an
attacker's possession. For example, an attacker might send an email attacker's possession. For example, an attacker might send an email
instructing the target user to visit the verification URL and enter instructing the target user to visit the verification URL and enter
the user code. To mitigate such an attack, it is RECOMMENDED to the user code. To mitigate such an attack, it is RECOMMENDED to
inform the user that they are authorizing a device during the user inform the user that they are authorizing a device during the user
interaction step (see Section 3.3), and to confirm that the device is interaction step (see Section 3.3), and to confirm that the device is
in their possession. The authorization server SHOULD display in their possession. The authorization server SHOULD display
information about the device so that the person can notice if a information about the device so that the person can notice if a
software client was attempting to impersonating a hardware device. software client was attempting to impersonating a hardware device.
skipping to change at page 13, line 21 skipping to change at page 14, line 17
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. Session Spying 5.5. Session Spying
While the device is pending authorization, it may be possible for a While the device is pending authorization, it may be possible for a
malicious user to spy on the device user interface and hijack the malicious user to spy on the device user interface and hijack the
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.6. 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.5 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.7. 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. close proximity. E.g., users who can see, or hear the device.
6. Usability Considerations 6. Usability Considerations
skipping to change at page 14, line 45 skipping to change at page 15, line 45
dashes and other punctuation it added for readability (making the dashes and other punctuation it added for readability (making the
inclusion of that punctuation by the user optional). For codes using inclusion of that punctuation by the user optional). For codes using
only characters in the A-Z range as with the base-20 charset defined only characters in the A-Z range as with the base-20 charset defined
above, the user's input should be upper-cased before comparison to above, the user's input should be upper-cased before comparison to
account for the fact that the user may input the equivalent lower- account for the fact that the user may input the equivalent lower-
case characters. Further stripping of all characters outside the case characters. Further stripping of all characters outside the
user_code charset is recommended to reduce instances where an user_code charset is recommended to reduce instances where an
errantly typed character (like a space character) invalidates errantly typed character (like a space character) invalidates
otherwise valid input. otherwise valid input.
It is RECOMMENDED to avoid character sets that contain two or more
characters that can easily be confused with each other like "0" and
"O", or "1", "l" and "I". Furthermore, the extent practical, where a
character set contains one character that may be confused with
characters outside the character set the character outside the set
MAY be substituted with the one in the character set that it is
commonly confused with (for example, "O" for "0" when using a
numerical 0-9 character set).
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 scope interaction other than via the verification URI is outside the scope
of this specification. of this specification.
7. IANA Considerations 7. IANA Considerations
7.1. OAuth URI Registration 7.1. OAuth Parameters 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]. Parameters" registry [IANA.OAuth.Parameters] established by
[RFC6749].
7.1.1. Registry Contents 7.1.1. Registry Contents
o Parameter name: device_code
o Parameter usage location: token request
o Change controller: IESG
o Specification Document: Section 3.1 of [[ this specification ]]
7.2. OAuth URI Registration
This specification registers the following values in the IANA "OAuth
URI" registry [IANA.OAuth.Parameters] established by [RFC6755].
7.2.1. Registry Contents
o URN: urn:ietf:params:oauth:grant-type:device_code o URN: urn:ietf:params:oauth:grant-type:device_code
o Common Name: Device flow grant type for OAuth 2.0 o Common Name: Device flow grant type for OAuth 2.0
o Change controller: IESG o Change controller: IESG
o Specification Document: Section 3.1 of [[ this specification ]] o Specification Document: Section 3.1 of [[ this specification ]]
7.2. OAuth Extensions Error Registration 7.3. OAuth Extensions Error Registration
This specification registers the following values in the IANA "OAuth This specification registers the following values in the IANA "OAuth
Extensions Error Registry" registry [IANA.OAuth.Parameters] Extensions Error Registry" registry [IANA.OAuth.Parameters]
established by [RFC6749]. established by [RFC6749].
7.2.1. Registry Contents 7.3.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 name: access_denied
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 ]]
skipping to change at page 16, line 7 skipping to change at page 17, line 31
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
o Specification Document: Section 3.5 of [[ this specification ]] o Specification Document: Section 3.5 of [[ this specification ]]
7.3. OAuth 2.0 Authorization Server Metadata 7.4. OAuth 2.0 Authorization Server Metadata
This specification registers the following values in the IANA "OAuth This specification registers the following values in the IANA "OAuth
2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters]
established by [RFC8414]. established by [RFC8414].
7.3.1. Registry Contents 7.4.1. Registry Contents
o Metadata name: device_authorization_endpoint o Metadata name: device_authorization_endpoint
o Metadata Description: The Device Authorization Endpoint. o Metadata Description: The Device Authorization Endpoint.
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
[HTML5] IANA, "HTML5",
<https://www.w3.org/TR/2014/REC-html5-20141028/>.
[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>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[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,
<https://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,
<https://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,
skipping to change at page 17, line 23 skipping to change at page 18, line 42
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414, Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018, DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>. <https://www.rfc-editor.org/info/rfc8414>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
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 contributed to those earlier drafts. OAuth working group members who contributed to those earlier drafts.
This document was produced in the OAuth working group under the This document was produced in the OAuth working group under the
chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with
Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as
Security Area Directors. 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:
Brian Campbell, Roshni Chandrashekhar, Eric Fazendin, Torsten Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin
Lodderstedt, James Manger, Breno de Medeiros, Simon Moffatt, Stein Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt,
Myrseth, Justin Richer, Nat Sakimura, Andrew Sciberras, Marius James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin
Scurtescu, Ken Wang, and Steven E. Wright. 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 ]]
-13
o Added a longer discussion about entropy, proposed by Benjamin
Kaduk.
o Added device_code to OAuth IANA registry.
o Expanded explanation of "case insensitive".
o Added security section on Device Code Brute Forcing.
o application/x-www-form-urlencoded normativly referenced.
o Editatorial improvements.
-12 -12
o Set a default polling interval to 5s explicitly. o Set a default polling interval to 5s explicitly.
o Defined the slow_down behavior that it should increase the current o Defined the slow_down behavior that it should increase the current
interval by 5s. interval by 5s.
o expires_in now REQUIRED o expires_in now REQUIRED
o Other changes in response to review feedback. o Other changes in response to review feedback.
-11 -11
o Updated reference to OAuth 2.0 Authorization Server Metadata. o Updated reference to OAuth 2.0 Authorization Server Metadata.
-10 -10
 End of changes. 48 change blocks. 
109 lines changed or deleted 201 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/