idnits 2.17.1 draft-ietf-oauth-device-flow-12.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 (August 1, 2018) is 2094 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 186, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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: 4 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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: February 2, 2019 Ping Identity 6 M. Jones 7 Microsoft 8 H. Tschofenig 9 ARM Limited 10 August 1, 2018 12 OAuth 2.0 Device Flow for Browserless and Input Constrained Devices 13 draft-ietf-oauth-device-flow-12 15 Abstract 17 This OAuth 2.0 authorization flow for browserless and input- 18 constrained devices, often referred to as the device flow, enables 19 OAuth clients to request user authorization from devices that have an 20 Internet connection, but don't have an easy input method (such as a 21 smart TV, media console, picture frame, or printer), or lack a 22 suitable browser for a more traditional OAuth flow. This 23 authorization flow instructs the user to perform the authorization 24 request on a secondary device, such as a smartphone. There is no 25 requirement for communication between the constrained device and the 26 user's secondary device. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on February 2, 2019. 45 Copyright Notice 47 Copyright (c) 2018 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3.1. Device Authorization Request . . . . . . . . . . . . . . 5 66 3.2. Device Authorization Response . . . . . . . . . . . . . . 6 67 3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7 68 3.3.1. Non-textual Verification URI Optimization . . . . . . 8 69 3.4. Device Access Token Request . . . . . . . . . . . . . . . 9 70 3.5. Device Access Token Response . . . . . . . . . . . . . . 10 71 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 11 72 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 73 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11 74 5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 12 75 5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 12 76 5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 13 77 5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 13 78 5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 13 79 6. Usability Considerations . . . . . . . . . . . . . . . . . . 13 80 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 14 81 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 83 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 15 84 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 85 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15 86 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 87 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 16 88 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 89 8. Normative References . . . . . . . . . . . . . . . . . . . . 16 90 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 91 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 94 1. Introduction 96 This OAuth 2.0 [RFC6749] protocol flow for browserless and input- 97 constrained devices, often referred to as the device flow, enables 98 OAuth clients to request user authorization from devices that have an 99 internet connection, but don't have an easy input method (such as a 100 smart TV, media console, picture frame, or printer), or lack a 101 suitable browser for a more traditional OAuth flow. This 102 authorization flow instructs the user to perform the authorization 103 request on a secondary device, such as a smartphone. 105 The device flow is not intended to replace browser-based OAuth in 106 native apps on capable devices (like smartphones). Those apps should 107 follow the practices specified in OAuth 2.0 for Native Apps 108 [RFC8252]. 110 The only requirements to use this flow are that the device is 111 connected to the Internet, and able to make outbound HTTPS requests, 112 be able to display or otherwise communicate a URI and code sequence 113 to the user, and that the user has a secondary device (e.g., personal 114 computer or smartphone) from which to process the request. There is 115 no requirement for two-way communication between the OAuth client and 116 the user-agent, enabling a broad range of use-cases. 118 Instead of interacting with the end user's user agent, the client 119 instructs the end user to use another computer or device and connect 120 to the authorization server to approve the access request. Since the 121 client cannot receive incoming requests, it polls the authorization 122 server repeatedly until the end user completes the approval process. 124 +----------+ +----------------+ 125 | |>---(A)-- Client Identifier --->| | 126 | | | | 127 | |<---(B)-- Verification Code, --<| | 128 | | User Code, | | 129 | | & Verification URI | | 130 | Device | | | 131 | Client | Client Identifier & | | 132 | |>---(E)-- Verification Code --->| | 133 | | polling... | | 134 | |>---(E)-- Verification Code --->| | 135 | | | Authorization | 136 | |<---(F)-- Access Token --------<| Server | 137 +----------+ (w/ Optional Refresh Token) | | 138 v | | 139 : | | 140 (C) User Code & Verification URI | | 141 : | | 142 v | | 143 +----------+ | | 144 | End user | | | 145 | at |<---(D)-- User authenticates -->| | 146 | Browser | | | 147 +----------+ +----------------+ 149 Figure 1: Device Flow. 151 The device flow illustrated in Figure 1 includes the following steps: 153 (A) The client requests access from the authorization server and 154 includes its client identifier in the request. 156 (B) The authorization server issues a verification code, an end- 157 user code, and provides the end-user verification URI. 159 (C) The client instructs the end user to use its user agent 160 (elsewhere) and visit the provided end-user verification URI. The 161 client provides the user with the end-user code to enter in order 162 to grant access. 164 (D) The authorization server authenticates the end user (via the 165 user agent) and prompts the user to grant the client's access 166 request. If the user agrees to the client's access request, the 167 user enters the user code provided by the client. The 168 authorization server validates the user code provided by the user. 170 (E) While the end user authorizes (or denies) the client's request 171 (step D), the client repeatedly polls the authorization server to 172 find out if the user completed the user authorization step. The 173 client includes the verification code and its client identifier. 175 (F) Assuming the end user granted access, the authorization server 176 validates the verification code provided by the client and 177 responds back with the access token. 179 2. Terminology 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in BCP 184 14 [RFC2119] [RFC8174] when, and only when, they appear in all 185 capitals, as shown here. 187 Device Authorization Endpoint: 188 The authorization server's endpoint capable of issuing device 189 verification codes, user codes, and verification URLs. 191 Device Verification Code: 192 A short-lived token representing an authorization session. 194 End-User Verification Code: 195 A short-lived token which the device displays to the end user, is 196 entered by the user on the authorization server, and is thus used 197 to bind the device to the user. 199 3. Protocol 201 3.1. Device Authorization Request 203 This specification defines a new OAuth endpoint, the device 204 authorization endpoint. This is separate from the OAuth 205 authorization endpoint defined in [RFC6749] with which the user 206 interacts with via a user-agent (i.e., a browser). By comparison, 207 when using the device authorization endpoint, the OAuth client on the 208 device interacts with the authorization server directly without 209 presenting the request in a user-agent, and the end user authorizes 210 the request on a separate device. This interaction is defined as 211 follows. 213 The client initiates the flow by requesting a set of verification 214 codes from the authorization server by making an HTTP "POST" request 215 to the device authorization endpoint. 217 All requests from the device MUST use the Transport Layer Security 218 (TLS) [RFC5246] protocol and implement the best practices of 219 [RFC7525]. 221 The client constructs the request with the following parameters, 222 encoded with the "application/x-www-form-urlencoded" content type: 224 client_id 225 REQUIRED. The client identifier as described in Section 2.2 of 226 [RFC6749]. 228 scope 229 OPTIONAL. The scope of the access request as described by 230 Section 3.3 of [RFC6749]. 232 For example, the client makes the following HTTPS request (line 233 breaks are for display purposes only): 235 POST /device_authorization HTTP/1.1 236 Host: server.example.com 237 Content-Type: application/x-www-form-urlencoded 239 client_id=459691054427 241 Parameters sent without a value MUST be treated as if they were 242 omitted from the request. The authorization server MUST ignore 243 unrecognized request parameters. Request and response parameters 244 MUST NOT be included more than once. 246 Due to the polling nature of this protocol, to avoid unneeded 247 requests on the token endpoint, the client SHOULD only commence a 248 device authorization request when prompted by the user, and not 249 automatically such as when the app starts. 251 3.2. Device Authorization Response 253 In response, the authorization server generates a device verification 254 code and an end-user code that are valid for a limited time and 255 includes them in the HTTP response body using the "application/json" 256 format [RFC8259] with a 200 (OK) status code. The response contains 257 the following parameters: 259 device_code 260 REQUIRED. The device verification code. 262 user_code 263 REQUIRED. The end-user verification code. 265 verification_uri 266 REQUIRED. The end-user verification URI on the authorization 267 server. The URI should be short and easy to remember as end users 268 will be asked to manually type it into their user-agent. 270 verification_uri_complete 271 OPTIONAL. A verification URI that includes the "user_code" (or 272 other information with the same function as the "user_code"), 273 designed for non-textual transmission. 275 expires_in 276 REQUIRED. The lifetime in seconds of the "device_code" and 277 "user_code". 279 interval 280 OPTIONAL. The minimum amount of time in seconds that the client 281 SHOULD wait between polling requests to the token endpoint. If no 282 value is provided, clients MUST use 5 as the default. 284 For example: 286 HTTP/1.1 200 OK 287 Content-Type: application/json 288 Cache-Control: no-store 290 { 291 "device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8", 292 "user_code":"WDJB-MJHT", 293 "verification_uri":"https://www.example.com/device", 294 "verification_uri_complete": 295 "https://www.example.com/device?user_code=WDJB-MJHT", 296 "expires_in" : 1800, 297 "interval": 5 298 } 300 3.3. User Interaction 302 After receiving a successful Authorization Response, the client 303 displays or otherwise communicates the "user_code" and the 304 "verification_uri" to the end user and instructs them to visit the 305 URI in a user agent on a secondary device (for example, in a browser 306 on their mobile phone), and enter the user code. 308 +-----------------------------------------------+ 309 | | 310 | Using a browser on another device, visit: | 311 | https://example.com/device | 312 | | 313 | And enter the code: | 314 | WDJB-MJHT | 315 | | 316 +-----------------------------------------------+ 318 Figure 2: Example User Instruction 320 The authorizing user navigates to the "verification_uri" and 321 authenticates with the authorization server in a secure TLS-protected 322 ([RFC5246]) session. The authorization server prompts the end user 323 to identify the device authorization session by entering the 324 "user_code" provided by the client. The authorization server should 325 then inform the user about the action they are undertaking and ask 326 them to approve or deny the request. Once the user interaction is 327 complete, the server MAY inform the user to return to their device. 329 During the user interaction, the device continuously polls the token 330 endpoint with the "device_code", as detailed in Section 3.4, until 331 the user completes the interaction, the code expires, or another 332 error occurs. The "device_code" is not intended for the end user 333 directly, and thus should not be displayed during the interaction to 334 avoid confusing the end user. 336 Authorization servers supporting this specification MUST implement a 337 user interaction sequence that starts with the user navigating to 338 "verification_uri" and continues with them supplying the "user_code" 339 at some stage during the interaction. Other than that, the exact 340 sequence and implementation of the user interaction is up to the 341 authorization server and is out of scope of this specification. 343 It is NOT RECOMMENDED for authorization servers to include the user 344 code in the verification URI ("verification_uri"), as this increases 345 the length and complexity of the URI that the user must type. The 346 next section documents user interaction with 347 "verification_uri_complete", which is designed to carry this 348 information. 350 3.3.1. Non-textual Verification URI Optimization 352 When "verification_uri_complete" is included in the Authorization 353 Response (Section 3.2), clients MAY present this URI in a non-textual 354 manner using any method that results in the browser being opened with 355 the URI, such as with QR (Quick Response) codes or NFC (Near Field 356 Communication), to save the user typing the URI. 358 For usability reasons, it is RECOMMENDED for clients to still display 359 the textual verification URI ("verification_uri") for users not able 360 to use such a shortcut. Clients MUST still display the "user_code", 361 as the authorization server may still require the user to confirm it 362 to disambiguate devices, or as a remote phishing mitigation (See 363 Section 5.3). 365 +-------------------------------------------------+ 366 | | 367 | Scan the QR code, or using +------------+ | 368 | a browser on another device, |[_].. . [_]| | 369 | visit: | . .. . .| | 370 | https://example.com/device | . . . ....| | 371 | |. . . . | | 372 | And enter the code: |[_]. ... . | | 373 | WDJB-MJHT +------------+ | 374 | | 375 +-------------------------------------------------+ 377 Figure 3: Example User Instruction with QR Code Representation of the 378 Complete Verification URI 380 3.4. Device Access Token Request 382 After displaying instructions to the user, the client makes an Access 383 Token Request to the token endpoint with a "grant_type" of 384 "urn:ietf:params:oauth:grant-type:device_code". This is an extension 385 grant type (as defined by Section 4.5 of [RFC6749]) with the 386 following parameters: 388 grant_type 389 REQUIRED. Value MUST be set to 390 "urn:ietf:params:oauth:grant-type:device_code". 392 device_code 393 REQUIRED. The device verification code, "device_code" from the 394 Device Authorization Response, defined in Section 3.2. 396 client_id 397 REQUIRED, if the client is not authenticating with the 398 authorization server as described in Section 3.2.1. of [RFC6749]. 400 For example, the client makes the following HTTPS request (line 401 breaks are for display purposes only): 403 POST /token HTTP/1.1 404 Host: server.example.com 405 Content-Type: application/x-www-form-urlencoded 407 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 408 &device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8 409 &client_id=459691054427 411 If the client was issued client credentials (or assigned other 412 authentication requirements), the client MUST authenticate with the 413 authorization server as described in Section 3.2.1 of [RFC6749]. 414 Note that there are security implications of statically distributed 415 client credentials, see Section 5.5. 417 The response to this request is defined in Section 3.5. Unlike other 418 OAuth grant types, it is expected for the client to try the Access 419 Token Request repeatedly in a polling fashion, based on the error 420 code in the response. 422 3.5. Device Access Token Response 424 If the user has approved the grant, the token endpoint responds with 425 a success response defined in Section 5.1 of [RFC6749]; otherwise it 426 responds with an error, as defined in Section 5.2 of [RFC6749]. 428 In addition to the error codes defined in Section 5.2 of [RFC6749], 429 the following error codes are specified by the device flow for use in 430 token endpoint responses: 432 authorization_pending 433 The authorization request is still pending as the end user hasn't 434 yet completed the user interaction steps (Section 3.3). The 435 client SHOULD repeat the Access Token Request to the token 436 endpoint (a process known as polling). Before each new request 437 the client MUST wait at least the number of seconds specified by 438 the "interval" parameter of the Device Authorization Response (see 439 Section 3.2), or 5 seconds if none was provided, and respect any 440 increase in the polling interval required by the "slow_down" 441 error. 443 slow_down 444 A variant of "authorization_pending", the authorization request is 445 still pending and polling should continue, but the interval MUST 446 be increased by 5 seconds for this and all subsequent requests. 448 access_denied 449 The end user denied the authorization request. 451 expired_token 452 The "device_code" has expired and the device flow authorization 453 session has concluded. The client MAY commence a new Device 454 Authorization Request but SHOULD wait for user interaction before 455 restarting to avoid unnecessary polling. 457 A client receiving an error response as defined in Section 5.2 of 458 [RFC6749] MUST stop polling and SHOULD react accordingly, for 459 example, by displaying an error to the user, except for the error 460 codes "authorization_pending" and "slow_down" which are be processed 461 as described above. 463 The assumption of this specification is that the secondary device the 464 user is authorizing the request on does not have a way to communicate 465 back to the OAuth client. Only a one-way channel is required to make 466 this flow useful in many scenarios. For example, an HTML application 467 on a TV that can only make outbound requests. If a return channel 468 were to exist for the chosen user interaction interface, then the 469 device MAY wait until notified on that channel that the user has 470 completed the action before initiating the token request (as an 471 alternative to polling). Such behavior is, however, outside the 472 scope of this specification. 474 4. Discovery Metadata 476 Support for the device flow MAY be declared in the OAuth 2.0 477 Authorization Server Metadata [RFC8414] with the following metadata: 479 device_authorization_endpoint 480 OPTIONAL. URL of the authorization server's device authorization 481 endpoint defined in Section 3.1. 483 5. Security Considerations 485 5.1. User Code Brute Forcing 487 Since the user code is typed by the user, shorter codes are more 488 desirable for usability reasons. This means the entropy is typically 489 less than would be used for the device code or other OAuth bearer 490 token types where the code length does not impact usability. It is 491 therefore recommended that the server rate-limit user code attempts. 492 The user code SHOULD have enough entropy that when combined with rate 493 limiting and other mitigations makes a brute-force attack infeasible. 495 A successful brute forcing of the user code would enable the attacker 496 to authenticate with their own credentials and make an authorization 497 grant to the device. This is the opposite scenario to an OAuth 498 bearer token being brute forced, whereby the attacker gains control 499 of the victim's authorization grant. Such attacks may not always 500 make economic sense, for example for a video app the device owner may 501 then be able to purchase movies using the attacker's account, though 502 a privacy risk would still remain and thus is important to protect 503 against. Furthermore, some uses of the device flow give the granting 504 account the ability to perform actions such as controlling the 505 device, which needs to be protected. 507 The precise length of the user code and the entropy contained within 508 is at the discretion of the authorization server, which needs to 509 consider the sensitivity of their specific protected resources, the 510 practicality of the code length from a usability standpoint, and any 511 mitigations that are in place such as rate-limiting, when determining 512 the user code format. 514 5.2. Device Trustworthiness 516 Unlike other native application OAuth 2.0 flows, the device 517 requesting the authorization is not the same as the device that the 518 user grants access from. Thus, signals from the approving user's 519 session and device are not relevant to the trustworthiness of the 520 client device. 522 Note that if an authorization server used with this flow is 523 malicious, then it could man-in-the-middle the backchannel flow to 524 another authorization server. In this scenario, the man-in-the- 525 middle is not completely hidden from sight, as the end user would end 526 up on the authorization page of the wrong service, giving them an 527 opportunity to notice that the authorization being requested is 528 wrong. For this to be possible, the device manufacturer must either 529 directly be the attacker, shipping a device intended to perform the 530 man-in-the-middle attack, or be using an authorization server that is 531 controlled by an attacker, possibly because the attacker compromised 532 the authorization server used by the device. In part, the person 533 purchasing the device is counting on it and its business partners to 534 be trustworthy. 536 5.3. Remote Phishing 538 It is possible for the device flow to be initiated on a device in an 539 attacker's possession. For example, an attacker might send an email 540 instructing the target user to visit the verification URL and enter 541 the user code. To mitigate such an attack, it is RECOMMENDED to 542 inform the user that they are authorizing a device during the user 543 interaction step (see Section 3.3), and to confirm that the device is 544 in their possession. The authorization server SHOULD display 545 information about the device so that the person can notice if a 546 software client was attempting to impersonating a hardware device. 548 For authorization servers that support the option specified in 549 Section 3.3.1 for the client to append the user code to the 550 authorization URI, it is particularly important to confirm that the 551 device is in the user's possession, as the user no longer has to type 552 the code manually. One possibility is to display the code during the 553 authorization flow and asking the user to verify that the same code 554 is being displayed on the device they are setting up. 556 The user code needs to have a long enough lifetime to be useable 557 (allowing the user to retrieve their secondary device, navigate to 558 the verification URI, login, etc.), but should be sufficiently short 559 to limit the usability of a code obtained for phishing. This doesn't 560 prevent a phisher presenting a fresh token, particularly in the case 561 they are interacting with the user in real time, but it does limit 562 the viability of codes sent over email or SMS. 564 5.4. Session Spying 566 While the device is pending authorization, it may be possible for a 567 malicious user to spy on the device user interface and hijack the 568 session by completing the authorization faster than the user that 569 initiated it. Devices SHOULD take into account the operating 570 environment when considering how to communicate the code to the user 571 to reduce the chances it will be observed by a malicious user. 573 5.5. Non-confidential Clients 575 Most device clients are incapable of being confidential clients, as 576 secrets that are statically included as part of an app distributed to 577 multiple users cannot be considered confidential. For such clients, 578 the recommendations of Section 5.3.1 of [RFC6819] and Section 8.5 of 579 [RFC8252] apply. 581 5.6. Non-Visual Code Transmission 583 There is no requirement that the user code be displayed by the device 584 visually. Other methods of one-way communication can potentially be 585 used, such as text-to-speech audio, or Bluetooth Low Energy. To 586 mitigate an attack in which a malicious user can bootstrap their 587 credentials on a device not in their control, it is RECOMMENDED that 588 any chosen communication channel only be accessible by people in 589 close proximity. E.g., users who can see, or hear the device. 591 6. Usability Considerations 593 This section is a non-normative discussion of usability 594 considerations. 596 6.1. User Code Recommendations 598 For many users, their nearest Internet-connected device will be their 599 mobile phone, and typically these devices offer input methods that 600 are more time consuming than a computer keyboard to change the case 601 or input numbers. To improve usability (improving entry speed, and 602 reducing retries), these limitations should be taken into account 603 when selecting the user-code character set. 605 One way to improve input speed is to restrict the character set to 606 case-insensitive A-Z characters, with no digits. These characters 607 can typically be entered on a mobile keyboard without using modifier 608 keys. Further removing vowels to avoid randomly creating words 609 results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes 610 or other punctuation may be included for readability. 612 An example user code following this guideline containing 8 613 significant characters and dashes added for end-user readability, 614 with a resulting entropy of 20^8: "WDJB-MJHT". 616 Pure numeric codes are also a good choice for usability, especially 617 for clients targeting locales where A-Z character keyboards are not 618 used, though their length needs to be longer to maintain a high 619 entropy. 621 An example numeric user code containing 9 significant digits and 622 dashes added for end-user readability, with an entropy of 10^9: 623 "019-450-730". 625 When processing the inputted user code, the server should strip 626 dashes and other punctuation it added for readability (making the 627 inclusion of that punctuation by the user optional). For codes using 628 only characters in the A-Z range as with the base-20 charset defined 629 above, the user's input should be upper-cased before comparison to 630 account for the fact that the user may input the equivalent lower- 631 case characters. Further stripping of all characters outside the 632 user_code charset is recommended to reduce instances where an 633 errantly typed character (like a space character) invalidates 634 otherwise valid input. 636 6.2. Non-Browser User Interaction 638 Devices and authorization servers MAY negotiate an alternative code 639 transmission and user interaction method in addition to the one 640 described in Section 3.3. Such an alternative user interaction flow 641 could obviate the need for a browser and manual input of the code, 642 for example, by using Bluetooth to transmit the code to the 643 authorization server's companion app. Such interaction methods can 644 utilize this protocol, as ultimately, the user just needs to identify 645 the authorization session to the authorization server; however, user 646 interaction other than via the verification URI is outside the scope 647 of this specification. 649 7. IANA Considerations 651 7.1. OAuth URI Registration 653 This specification registers the following values in the IANA "OAuth 654 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 656 7.1.1. Registry Contents 658 o URN: urn:ietf:params:oauth:grant-type:device_code 659 o Common Name: Device flow grant type for OAuth 2.0 660 o Change controller: IESG 661 o Specification Document: Section 3.1 of [[ this specification ]] 663 7.2. OAuth Extensions Error Registration 665 This specification registers the following values in the IANA "OAuth 666 Extensions Error Registry" registry [IANA.OAuth.Parameters] 667 established by [RFC6749]. 669 7.2.1. Registry Contents 671 o Error name: authorization_pending 672 o Error usage location: Token endpoint response 673 o Related protocol extension: [[ this specification ]] 674 o Change controller: IETF 675 o Specification Document: Section 3.5 of [[ this specification ]] 677 o Error name: access_denied 678 o Error usage location: Token endpoint response 679 o Related protocol extension: [[ this specification ]] 680 o Change controller: IETF 681 o Specification Document: Section 3.5 of [[ this specification ]] 683 o Error name: slow_down 684 o Error usage location: Token endpoint response 685 o Related protocol extension: [[ this specification ]] 686 o Change controller: IETF 687 o Specification Document: Section 3.5 of [[ this specification ]] 689 o Error name: expired_token 690 o Error usage location: Token endpoint response 691 o Related protocol extension: [[ this specification ]] 692 o Change controller: IETF 693 o Specification Document: Section 3.5 of [[ this specification ]] 695 7.3. OAuth 2.0 Authorization Server Metadata 697 This specification registers the following values in the IANA "OAuth 698 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 699 established by [RFC8414]. 701 7.3.1. Registry Contents 703 o Metadata name: device_authorization_endpoint 704 o Metadata Description: The Device Authorization Endpoint. 705 o Change controller: IESG 706 o Specification Document: Section 4 of [[ this specification ]] 708 8. Normative References 710 [IANA.OAuth.Parameters] 711 IANA, "OAuth Parameters", 712 . 714 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 715 (TLS) Protocol Version 1.2", RFC 5246, 716 DOI 10.17487/RFC5246, August 2008, 717 . 719 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 720 RFC 6749, DOI 10.17487/RFC6749, October 2012, 721 . 723 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 724 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 725 . 727 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 728 Threat Model and Security Considerations", RFC 6819, 729 DOI 10.17487/RFC6819, January 2013, 730 . 732 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 733 "Recommendations for Secure Use of Transport Layer 734 Security (TLS) and Datagram Transport Layer Security 735 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 736 2015, . 738 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 739 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 740 May 2017, . 742 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 743 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 744 . 746 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 747 Interchange Format", STD 90, RFC 8259, 748 DOI 10.17487/RFC8259, December 2017, 749 . 751 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 752 Authorization Server Metadata", RFC 8414, 753 DOI 10.17487/RFC8414, June 2018, 754 . 756 Appendix A. Acknowledgements 758 The starting point for this document was the Internet-Draft draft- 759 recordon-oauth-v2-device, authored by David Recordon and Brent 760 Goldman, which itself was based on content in draft versions of the 761 OAuth 2.0 protocol specification removed prior to publication due to 762 a then lack of sufficient deployment expertise. Thank you to the 763 OAuth working group members who contributed to those earlier drafts. 765 This document was produced in the OAuth working group under the 766 chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with 767 Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as 768 Security Area Directors. 770 The following individuals contributed ideas, feedback, and wording 771 that shaped and formed the final specification: 773 Brian Campbell, Roshni Chandrashekhar, Eric Fazendin, Torsten 774 Lodderstedt, James Manger, Breno de Medeiros, Simon Moffatt, Stein 775 Myrseth, Justin Richer, Nat Sakimura, Andrew Sciberras, Marius 776 Scurtescu, Ken Wang, and Steven E. Wright. 778 Appendix B. Document History 780 [[ to be removed by the RFC Editor before publication as an RFC ]] 782 -12 784 o Set a default polling interval to 5s explicitly. 786 o Defined the slow_down behavior that it should increase the current 787 interval by 5s. 788 o expires_in now REQUIRED 789 o Other changes in response to review feedback. 791 -11 793 o Updated reference to OAuth 2.0 Authorization Server Metadata. 795 -10 797 o Added a missing definition of access_denied for use on the token 798 endpoint. 799 o Corrected text documenting which error code should be returned for 800 expired tokens (it's "expired_token", not "invalid_grant"). 801 o Corrected section reference to RFC 8252 (the section numbers had 802 changed after the initial reference was made). 803 o Fixed line length of one diagram (was causing xml2rfc warnings). 804 o Added line breaks so the URN grant_type is presented on an 805 unbroken line. 806 o Typos fixed and other stylistic improvements. 808 -09 810 o Addressed review comments by Security Area Director Eric Rescorla 811 about the potential of a confused deputy attack. 813 -08 815 o Expanded the User Code Brute Forcing section to include more 816 detail on this attack. 818 -07 820 o Replaced the "user_code" URI parameter optimization with 821 verification_uri_complete following the IETF99 working group 822 discussion. 823 o Added security consideration about spying. 824 o Required that device_code not be shown. 825 o Added text regarding a minimum polling interval. 827 -06 829 o Clarified usage of the "user_code" URI parameter optimization 830 following the IETF98 working group discussion. 832 -05 833 o response_type parameter removed from authorization request. 834 o Added option for clients to include the user_code on the 835 verification URI. 836 o Clarified token expiry, and other nits. 838 -04 840 o Security & Usability sections. OAuth Discovery Metadata. 842 -03 844 o device_code is now a URN. Added IANA Considerations 846 -02 848 o Added token request & response specification. 850 -01 852 o Applied spelling and grammar corrections and added the Document 853 History appendix. 855 -00 857 o Initial working group draft based on draft-recordon-oauth- 858 v2-device. 860 Authors' Addresses 862 William Denniss 863 Google 864 1600 Amphitheatre Pkwy 865 Mountain View, CA 94043 866 USA 868 Email: wdenniss@google.com 869 URI: http://wdenniss.com/device-flow 871 John Bradley 872 Ping Identity 874 Email: ve7jtb@ve7jtb.com 875 URI: http://www.thread-safe.com/ 876 Michael B. Jones 877 Microsoft 879 Email: mbj@microsoft.com 880 URI: http://self-issued.info/ 882 Hannes Tschofenig 883 ARM Limited 884 Austria 886 Email: Hannes.Tschofenig@gmx.net 887 URI: http://www.tschofenig.priv.at