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