idnits 2.17.1
draft-ietf-oauth-device-flow-14.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (January 16, 2019) is 1926 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Missing Reference: 'RFC2119' is mentioned on line 209, but not defined
-- Possible downref: Non-RFC (?) normative reference: ref. 'HTML5'
** Downref: Normative reference to an Informational RFC: RFC 6755
** Downref: Normative reference to an Informational RFC: RFC 6819
** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325)
Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 OAuth W. Denniss
3 Internet-Draft Google
4 Intended status: Standards Track J. Bradley
5 Expires: July 20, 2019 Ping Identity
6 M. Jones
7 Microsoft
8 H. Tschofenig
9 ARM Limited
10 January 16, 2019
12 OAuth 2.0 Device Flow for Browserless and Input Constrained Devices
13 draft-ietf-oauth-device-flow-14
15 Abstract
17 This OAuth 2.0 authorization flow is designed for devices that either
18 lack a browser to perform a user-agent based OAuth flow, or are
19 input-constrained to the extent that requiring the user to input a
20 lot of text (like their credentials to authenticate with the
21 authorization server) is impractical. It enables OAuth clients on
22 such devices (like smart TVs, media consoles, digital picture frames,
23 and printers) to obtain user authorization to access protected
24 resources without using an on-device user-agent, provided that they
25 have an Internet connection.
27 Status of This Memo
29 This Internet-Draft is submitted in full conformance with the
30 provisions of BCP 78 and BCP 79.
32 Internet-Drafts are working documents of the Internet Engineering
33 Task Force (IETF). Note that other groups may also distribute
34 working documents as Internet-Drafts. The list of current Internet-
35 Drafts is at https://datatracker.ietf.org/drafts/current/.
37 Internet-Drafts are draft documents valid for a maximum of six months
38 and may be updated, replaced, or obsoleted by other documents at any
39 time. It is inappropriate to use Internet-Drafts as reference
40 material or to cite them other than as "work in progress."
42 This Internet-Draft will expire on July 20, 2019.
44 Copyright Notice
46 Copyright (c) 2019 IETF Trust and the persons identified as the
47 document authors. All rights reserved.
49 This document is subject to BCP 78 and the IETF Trust's Legal
50 Provisions Relating to IETF Documents
51 (https://trustee.ietf.org/license-info) in effect on the date of
52 publication of this document. Please review these documents
53 carefully, as they describe your rights and restrictions with respect
54 to this document. Code Components extracted from this document must
55 include Simplified BSD License text as described in Section 4.e of
56 the Trust Legal Provisions and are provided without warranty as
57 described in the Simplified BSD License.
59 Table of Contents
61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
63 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5
64 3.1. Device Authorization Request . . . . . . . . . . . . . . 5
65 3.2. Device Authorization Response . . . . . . . . . . . . . . 6
66 3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7
67 3.3.1. Non-textual Verification URI Optimization . . . . . . 9
68 3.4. Device Access Token Request . . . . . . . . . . . . . . . 9
69 3.5. Device Access Token Response . . . . . . . . . . . . . . 10
70 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12
71 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
72 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12
73 5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13
74 5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13
75 5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13
76 5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14
77 5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14
78 5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 15
79 6. Usability Considerations . . . . . . . . . . . . . . . . . . 15
80 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15
81 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16
82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
83 7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16
84 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
85 7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 17
86 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
87 7.3. OAuth Extensions Error Registration . . . . . . . . . . . 17
88 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
89 7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 18
90 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
91 8. Normative References . . . . . . . . . . . . . . . . . . . . 18
92 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
93 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19
94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
96 1. Introduction
98 This OAuth 2.0 [RFC6749] protocol extension known as the "device
99 flow" enables OAuth clients to request user authorization from
100 applications on devices that have limited input capabilities or lack
101 a suitable browser. Such devices include those smart TVs, media
102 console, picture frames and printers which lack an easy input method
103 or suitable browser required for a more traditional OAuth flow. This
104 authorization flow instructs the user to perform the authorization
105 request on a secondary device, such as a smartphone which does have
106 the requisite input and browser capabilities for an OAuth flow.
108 The device flow is not intended to replace browser-based OAuth in
109 native apps on capable devices (like smartphones). Those apps should
110 follow the practices specified in OAuth 2.0 for Native Apps
111 [RFC8252].
113 The operating requirements to be able to use this authorization flow
114 are:
116 (1) The device is already connected to the Internet.
118 (2) The device is able to make outbound HTTPS requests.
120 (3) The device is able to display or otherwise communicate a URI and
121 code sequence to the user.
123 (4) The user has a secondary device (e.g., personal computer or
124 smartphone) from which they can process the request.
126 As the device flow does not require two-way communication between the
127 OAuth client and the user-agent (unlike other OAuth 2 flows), it
128 supports several use cases that cannot be served by those other
129 approaches.
131 Instead of interacting with the end user's user agent, the client
132 instructs the end user to use another computer or device and connect
133 to the authorization server to approve the access request. Since the
134 client cannot receive incoming requests, it polls the authorization
135 server repeatedly until the end user completes the approval process.
137 The device typically chooses the set of authorization servers to
138 support (i.e., its own authorization server, or those by providers it
139 has relationships with). It is not uncommon for the device
140 application to support only a single authorization server, such as
141 with a TV application for a specific media provider that supports
142 only that media provider's authorization server. The user may not
143 have an established relationship yet with that authorization
144 provider, though one can potentially be set up during the
145 authorization flow.
147 +----------+ +----------------+
148 | |>---(A)-- Client Identifier --->| |
149 | | | |
150 | |<---(B)-- Verification Code, --<| |
151 | | User Code, | |
152 | | & Verification URI | |
153 | Device | | |
154 | Client | Client Identifier & | |
155 | |>---(E)-- Verification Code --->| |
156 | | polling... | |
157 | |>---(E)-- Verification Code --->| |
158 | | | Authorization |
159 | |<---(F)-- Access Token --------<| Server |
160 +----------+ (w/ Optional Refresh Token) | |
161 v | |
162 : | |
163 (C) User Code & Verification URI | |
164 : | |
165 v | |
166 +----------+ | |
167 | End user | | |
168 | at |<---(D)-- User authenticates -->| |
169 | Browser | | |
170 +----------+ +----------------+
172 Figure 1: Device Flow.
174 The device flow illustrated in Figure 1 includes the following steps:
176 (A) The client requests access from the authorization server and
177 includes its client identifier in the request.
179 (B) The authorization server issues a verification code, an end-
180 user code, and provides the end-user verification URI.
182 (C) The client instructs the end user to use its user agent
183 (elsewhere) and visit the provided end-user verification URI. The
184 client provides the user with the end-user code to enter in order
185 to grant access.
187 (D) The authorization server authenticates the end user (via the
188 user agent) and prompts the user to grant the client's access
189 request. If the user agrees to the client's access request, the
190 user enters the user code provided by the client. The
191 authorization server validates the user code provided by the user.
193 (E) While the end user authorizes (or denies) the client's request
194 (step D), the client repeatedly polls the authorization server to
195 find out if the user completed the user authorization step. The
196 client includes the verification code and its client identifier.
198 (F) Assuming the end user granted access, the authorization server
199 validates the verification code provided by the client and
200 responds back with the access token.
202 2. Terminology
204 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
205 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
206 "OPTIONAL" in this document are to be interpreted as described in BCP
207 14 [RFC2119] [RFC8174] when, and only when, they appear in all
208 capitals, as shown here.
210 Device Authorization Endpoint:
211 The authorization server's endpoint capable of issuing device
212 verification codes, user codes, and verification URLs.
214 Device Verification Code:
215 A short-lived token representing an authorization session.
217 End-User Verification Code:
218 A short-lived token which the device displays to the end user, is
219 entered by the user on the authorization server, and is thus used
220 to bind the device to the user.
222 3. Protocol
224 3.1. Device Authorization Request
226 This specification defines a new OAuth endpoint, the device
227 authorization endpoint. This is separate from the OAuth
228 authorization endpoint defined in [RFC6749] with which the user
229 interacts with via a user-agent (i.e., a browser). By comparison,
230 when using the device authorization endpoint, the OAuth client on the
231 device interacts with the authorization server directly without
232 presenting the request in a user-agent, and the end user authorizes
233 the request on a separate device. This interaction is defined as
234 follows.
236 The client initiates the authorization flow by requesting a set of
237 verification codes from the authorization server by making an HTTP
238 "POST" request to the device authorization endpoint.
240 The client constructs the request with the following parameters, sent
241 as the body of the request, encoded with the "application/x-www-form-
242 urlencoded" encoding algorithm defined by Section 4.10.22.6 of
243 [HTML5]:
245 client_id
246 REQUIRED. The client identifier as described in Section 2.2 of
247 [RFC6749].
249 scope
250 OPTIONAL. The scope of the access request as described by
251 Section 3.3 of [RFC6749].
253 For example, the client makes the following HTTPS request:
255 POST /device_authorization HTTP/1.1
256 Host: server.example.com
257 Content-Type: application/x-www-form-urlencoded
259 client_id=459691054427
261 All requests from the device MUST use the Transport Layer Security
262 (TLS) [RFC8446] protocol and implement the best practices of BCP 195
263 [RFC7525].
265 Parameters sent without a value MUST be treated as if they were
266 omitted from the request. The authorization server MUST ignore
267 unrecognized request parameters. Request and response parameters
268 MUST NOT be included more than once.
270 Due to the polling nature of this protocol, care is needed to avoid
271 overloading the capacity of the token endpoint. To avoid unneeded
272 requests on the token endpoint, the client SHOULD only commence a
273 device authorization request when prompted by the user, and not
274 automatically such as when the app starts or when the previous
275 authorization session expires or fails.
277 3.2. Device Authorization Response
279 In response, the authorization server generates a unique device
280 verification code and an end-user code that are valid for a limited
281 time and includes them in the HTTP response body using the
282 "application/json" format [RFC8259] with a 200 (OK) status code. The
283 response contains the following parameters:
285 device_code
286 REQUIRED. The device verification code.
288 user_code
289 REQUIRED. The end-user verification code.
291 verification_uri
292 REQUIRED. The end-user verification URI on the authorization
293 server. The URI should be short and easy to remember as end users
294 will be asked to manually type it into their user-agent.
296 verification_uri_complete
297 OPTIONAL. A verification URI that includes the "user_code" (or
298 other information with the same function as the "user_code"),
299 designed for non-textual transmission.
301 expires_in
302 REQUIRED. The lifetime in seconds of the "device_code" and
303 "user_code".
305 interval
306 OPTIONAL. The minimum amount of time in seconds that the client
307 SHOULD wait between polling requests to the token endpoint. If no
308 value is provided, clients MUST use 5 as the default.
310 For example:
312 HTTP/1.1 200 OK
313 Content-Type: application/json
314 Cache-Control: no-store
316 {
317 "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
318 "user_code": "WDJB-MJHT",
319 "verification_uri": "https://example.com/device",
320 "verification_uri_complete":
321 "https://example.com/device?user_code=WDJB-MJHT",
322 "expires_in": 1800,
323 "interval": 5
324 }
326 3.3. User Interaction
328 After receiving a successful Authorization Response, the client
329 displays or otherwise communicates the "user_code" and the
330 "verification_uri" to the end user and instructs them to visit the
331 URI in a user agent on a secondary device (for example, in a browser
332 on their mobile phone), and enter the user code.
334 +-----------------------------------------------+
335 | |
336 | Using a browser on another device, visit: |
337 | https://example.com/device |
338 | |
339 | And enter the code: |
340 | WDJB-MJHT |
341 | |
342 +-----------------------------------------------+
344 Figure 2: Example User Instruction
346 The authorizing user navigates to the "verification_uri" and
347 authenticates with the authorization server in a secure TLS-protected
348 ([RFC8446]) session. The authorization server prompts the end user
349 to identify the device authorization session by entering the
350 "user_code" provided by the client. The authorization server should
351 then inform the user about the action they are undertaking and ask
352 them to approve or deny the request. Once the user interaction is
353 complete, the server MAY inform the user to return to their device.
355 During the user interaction, the device continuously polls the token
356 endpoint with the "device_code", as detailed in Section 3.4, until
357 the user completes the interaction, the code expires, or another
358 error occurs. The "device_code" is not intended for the end user
359 directly, and thus should not be displayed during the interaction to
360 avoid confusing the end user.
362 Authorization servers supporting this specification MUST implement a
363 user interaction sequence that starts with the user navigating to
364 "verification_uri" and continues with them supplying the "user_code"
365 at some stage during the interaction. Other than that, the exact
366 sequence and implementation of the user interaction is up to the
367 authorization server, for example, the authorization server may
368 enable new users to sign up for an account during the authorization
369 flow, or add additional security verification steps.
371 It is NOT RECOMMENDED for authorization servers to include the user
372 code in the verification URI ("verification_uri"), as this increases
373 the length and complexity of the URI that the user must type. While
374 the user must still type the same number of characters with the
375 user_code separated, once they successfully navigate to the
376 verification_uri, any errors in entering the code can be highlighted
377 by the authorization server to improve the user experience. The next
378 section documents user interaction with "verification_uri_complete",
379 which is designed to carry both pieces of information.
381 3.3.1. Non-textual Verification URI Optimization
383 When "verification_uri_complete" is included in the Authorization
384 Response (Section 3.2), clients MAY present this URI in a non-textual
385 manner using any method that results in the browser being opened with
386 the URI, such as with QR (Quick Response) codes or NFC (Near Field
387 Communication), to save the user typing the URI.
389 For usability reasons, it is RECOMMENDED for clients to still display
390 the textual verification URI ("verification_uri") for users not able
391 to use such a shortcut. Clients MUST still display the "user_code",
392 as the authorization server will require the user to confirm it to
393 disambiguate devices, or as a remote phishing mitigation (See
394 Section 5.4).
396 If the user starts the user interaction by browsing to
397 "verification_uri_complete", then the user interaction described in
398 Section 3.3 is still followed, but with the optimization that the
399 user does not need to type the "user_code". The server SHOULD
400 display the "user_code" to the user and ask them to verify that it
401 matches the "user_code" being displayed on the device, to confirm
402 they are authorizing the correct device. As before, in addition to
403 taking steps to confirm the identity of the device, the user should
404 also be afforded the choice to approve or deny the authorization
405 request.
407 +-------------------------------------------------+
408 | |
409 | Scan the QR code, or using +------------+ |
410 | a browser on another device, |[_].. . [_]| |
411 | visit: | . .. . .| |
412 | https://example.com/device | . . . ....| |
413 | |. . . . | |
414 | And enter the code: |[_]. ... . | |
415 | WDJB-MJHT +------------+ |
416 | |
417 +-------------------------------------------------+
419 Figure 3: Example User Instruction with QR Code Representation of the
420 Complete Verification URI
422 3.4. Device Access Token Request
424 After displaying instructions to the user, the client makes an Access
425 Token Request to the token endpoint (as defined by Section 3.2 of
426 [RFC6749]) with a "grant_type" of
427 "urn:ietf:params:oauth:grant-type:device_code". This is an extension
428 grant type (as defined by Section 4.5 of [RFC6749]) created by this
429 specification, with the following parameters:
431 grant_type
432 REQUIRED. Value MUST be set to
433 "urn:ietf:params:oauth:grant-type:device_code".
435 device_code
436 REQUIRED. The device verification code, "device_code" from the
437 Device Authorization Response, defined in Section 3.2.
439 client_id
440 REQUIRED, if the client is not authenticating with the
441 authorization server as described in Section 3.2.1. of [RFC6749].
443 For example, the client makes the following HTTPS request (line
444 breaks are for display purposes only):
446 POST /token HTTP/1.1
447 Host: server.example.com
448 Content-Type: application/x-www-form-urlencoded
450 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
451 &device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
452 &client_id=459691054427
454 If the client was issued client credentials (or assigned other
455 authentication requirements), the client MUST authenticate with the
456 authorization server as described in Section 3.2.1 of [RFC6749].
457 Note that there are security implications of statically distributed
458 client credentials, see Section 5.6.
460 The response to this request is defined in Section 3.5. Unlike other
461 OAuth grant types, it is expected for the client to try the Access
462 Token Request repeatedly in a polling fashion, based on the error
463 code in the response.
465 3.5. Device Access Token Response
467 If the user has approved the grant, the token endpoint responds with
468 a success response defined in Section 5.1 of [RFC6749]; otherwise it
469 responds with an error, as defined in Section 5.2 of [RFC6749].
471 In addition to the error codes defined in Section 5.2 of [RFC6749],
472 the following error codes are specified by the device flow for use in
473 token endpoint responses:
475 authorization_pending
476 The authorization request is still pending as the end user hasn't
477 yet completed the user interaction steps (Section 3.3). The
478 client SHOULD repeat the Access Token Request to the token
479 endpoint (a process known as polling). Before each new request
480 the client MUST wait at least the number of seconds specified by
481 the "interval" parameter of the Device Authorization Response (see
482 Section 3.2), or 5 seconds if none was provided, and respect any
483 increase in the polling interval required by the "slow_down"
484 error.
486 slow_down
487 A variant of "authorization_pending", the authorization request is
488 still pending and polling should continue, but the interval MUST
489 be increased by 5 seconds for this and all subsequent requests.
491 access_denied
492 The end user denied the authorization request.
494 expired_token
495 The "device_code" has expired and the device flow authorization
496 session has concluded. The client MAY commence a new Device
497 Authorization Request but SHOULD wait for user interaction before
498 restarting to avoid unnecessary polling.
500 A client receiving an error response as defined in Section 5.2 of
501 [RFC6749] MUST stop polling and SHOULD react accordingly, for
502 example, by displaying an error to the user, except for the error
503 codes "authorization_pending" and "slow_down" which are processed as
504 described above.
506 On encountering a connection timeout, clients MUST unilaterally
507 reduce their polling frequency before retrying. The use of an
508 exponential backoff algorithm to achieve this, such as by doubling
509 the polling interval on each such connection timeout, is RECOMMENDED.
511 The assumption of this specification is that the secondary device the
512 user is authorizing the request on does not have a way to communicate
513 back to the OAuth client. Only a one-way channel is required to make
514 this flow useful in many scenarios. For example, an HTML application
515 on a TV that can only make outbound requests. If a return channel
516 were to exist for the chosen user interaction interface, then the
517 device MAY wait until notified on that channel that the user has
518 completed the action before initiating the token request (as an
519 alternative to polling). Such behavior is, however, outside the
520 scope of this specification.
522 4. Discovery Metadata
524 Support for the device flow MAY be declared in the OAuth 2.0
525 Authorization Server Metadata [RFC8414] with the following metadata:
527 device_authorization_endpoint
528 OPTIONAL. URL of the authorization server's device authorization
529 endpoint defined in Section 3.1.
531 5. Security Considerations
533 5.1. User Code Brute Forcing
535 Since the user code is typed by the user, shorter codes are more
536 desirable for usability reasons. This means the entropy is typically
537 less than would be used for the device code or other OAuth bearer
538 token types where the code length does not impact usability. It is
539 therefore recommended that the server rate-limit user code attempts.
541 The user code SHOULD have enough entropy that when combined with rate
542 limiting and other mitigations makes a brute-force attack infeasible.
543 For example, it's generally held that 128-bit symmetric keys for
544 encryption are seen as good enough today because an attacker has to
545 put in 2^96 work to have a 2^-32 chance of guessing correctly via
546 brute force. The rate limiting and finite lifetime on the user code
547 places an artificial limit on the amount of work an attacker can
548 "do", so if, for instance, one uses a 8-character base-20 user code
549 (with roughly 34.5 bits of entropy), the rate-limiting interval and
550 validity period would need to only allow 5 attempts in order to get
551 the same 2^-32 probability of success by random guessing.
553 A successful brute forcing of the user code would enable the attacker
554 to authenticate with their own credentials and make an authorization
555 grant to the device. This is the opposite scenario to an OAuth
556 bearer token being brute forced, whereby the attacker gains control
557 of the victim's authorization grant. Such attacks may not always
558 make economic sense, for example for a video app the device owner may
559 then be able to purchase movies using the attacker's account, though
560 a privacy risk would still remain and thus is important to protect
561 against. Furthermore, some uses of the device flow give the granting
562 account the ability to perform actions such as controlling the
563 device, which needs to be protected.
565 The precise length of the user code and the entropy contained within
566 is at the discretion of the authorization server, which needs to
567 consider the sensitivity of their specific protected resources, the
568 practicality of the code length from a usability standpoint, and any
569 mitigations that are in place such as rate-limiting, when determining
570 the user code format.
572 5.2. Device Code Brute Forcing
574 An attacker who guesses the device code would be able to potentially
575 obtain the authorization code once the user completes the flow. As
576 the device code is not displayed to the user and thus there are
577 usability considerations on the length, a very high entropy code
578 SHOULD be used.
580 5.3. Device Trustworthiness
582 Unlike other native application OAuth 2.0 flows, the device
583 requesting the authorization is not the same as the device that the
584 user grants access from. Thus, signals from the approving user's
585 session and device are not relevant to the trustworthiness of the
586 client device.
588 Note that if an authorization server used with this flow is
589 malicious, then it could man-in-the-middle the backchannel flow to
590 another authorization server. In this scenario, the man-in-the-
591 middle is not completely hidden from sight, as the end user would end
592 up on the authorization page of the wrong service, giving them an
593 opportunity to notice that the URL in the browser's address bar is
594 wrong. For this to be possible, the device manufacturer must either
595 directly be the attacker, shipping a device intended to perform the
596 man-in-the-middle attack, or be using an authorization server that is
597 controlled by an attacker, possibly because the attacker compromised
598 the authorization server used by the device. In part, the person
599 purchasing the device is counting on it and its business partners to
600 be trustworthy.
602 5.4. Remote Phishing
604 It is possible for the device flow to be initiated on a device in an
605 attacker's possession. For example, an attacker might send an email
606 instructing the target user to visit the verification URL and enter
607 the user code. To mitigate such an attack, it is RECOMMENDED to
608 inform the user that they are authorizing a device during the user
609 interaction step (see Section 3.3), and to confirm that the device is
610 in their possession. The authorization server SHOULD display
611 information about the device so that the person can notice if a
612 software client was attempting to impersonating a hardware device.
614 For authorization servers that support the option specified in
615 Section 3.3.1 for the client to append the user code to the
616 authorization URI, it is particularly important to confirm that the
617 device is in the user's possession, as the user no longer has to type
618 the code manually. One possibility is to display the code during the
619 authorization flow and asking the user to verify that the same code
620 is being displayed on the device they are setting up.
622 The user code needs to have a long enough lifetime to be useable
623 (allowing the user to retrieve their secondary device, navigate to
624 the verification URI, login, etc.), but should be sufficiently short
625 to limit the usability of a code obtained for phishing. This doesn't
626 prevent a phisher presenting a fresh token, particularly in the case
627 they are interacting with the user in real time, but it does limit
628 the viability of codes sent over email or SMS.
630 5.5. Session Spying
632 While the device is pending authorization, it may be possible for a
633 malicious user to physically spy on the device user interface (by
634 viewing the screen on which it's displayed, for example) and hijack
635 the session by completing the authorization faster than the user that
636 initiated it. Devices SHOULD take into account the operating
637 environment when considering how to communicate the code to the user
638 to reduce the chances it will be observed by a malicious user.
640 5.6. Non-confidential Clients
642 Device clients are generally incapable of maintaining the
643 confidentiality of their credentials, as users in possession of the
644 device can reverse engineer it and extract the credentials.
645 Therefore, unless additional measures are taken, they should be
646 treated as public clients (as defined by Section 2.1 of OAuth 2.0)
647 susceptible to impersonation. The security considerations of
648 Section 5.3.1 of [RFC6819] and Sections 8.5 and 8.6 of [RFC8252]
649 apply to such clients.
651 The user may also be able to obtain the device_code and/or other
652 OAuth bearer tokens issued to their client, which would allow them to
653 use their own authorization grant directly by impersonating the
654 client. Given that the user in possession of the client credentials
655 can already impersonate the client and create a new authorization
656 grant (with a new device_code), this doesn't represent a separate
657 impersonation vector.
659 5.7. Non-Visual Code Transmission
661 There is no requirement that the user code be displayed by the device
662 visually. Other methods of one-way communication can potentially be
663 used, such as text-to-speech audio, or Bluetooth Low Energy. To
664 mitigate an attack in which a malicious user can bootstrap their
665 credentials on a device not in their control, it is RECOMMENDED that
666 any chosen communication channel only be accessible by people in
667 close proximity. E.g., users who can see, or hear the device.
669 6. Usability Considerations
671 This section is a non-normative discussion of usability
672 considerations.
674 6.1. User Code Recommendations
676 For many users, their nearest Internet-connected device will be their
677 mobile phone, and typically these devices offer input methods that
678 are more time consuming than a computer keyboard to change the case
679 or input numbers. To improve usability (improving entry speed, and
680 reducing retries), these limitations should be taken into account
681 when selecting the user-code character set.
683 One way to improve input speed is to restrict the character set to
684 case-insensitive A-Z characters, with no digits. These characters
685 can typically be entered on a mobile keyboard without using modifier
686 keys. Further removing vowels to avoid randomly creating words
687 results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes
688 or other punctuation may be included for readability.
690 An example user code following this guideline containing 8
691 significant characters and dashes added for end-user readability,
692 with a resulting entropy of 20^8: "WDJB-MJHT".
694 Pure numeric codes are also a good choice for usability, especially
695 for clients targeting locales where A-Z character keyboards are not
696 used, though their length needs to be longer to maintain a high
697 entropy.
699 An example numeric user code containing 9 significant digits and
700 dashes added for end-user readability, with an entropy of 10^9:
701 "019-450-730".
703 When processing the inputted user code, the server should strip
704 dashes and other punctuation it added for readability (making the
705 inclusion of that punctuation by the user optional). For codes using
706 only characters in the A-Z range as with the base-20 charset defined
707 above, the user's input should be upper-cased before comparison to
708 account for the fact that the user may input the equivalent lower-
709 case characters. Further stripping of all characters outside the
710 user_code charset is recommended to reduce instances where an
711 errantly typed character (like a space character) invalidates
712 otherwise valid input.
714 It is RECOMMENDED to avoid character sets that contain two or more
715 characters that can easily be confused with each other like "0" and
716 "O", or "1", "l" and "I". Furthermore, the extent practical, where a
717 character set contains one character that may be confused with
718 characters outside the character set the character outside the set
719 MAY be substituted with the one in the character set that it is
720 commonly confused with (for example, "O" for "0" when using a
721 numerical 0-9 character set).
723 6.2. Non-Browser User Interaction
725 Devices and authorization servers MAY negotiate an alternative code
726 transmission and user interaction method in addition to the one
727 described in Section 3.3. Such an alternative user interaction flow
728 could obviate the need for a browser and manual input of the code,
729 for example, by using Bluetooth to transmit the code to the
730 authorization server's companion app. Such interaction methods can
731 utilize this protocol, as ultimately, the user just needs to identify
732 the authorization session to the authorization server; however, user
733 interaction other than via the verification URI is outside the scope
734 of this specification.
736 7. IANA Considerations
738 7.1. OAuth Parameters Registration
740 This specification registers the following values in the IANA "OAuth
741 Parameters" registry [IANA.OAuth.Parameters] established by
742 [RFC6749].
744 7.1.1. Registry Contents
746 o Parameter name: device_code
747 o Parameter usage location: token request
748 o Change controller: IESG
749 o Specification Document: Section 3.1 of [[ this specification ]]
751 7.2. OAuth URI Registration
753 This specification registers the following values in the IANA "OAuth
754 URI" registry [IANA.OAuth.Parameters] established by [RFC6755].
756 7.2.1. Registry Contents
758 o URN: urn:ietf:params:oauth:grant-type:device_code
759 o Common Name: Device flow grant type for OAuth 2.0
760 o Change controller: IESG
761 o Specification Document: Section 3.1 of [[ this specification ]]
763 7.3. OAuth Extensions Error Registration
765 This specification registers the following values in the IANA "OAuth
766 Extensions Error Registry" registry [IANA.OAuth.Parameters]
767 established by [RFC6749].
769 7.3.1. Registry Contents
771 o Error name: authorization_pending
772 o Error usage location: Token endpoint response
773 o Related protocol extension: [[ this specification ]]
774 o Change controller: IETF
775 o Specification Document: Section 3.5 of [[ this specification ]]
777 o Error name: access_denied
778 o Error usage location: Token endpoint response
779 o Related protocol extension: [[ this specification ]]
780 o Change controller: IETF
781 o Specification Document: Section 3.5 of [[ this specification ]]
783 o Error name: slow_down
784 o Error usage location: Token endpoint response
785 o Related protocol extension: [[ this specification ]]
786 o Change controller: IETF
787 o Specification Document: Section 3.5 of [[ this specification ]]
789 o Error name: expired_token
790 o Error usage location: Token endpoint response
791 o Related protocol extension: [[ this specification ]]
792 o Change controller: IETF
793 o Specification Document: Section 3.5 of [[ this specification ]]
795 7.4. OAuth 2.0 Authorization Server Metadata
797 This specification registers the following values in the IANA "OAuth
798 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters]
799 established by [RFC8414].
801 7.4.1. Registry Contents
803 o Metadata name: device_authorization_endpoint
804 o Metadata Description: The Device Authorization Endpoint.
805 o Change controller: IESG
806 o Specification Document: Section 4 of [[ this specification ]]
808 8. Normative References
810 [HTML5] IANA, "HTML5",
811 .
813 [IANA.OAuth.Parameters]
814 IANA, "OAuth Parameters",
815 .
817 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
818 RFC 6749, DOI 10.17487/RFC6749, October 2012,
819 .
821 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
822 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
823 .
825 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
826 Threat Model and Security Considerations", RFC 6819,
827 DOI 10.17487/RFC6819, January 2013,
828 .
830 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
831 "Recommendations for Secure Use of Transport Layer
832 Security (TLS) and Datagram Transport Layer Security
833 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
834 2015, .
836 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
837 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
838 May 2017, .
840 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
841 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
842 .
844 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
845 Interchange Format", STD 90, RFC 8259,
846 DOI 10.17487/RFC8259, December 2017,
847 .
849 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
850 Authorization Server Metadata", RFC 8414,
851 DOI 10.17487/RFC8414, June 2018,
852 .
854 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
855 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
856 .
858 Appendix A. Acknowledgements
860 The starting point for this document was the Internet-Draft draft-
861 recordon-oauth-v2-device, authored by David Recordon and Brent
862 Goldman, which itself was based on content in draft versions of the
863 OAuth 2.0 protocol specification removed prior to publication due to
864 a then lack of sufficient deployment expertise. Thank you to the
865 OAuth working group members who contributed to those earlier drafts.
867 This document was produced in the OAuth working group under the
868 chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with
869 Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as
870 Security Area Directors.
872 The following individuals contributed ideas, feedback, and wording
873 that shaped and formed the final specification:
875 Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin
876 Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt,
877 James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin
878 Richer, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Ken Wang,
879 and Steven E. Wright.
881 Appendix B. Document History
883 [[ to be removed by the RFC Editor before publication as an RFC ]]
885 -14
887 o Added more normative text on polling behavior.
888 o Added discussion on risk of user retrieving their own device_code.
889 o Editorial improvements.
891 -13
892 o Added a longer discussion about entropy, proposed by Benjamin
893 Kaduk.
894 o Added device_code to OAuth IANA registry.
895 o Expanded explanation of "case insensitive".
896 o Added security section on Device Code Brute Forcing.
897 o application/x-www-form-urlencoded normativly referenced.
898 o Editorial improvements.
900 -12
902 o Set a default polling interval to 5s explicitly.
903 o Defined the slow_down behavior that it should increase the current
904 interval by 5s.
905 o expires_in now REQUIRED
906 o Other changes in response to review feedback.
908 -11
910 o Updated reference to OAuth 2.0 Authorization Server Metadata.
912 -10
914 o Added a missing definition of access_denied for use on the token
915 endpoint.
916 o Corrected text documenting which error code should be returned for
917 expired tokens (it's "expired_token", not "invalid_grant").
918 o Corrected section reference to RFC 8252 (the section numbers had
919 changed after the initial reference was made).
920 o Fixed line length of one diagram (was causing xml2rfc warnings).
921 o Added line breaks so the URN grant_type is presented on an
922 unbroken line.
923 o Typos fixed and other stylistic improvements.
925 -09
927 o Addressed review comments by Security Area Director Eric Rescorla
928 about the potential of a confused deputy attack.
930 -08
932 o Expanded the User Code Brute Forcing section to include more
933 detail on this attack.
935 -07
937 o Replaced the "user_code" URI parameter optimization with
938 verification_uri_complete following the IETF99 working group
939 discussion.
941 o Added security consideration about spying.
942 o Required that device_code not be shown.
943 o Added text regarding a minimum polling interval.
945 -06
947 o Clarified usage of the "user_code" URI parameter optimization
948 following the IETF98 working group discussion.
950 -05
952 o response_type parameter removed from authorization request.
953 o Added option for clients to include the user_code on the
954 verification URI.
955 o Clarified token expiry, and other nits.
957 -04
959 o Security & Usability sections. OAuth Discovery Metadata.
961 -03
963 o device_code is now a URN. Added IANA Considerations
965 -02
967 o Added token request & response specification.
969 -01
971 o Applied spelling and grammar corrections and added the Document
972 History appendix.
974 -00
976 o Initial working group draft based on draft-recordon-oauth-
977 v2-device.
979 Authors' Addresses
981 William Denniss
982 Google
983 1600 Amphitheatre Pkwy
984 Mountain View, CA 94043
985 USA
987 Email: wdenniss@google.com
988 URI: http://wdenniss.com/device-flow
989 John Bradley
990 Ping Identity
992 Email: ve7jtb@ve7jtb.com
993 URI: http://www.thread-safe.com/
995 Michael B. Jones
996 Microsoft
998 Email: mbj@microsoft.com
999 URI: http://self-issued.info/
1001 Hannes Tschofenig
1002 ARM Limited
1003 Austria
1005 Email: Hannes.Tschofenig@gmx.net
1006 URI: http://www.tschofenig.priv.at