draft-ietf-oauth-device-flow-15.txt   rfc8628.txt 
OAuth W. Denniss Internet Engineering Task Force (IETF) W. Denniss
Internet-Draft Google Request for Comments: 8628 Google
Intended status: Standards Track J. Bradley Category: Standards Track J. Bradley
Expires: September 12, 2019 Ping Identity ISSN: 2070-1721 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
March 11, 2019 August 2019
OAuth 2.0 Device Authorization Grant OAuth 2.0 Device Authorization Grant
draft-ietf-oauth-device-flow-15
Abstract Abstract
The OAuth 2.0 Device Authorization Grant is designed for internet- The OAuth 2.0 device authorization grant is designed for Internet-
connected devices that either lack a browser to perform a user-agent connected devices that either lack a browser to perform a user-agent-
based authorization, or are input-constrained to the extent that based authorization or are input constrained to the extent that
requiring the user to input text in order to authenticate during the requiring the user to input text in order to authenticate during the
authorization flow is impractical. It enables OAuth clients on such authorization flow is impractical. It enables OAuth clients on such
devices (like smart TVs, media consoles, digital picture frames, and devices (like smart TVs, media consoles, digital picture frames, and
printers) to obtain user authorization to access protected resources printers) to obtain user authorization to access protected resources
without using an on-device user-agent. by using a user agent on a separate device.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on September 12, 2019. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc8628.
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 23 skipping to change at page 2, line 28
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Device Authorization Request . . . . . . . . . . . . . . 5 3.1. Device Authorization Request . . . . . . . . . . . . . . 5
3.2. Device Authorization Response . . . . . . . . . . . . . . 7 3.2. Device Authorization Response . . . . . . . . . . . . . . 7
3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . 10 3.4. Device Access Token Request . . . . . . . . . . . . . . . 10
3.5. Device Access Token Response . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . 13 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12
5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13 5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13
5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 14 5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13
5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 14 5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 14
5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 15 5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 15
5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . 16
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 16 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 16
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 17 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 17
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 17 7.1. OAuth Parameter Registration . . . . . . . . . . . . . . 17
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.3. OAuth Extensions Error Registration . . . . . . . . . . . 18
7.3. OAuth Extensions Error Registration . . . . . . . . . . . 17 7.4. OAuth Authorization Server Metadata . . . . . . . . . . . 18
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 8. Normative References . . . . . . . . . . . . . . . . . . . . 19
7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 18 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20
7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
8. Normative References . . . . . . . . . . . . . . . . . . . . 18
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
Appendix B. Document History . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction 1. Introduction
This OAuth 2.0 [RFC6749] protocol extension, sometimes referred to as This OAuth 2.0 [RFC6749] protocol extension enables OAuth clients to
"device flow", enables OAuth clients to request user authorization request user authorization from applications on devices that have
from applications on devices that have limited input capabilities or limited input capabilities or lack a suitable browser. Such devices
lack a suitable browser. Such devices include those smart TVs, media include smart TVs, media consoles, picture frames, and printers,
console, picture frames and printers which lack an easy input method which lack an easy input method or a suitable browser required for
or suitable browser required for traditional OAuth interactions. The traditional OAuth interactions. The authorization flow defined by
authorization flow defined by this specification instructs the user this specification, sometimes referred to as the "device flow",
to review the authorization request on a secondary device, such as a instructs the user to review the authorization request on a secondary
smartphone which does have the requisite input and browser device, such as a smartphone, which does have the requisite input and
capabilities to complete the user interaction. browser capabilities to complete the user interaction.
The Device Authorization Grant is not intended to replace browser- The device authorization grant is not intended to replace browser-
based OAuth in native apps on capable devices like smartphones. based OAuth in native apps on capable devices like smartphones.
Those apps should follow the practices specified in OAuth 2.0 for Those apps should follow the practices specified in "OAuth 2.0 for
Native Apps [RFC8252]. Native Apps" [RFC8252].
The operating requirements to be able to use this authorization grant The operating requirements for using this authorization grant type
type are: 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 authorization grant does not require two-way As the device authorization grant does not require two-way
communication between the OAuth client and the user-agent (unlike communication between the OAuth client on the device and the user
other OAuth 2 grant types such as the Authorization Code and Implicit agent (unlike other OAuth 2 grant types, such as the authorization
grant types), it supports several use cases that cannot be served by code and implicit grant types), it supports several use cases that
those other approaches. cannot be served by those other approaches.
Instead of interacting with the end user's user agent, the client Instead of interacting directly with the end user's user agent (i.e.,
instructs the end user to use another computer or device and connect browser), the device client instructs the end user to use another
to the authorization server to approve the access request. Since the computer or device and connect to the authorization server to approve
protocol supports clients that can't receive incoming requests, the access request. Since the protocol supports clients that can't
clients poll the authorization server repeatedly until the end user receive incoming requests, clients poll the authorization server
completes the approval process. repeatedly until the end user completes the approval process.
The device typically chooses the set of authorization servers to The device client typically chooses the set of authorization servers
support (i.e., its own authorization server, or those by providers it to support (i.e., its own authorization server or those of providers
has relationships with). It is not uncommon for the device with which it has relationships). It is common for the device client
application to support only a single authorization server, such as to support only one authorization server, such as in the case of a TV
with a TV application for a specific media provider that supports application for a specific media provider that supports only that
only that media provider's authorization server. The user may not media provider's authorization server. The user may not yet have an
have an established relationship yet with that authorization established relationship with that authorization provider, though one
provider, though one can potentially be set up during the can potentially be set up during the authorization flow.
authorization flow.
+----------+ +----------------+ +----------+ +----------------+
| |>---(A)-- Client Identifier --->| | | |>---(A)-- Client Identifier --->| |
| | | | | | | |
| |<---(B)-- Device Code, ---<| | | |<---(B)-- Device Code, ---<| |
| | User Code, | | | | User Code, | |
| Device | & Verification URI | | | Device | & Verification URI | |
| Client | | | | Client | | |
| | [polling] | | | | [polling] | |
| |>---(E)-- Device Code, --->| | | |>---(E)-- Device Code --->| |
| | & Client Identifier | | | | & Client Identifier | |
| | | Authorization | | | | Authorization |
| |<---(F)-- Access Token ---<| Server | | |<---(F)-- Access Token ---<| Server |
+----------+ (& 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)-- End user reviews --->| | | at |<---(D)-- End user reviews --->| |
| Browser | authorization request | | | Browser | authorization request | |
+----------+ +----------------+ +----------+ +----------------+
Figure 1: Device Authorization Flow Figure 1: Device Authorization Flow
The device authorization flow illustrated in Figure 1 includes the The device authorization flow illustrated in Figure 1 includes the
following steps: 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 device code, an end-user (B) The authorization server issues a device code and an end-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 (on (C) The client instructs the end user to use a user agent on another
another device) and visit the provided end-user verification URI. device and visit the provided end-user verification URI. The
The client provides the user with the end-user code to enter in client provides the user with the end-user code to enter in
order to review the authorization request. 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 input the user code
request. If the user agrees to the client's access request, the provided by the device client. The authorization server
user enters the user code provided by the client. The validates the user code provided by the user, and prompts the
authorization server validates the user code provided by the user. user to accept or decline the request.
(E) While the end user reviews the client's request (step D), the (E) While the end user reviews the client's request (step D), the
client repeatedly polls the authorization server to find out if client repeatedly polls the authorization server to find out if
the user completed the user authorization step. The client the user completed the user authorization step. The client
includes the verification code and its client identifier. includes the device code and its client identifier.
(F) The authorization server validates the verification code (F) The authorization server validates the device code provided by
provided by the client and responds back with the access token if the client and responds with the access token if the client is
the user granted access, an error if they denied access, or granted access, an error if they are denied access, or an
indicates that the client should continue to poll. indication 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
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Device Authorization Endpoint:
The authorization server's endpoint capable of issuing device
verification codes, user codes, and verification URLs.
Device Verification Code:
A short-lived token representing an authorization session.
End-User Verification Code:
A short-lived token which the device displays to the end user, is
entered by the user on the authorization server, and is thus used
to bind the device to the user.
3. Protocol 3. Protocol
3.1. Device Authorization Request 3.1. Device Authorization Request
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 via a user agent (i.e., a browser). By comparison, when
when using the device authorization endpoint, the OAuth client on the 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 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 makes a device authorization request to the device
as the body of the request, encoded with the "application/x-www-form- authorization endpoint by including the following parameters using
urlencoded" encoding algorithm defined by Section 4.10.22.6 of the "application/x-www-form-urlencoded" format, per Appendix B of
[HTML5]: [RFC6749], with a character encoding of UTF-8 in the HTTP request
entity-body:
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]. 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 defined 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
client_id=459691054427 client_id=1406020730&scope=example_scope
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) protocol [RFC8446] 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.
The client authentication requirements of Section 3.2.1 of [RFC6749] The client authentication requirements of Section 3.2.1 of [RFC6749]
apply to requests on this endpoint, which means that confidential apply to requests on this endpoint, which means that confidential
clients (those that have established client credentials) authenticate clients (those that have established client credentials) authenticate
in the same manner as when making requests to the token endpoint, and in the same manner as when making requests to the token endpoint, and
public clients provide the "client_id" parameter to identify public clients provide the "client_id" parameter to identify
themselves. themselves.
Due to the polling nature of this protocol (as specified in Due to the polling nature of this protocol (as specified in
Section 3.4), care is needed to avoid overloading the capacity of the Section 3.4), care is needed to avoid overloading the capacity of the
token endpoint. To avoid unneeded requests on the token endpoint, token endpoint. To avoid unneeded requests on the token endpoint,
the client SHOULD only commence a device authorization request when the client SHOULD only commence a device authorization request when
prompted by the user, and not automatically, such as when the app prompted by the user and not automatically, such as when the app
starts or when the previous authorization session expires or fails. 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
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
will be asked to manually type it into their user-agent. will be asked to manually type it into their user agent.
verification_uri_complete verification_uri_complete
OPTIONAL. A verification URI that includes the "user_code" (or OPTIONAL. A verification URI that includes the "user_code" (or
other information with the same function as the "user_code"), other information with the same function as the "user_code"),
designed for non-textual transmission. which is designed for non-textual transmission.
expires_in expires_in
REQUIRED. The lifetime in seconds of the "device_code" and REQUIRED. The lifetime in seconds of the "device_code" and
"user_code". "user_code".
interval interval
OPTIONAL. The minimum amount of time in seconds that the client OPTIONAL. The minimum amount of time in seconds that the client
SHOULD wait between polling requests to the token endpoint. 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.
skipping to change at page 8, line 11 skipping to change at page 8, line 11
"expires_in": 1800, "expires_in": 1800,
"interval": 5 "interval": 5
} }
In the event of an error (such as an invalidly configured client), In the event of an error (such as an invalidly configured client),
the authorization server responds in the same way as the token the authorization server responds in the same way as the token
endpoint specified in Section 5.2 of [RFC6749]. 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.
+-----------------------------------------------+ +-----------------------------------------------+
| | | |
| Using a browser on another device, visit: | | Using a browser on another device, visit: |
| https://example.com/device | | https://example.com/device |
| | | |
| 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
([RFC8446]) session. The authorization server prompts the end user [RFC8446] session. The authorization server prompts the end user to
to identify the device authorization session by entering the identify the device authorization session by entering the "user_code"
"user_code" provided by the client. The authorization server should provided by the client. The authorization server should then inform
then inform the user about the action they are undertaking and ask the user about the action they are undertaking and ask them to
them to approve or deny the request. Once the user interaction is approve or deny the request. Once the user interaction is complete,
complete, the server MAY inform the user to return to their device. the server instructs 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; thus, it 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, 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 ("user_code") in the verification URI ("verification_uri"), as
the length and complexity of the URI that the user must type. While this increases the length and complexity of the URI that the user
the user must still type the same number of characters with the must type. While the user must still type a similar number of
"user_code" separated, once they successfully navigate to the characters with the "user_code" separated, once they successfully
"verification_uri", any errors in entering the code can be navigate to the "verification_uri", any errors in entering the code
highlighted by the authorization server to improve the user can be highlighted by the authorization server to improve the user
experience. The next section documents user interaction with experience. The next section documents the user interaction with
"verification_uri_complete", which is designed to carry both pieces "verification_uri_complete", which is designed to carry both pieces
of information. 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 from 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 who are
to use such a shortcut. Clients MUST still display the "user_code", not able to use such a shortcut. Clients MUST still display the
as the authorization server will require the user to confirm it to "user_code", as the authorization server will require the user to
disambiguate devices, or as a remote phishing mitigation (See confirm it to disambiguate devices or as remote phishing mitigation
Section 5.4). (see Section 5.4).
If the user starts the user interaction by browsing to If the user starts the user interaction by navigating to
"verification_uri_complete", then the user interaction described in "verification_uri_complete", then the user interaction described in
Section 3.3 is still followed, but with the optimization that the Section 3.3 is still followed, with the optimization that the user
user does not need to type the "user_code". The server SHOULD does not need to type in the "user_code". The server SHOULD display
display the "user_code" to the user and ask them to verify that it the "user_code" to the user and ask them to verify that it matches
matches the "user_code" being displayed on the device, to confirm the "user_code" being displayed on the device to confirm they are
they are authorizing the correct device. As before, in addition to authorizing the correct device. As before, in addition to taking
taking steps to confirm the identity of the device, the user should steps to confirm the identity of the device, the user should also be
also be afforded the choice to approve or deny the authorization afforded the choice to approve or deny the authorization request.
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
Complete Verification URI of the 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 creates an
Token Request to the token endpoint (as defined by Section 3.2 of access token request and sends it to the token endpoint (as defined
[RFC6749]) with a "grant_type" of 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]) created by this grant type (as defined by Section 4.5 of [RFC6749]) created by this
specification, with the 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
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]. 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
&client_id=459691054427 &client_id=1406020730
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.6. 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
code in the response. 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 for use with the device the following error codes are specified for use with the device
authorization grant in 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"
error. error.
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 authorization request was denied.
expired_token expired_token
The "device_code" has expired and the device authorization session The "device_code" has expired, and the device authorization
has concluded. The client MAY commence a new Device Authorization session has concluded. The client MAY commence a new device
Request but SHOULD wait for user interaction before restarting to authorization request but SHOULD wait for user interaction before
avoid unnecessary polling. restarting to avoid unnecessary polling.
The "authorization_pending" and "slow_down" error codes define The "authorization_pending" and "slow_down" error codes define
particularly unique behavior, as they indicate that the OAuth client particularly unique behavior, as they indicate that the OAuth client
should continue to poll the token endpoint by repeating the token should continue to poll the token endpoint by repeating the token
request (implementing the precise behavior defined above). If the request (implementing the precise behavior defined above). If the
client receives an error response with any other error code, it MUST client receives an error response with any other error code, it MUST
stop polling and SHOULD react accordingly, for example, by displaying stop polling and SHOULD react accordingly, for example, by displaying
an error to the user. 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 doubling the
the polling interval on each such connection timeout, is RECOMMENDED. polling interval on each such connection timeout, is RECOMMENDED.
The assumption of this specification is that the separate device the The assumption of this specification is that the separate device on
user is authorizing the request on does not have a way to communicate which the user is authorizing the request does not have a way to
back to device with the OAuth client. This protocol only requires a communicate back to the device with the OAuth client. This protocol
one-way channel in order to maximise the viability of the protocol in only requires a one-way channel in order to maximize the viability of
restricted environments, like an application running on a TV that is the protocol in restricted environments, like an application running
only capable of outbound requests. If a return channel were to exist on a TV that is only capable of outbound requests. If a return
for the chosen user interaction interface, then the device MAY wait channel were to exist for the chosen user-interaction interface, then
until notified on that channel that the user has completed the action the device MAY wait until notified on that channel that the user has
before initiating the token request (as an alternative to polling). completed the action before initiating the token request (as an
Such behavior is, however, outside the scope of this specification. alternative to polling). Such behavior is, however, outside the
scope of this specification.
4. Discovery Metadata 4. Discovery Metadata
Support for this specification MAY be declared in the OAuth 2.0 Support for this protocol is declared in OAuth 2.0 Authorization
Authorization Server Metadata [RFC8414] by including the value Server Metadata [RFC8414] as follows. The value
"urn:ietf:params:oauth:grant-type:device_code" in the "urn:ietf:params:oauth:grant-type:device_code" is included in values
"grant_types_supported" parameter, and by adding the following new of the "grant_types_supported" key, and the following new key value
parameter: pair is added:
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, as 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.
therefore recommended that the server rate-limit user code attempts. Therefore, it is 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
limiting and other mitigations makes a brute-force attack infeasible. rate-limiting and other mitigations, a brute-force attack becomes
For example, it's generally held that 128-bit symmetric keys for infeasible. For example, it's generally held that 128-bit symmetric
encryption are seen as good enough today because an attacker has to keys for encryption are seen as good enough today because an attacker
put in 2^96 work to have a 2^-32 chance of guessing correctly via has to put in 2^96 work to have a 2^-32 chance of guessing correctly
brute force. The rate limiting and finite lifetime on the user code via brute force. The rate-limiting and finite lifetime on the user
places an artificial limit on the amount of work an attacker can code place 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 "do". If, for instance, one uses an 8-character base 20 user code
(with roughly 34.5 bits of entropy), the rate-limiting interval and (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 validity period would need to only allow 5 attempts in order to get
the same 2^-32 probability of success by random guessing. 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 approve the authorization grant with their own credentials, after
grant to the device. This is the opposite scenario to an OAuth which the device would receive a device authorization grant linked to
the attacker's account. 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
then be able to purchase movies using the attacker's account, though may then be able to purchase movies using the attacker's account
a privacy risk would still remain and thus is important to protect (though even in this case a privacy risk would still remain and thus
against. Furthermore, some uses of the device flow give the granting is important to protect against). Furthermore, some uses of the
account the ability to perform actions such as controlling the device flow give the granting account the ability to perform actions
device, which needs to be protected. that need to be protected, such as controlling the device.
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
the user code format. determining 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 no 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 from which
user grants access from. Thus, signals from the approving user's the user grants access. Thus, signals from the approving user's
session and device are not relevant to the trustworthiness of the session and device are not always relevant to the trustworthiness of
client device. the 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 perform a man-in-the-middle attack on the
another authorization server. In this scenario, the man-in-the- backchannel flow to another authorization server. In this scenario,
middle is not completely hidden from sight, as the end user would end the man-in-the-middle is not completely hidden from sight, as the end
up on the authorization page of the wrong service, giving them an user would end up on the authorization page of the wrong service,
opportunity to notice that the URL in the browser's address bar is giving them an opportunity to notice that the URL in the browser's
wrong. For this to be possible, the device manufacturer must either address bar is wrong. For this to be possible, the device
directly be the attacker, shipping a device intended to perform the manufacturer must either be the attacker and shipping a device
man-in-the-middle attack, or be using an authorization server that is intended to perform the man-in-the-middle attack, or be using an
controlled by an attacker, possibly because the attacker compromised authorization server that is controlled by an attacker, possibly
the authorization server used by the device. In part, the person because the attacker compromised the authorization server used by the
purchasing the device is counting on it and its business partners to device. In part, the person purchasing the device is counting on the
be trustworthy. manufacturer and its business partners to be trustworthy.
5.4. 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 user could notice if a
software client was attempting to impersonating a hardware device. software client was attempting to impersonate a hardware device.
For authorization servers that support the option specified in For authorization servers that support the
Section 3.3.1 for the client to append the user code to the "verification_uri_complete" optimization discussed in Section 3.3.1,
authorization URI, it is particularly important to confirm that the it is particularly important to confirm that the device is in the
device is in the user's possession, as the user no longer has to type user's possession, as the user no longer has to type in the code
the code manually. One possibility is to display the code during the being displayed on the device manually. One suggestion is to display
authorization flow and asking the user to verify that the same code the code during the authorization flow and ask the user to verify
is being displayed on the device they are setting up. that the same code is currently 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, log in, 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 from presenting a fresh token, particularly if they
they are interacting with the user in real time, but it does limit are interacting with the user in real time, but it does limit the
the viability of codes sent over email or SMS. viability of codes sent over email or text message.
5.5. 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 physically spy on the device user interface (by malicious user to physically spy on the device user interface (by
viewing the screen on which it's displayed, for example) and hijack viewing the screen on which it's displayed, for example) and hijack
the session by completing the authorization faster than the user that the 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.6. Non-confidential Clients 5.6. Non-Confidential Clients
Device clients are generally incapable of maintaining the Device clients are generally incapable of maintaining the
confidentiality of their credentials, as users in possession of the confidentiality of their credentials, as users in possession of the
device can reverse engineer it and extract the credentials. device can reverse-engineer it and extract the credentials.
Therefore, unless additional measures are taken, they should be Therefore, unless additional measures are taken, they should be
treated as public clients (as defined by Section 2.1 of OAuth 2.0) treated as public clients (as defined by Section 2.1 of [RFC6749]),
susceptible to impersonation. The security considerations of which are susceptible to impersonation. The security considerations
Section 5.3.1 of [RFC6819] and Sections 8.5 and 8.6 of [RFC8252] of Section 5.3.1 of [RFC6819] and Sections 8.5 and 8.6 of [RFC8252]
apply to such clients. apply to such clients.
The user may also be able to obtain the device_code and/or other The user may also be able to obtain the "device_code" and/or other
OAuth bearer tokens issued to their client, which would allow them to OAuth bearer tokens issued to their client, which would allow them to
use their own authorization grant directly by impersonating the use their own authorization grant directly by impersonating the
client. Given that the user in possession of the client credentials client. Given that the user in possession of the client credentials
can already impersonate the client and create a new authorization can already impersonate the client and create a new authorization
grant (with a new device_code), this doesn't represent a separate grant (with a new "device_code"), this doesn't represent a separate
impersonation vector. impersonation vector.
5.7. 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, for example, users who can see or hear the device.
6. Usability Considerations 6. Usability Considerations
This section is a non-normative discussion of usability This section is a non-normative discussion of usability
considerations. considerations.
6.1. User Code Recommendations 6.1. User Code Recommendations
For many users, their nearest Internet-connected device will be their For many users, their nearest Internet-connected device will be their
mobile phone, and typically these devices offer input methods that mobile phone; typically, these devices offer input methods that are
are more time consuming than a computer keyboard to change the case more time-consuming than a computer keyboard to change the case or
or input numbers. To improve usability (improving entry speed, and input numbers. To improve usability (improving entry speed and
reducing retries), these limitations should be taken into account reducing retries), the limitations of such devices should be taken
when selecting the user-code character set. into account when selecting the user code character set.
One way to improve input speed is to restrict the character set to One way to improve input speed is to restrict the character set to
case-insensitive A-Z characters, with no digits. These characters case-insensitive A-Z characters, with no digits. These characters
can typically be entered on a mobile keyboard without using modifier can typically be entered on a mobile keyboard without using modifier
keys. Further removing vowels to avoid randomly creating words keys. Further removing vowels to avoid randomly creating words
results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes results in the base 20 character set "BCDFGHJKLMNPQRSTVWXZ". Dashes
or other punctuation may be included for readability. or other punctuation may be included for readability.
An example user code following this guideline containing 8 An example user code following this guideline, "WDJB-MJHT", contains
significant characters and dashes added for end-user readability, 8 significant characters and has dashes added for end-user
with a resulting entropy of 20^8: "WDJB-MJHT". readability. The resulting entropy is 20^8.
Pure numeric codes are also a good choice for usability, especially Pure numeric codes are also a good choice for usability, especially
for clients targeting locales where A-Z character keyboards are not for clients targeting locales where A-Z character keyboards are not
used, though their length needs to be longer to maintain a high used, though the length of such a code needs to be longer to maintain
entropy. high entropy.
An example numeric user code containing 9 significant digits and An example numeric user code that contains 9 significant digits and
dashes added for end-user readability, with an entropy of 10^9: dashes added for end-user readability with an entropy of 10^9 is
"019-450-730". "019-450-730".
When processing the inputted user code, the server should strip When processing the inputted user code, the server should strip
dashes and other punctuation it added for readability (making the dashes and other punctuation that it added for readability (making
inclusion of that punctuation by the user optional). For codes using the inclusion of such punctuation by the user optional). For codes
only characters in the A-Z range as with the base-20 charset defined using only characters in the A-Z range, as with the base 20 charset
above, the user's input should be upper-cased before comparison to defined above, the user's input should be uppercased before a
account for the fact that the user may input the equivalent lower- comparison to account for the fact that the user may input the
case characters. Further stripping of all characters outside the equivalent lowercase characters. Further stripping of all characters
user_code charset is recommended to reduce instances where an outside the chosen character set is recommended to reduce instances
errantly typed character (like a space character) invalidates where an errantly typed character (like a space character)
otherwise valid input. invalidates otherwise valid input.
It is RECOMMENDED to avoid character sets that contain two or more It is RECOMMENDED to avoid character sets that contain two or more
characters that can easily be confused with each other like "0" and characters that can easily be confused with each other, like "0" and
"O", or "1", "l" and "I". Furthermore, the extent practical, where a "O" or "1", "l" and "I". Furthermore, to the extent practical, when
character set contains one character that may be confused with a character set contains a character that may be confused with
characters outside the character set the character outside the set characters outside the character set, a character outside the set MAY
MAY be substituted with the one in the character set that it is be substituted with the one in the character set with which it is
commonly confused with (for example, "O" for "0" when using a commonly confused; for example, "O" may be substituted for "0" when
numerical 0-9 character set). using the 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 through the verification URI is outside the
of this specification. scope of this specification.
7. IANA Considerations 7. IANA Considerations
7.1. OAuth Parameters Registration 7.1. OAuth Parameter Registration
This specification registers the following values in the IANA "OAuth This specification registers the following values in the IANA "OAuth
Parameters" registry [IANA.OAuth.Parameters] established by Parameters" registry [IANA.OAuth.Parameters] established by
[RFC6749]. [RFC6749].
7.1.1. Registry Contents Name: device_code
Parameter Usage Location: token request
o Parameter name: device_code Change Controller: IESG
o Parameter usage location: token request Reference: Section 3.4 of RFC 8628
o Change controller: IESG
o Specification Document: Section 3.1 of [[ this specification ]]
7.2. OAuth URI Registration 7.2. OAuth URI Registration
This specification registers the following values in the IANA "OAuth This specification registers the following values in the IANA "OAuth
URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. URI" registry [IANA.OAuth.Parameters] established by [RFC6755].
7.2.1. Registry Contents URN: urn:ietf:params:oauth:grant-type:device_code
Common Name: Device Authorization Grant Type for OAuth 2.0
o URN: urn:ietf:params:oauth:grant-type:device_code Change Controller: IESG
o Common Name: Device flow grant type for OAuth 2.0 Specification Document: Section 3.4 of RFC 8628
o Change controller: IESG
o Specification Document: Section 3.1 of [[ this specification ]]
7.3. 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.3.1. Registry Contents Name: authorization_pending
Usage Location: Token endpoint response
o Error name: authorization_pending Protocol Extension: RFC 8628
o Error usage location: Token endpoint response Change Controller: IETF
o Related protocol extension: [[ this specification ]] Reference: Section 3.5 of RFC 8628
o Change controller: IETF
o Specification Document: Section 3.5 of [[ this specification ]]
o Error name: access_denied Name: access_denied
o Error usage location: Token endpoint response Usage Location: Token endpoint response
o Related protocol extension: [[ this specification ]] Protocol Extension: RFC 8628
o Change controller: IETF Change Controller: IETF
o Specification Document: Section 3.5 of [[ this specification ]] Reference: Section 3.5 of RFC 8628
o Error name: slow_down Name: slow_down
o Error usage location: Token endpoint response Usage Location: Token endpoint response
o Related protocol extension: [[ this specification ]] Protocol Extension: RFC 8628
o Change controller: IETF Change Controller: IETF
o Specification Document: Section 3.5 of [[ this specification ]] Reference: Section 3.5 of RFC 8628
o Error name: expired_token Name: expired_token
o Error usage location: Token endpoint response Usage Location: Token endpoint response
o Related protocol extension: [[ this specification ]] Protocol Extension: RFC 8628
o Change controller: IETF Change Controller: IETF
o Specification Document: Section 3.5 of [[ this specification ]] Reference: Section 3.5 of RFC 8628
7.4. OAuth 2.0 Authorization Server Metadata 7.4. OAuth 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] Authorization Server Metadata" registry [IANA.OAuth.Parameters]
established by [RFC8414]. established by [RFC8414].
7.4.1. Registry Contents Metadata name: device_authorization_endpoint
Metadata Description: URL of the authorization server's device
o Metadata name: device_authorization_endpoint authorization endpoint
o Metadata Description: The Device Authorization Endpoint. Change Controller: IESG
o Change controller: IESG Reference: Section 4 of RFC 8628
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>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<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 19, line 46 skipping to change at page 20, line 9
[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 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
Appendix A. Acknowledgements Acknowledgements
The starting point for this document was the Internet-Draft draft- The starting point for this document was the Internet-Draft
recordon-oauth-v2-device, authored by David Recordon and Brent draft-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:
Alissa Cooper, Ben Campbell, Brian Campbell, Roshni Chandrashekhar, Ben Campbell, Brian Campbell, Roshni Chandrashekhar, Alissa Cooper,
Eric Fazendin, Benjamin Kaduk, Jamshid Khosravian, Torsten Eric Fazendin, Benjamin Kaduk, Jamshid Khosravian, Mirja Kuehlewind,
Lodderstedt, James Manger, Dan McNulty, Breno de Medeiros, Simon Torsten Lodderstedt, James Manger, Dan McNulty, Breno de Medeiros,
Moffatt, Stein Myrseth, Emond Papegaaij, Justin Richer, Adam Roach, Alexey Melnikov, Simon Moffatt, Stein Myrseth, Emond Papegaaij,
Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Filip Skokan, Ken Justin Richer, Adam Roach, Nat Sakimura, Andrew Sciberras, Marius
Wang, and Steven E. Wright. Scurtescu, Filip Skokan, Robert Sparks, Ken Wang, Christopher Wood,
Steven E. Wright, and Qin Wu.
Appendix B. Document History
[[ 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
o Added more normative text on polling behavior.
o Added discussion on risk of user retrieving their own device_code.
o Editorial improvements.
-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 Editorial improvements.
-12
o Set a default polling interval to 5s explicitly.
o Defined the slow_down behavior that it should increase the current
interval by 5s.
o expires_in now REQUIRED
o Other changes in response to review feedback.
-11
o Updated reference to OAuth 2.0 Authorization Server Metadata.
-10
o Added a missing definition of access_denied for use on the token
endpoint.
o Corrected text documenting which error code should be returned for
expired tokens (it's "expired_token", not "invalid_grant").
o Corrected section reference to RFC 8252 (the section numbers had
changed after the initial reference was made).
o Fixed line length of one diagram (was causing xml2rfc warnings).
o Added line breaks so the URN grant_type is presented on an
unbroken line.
o Typos fixed and other stylistic improvements.
-09
o Addressed review comments by Security Area Director Eric Rescorla
about the potential of a confused deputy attack.
-08
o Expanded the User Code Brute Forcing section to include more
detail on this attack.
-07
o Replaced the "user_code" URI parameter optimization with
verification_uri_complete following the IETF99 working group
discussion.
o Added security consideration about spying.
o Required that device_code not be shown.
o Added text regarding a minimum polling interval.
-06
o Clarified usage of the "user_code" URI parameter optimization
following the IETF98 working group discussion.
-05
o response_type parameter removed from authorization request.
o Added option for clients to include the user_code on the
verification URI.
o Clarified token expiry, and other nits.
-04
o Security & Usability sections. OAuth Discovery Metadata.
-03
o device_code is now a URN. Added IANA Considerations
-02
o Added token request & response specification.
-01
o Applied spelling and grammar corrections and added the Document
History appendix.
-00
o Initial working group draft based on draft-recordon-oauth-
v2-device.
Authors' Addresses Authors' Addresses
William Denniss William Denniss
Google Google
1600 Amphitheatre Pkwy 1600 Amphitheatre Pkwy
Mountain View, CA 94043 Mountain View, CA 94043
USA United States of America
Email: wdenniss@google.com Email: wdenniss@google.com
URI: http://wdenniss.com/device-flow URI: https://wdenniss.com/deviceflow
John Bradley John Bradley
Ping Identity Ping Identity
Email: ve7jtb@ve7jtb.com Email: ve7jtb@ve7jtb.com
URI: http://www.thread-safe.com/ URI: http://www.thread-safe.com/
Michael B. Jones Michael B. Jones
Microsoft Microsoft
Email: mbj@microsoft.com Email: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
Hannes Tschofenig Hannes Tschofenig
ARM Limited ARM Limited
Austria Austria
 End of changes. 125 change blocks. 
480 lines changed or deleted 356 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/