idnits 2.17.1 draft-ietf-oauth-device-flow-09.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 14 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 20, 2018) is 2191 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) ** Downref: Normative reference to an Informational RFC: RFC 6755 ** Downref: Normative reference to an Informational RFC: RFC 6819 Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 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: October 22, 2018 Ping Identity 6 M. Jones 7 Microsoft 8 H. Tschofenig 9 ARM Limited 10 April 20, 2018 12 OAuth 2.0 Device Flow for Browserless and Input Constrained Devices 13 draft-ietf-oauth-device-flow-09 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 October 22, 2018. 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 . . . . . . . . . . . . . . . . 13 81 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 83 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14 84 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 85 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15 86 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 87 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 15 88 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 89 8. Normative References . . . . . . . . . . . . . . . . . . . . 15 90 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 91 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 94 1. Introduction 96 This OAuth 2.0 protocol flow for browserless and input constrained 97 devices, often referred to as the device flow, enables OAuth clients 98 to request user authorization from devices that have an internet 99 connection, but don't have an easy input method (such as a smart TV, 100 media console, picture frame, or printer), or lack a suitable browser 101 for a more traditional OAuth flow. This authorization flow instructs 102 the user to perform the authorization request on a secondary device, 103 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 OAuth 2.0 108 for Native Apps [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 end-user with the end-user code to enter in 162 order to grant access. 164 (D) The authorization server authenticates the end-user (via the 165 user-agent) and prompts the end-user to grant the client's access 166 request. If the end-user agrees to the client's access request, 167 the end-user enters the end-user code provided by the client. The 168 authorization server validates the end-user code provided by the 169 end-user. 171 (E) While the end-user authorizes (or denies) the client's request 172 (step D), the client repeatedly polls the authorization server to 173 find out if the end-user completed the end-user authorization 174 step. The client includes the verification code and its client 175 identifier. 177 (F) Assuming the end-user granted access, the authorization server 178 validates the verification code provided by the client and 179 responds back with the access token. 181 2. Terminology 183 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 184 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 185 "OPTIONAL" in this document are to be interpreted as described in 186 [RFC2119]. 188 Device Authorization Endpoint: 189 The authorization server's endpoint capable of issuing device 190 verification codes, user codes, and verification URLs. 192 Device Verification Code: 193 A short-lived token representing an authorization session. 195 End-User Verification Code: 196 A short-lived token which the device displays to the end user, is 197 entered by the end-user on the authorization server, and is thus 198 used to bind the device to the end-user. 200 3. Protocol 202 3.1. Device Authorization Request 204 The client initiates the flow by requesting a set of verification 205 codes from the authorization server by making an HTTP "POST" request 206 to the device authorization endpoint. The client constructs the 207 request with the following parameters, encoded with the "application/ 208 x-www-form-urlencoded" content type: 210 client_id 211 REQUIRED. The client identifier as described in Section 2.2 of 212 [RFC6749]. 214 scope 215 OPTIONAL. The scope of the access request as described by 216 Section 3.3 of [RFC6749]. 218 For example, the client makes the following HTTPS request (line 219 breaks are for display purposes only): 221 POST /device_authorization HTTP/1.1 222 Host: server.example.com 223 Content-Type: application/x-www-form-urlencoded 225 client_id=459691054427 227 Parameters sent without a value MUST be treated as if they were 228 omitted from the request. The authorization server MUST ignore 229 unrecognized request parameters. Request and response parameters 230 MUST NOT be included more than once. 232 3.2. Device Authorization Response 234 In response, the authorization server generates a device verification 235 code and an end-user code that are valid for a limited time and 236 includes them in the HTTP response body using the "application/json" 237 format with a 200 (OK) status code. The response contains the 238 following parameters: 240 device_code 241 REQUIRED. The device verification code. 243 user_code 244 REQUIRED. The end-user verification code. 246 verification_uri 247 REQUIRED. The end-user verification URI on the authorization 248 server. The URI should be short and easy to remember as end-users 249 will be asked to manually type it into their user-agent. 251 verification_uri_complete 252 OPTIONAL. A verification URI that includes the "user_code" (or 253 other information with the same function as the "user_code"), 254 designed for non-textual transmission. 256 expires_in 257 OPTIONAL. The lifetime in seconds of the "device_code" and 258 "user_code". 260 interval 261 OPTIONAL. The minimum amount of time in seconds that the client 262 SHOULD wait between polling requests to the token endpoint. 264 For example: 266 HTTP/1.1 200 OK 267 Content-Type: application/json 268 Cache-Control: no-store 270 { 271 "device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8", 272 "user_code":"WDJB-MJHT", 273 "verification_uri":"https://www.example.com/device", 274 "verification_uri_complete":"https://www.example.com/device?user_code=WDJB-MJHT", 275 "expires_in" : 1800, 276 "interval": 5 277 } 279 3.3. User Interaction 281 After receiving a successful Authorization Response, the client 282 displays or otherwise communicates the "user_code" and the 283 "verification_uri" to the end-user and instructs them to visit the 284 URI in a user agent on a secondary device (for example, in a browser 285 on their mobile phone), and enter the user code. 287 +-----------------------------------------------+ 288 | | 289 | Using a browser on another device, visit: | 290 | https://example.com/device | 291 | | 292 | And enter the code: | 293 | WDJB-MJHT | 294 | | 295 +-----------------------------------------------+ 297 Figure 2: Example User Instruction 299 The authorizing user navigates to the "verification_uri" and 300 authenticates with the authorization server in a secure TLS-protected 301 session. The authorization server prompts the end-user to identify 302 the device authorization session by entering the "user_code" provided 303 by the client. The authorization server should then inform the user 304 about the action they are undertaking and ask them to approve or deny 305 the request. Once the user interaction is complete, the server 306 informs the user to return to their device. 308 During the user interaction, the device continuously polls the token 309 endpoint with the "device_code", as detailed in Section 3.4, until 310 the user completes the interaction, the code expires, or another 311 error occurs. The "device_code" is not intended for the end-user and 312 MUST NOT be displayed or communicated. 314 Authorization servers supporting this specification MUST implement a 315 user interaction sequence that starts with the user navigating to 316 "verification_uri" and continues with them supplying the "user_code" 317 at some stage during the interaction. Other than that, the exact 318 sequence and implementation of the user interaction is up to the 319 authorization server and is out of scope of this specification. 321 It is NOT RECOMMENDED for authorization servers to include the user 322 code in the verification URI ("verification_uri"), as this increases 323 the length and complexity of the URI that the user must type. The 324 next section documents user interaction with 325 "verification_uri_complete", which is designed to carry this 326 information. 328 3.3.1. Non-textual Verification URI Optimization 330 When "verification_uri_complete" is included in the Authorization 331 Response (Section 3.2), clients MAY present this URI in a non-textual 332 manner using any method that results in the browser being opened with 333 the URI, such as with QR codes or NFC, to save the user typing the 334 URI. 336 For usability reasons, it is RECOMMENDED for clients to still display 337 the textual verification URI ("verification_uri") for users not able 338 to use such a shortcut. Clients MUST still display the "user_code", 339 as the authorization server may still require the user to confirm it 340 to disambiguate devices, or as a remote phishing mitigation (See 341 Section 5.3). 343 +-------------------------------------------------+ 344 | | 345 | Using a browser on another +------------+ | 346 | device, visit: |[_].. . [_]| | 347 | https://example.com/device | . .. . .| | 348 | | . . . ....| | 349 | |. . . . | | 350 | And enter the code: |[_]. ... . | | 351 | WDJB-MJHT +------------+ | 352 | | 353 +-------------------------------------------------+ 355 Figure 3: Example User Instruction with QR Code Representation of the 356 Complete Verification URI 358 3.4. Device Access Token Request 360 After displaying instructions to the user, the client makes an Access 361 Token Request to the token endpoint with a "grant_type" of 362 "urn:ietf:params:oauth:grant-type:device_code". This is an extension 363 grant type (as defined by Section 4.5 of [RFC6749]) with the 364 following parameters: 366 grant_type 367 REQUIRED. Value MUST be set to "urn:ietf:params:oauth:grant- 368 type:device_code". 370 device_code 371 REQUIRED. The device verification code, "device_code" from the 372 Device Authorization Response, defined in Section 3.2. 374 client_id 375 REQUIRED, if the client is not authenticating with the 376 authorization server as described in Section 3.2.1. of [RFC6749]. 378 For example, the client makes the following HTTPS request (line 379 breaks are for display purposes only): 381 POST /token HTTP/1.1 382 Host: server.example.com 383 Content-Type: application/x-www-form-urlencoded 385 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 386 &device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8 387 &client_id=459691054427 389 If the client was issued client credentials (or assigned other 390 authentication requirements), the client MUST authenticate with the 391 authorization server as described in Section 3.2.1 of [RFC6749]. 392 Note that there are security implications of statically distributed 393 client credentials, see Section 5.5. 395 The response to this request is defined in Section 3.5. Unlike other 396 OAuth grant types, it is expected for the client to try the Access 397 Token Request repeatedly in a polling fashion, based on the error 398 code in the response. 400 3.5. Device Access Token Response 402 If the user has approved the grant, the token endpoint responds with 403 a success response defined in Section 5.1 of [RFC6749]; otherwise it 404 responds with an error, as defined in Section 5.2 of [RFC6749]. 406 In addition to the error codes defined in Section 5.2 of [RFC6749], 407 the following error codes are specific for the device flow: 409 authorization_pending 410 The authorization request is still pending as the end-user hasn't 411 yet completed the user interaction steps (Section 3.3). The 412 client should repeat the Access Token Request to the token 413 endpoint. 415 slow_down 416 The client is polling too quickly and should back off at a 417 reasonable rate. 419 expired_token 420 The "device_code" has expired. The client will need to make a new 421 Device Authorization Request. 423 The error codes "authorization_pending" and "slow_down" are 424 considered soft errors. The client should continue to poll the token 425 endpoint by repeating the Device Token Request (Section 3.4) when 426 receiving soft errors, increasing the time between polls if a 427 "slow_down" error is received. Other error codes are considered hard 428 errors; the client should stop polling and react accordingly, for 429 example, by displaying an error to the user. 431 If the verification codes have expired, the server SHOULD respond 432 with the standard OAuth error "invalid_grant". Clients MAY then 433 choose to start a new device authorization session. 435 The interval at which the client polls MUST NOT be more frequent than 436 the "interval" parameter returned in the Device Authorization 437 Response (see Section 3.2). If no interval was provided, the client 438 MUST use a reasonable default polling interval. 440 The assumption of this specification is that the secondary device the 441 user is authorizing the request on does not have a way to communicate 442 back to the OAuth client. Only a one-way channel is required to make 443 this flow useful in many scenarios. For example, an HTML application 444 on a TV that can only make outbound requests. If a return channel 445 were to exist for the chosen user interaction interface, then the 446 device MAY wait until notified on that channel that the user has 447 completed the action before initiating the token request. Such 448 behavior is, however, outside the scope of this specification. 450 4. Discovery Metadata 452 Support for the device flow MAY be declared in the OAuth 2.0 453 Authorization Server Metadata [I-D.ietf-oauth-discovery] with the 454 following metadata: 456 device_authorization_endpoint 457 OPTIONAL. URL of the authorization server's device authorization 458 endpoint defined in Section 3.1. 460 5. Security Considerations 462 5.1. User Code Brute Forcing 464 Since the user code is typed by the user, shorter codes are more 465 desirable for usability reasons. This means the entropy is typically 466 less than would be used for the device code or other OAuth bearer 467 token types where the code length does not impact usability. It is 468 therefore recommended that the server rate-limit user code attempts. 469 The user code SHOULD have enough entropy that when combined with rate 470 limiting and other mitigations makes a brute-force attack infeasible. 472 A successful brute forcing of the user code would enable the attacker 473 to authenticate with their own credentials and make an authorization 474 grant to the device. This is the opposite scenario to an OAuth 475 bearer token being brute forced, whereby the attacker gains control 476 of the victim's authorization grant. In some applications this 477 attack may not make much economic sense, for example for a video app, 478 the owner of the device may then be able to purchase movies with the 479 attacker's account, however there are still privacy considerations in 480 that case as well as other uses of the device flow whereby the 481 granting account may be able to perform sensitive actions such as 482 controlling the victim's device. 484 The precise length of the user code and the entropy contained within 485 is at the discretion of the authorization server, which needs to 486 consider the sensitivity of their specific protected resources, the 487 practicality of the code length from a usability standpoint, and any 488 mitigations that are in place such as rate-limiting, when determining 489 the user code format. 491 5.2. Device Trustworthiness 493 Unlike other native application OAuth 2.0 flows, the device 494 requesting the authorization is not the same as the device that the 495 user grants access from. Thus, signals from the approving user's 496 session and device are not relevant to the trustworthiness of the 497 client device. 499 Note that if an authorization server used with this flow is 500 malicious, then it could man-in-the middle the backchannel flow to 501 another authorization server. In this scenario, the man-in-the- 502 middle is not completely hidden from sight, as the end-user would end 503 up on the authorization page of the wrong service, giving them an 504 opportunity to notice that the authorization being requested is 505 wrong. For this to be possible, the device manufacturer must either 506 directly be the attacker, shipping a device intended to perform the 507 man-in-the-middle attack, or be using an authorization server that is 508 controlled by an attacker, possibly because the attacker compromised 509 the authorization server used by the device. In part, the person 510 purchasing the device is counting on it and its business partners to 511 be trustworthy. 513 5.3. Remote Phishing 515 It is possible for the device flow to be initiated on a device in an 516 attacker's possession. For example, the attacker might send an email 517 instructing the target user to visit the verification URL and enter 518 the user code. To mitigate such an attack, it is RECOMMENDED to 519 inform the user that they are authorizing a device during the user 520 interaction step (see Section 3.3), and to confirm that the device is 521 in their possession. The authorization server SHOULD display 522 information about the device so that the person can notice if a 523 software client was attempting to impersonating a hardware device. 525 For authorization servers that support the option specified in 526 Section 3.3.1 for the client to append the user code to the 527 authorization URI, it is particularly important to confirm that the 528 device is in the user's possession, as the user no longer has to type 529 the code manually. One possibility is to display the code during the 530 authorization flow and asking the user to verify that the same code 531 is being displayed on the device they are setting up. 533 The user code needs to have a long enough lifetime to be useable 534 (allowing the user to retrieve their secondary device, navigate to 535 the verification URI, login, etc.), but should be sufficiently short 536 to limit the usability of a code obtained for phishing. This doesn't 537 prevent a phisher presenting a fresh token, particularly in the case 538 they are interacting with the user in real time, but it does limit 539 the viability of codes sent over email or SMS. 541 5.4. Session Spying 543 While the device is pending authorization, it may be possible for a 544 malicious user to spy on the device user interface and hijack the 545 session by completing the authorization faster than the user that 546 initiated it. Devices SHOULD take into account the operating 547 environment when considering how to communicate the code to the user 548 to reduce the chances it will be observed by a malicious user. 550 5.5. Non-confidential Clients 552 Most device clients are incapable of being confidential clients, as 553 secrets that are statically included as part of an app distributed to 554 multiple users cannot be considered confidential. For such clients, 555 the recommendations of Section 5.3.1 of [RFC6819] and Section 8.9 of 556 [RFC8252] apply. 558 5.6. Non-Visual Code Transmission 560 There is no requirement that the user code be displayed by the device 561 visually. Other methods of one-way communication can potentially be 562 used, such as text-to-speech audio, or Bluetooth Low Energy. To 563 mitigate an attack in which a malicious user can bootstrap their 564 credentials on a device not in their control, it is RECOMMENDED that 565 any chosen communication channel only be accessible by people in 566 close proximity. E.g., users who can see, or hear the device, or 567 within range of a short-range wireless signal. 569 6. Usability Considerations 571 This section is a non-normative discussion of usability 572 considerations. 574 6.1. User Code Recommendations 576 For many users, their nearest Internet-connected device will be their 577 mobile phone, and typically these devices offer input methods that 578 are more time consuming than a computer keyboard to change the case 579 or input numbers. To improve usability (improving entry speed, and 580 reducing retries), these limitations should be taken into account 581 when selecting the user-code character set. 583 One way to improve input speed is to restrict the character set to 584 case-insensitive A-Z characters, with no digits. These characters 585 can typically be entered on a mobile keyboard without using modifier 586 keys. Further removing vowels to avoid randomly creating words 587 results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes 588 or other punctuation may be included for readability. 590 An example user code following this guideline, with an entropy of 591 20^8: "WDJB-MJHT". 593 Pure numeric codes are also a good choice for usability, especially 594 for clients targeting locales where A-Z character keyboards are not 595 used, through their length needs to be longer to maintain a high 596 entropy. 598 An example numeric user code, with an entropy of 10^9: "019-450-730". 600 The server should ignore any characters like punctuation that are not 601 in the user-code character set. Provided that the character set 602 doesn't include characters of different case, the comparison should 603 be case insensitive. 605 6.2. Non-Browser User Interaction 607 Devices and authorization servers MAY negotiate an alternative code 608 transmission and user interaction method in addition to the one 609 described in Section 3.3. Such an alternative user interaction flow 610 could obviate the need for a browser and manual input of the code, 611 for example, by using Bluetooth to transmit the code to the 612 authorization server's companion app. Such interaction methods can 613 utilize this protocol, as ultimately, the user just needs to identify 614 the authorization session to the authorization server; however, user 615 interaction other than via the verification URI is outside the scope 616 of this specification. 618 7. IANA Considerations 620 7.1. OAuth URI Registration 622 This specification registers the following values in the IANA "OAuth 623 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 625 7.1.1. Registry Contents 627 o URN: urn:ietf:params:oauth:grant-type:device_code 628 o Common Name: Device flow grant type for OAuth 2.0 629 o Change controller: IESG 630 o Specification Document: Section 3.1 of [[ this specification ]] 632 7.2. OAuth Extensions Error Registration 634 This specification registers the following values in the IANA "OAuth 635 Extensions Error Registry" registry [IANA.OAuth.Parameters] 636 established by [RFC6749]. 638 7.2.1. Registry Contents 640 o Error name: authorization_pending 641 o Error usage location: Token endpoint response 642 o Related protocol extension: [[ this specification ]] 643 o Change controller: IETF 644 o Specification Document: Section 3.5 of [[ this specification ]] 646 o Error name: slow_down 647 o Error usage location: Token endpoint response 648 o Related protocol extension: [[ this specification ]] 649 o Change controller: IETF 650 o Specification Document: Section 3.5 of [[ this specification ]] 652 o Error name: expired_token 653 o Error usage location: Token endpoint response 654 o Related protocol extension: [[ this specification ]] 655 o Change controller: IETF 656 o Specification Document: Section 3.5 of [[ this specification ]] 658 7.3. OAuth 2.0 Authorization Server Metadata 660 This specification registers the following values in the IANA "OAuth 661 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 662 established by [I-D.ietf-oauth-discovery]. 664 7.3.1. Registry Contents 666 o Metadata name: device_authorization_endpoint 667 o Metadata Description: The Device Authorization Endpoint. 668 o Change controller: IESG 669 o Specification Document: Section 4 of [[ this specification ]] 671 8. Normative References 673 [I-D.ietf-oauth-discovery] 674 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 675 Authorization Server Metadata", draft-ietf-oauth- 676 discovery-10 (work in progress), March 2018. 678 [IANA.OAuth.Parameters] 679 IANA, "OAuth Parameters", 680 . 682 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 683 Requirement Levels", BCP 14, RFC 2119, 684 DOI 10.17487/RFC2119, March 1997, 685 . 687 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 688 RFC 6749, DOI 10.17487/RFC6749, October 2012, 689 . 691 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 692 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 693 . 695 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 696 Threat Model and Security Considerations", RFC 6819, 697 DOI 10.17487/RFC6819, January 2013, 698 . 700 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 701 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 702 . 704 Appendix A. Acknowledgements 706 The starting point for this document was the Internet-Draft draft- 707 recordon-oauth-v2-device, authored by David Recordon and Brent 708 Goldman, which itself was based on content in draft versions of the 709 OAuth 2.0 protocol specification removed prior to publication due to 710 a then lack of sufficient deployment expertise. Thank you to the 711 OAuth working group members who worked on this specification through 712 2010. 714 The following individuals contributed ideas, feedback, and wording 715 that shaped and formed the final specification: 717 Roshni Chandrashekhar, Marius Scurtescu, Breno de Medeiros, Stein 718 Myrseth, Simon Moffatt, Brian Campbell, James Manger, Justin Richer, 719 Ken Wang, Steven E. Wright, Nat Sakimura, and Torsten Lodderstedt. 721 Appendix B. Document History 723 [[ to be removed by the RFC Editor before publication as an RFC ]] 725 -09 726 o Addressed review comments by Security Area Director Eric Rescorla 727 about the potential of a confused deputy attack. 729 -08 731 o Expanded the User Code Brute Forcing section to include more 732 detail on this attack. 734 -07 736 o Replaced the "user_code" URI parameter optimization with 737 verification_uri_complete following the IETF99 working group 738 discussion. 739 o Added security consideration about spying. 740 o Required that device_code not be shown. 741 o Added text regarding a minimum polling interval. 743 -06 745 o Clarified usage of the "user_code" URI parameter optimization 746 following the IETF98 working group discussion. 748 -05 750 o response_type parameter removed from authorization request. 751 o Added option for clients to include the user_code on the 752 verification URI. 753 o Clarified token expiry, and other nits. 755 -04 757 o Security & Usability sections. OAuth Discovery Metadata. 759 -03 761 o device_code is now a URN. Added IANA Considerations 763 -02 765 o Added token request & response specification. 767 -01 769 o Applied spelling and grammar corrections and added the Document 770 History appendix. 772 -00 773 o Initial working group draft based on draft-recordon-oauth- 774 v2-device. 776 Authors' Addresses 778 William Denniss 779 Google 780 1600 Amphitheatre Pkwy 781 Mountain View, CA 94043 782 USA 784 Email: wdenniss@google.com 785 URI: http://wdenniss.com/device-flow 787 John Bradley 788 Ping Identity 790 Email: ve7jtb@ve7jtb.com 791 URI: http://www.thread-safe.com/ 793 Michael B. Jones 794 Microsoft 796 Email: mbj@microsoft.com 797 URI: http://self-issued.info/ 799 Hannes Tschofenig 800 ARM Limited 801 Austria 803 Email: Hannes.Tschofenig@gmx.net 804 URI: http://www.tschofenig.priv.at