< draft-ietf-oauth-device-flow-11.txt   draft-ietf-oauth-device-flow-12.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: January 18, 2019 Ping Identity Expires: February 2, 2019 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
July 17, 2018 August 1, 2018
OAuth 2.0 Device Flow for Browserless and Input Constrained Devices OAuth 2.0 Device Flow for Browserless and Input Constrained Devices
draft-ietf-oauth-device-flow-11 draft-ietf-oauth-device-flow-12
Abstract Abstract
This OAuth 2.0 authorization flow for browserless and input This OAuth 2.0 authorization flow for browserless and input-
constrained devices, often referred to as the device flow, enables constrained devices, often referred to as the device flow, enables
OAuth clients to request user authorization from devices that have an OAuth clients to request user authorization from devices that have an
Internet connection, but don't have an easy input method (such as a Internet connection, but don't have an easy input method (such as a
smart TV, media console, picture frame, or printer), or lack a smart TV, media console, picture frame, or printer), or lack a
suitable browser for a more traditional OAuth flow. This suitable browser for a more traditional OAuth flow. This
authorization flow instructs the user to perform the authorization authorization flow instructs the user to perform the authorization
request on a secondary device, such as a smartphone. There is no request on a secondary device, such as a smartphone. There is no
requirement for communication between the constrained device and the requirement for communication between the constrained device and the
user's secondary device. user's secondary device.
skipping to change at page 1, line 44 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at 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 January 18, 2019. This Internet-Draft will expire on February 2, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 40 skipping to change at page 2, line 40
3.5. Device Access Token Response . . . . . . . . . . . . . . 10 3.5. Device Access Token Response . . . . . . . . . . . . . . 10
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 11 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 11
5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11
5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 12 5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 12
5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 12 5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 12
5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 13 5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 13
5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 13 5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 13
5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 13 5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 13
6. Usability Considerations . . . . . . . . . . . . . . . . . . 13 6. Usability Considerations . . . . . . . . . . . . . . . . . . 13
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 13 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 14
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 15
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 15 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 16
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
8. Normative References . . . . . . . . . . . . . . . . . . . . 16 8. Normative References . . . . . . . . . . . . . . . . . . . . 16
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17
Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
1. Introduction 1. Introduction
This OAuth 2.0 protocol flow for browserless and input constrained This OAuth 2.0 [RFC6749] protocol flow for browserless and input-
devices, often referred to as the device flow, enables OAuth clients constrained devices, often referred to as the device flow, enables
to request user authorization from devices that have an internet OAuth clients to request user authorization from devices that have an
connection, but don't have an easy input method (such as a smart TV, internet connection, but don't have an easy input method (such as a
media console, picture frame, or printer), or lack a suitable browser smart TV, media console, picture frame, or printer), or lack a
for a more traditional OAuth flow. This authorization flow instructs suitable browser for a more traditional OAuth flow. This
the user to perform the authorization request on a secondary device, authorization flow instructs the user to perform the authorization
such as a smartphone. request on a secondary device, such as a smartphone.
The device flow is not intended to replace browser-based OAuth in The device flow is not intended to replace browser-based OAuth in
native apps on capable devices (like smartphones). Those apps should native apps on capable devices (like smartphones). Those apps should
follow the practices specified in OAuth 2.0 for Native Apps OAuth 2.0 follow the practices specified in OAuth 2.0 for Native Apps
for Native Apps [RFC8252]. [RFC8252].
The only requirements to use this flow are that the device is The only requirements to use this flow are that the device is
connected to the Internet, and able to make outbound HTTPS requests, connected to the Internet, and able to make outbound HTTPS requests,
be able to display or otherwise communicate a URI and code sequence be able to display or otherwise communicate a URI and code sequence
to the user, and that the user has a secondary device (e.g., personal to the user, and that the user has a secondary device (e.g., personal
computer or smartphone) from which to process the request. There is computer or smartphone) from which to process the request. There is
no requirement for two-way communication between the OAuth client and no requirement for two-way communication between the OAuth client and
the user-agent, enabling a broad range of use-cases. the user-agent, enabling a broad range of use-cases.
Instead of interacting with the end-user's user-agent, the client Instead of interacting with the end user's user agent, the client
instructs the end-user to use another computer or device and connect instructs the end user to use another computer or device and connect
to the authorization server to approve the access request. Since the to the authorization server to approve the access request. Since the
client cannot receive incoming requests, it polls the authorization client cannot receive incoming requests, it polls the authorization
server repeatedly until the end-user completes the approval process. server repeatedly until the end user completes the approval process.
+----------+ +----------------+ +----------+ +----------------+
| |>---(A)-- Client Identifier --->| | | |>---(A)-- Client Identifier --->| |
| | | | | | | |
| |<---(B)-- Verification Code, --<| | | |<---(B)-- Verification Code, --<| |
| | User Code, | | | | User Code, | |
| | & Verification URI | | | | & Verification URI | |
| Device | | | | Device | | |
| Client | Client Identifier & | | | Client | Client Identifier & | |
| |>---(E)-- Verification Code --->| | | |>---(E)-- Verification Code --->| |
skipping to change at page 4, line 25 skipping to change at page 4, line 25
| |>---(E)-- Verification Code --->| | | |>---(E)-- Verification Code --->| |
| | | Authorization | | | | Authorization |
| |<---(F)-- Access Token --------<| Server | | |<---(F)-- Access Token --------<| Server |
+----------+ (w/ Optional Refresh Token) | | +----------+ (w/ 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)-- User authenticates -->| |
| Browser | | | | Browser | | |
+----------+ +----------------+ +----------+ +----------------+
Figure 1: Device Flow. Figure 1: Device Flow.
The device flow illustrated in Figure 1 includes the following steps: The device 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 verification code, an end-
user code, and provides the end-user verification URI. user 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
(elsewhere) and visit the provided end-user verification URI. The (elsewhere) and visit the provided end-user verification URI. The
client provides the end-user with the end-user code to enter in client provides the user with the end-user code to enter in order
order to grant access. to grant access.
(D) The authorization server authenticates the end-user (via the (D) The authorization server authenticates the end user (via the
user-agent) and prompts the end-user to grant the client's access user agent) and prompts the user to grant the client's access
request. If the end-user agrees to the client's access request, request. If the user agrees to the client's access request, the
the end-user enters the end-user code provided by the client. The user enters the user code provided by the client. The
authorization server validates the end-user code provided by the authorization server validates the user code provided by the user.
end-user.
(E) While the end-user authorizes (or denies) the client's request (E) While the end user authorizes (or denies) the client's request
(step D), the client repeatedly polls the authorization server to (step D), the client repeatedly polls the authorization server to
find out if the end-user completed the end-user authorization find out if the user completed the user authorization step. The
step. The client includes the verification code and its client client includes the verification code and its client identifier.
identifier.
(F) Assuming the end-user granted access, the authorization server (F) Assuming the end user granted access, the authorization server
validates the verification code provided by the client and validates the verification code provided by the client and
responds back with the access token. responds back with the access token.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in BCP
[RFC2119]. 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Device Authorization Endpoint: Device Authorization Endpoint:
The authorization server's endpoint capable of issuing device The authorization server's endpoint capable of issuing device
verification codes, user codes, and verification URLs. verification codes, user codes, and verification URLs.
Device Verification Code: Device Verification Code:
A short-lived token representing an authorization session. A short-lived token representing an authorization session.
End-User Verification Code: End-User Verification Code:
A short-lived token which the device displays to the end user, is A short-lived token which the device displays to the end user, is
entered by the end-user on the authorization server, and is thus entered by the user on the authorization server, and is thus used
used to bind the device to the end-user. 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
authorization endpoint. This is separate from the OAuth
authorization endpoint defined in [RFC6749] with which the user
interacts with via a user-agent (i.e., a browser). By comparison,
when using the device authorization endpoint, the OAuth client on the
device interacts with the authorization server directly without
presenting the request in a user-agent, and the end user authorizes
the request on a separate device. This interaction is defined as
follows.
The client initiates the flow by requesting a set of verification The client initiates the flow by requesting a set of verification
codes from the authorization server by making an HTTP "POST" request codes from the authorization server by making an HTTP "POST" request
to the device authorization endpoint. The client constructs the to the device authorization endpoint.
request with the following parameters, encoded with the "application/
x-www-form-urlencoded" content type: All requests from the device MUST use the Transport Layer Security
(TLS) [RFC5246] protocol and implement the best practices of
[RFC7525].
The client constructs the request with the following parameters,
encoded with the "application/x-www-form-urlencoded" content type:
client_id client_id
REQUIRED. The client identifier as described in Section 2.2 of REQUIRED. The client identifier as described in Section 2.2 of
[RFC6749]. [RFC6749].
scope scope
OPTIONAL. The scope of the access request as described by OPTIONAL. The scope of the access request as described by
Section 3.3 of [RFC6749]. Section 3.3 of [RFC6749].
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
skipping to change at page 6, line 19 skipping to change at page 6, line 30
Host: server.example.com Host: server.example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
client_id=459691054427 client_id=459691054427
Parameters sent without a value MUST be treated as if they were Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters unrecognized request parameters. Request and response parameters
MUST NOT be included more than once. MUST NOT be included more than once.
Due to the polling nature of this protocol, to avoid unneeded
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.
3.2. Device Authorization Response 3.2. Device Authorization Response
In response, the authorization server generates a device verification In response, the authorization server generates a device verification
code and an end-user code that are valid for a limited time and code and an end-user code that are valid for a limited time and
includes them in the HTTP response body using the "application/json" includes them in the HTTP response body using the "application/json"
format with a 200 (OK) status code. The response contains the format [RFC8259] with a 200 (OK) status code. The response contains
following parameters: 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. designed for non-textual transmission.
expires_in expires_in
OPTIONAL. 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. SHOULD wait between polling requests to the token endpoint. If no
value is provided, clients MUST use 5 as the default.
For example: For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8", "device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code":"WDJB-MJHT", "user_code":"WDJB-MJHT",
skipping to change at page 7, line 23 skipping to change at page 7, line 39
"verification_uri_complete": "verification_uri_complete":
"https://www.example.com/device?user_code=WDJB-MJHT", "https://www.example.com/device?user_code=WDJB-MJHT",
"expires_in" : 1800, "expires_in" : 1800,
"interval": 5 "interval": 5
} }
3.3. User Interaction 3.3. User Interaction
After receiving a successful Authorization Response, the client After receiving a successful Authorization Response, the client
displays or otherwise communicates the "user_code" and the displays or otherwise communicates the "user_code" and the
"verification_uri" to the end-user and instructs them to visit the "verification_uri" to the end user and instructs them to visit the
URI in a user agent on a secondary device (for example, in a browser URI in a user agent on a secondary device (for example, in a browser
on their mobile phone), and enter the user code. on their mobile phone), and enter the user code.
+-----------------------------------------------+ +-----------------------------------------------+
| | | |
| 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
session. The authorization server prompts the end-user to identify ([RFC5246]) session. The authorization server prompts the end user
the device authorization session by entering the "user_code" provided to identify the device authorization session by entering the
by the client. The authorization server should then inform the user "user_code" provided by the client. The authorization server should
about the action they are undertaking and ask them to approve or deny then inform the user about the action they are undertaking and ask
the request. Once the user interaction is complete, the server them to approve or deny the request. Once the user interaction is
informs the user to return to their device. complete, the server MAY inform the user to return to their device.
During the user interaction, the device continuously polls the token During the user interaction, the device continuously polls the token
endpoint with the "device_code", as detailed in Section 3.4, until endpoint with the "device_code", as detailed in Section 3.4, until
the user completes the interaction, the code expires, or another the user completes the interaction, the code expires, or another
error occurs. The "device_code" is not intended for the end-user and error occurs. The "device_code" is not intended for the end user
MUST NOT be displayed or communicated. directly, and thus should not be displayed during the interaction to
avoid confusing the end user.
Authorization servers supporting this specification MUST implement a Authorization servers supporting this specification MUST implement a
user interaction sequence that starts with the user navigating to user interaction sequence that starts with the user navigating to
"verification_uri" and continues with them supplying the "user_code" "verification_uri" and continues with them supplying the "user_code"
at some stage during the interaction. Other than that, the exact at some stage during the interaction. Other than that, the exact
sequence and implementation of the user interaction is up to the sequence and implementation of the user interaction is up to the
authorization server and is out of scope of this specification. authorization server and is out of scope of this specification.
It is NOT RECOMMENDED for authorization servers to include the user It is NOT RECOMMENDED for authorization servers to include the user
code in the verification URI ("verification_uri"), as this increases code in the verification URI ("verification_uri"), as this increases
the length and complexity of the URI that the user must type. The the length and complexity of the URI that the user must type. The
next section documents user interaction with next section documents user interaction with
"verification_uri_complete", which is designed to carry this "verification_uri_complete", which is designed to carry this
information. 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 codes or NFC, to save the user typing the the URI, such as with QR (Quick Response) codes or NFC (Near Field
URI. Communication), to save the user typing the URI.
For usability reasons, it is RECOMMENDED for clients to still display For usability reasons, it is RECOMMENDED for clients to still display
the textual verification URI ("verification_uri") for users not able the textual verification URI ("verification_uri") for users not able
to use such a shortcut. Clients MUST still display the "user_code", to use such a shortcut. Clients MUST still display the "user_code",
as the authorization server may still require the user to confirm it as the authorization server may still require the user to confirm it
to disambiguate devices, or as a remote phishing mitigation (See to disambiguate devices, or as a remote phishing mitigation (See
Section 5.3). Section 5.3).
+-------------------------------------------------+ +-------------------------------------------------+
| | | |
| Using a browser on another +------------+ | | Scan the QR code, or using +------------+ |
| device, visit: |[_].. . [_]| | | a browser on another device, |[_].. . [_]| |
| https://example.com/device | . .. . .| | | visit: | . .. . .| |
| | . . . ....| | | https://example.com/device | . . . ....| |
| |. . . . | | | |. . . . | |
| And enter the code: |[_]. ... . | | | And enter the code: |[_]. ... . | |
| WDJB-MJHT +------------+ | | WDJB-MJHT +------------+ |
| | | |
+-------------------------------------------------+ +-------------------------------------------------+
Figure 3: Example User Instruction with QR Code Representation of the Figure 3: Example User Instruction with QR Code Representation of the
Complete Verification URI Complete Verification URI
3.4. Device Access Token Request 3.4. Device Access Token Request
skipping to change at page 10, line 16 skipping to change at page 10, line 35
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 by the device flow for use in
token endpoint responses: 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. endpoint (a process known as polling). Before each new request
the client MUST wait at least the number of seconds specified by
access_denied the "interval" parameter of the Device Authorization Response (see
The end-user denied the authorization request. Section 3.2), or 5 seconds if none was provided, and respect any
increase in the polling interval required by the "slow_down"
error.
slow_down slow_down
The client is polling too quickly and should back off at a A variant of "authorization_pending", the authorization request is
reasonable rate. still pending and polling should continue, but the interval MUST
be increased by 5 seconds for this and all subsequent requests.
expired_token
The "device_code" has expired. The client will need to make a new
Device Authorization Request.
The error codes "authorization_pending" and "slow_down" are access_denied
considered soft errors. The client should continue to poll the token The end user denied the authorization request.
endpoint by repeating the Device Token Request (Section 3.4) when
receiving soft errors, increasing the time between polls if a
"slow_down" error is received. Other error codes are considered hard
errors; the client should stop polling and react accordingly, for
example, by displaying an error to the user.
If the verification codes have expired, the server SHOULD respond expired_token
with the error code "expired_token". Clients MAY then choose to The "device_code" has expired and the device flow authorization
start a new device authorization session. session has concluded. The client MAY commence a new Device
Authorization Request but SHOULD wait for user interaction before
restarting to avoid unnecessary polling.
The interval at which the client polls MUST NOT be more frequent than A client receiving an error response as defined in Section 5.2 of
the "interval" parameter returned in the Device Authorization [RFC6749] MUST stop polling and SHOULD react accordingly, for
Response (see Section 3.2). If no interval was provided, the client example, by displaying an error to the user, except for the error
MUST use a reasonable default polling interval. codes "authorization_pending" and "slow_down" which are be processed
as described above.
The assumption of this specification is that the secondary device the The assumption of this specification is that the secondary device the
user is authorizing the request on does not have a way to communicate user is authorizing the request on does not have a way to communicate
back to the OAuth client. Only a one-way channel is required to make back to the OAuth client. Only a one-way channel is required to make
this flow useful in many scenarios. For example, an HTML application this flow useful in many scenarios. For example, an HTML application
on a TV that can only make outbound requests. If a return channel on a TV that can only make outbound requests. If a return channel
were to exist for the chosen user interaction interface, then the were to exist for the chosen user interaction interface, then the
device MAY wait until notified on that channel that the user has device MAY wait until notified on that channel that the user has
completed the action before initiating the token request. Such completed the action before initiating the token request (as an
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 the device flow MAY be declared in the OAuth 2.0 Support for the device flow MAY be declared in the OAuth 2.0
Authorization Server Metadata [RFC8414] with the following metadata: Authorization Server Metadata [RFC8414] with the following metadata:
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.
skipping to change at page 11, line 35 skipping to change at page 12, line 4
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.
A successful brute forcing of the user code would enable the attacker A successful brute forcing of the user code would enable the attacker
to authenticate with their own credentials and make an authorization to authenticate with their own credentials and make an authorization
grant to the device. This is the opposite scenario to an OAuth grant to the device. This is the opposite scenario to an OAuth
bearer token being brute forced, whereby the attacker gains control bearer token being brute forced, whereby the attacker gains control
of the victim's authorization grant. In some applications this of the victim's authorization grant. Such attacks may not always
attack may not make much economic sense, for example for a video app, make economic sense, for example for a video app the device owner may
the owner of the device may then be able to purchase movies with the then be able to purchase movies using the attacker's account, though
attacker's account, however there are still privacy considerations in a privacy risk would still remain and thus is important to protect
that case as well as other uses of the device flow whereby the against. Furthermore, some uses of the device flow give the granting
granting account may be able to perform sensitive actions such as account the ability to perform actions such as controlling the
controlling the victim's device. device, which needs to be protected.
The precise length of the user code and the entropy contained within The precise length of the user code and the entropy contained within
is at the discretion of the authorization server, which needs to is at the discretion of the authorization server, which needs to
consider the sensitivity of their specific protected resources, the consider the sensitivity of their specific protected resources, the
practicality of the code length from a usability standpoint, and any practicality of the code length from a usability standpoint, and any
mitigations that are in place such as rate-limiting, when determining mitigations that are in place such as rate-limiting, when determining
the user code format. the user code format.
5.2. Device Trustworthiness 5.2. Device Trustworthiness
Unlike other native application OAuth 2.0 flows, the device Unlike other native application OAuth 2.0 flows, the device
requesting the authorization is not the same as the device that the requesting the authorization is not the same as the device that the
user grants access from. Thus, signals from the approving user's user grants access from. Thus, signals from the approving user's
session and device are not relevant to the trustworthiness of the session and device are not relevant to the trustworthiness of the
client device. client device.
Note that if an authorization server used with this flow is Note that if an authorization server used with this flow is
malicious, then it could man-in-the middle the backchannel flow to malicious, then it could man-in-the-middle the backchannel flow to
another authorization server. In this scenario, the man-in-the- another authorization server. In this scenario, the man-in-the-
middle is not completely hidden from sight, as the end-user would end middle is not completely hidden from sight, as the end user would end
up on the authorization page of the wrong service, giving them an up on the authorization page of the wrong service, giving them an
opportunity to notice that the authorization being requested is opportunity to notice that the authorization being requested is
wrong. For this to be possible, the device manufacturer must either wrong. For this to be possible, the device manufacturer must either
directly be the attacker, shipping a device intended to perform the directly be the attacker, shipping a device intended to perform the
man-in-the-middle attack, or be using an authorization server that is man-in-the-middle attack, or be using an authorization server that is
controlled by an attacker, possibly because the attacker compromised controlled by an attacker, possibly because the attacker compromised
the authorization server used by the device. In part, the person the authorization server used by the device. In part, the person
purchasing the device is counting on it and its business partners to purchasing the device is counting on it and its business partners to
be trustworthy. be trustworthy.
5.3. Remote Phishing 5.3. 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, the attacker might send an email attacker's possession. For example, an attacker might send an email
instructing the target user to visit the verification URL and enter instructing the target user to visit the verification URL and enter
the user code. To mitigate such an attack, it is RECOMMENDED to the user code. To mitigate such an attack, it is RECOMMENDED to
inform the user that they are authorizing a device during the user inform the user that they are authorizing a device during the user
interaction step (see Section 3.3), and to confirm that the device is interaction step (see Section 3.3), and to confirm that the device is
in their possession. The authorization server SHOULD display in their possession. The authorization server SHOULD display
information about the device so that the person can notice if a information about the device so that the person can notice if a
software client was attempting to impersonating a hardware device. software client was attempting to impersonating a hardware device.
For authorization servers that support the option specified in For authorization servers that support the option specified in
Section 3.3.1 for the client to append the user code to the Section 3.3.1 for the client to append the user code to the
skipping to change at page 13, line 32 skipping to change at page 13, line 46
[RFC8252] apply. [RFC8252] apply.
5.6. Non-Visual Code Transmission 5.6. Non-Visual Code Transmission
There is no requirement that the user code be displayed by the device There is no requirement that the user code be displayed by the device
visually. Other methods of one-way communication can potentially be visually. Other methods of one-way communication can potentially be
used, such as text-to-speech audio, or Bluetooth Low Energy. To used, such as text-to-speech audio, or Bluetooth Low Energy. To
mitigate an attack in which a malicious user can bootstrap their mitigate an attack in which a malicious user can bootstrap their
credentials on a device not in their control, it is RECOMMENDED that credentials on a device not in their control, it is RECOMMENDED that
any chosen communication channel only be accessible by people in any chosen communication channel only be accessible by people in
close proximity. E.g., users who can see, or hear the device, or close proximity. E.g., users who can see, or hear the device.
within range of a short-range wireless signal.
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, and typically these devices offer input methods that
skipping to change at page 14, line 8 skipping to change at page 14, line 21
reducing retries), these limitations should be taken into account reducing retries), these limitations should be taken into account
when selecting the user-code character set. when selecting the user-code character set.
One way to improve input speed is to restrict the character set to One way to improve input speed is to restrict the character set to
case-insensitive A-Z characters, with no digits. These characters case-insensitive A-Z characters, with no digits. These characters
can typically be entered on a mobile keyboard without using modifier can typically be entered on a mobile keyboard without using modifier
keys. Further removing vowels to avoid randomly 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, with an entropy of An example user code following this guideline containing 8
20^8: "WDJB-MJHT". significant characters and dashes added for end-user readability,
with a resulting entropy of 20^8: "WDJB-MJHT".
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 their length needs to be longer to maintain a high
entropy. entropy.
An example numeric user code, with an entropy of 10^9: "019-450-730". An example numeric user code containing 9 significant digits and
dashes added for end-user readability, with an entropy of 10^9:
"019-450-730".
The server should ignore any characters like punctuation that are not When processing the inputted user code, the server should strip
in the user-code character set. Provided that the character set dashes and other punctuation it added for readability (making the
doesn't include characters of different case, the comparison should inclusion of that punctuation by the user optional). For codes using
be case insensitive. only characters in the A-Z range as with the base-20 charset defined
above, the user's input should be upper-cased before comparison to
account for the fact that the user may input the equivalent lower-
case characters. Further stripping of all characters outside the
user_code charset is recommended to reduce instances where an
errantly typed character (like a space character) invalidates
otherwise valid input.
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
skipping to change at page 16, line 11 skipping to change at page 16, line 26
o Metadata Description: The Device Authorization Endpoint. o Metadata Description: The Device Authorization Endpoint.
o Change controller: IESG o Change controller: IESG
o Specification Document: Section 4 of [[ this specification ]] o Specification Document: Section 4 of [[ this specification ]]
8. Normative References 8. Normative References
[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 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
Requirement Levels", BCP 14, RFC 2119, (TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc5246>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<https://www.rfc-editor.org/info/rfc6755>. <https://www.rfc-editor.org/info/rfc6755>.
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013, DOI 10.17487/RFC6819, January 2013,
<https://www.rfc-editor.org/info/rfc6819>. <https://www.rfc-editor.org/info/rfc6819>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <https://www.rfc-editor.org/info/rfc7525>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>. <https://www.rfc-editor.org/info/rfc8252>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414, Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018, DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>. <https://www.rfc-editor.org/info/rfc8414>.
Appendix A. Acknowledgements Appendix A. Acknowledgements
The starting point for this document was the Internet-Draft draft- The starting point for this document was the Internet-Draft draft-
recordon-oauth-v2-device, authored by David Recordon and Brent recordon-oauth-v2-device, authored by David Recordon and Brent
Goldman, which itself was based on content in draft versions of the Goldman, which itself was based on content in draft versions of the
skipping to change at page 17, line 17 skipping to change at page 17, line 49
Brian Campbell, Roshni Chandrashekhar, Eric Fazendin, Torsten Brian Campbell, Roshni Chandrashekhar, Eric Fazendin, Torsten
Lodderstedt, James Manger, Breno de Medeiros, Simon Moffatt, Stein Lodderstedt, James Manger, Breno de Medeiros, Simon Moffatt, Stein
Myrseth, Justin Richer, Nat Sakimura, Andrew Sciberras, Marius Myrseth, Justin Richer, Nat Sakimura, Andrew Sciberras, Marius
Scurtescu, Ken Wang, and Steven E. Wright. Scurtescu, Ken Wang, and Steven E. Wright.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-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 -11
o Updated reference to OAuth 2.0 Authorization Server Metadata. o Updated reference to OAuth 2.0 Authorization Server Metadata.
-10 -10
o Added a missing definition of access_denied for use on the token o Added a missing definition of access_denied for use on the token
endpoint. endpoint.
o Corrected text documenting which error code should be returned for o Corrected text documenting which error code should be returned for
expired tokens (it's "expired_token", not "invalid_grant"). expired tokens (it's "expired_token", not "invalid_grant").
 End of changes. 54 change blocks. 
119 lines changed or deleted 170 lines changed or added

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