< draft-ietf-oauth-device-flow-14.txt   draft-ietf-oauth-device-flow-15.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: July 20, 2019 Ping Identity Expires: September 12, 2019 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
January 16, 2019 March 11, 2019
OAuth 2.0 Device Flow for Browserless and Input Constrained Devices OAuth 2.0 Device Authorization Grant
draft-ietf-oauth-device-flow-14 draft-ietf-oauth-device-flow-15
Abstract Abstract
This OAuth 2.0 authorization flow is designed for devices that either The OAuth 2.0 Device Authorization Grant is designed for internet-
lack a browser to perform a user-agent based OAuth flow, or are connected devices that either lack a browser to perform a user-agent
input-constrained to the extent that requiring the user to input a based authorization, or are input-constrained to the extent that
lot of text (like their credentials to authenticate with the requiring the user to input text in order to authenticate during the
authorization server) is impractical. It enables OAuth clients on authorization flow is impractical. It enables OAuth clients on such
such devices (like smart TVs, media consoles, digital picture frames, devices (like smart TVs, media consoles, digital picture frames, and
and printers) to obtain user authorization to access protected printers) to obtain user authorization to access protected resources
resources without using an on-device user-agent, provided that they without using an on-device user-agent.
have an Internet connection.
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 July 20, 2019. This Internet-Draft will expire on September 12, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 21 skipping to change at page 2, line 21
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 . . . . . . . . . . . . . . 7
3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7 3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 8
3.3.1. Non-textual Verification URI Optimization . . . . . . 9 3.3.1. Non-textual Verification URI Optimization . . . . . . 9
3.4. Device Access Token Request . . . . . . . . . . . . . . . 9 3.4. Device Access Token Request . . . . . . . . . . . . . . . 10
3.5. Device Access Token Response . . . . . . . . . . . . . . 10 3.5. Device Access Token Response . . . . . . . . . . . . . . 11
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12
5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 13
5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13 5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13
5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13 5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 14
5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13 5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 14
5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14 5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 15
5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14 5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 15
5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 15 5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 15
6. Usability Considerations . . . . . . . . . . . . . . . . . . 15 6. Usability Considerations . . . . . . . . . . . . . . . . . . 15
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 16
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 17
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16 7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 17
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 17 7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 17
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
7.3. OAuth Extensions Error Registration . . . . . . . . . . . 17 7.3. OAuth Extensions Error Registration . . . . . . . . . . . 17
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 18 7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 18
7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
8. Normative References . . . . . . . . . . . . . . . . . . . . 18 8. Normative References . . . . . . . . . . . . . . . . . . . . 18
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 Appendix B. Document History . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction 1. Introduction
This OAuth 2.0 [RFC6749] protocol extension known as the "device This OAuth 2.0 [RFC6749] protocol extension, sometimes referred to as
flow" enables OAuth clients to request user authorization from "device flow", enables OAuth clients to request user authorization
applications on devices that have limited input capabilities or lack from applications on devices that have limited input capabilities or
a suitable browser. Such devices include those smart TVs, media lack a suitable browser. Such devices include those smart TVs, media
console, picture frames and printers which lack an easy input method console, picture frames and printers which lack an easy input method
or suitable browser required for a more traditional OAuth flow. This or suitable browser required for traditional OAuth interactions. The
authorization flow instructs the user to perform the authorization authorization flow defined by this specification instructs the user
request on a secondary device, such as a smartphone which does have to review the authorization request on a secondary device, such as a
the requisite input and browser capabilities for an OAuth flow. smartphone which does have the requisite input and browser
capabilities to complete the user interaction.
The device flow is not intended to replace browser-based OAuth in The Device Authorization Grant is not intended to replace browser-
native apps on capable devices (like smartphones). Those apps should based OAuth in native apps on capable devices like smartphones.
follow the practices specified in OAuth 2.0 for Native Apps Those apps should follow the practices specified in OAuth 2.0 for
[RFC8252]. Native Apps [RFC8252].
The operating requirements to be able to use this authorization flow The operating requirements to be able to use this authorization grant
are: type are:
(1) The device is already connected to the Internet. (1) The device is already connected to the Internet.
(2) The device is able to make outbound HTTPS requests. (2) The device is able to make outbound HTTPS requests.
(3) The device is able to display or otherwise communicate a URI and (3) The device is able to display or otherwise communicate a URI and
code sequence to the user. code sequence to the user.
(4) The user has a secondary device (e.g., personal computer or (4) The user has a secondary device (e.g., personal computer or
smartphone) from which they can process the request. smartphone) from which they can process the request.
As the device flow does not require two-way communication between the As the device authorization grant does not require two-way
OAuth client and the user-agent (unlike other OAuth 2 flows), it communication between the OAuth client and the user-agent (unlike
supports several use cases that cannot be served by those other other OAuth 2 grant types such as the Authorization Code and Implicit
approaches. grant types), 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 protocol supports clients that can't receive incoming requests,
server repeatedly until the end user completes the approval process. clients poll the authorization server repeatedly until the end user
completes the approval process.
The device typically chooses the set of authorization servers to The device typically chooses the set of authorization servers to
support (i.e., its own authorization server, or those by providers it support (i.e., its own authorization server, or those by providers it
has relationships with). It is not uncommon for the device has relationships with). It is not uncommon for the device
application to support only a single authorization server, such as application to support only a single authorization server, such as
with a TV application for a specific media provider that supports with a TV application for a specific media provider that supports
only that media provider's authorization server. The user may not only that media provider's authorization server. The user may not
have an established relationship yet with that authorization have an established relationship yet with that authorization
provider, though one can potentially be set up during the provider, though one can potentially be set up during the
authorization flow. authorization flow.
+----------+ +----------------+ +----------+ +----------------+
| |>---(A)-- Client Identifier --->| | | |>---(A)-- Client Identifier --->| |
| | | | | | | |
| |<---(B)-- Verification Code, --<| | | |<---(B)-- Device Code, ---<| |
| | User Code, | | | | User Code, | |
| | & Verification URI | | | Device | & Verification URI | |
| Device | | | | Client | | |
| Client | Client Identifier & | | | | [polling] | |
| |>---(E)-- Verification Code --->| | | |>---(E)-- Device Code, --->| |
| | polling... | | | | & Client Identifier | |
| |>---(E)-- Verification Code --->| |
| | | Authorization | | | | Authorization |
| |<---(F)-- Access Token --------<| Server | | |<---(F)-- Access Token ---<| Server |
+----------+ (w/ Optional Refresh Token) | | +----------+ (& Optional Refresh Token) | |
v | | v | |
: | | : | |
(C) User Code & Verification URI | | (C) User Code & Verification URI | |
: | | : | |
v | | v | |
+----------+ | | +----------+ | |
| End user | | | | End user | | |
| at |<---(D)-- User authenticates -->| | | at |<---(D)-- End user reviews --->| |
| Browser | | | | Browser | authorization request | |
+----------+ +----------------+ +----------+ +----------------+
Figure 1: Device Flow. Figure 1: Device Authorization Flow
The device flow illustrated in Figure 1 includes the following steps: The device authorization flow illustrated in Figure 1 includes the
following steps:
(A) The client requests access from the authorization server and (A) The client requests access from the authorization server and
includes its client identifier in the request. includes its client identifier in the request.
(B) The authorization server issues a verification code, an end- (B) The authorization server issues a device code, an end-user
user code, and provides the end-user verification URI. code, and provides the end-user verification URI.
(C) The client instructs the end user to use its user agent (C) The client instructs the end user to use its user agent (on
(elsewhere) and visit the provided end-user verification URI. The another device) and visit the provided end-user verification URI.
client provides the user with the end-user code to enter in order The client provides the user with the end-user code to enter in
to grant access. order to review the authorization request.
(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 user to grant the client's access user agent) and prompts the user to grant the client's access
request. If the user agrees to the client's access request, the request. If the user agrees to the client's access request, the
user enters the user code provided by the client. The user enters the user code provided by the client. The
authorization server validates the user code provided by the user. authorization server validates the user code provided by the user.
(E) While the end user authorizes (or denies) the client's request (E) While the end user reviews the client's request (step D), the
(step D), the client repeatedly polls the authorization server to client repeatedly polls the authorization server to find out if
find out if the user completed the user authorization step. The the user completed the user authorization step. The client
client includes the verification code and its client identifier. includes the verification code and its client identifier.
(F) Assuming the end user granted access, the authorization server (F) The authorization server validates the verification code
validates the verification code provided by the client and provided by the client and responds back with the access token if
responds back with the access token. the user granted access, an error if they denied access, or
indicates that the client should continue to poll.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Device Authorization Endpoint: Device Authorization Endpoint:
skipping to change at page 6, line 11 skipping to change at page 6, line 15
The client initiates the authorization flow by requesting a set of The client initiates the authorization flow by requesting a set of
verification codes from the authorization server by making an HTTP verification codes from the authorization server by making an HTTP
"POST" request to the device authorization endpoint. "POST" request to the device authorization endpoint.
The client constructs the request with the following parameters, sent The client constructs the request with the following parameters, sent
as the body of the request, encoded with the "application/x-www-form- as the body of the request, encoded with the "application/x-www-form-
urlencoded" encoding algorithm defined by Section 4.10.22.6 of urlencoded" encoding algorithm defined by Section 4.10.22.6 of
[HTML5]: [HTML5]:
client_id client_id
REQUIRED. The client identifier as described in Section 2.2 of REQUIRED, if the client is not authenticating with the
[RFC6749]. authorization server as described in Section 3.2.1. of [RFC6749].
The client identifier as described in Section 2.2 of [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: For example, the client makes the following HTTPS request:
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
skipping to change at page 6, line 35 skipping to change at page 6, line 40
All requests from the device MUST use the Transport Layer Security All requests from the device MUST use the Transport Layer Security
(TLS) [RFC8446] protocol and implement the best practices of BCP 195 (TLS) [RFC8446] protocol and implement the best practices of BCP 195
[RFC7525]. [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, care is needed to avoid The client authentication requirements of Section 3.2.1 of [RFC6749]
overloading the capacity of the token endpoint. To avoid unneeded apply to requests on this endpoint, which means that confidential
requests on the token endpoint, the client SHOULD only commence a clients (those that have established client credentials) authenticate
device authorization request when prompted by the user, and not in the same manner as when making requests to the token endpoint, and
automatically such as when the app starts or when the previous public clients provide the "client_id" parameter to identify
authorization session expires or fails. themselves.
Due to the polling nature of this protocol (as specified in
Section 3.4), care is needed to avoid overloading the capacity of the
token endpoint. To avoid unneeded requests on the token endpoint,
the client SHOULD only commence a device authorization request when
prompted by the user, and not automatically, such as when the app
starts or when the previous authorization session expires or fails.
3.2. Device Authorization Response 3.2. Device Authorization Response
In response, the authorization server generates a unique device In response, the authorization server generates a unique device
verification code and an end-user code that are valid for a limited verification code and an end-user code that are valid for a limited
time and includes them in the HTTP response body using the time and includes them in the HTTP response body using the
"application/json" format [RFC8259] with a 200 (OK) status code. The "application/json" format [RFC8259] with a 200 (OK) status code. The
response contains the following parameters: response contains the following parameters:
device_code device_code
skipping to change at page 7, line 43 skipping to change at page 8, line 5
{ {
"device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS", "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
"user_code": "WDJB-MJHT", "user_code": "WDJB-MJHT",
"verification_uri": "https://example.com/device", "verification_uri": "https://example.com/device",
"verification_uri_complete": "verification_uri_complete":
"https://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
} }
In the event of an error (such as an invalidly configured client),
the authorization server responds in the same way as the token
endpoint specified in Section 5.2 of [RFC6749].
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 46 skipping to change at page 9, line 9
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, for example, the authorization server may authorization server, for example, the authorization server may
enable new users to sign up for an account during the authorization enable new users to sign up for an account during the authorization
flow, or add additional security verification steps. 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. While the length and complexity of the URI that the user must type. While
the user must still type the same number of characters with the the user must still type the same number of characters with the
user_code separated, once they successfully navigate to the "user_code" separated, once they successfully navigate to the
verification_uri, any errors in entering the code can be highlighted "verification_uri", any errors in entering the code can be
by the authorization server to improve the user experience. The next highlighted by the authorization server to improve the user
section documents user interaction with "verification_uri_complete", experience. The next section documents user interaction with
which is designed to carry both pieces of information. "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
skipping to change at page 10, line 19 skipping to change at page 10, line 40
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
REQUIRED, if the client is not authenticating with the REQUIRED, if the client is not authenticating with the
authorization server as described in Section 3.2.1. of [RFC6749]. authorization server as described in Section 3.2.1. of [RFC6749].
The client identifier as described in Section 2.2 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=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS &device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
skipping to change at page 11, line 6 skipping to change at page 11, line 31
Token Request repeatedly in a polling fashion, based on the error Token Request repeatedly in a polling fashion, based on the error
code in the response. code in the response.
3.5. Device Access Token Response 3.5. Device Access Token Response
If the user has approved the grant, the token endpoint responds with If the user has approved the grant, the token endpoint responds with
a success response defined in Section 5.1 of [RFC6749]; otherwise it a success response defined in Section 5.1 of [RFC6749]; otherwise it
responds with an error, as defined in Section 5.2 of [RFC6749]. responds with an error, as defined in Section 5.2 of [RFC6749].
In addition to the error codes defined in Section 5.2 of [RFC6749], In addition to the error codes defined in Section 5.2 of [RFC6749],
the following error codes are specified by the device flow for use in the following error codes are specified for use with the device
token endpoint responses: authorization grant in token endpoint responses:
authorization_pending authorization_pending
The authorization request is still pending as the end user hasn't The authorization request is still pending as the end user hasn't
yet completed the user interaction steps (Section 3.3). The yet completed the user interaction steps (Section 3.3). The
client SHOULD repeat the Access Token Request to the token client SHOULD repeat the Access Token Request to the token
endpoint (a process known as polling). Before each new request endpoint (a process known as polling). Before each new request
the client MUST wait at least the number of seconds specified by the client MUST wait at least the number of seconds specified by
the "interval" parameter of the Device Authorization Response (see the "interval" parameter of the Device Authorization Response (see
Section 3.2), or 5 seconds if none was provided, and respect any Section 3.2), or 5 seconds if none was provided, and respect any
increase in the polling interval required by the "slow_down" increase in the polling interval required by the "slow_down"
skipping to change at page 11, line 29 skipping to change at page 12, line 6
slow_down slow_down
A variant of "authorization_pending", the authorization request is A variant of "authorization_pending", the authorization request is
still pending and polling should continue, but the interval MUST still pending and polling should continue, but the interval MUST
be increased by 5 seconds for this and all subsequent requests. be increased by 5 seconds for this and all subsequent requests.
access_denied access_denied
The end user denied the authorization request. The end user denied the authorization request.
expired_token expired_token
The "device_code" has expired and the device flow authorization The "device_code" has expired and the device authorization session
session has concluded. The client MAY commence a new Device has concluded. The client MAY commence a new Device Authorization
Authorization Request but SHOULD wait for user interaction before Request but SHOULD wait for user interaction before restarting to
restarting to avoid unnecessary polling. avoid unnecessary polling.
A client receiving an error response as defined in Section 5.2 of The "authorization_pending" and "slow_down" error codes define
[RFC6749] MUST stop polling and SHOULD react accordingly, for particularly unique behavior, as they indicate that the OAuth client
example, by displaying an error to the user, except for the error should continue to poll the token endpoint by repeating the token
codes "authorization_pending" and "slow_down" which are processed as request (implementing the precise behavior defined above). If the
described above. client receives an error response with any other error code, it MUST
stop polling and SHOULD react accordingly, for example, by displaying
an error to the user.
On encountering a connection timeout, clients MUST unilaterally On encountering a connection timeout, clients MUST unilaterally
reduce their polling frequency before retrying. The use of an reduce their polling frequency before retrying. The use of an
exponential backoff algorithm to achieve this, such as by doubling exponential backoff algorithm to achieve this, such as by doubling
the polling interval on each such connection timeout, is RECOMMENDED. the polling interval on each such connection timeout, is RECOMMENDED.
The assumption of this specification is that the secondary device the The assumption of this specification is that the separate 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 device with the OAuth client. This protocol only requires a
this flow useful in many scenarios. For example, an HTML application one-way channel in order to maximise the viability of the protocol in
on a TV that can only make outbound requests. If a return channel restricted environments, like an application running on a TV that is
were to exist for the chosen user interaction interface, then the only capable of outbound requests. If a return channel were to exist
device MAY wait until notified on that channel that the user has for the chosen user interaction interface, then the device MAY wait
completed the action before initiating the token request (as an until notified on that channel that the user has completed the action
alternative to polling). Such behavior is, however, outside the before initiating the token request (as an alternative to polling).
scope of this specification. Such behavior is, however, outside the scope of this specification.
4. Discovery Metadata 4. Discovery Metadata
Support for the device flow MAY be declared in the OAuth 2.0 Support for this specification MAY be declared in the OAuth 2.0
Authorization Server Metadata [RFC8414] with the following metadata: Authorization Server Metadata [RFC8414] by including the value
"urn:ietf:params:oauth:grant-type:device_code" in the
"grant_types_supported" parameter, and by adding the following new
parameter:
device_authorization_endpoint device_authorization_endpoint
OPTIONAL. URL of the authorization server's device authorization OPTIONAL. URL of the authorization server's device authorization
endpoint defined in Section 3.1. endpoint defined in Section 3.1.
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.
skipping to change at page 13, line 13 skipping to change at page 13, line 47
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 Code Brute Forcing 5.2. Device Code Brute Forcing
An attacker who guesses the device code would be able to potentially An attacker who guesses the device code would be able to potentially
obtain the authorization code once the user completes the flow. As obtain the authorization code once the user completes the flow. As
the device code is not displayed to the user and thus there are the device code is not displayed to the user and thus there are no
usability considerations on the length, a very high entropy code usability considerations on the length, a very high entropy code
SHOULD be used. SHOULD be used.
5.3. Device Trustworthiness 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.
skipping to change at page 19, line 36 skipping to change at page 20, line 15
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:
Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin Alissa Cooper, Ben Campbell, Brian Campbell, Roshni Chandrashekhar,
Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt, Eric Fazendin, Benjamin Kaduk, Jamshid Khosravian, Torsten
James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin Lodderstedt, James Manger, Dan McNulty, Breno de Medeiros, Simon
Richer, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Ken Wang, Moffatt, Stein Myrseth, Emond Papegaaij, Justin Richer, Adam Roach,
and Steven E. Wright. Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Filip Skokan, 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 ]]
-15
o Renamed and dropped most usage of the term "flow"
o Documented error responses on the authorization endpoint
o Documented client authentication for the authorization endpoint
-14 -14
o Added more normative text on polling behavior. o Added more normative text on polling behavior.
o Added discussion on risk of user retrieving their own device_code. o Added discussion on risk of user retrieving their own device_code.
o Editorial improvements. o Editorial improvements.
-13 -13
o Added a longer discussion about entropy, proposed by Benjamin o Added a longer discussion about entropy, proposed by Benjamin
Kaduk. Kaduk.
o Added device_code to OAuth IANA registry. o Added device_code to OAuth IANA registry.
o Expanded explanation of "case insensitive". o Expanded explanation of "case insensitive".
o Added security section on Device Code Brute Forcing. o Added security section on Device Code Brute Forcing.
o application/x-www-form-urlencoded normativly referenced. o application/x-www-form-urlencoded normativly referenced.
o Editorial improvements. o Editorial improvements.
-12 -12
 End of changes. 43 change blocks. 
120 lines changed or deleted 149 lines changed or added

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