idnits 2.17.1 draft-ietf-oauth-device-flow-11.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 (July 17, 2018) is 2103 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: 2 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: January 18, 2019 Ping Identity 6 M. Jones 7 Microsoft 8 H. Tschofenig 9 ARM Limited 10 July 17, 2018 12 OAuth 2.0 Device Flow for Browserless and Input Constrained Devices 13 draft-ietf-oauth-device-flow-11 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 January 18, 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 . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . 16 90 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 91 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 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": 275 "https://www.example.com/device?user_code=WDJB-MJHT", 276 "expires_in" : 1800, 277 "interval": 5 278 } 280 3.3. User Interaction 282 After receiving a successful Authorization Response, the client 283 displays or otherwise communicates the "user_code" and the 284 "verification_uri" to the end-user and instructs them to visit the 285 URI in a user agent on a secondary device (for example, in a browser 286 on their mobile phone), and enter the user code. 288 +-----------------------------------------------+ 289 | | 290 | Using a browser on another device, visit: | 291 | https://example.com/device | 292 | | 293 | And enter the code: | 294 | WDJB-MJHT | 295 | | 296 +-----------------------------------------------+ 298 Figure 2: Example User Instruction 300 The authorizing user navigates to the "verification_uri" and 301 authenticates with the authorization server in a secure TLS-protected 302 session. The authorization server prompts the end-user to identify 303 the device authorization session by entering the "user_code" provided 304 by the client. The authorization server should then inform the user 305 about the action they are undertaking and ask them to approve or deny 306 the request. Once the user interaction is complete, the server 307 informs the user to return to their device. 309 During the user interaction, the device continuously polls the token 310 endpoint with the "device_code", as detailed in Section 3.4, until 311 the user completes the interaction, the code expires, or another 312 error occurs. The "device_code" is not intended for the end-user and 313 MUST NOT be displayed or communicated. 315 Authorization servers supporting this specification MUST implement a 316 user interaction sequence that starts with the user navigating to 317 "verification_uri" and continues with them supplying the "user_code" 318 at some stage during the interaction. Other than that, the exact 319 sequence and implementation of the user interaction is up to the 320 authorization server and is out of scope of this specification. 322 It is NOT RECOMMENDED for authorization servers to include the user 323 code in the verification URI ("verification_uri"), as this increases 324 the length and complexity of the URI that the user must type. The 325 next section documents user interaction with 326 "verification_uri_complete", which is designed to carry this 327 information. 329 3.3.1. Non-textual Verification URI Optimization 331 When "verification_uri_complete" is included in the Authorization 332 Response (Section 3.2), clients MAY present this URI in a non-textual 333 manner using any method that results in the browser being opened with 334 the URI, such as with QR codes or NFC, to save the user typing the 335 URI. 337 For usability reasons, it is RECOMMENDED for clients to still display 338 the textual verification URI ("verification_uri") for users not able 339 to use such a shortcut. Clients MUST still display the "user_code", 340 as the authorization server may still require the user to confirm it 341 to disambiguate devices, or as a remote phishing mitigation (See 342 Section 5.3). 344 +-------------------------------------------------+ 345 | | 346 | Using a browser on another +------------+ | 347 | device, visit: |[_].. . [_]| | 348 | https://example.com/device | . .. . .| | 349 | | . . . ....| | 350 | |. . . . | | 351 | And enter the code: |[_]. ... . | | 352 | WDJB-MJHT +------------+ | 353 | | 354 +-------------------------------------------------+ 356 Figure 3: Example User Instruction with QR Code Representation of the 357 Complete Verification URI 359 3.4. Device Access Token Request 361 After displaying instructions to the user, the client makes an Access 362 Token Request to the token endpoint with a "grant_type" of 363 "urn:ietf:params:oauth:grant-type:device_code". This is an extension 364 grant type (as defined by Section 4.5 of [RFC6749]) with the 365 following parameters: 367 grant_type 368 REQUIRED. Value MUST be set to 369 "urn:ietf:params:oauth:grant-type:device_code". 371 device_code 372 REQUIRED. The device verification code, "device_code" from the 373 Device Authorization Response, defined in Section 3.2. 375 client_id 376 REQUIRED, if the client is not authenticating with the 377 authorization server as described in Section 3.2.1. of [RFC6749]. 379 For example, the client makes the following HTTPS request (line 380 breaks are for display purposes only): 382 POST /token HTTP/1.1 383 Host: server.example.com 384 Content-Type: application/x-www-form-urlencoded 386 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 387 &device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8 388 &client_id=459691054427 390 If the client was issued client credentials (or assigned other 391 authentication requirements), the client MUST authenticate with the 392 authorization server as described in Section 3.2.1 of [RFC6749]. 393 Note that there are security implications of statically distributed 394 client credentials, see Section 5.5. 396 The response to this request is defined in Section 3.5. Unlike other 397 OAuth grant types, it is expected for the client to try the Access 398 Token Request repeatedly in a polling fashion, based on the error 399 code in the response. 401 3.5. Device Access Token Response 403 If the user has approved the grant, the token endpoint responds with 404 a success response defined in Section 5.1 of [RFC6749]; otherwise it 405 responds with an error, as defined in Section 5.2 of [RFC6749]. 407 In addition to the error codes defined in Section 5.2 of [RFC6749], 408 the following error codes are specified by the device flow for use in 409 token endpoint responses: 411 authorization_pending 412 The authorization request is still pending as the end-user hasn't 413 yet completed the user interaction steps (Section 3.3). The 414 client should repeat the Access Token Request to the token 415 endpoint. 417 access_denied 418 The end-user denied the authorization request. 420 slow_down 421 The client is polling too quickly and should back off at a 422 reasonable rate. 424 expired_token 425 The "device_code" has expired. The client will need to make a new 426 Device Authorization Request. 428 The error codes "authorization_pending" and "slow_down" are 429 considered soft errors. The client should continue to poll the token 430 endpoint by repeating the Device Token Request (Section 3.4) when 431 receiving soft errors, increasing the time between polls if a 432 "slow_down" error is received. Other error codes are considered hard 433 errors; the client should stop polling and react accordingly, for 434 example, by displaying an error to the user. 436 If the verification codes have expired, the server SHOULD respond 437 with the error code "expired_token". Clients MAY then choose to 438 start a new device authorization session. 440 The interval at which the client polls MUST NOT be more frequent than 441 the "interval" parameter returned in the Device Authorization 442 Response (see Section 3.2). If no interval was provided, the client 443 MUST use a reasonable default polling interval. 445 The assumption of this specification is that the secondary device the 446 user is authorizing the request on does not have a way to communicate 447 back to the OAuth client. Only a one-way channel is required to make 448 this flow useful in many scenarios. For example, an HTML application 449 on a TV that can only make outbound requests. If a return channel 450 were to exist for the chosen user interaction interface, then the 451 device MAY wait until notified on that channel that the user has 452 completed the action before initiating the token request. Such 453 behavior is, however, outside the scope of this specification. 455 4. Discovery Metadata 457 Support for the device flow MAY be declared in the OAuth 2.0 458 Authorization Server Metadata [RFC8414] with the following metadata: 460 device_authorization_endpoint 461 OPTIONAL. URL of the authorization server's device authorization 462 endpoint defined in Section 3.1. 464 5. Security Considerations 466 5.1. User Code Brute Forcing 468 Since the user code is typed by the user, shorter codes are more 469 desirable for usability reasons. This means the entropy is typically 470 less than would be used for the device code or other OAuth bearer 471 token types where the code length does not impact usability. It is 472 therefore recommended that the server rate-limit user code attempts. 473 The user code SHOULD have enough entropy that when combined with rate 474 limiting and other mitigations makes a brute-force attack infeasible. 476 A successful brute forcing of the user code would enable the attacker 477 to authenticate with their own credentials and make an authorization 478 grant to the device. This is the opposite scenario to an OAuth 479 bearer token being brute forced, whereby the attacker gains control 480 of the victim's authorization grant. In some applications this 481 attack may not make much economic sense, for example for a video app, 482 the owner of the device may then be able to purchase movies with the 483 attacker's account, however there are still privacy considerations in 484 that case as well as other uses of the device flow whereby the 485 granting account may be able to perform sensitive actions such as 486 controlling the victim's device. 488 The precise length of the user code and the entropy contained within 489 is at the discretion of the authorization server, which needs to 490 consider the sensitivity of their specific protected resources, the 491 practicality of the code length from a usability standpoint, and any 492 mitigations that are in place such as rate-limiting, when determining 493 the user code format. 495 5.2. Device Trustworthiness 497 Unlike other native application OAuth 2.0 flows, the device 498 requesting the authorization is not the same as the device that the 499 user grants access from. Thus, signals from the approving user's 500 session and device are not relevant to the trustworthiness of the 501 client device. 503 Note that if an authorization server used with this flow is 504 malicious, then it could man-in-the middle the backchannel flow to 505 another authorization server. In this scenario, the man-in-the- 506 middle is not completely hidden from sight, as the end-user would end 507 up on the authorization page of the wrong service, giving them an 508 opportunity to notice that the authorization being requested is 509 wrong. For this to be possible, the device manufacturer must either 510 directly be the attacker, shipping a device intended to perform the 511 man-in-the-middle attack, or be using an authorization server that is 512 controlled by an attacker, possibly because the attacker compromised 513 the authorization server used by the device. In part, the person 514 purchasing the device is counting on it and its business partners to 515 be trustworthy. 517 5.3. Remote Phishing 519 It is possible for the device flow to be initiated on a device in an 520 attacker's possession. For example, the attacker might send an email 521 instructing the target user to visit the verification URL and enter 522 the user code. To mitigate such an attack, it is RECOMMENDED to 523 inform the user that they are authorizing a device during the user 524 interaction step (see Section 3.3), and to confirm that the device is 525 in their possession. The authorization server SHOULD display 526 information about the device so that the person can notice if a 527 software client was attempting to impersonating a hardware device. 529 For authorization servers that support the option specified in 530 Section 3.3.1 for the client to append the user code to the 531 authorization URI, it is particularly important to confirm that the 532 device is in the user's possession, as the user no longer has to type 533 the code manually. One possibility is to display the code during the 534 authorization flow and asking the user to verify that the same code 535 is being displayed on the device they are setting up. 537 The user code needs to have a long enough lifetime to be useable 538 (allowing the user to retrieve their secondary device, navigate to 539 the verification URI, login, etc.), but should be sufficiently short 540 to limit the usability of a code obtained for phishing. This doesn't 541 prevent a phisher presenting a fresh token, particularly in the case 542 they are interacting with the user in real time, but it does limit 543 the viability of codes sent over email or SMS. 545 5.4. Session Spying 547 While the device is pending authorization, it may be possible for a 548 malicious user to spy on the device user interface and hijack the 549 session by completing the authorization faster than the user that 550 initiated it. Devices SHOULD take into account the operating 551 environment when considering how to communicate the code to the user 552 to reduce the chances it will be observed by a malicious user. 554 5.5. Non-confidential Clients 556 Most device clients are incapable of being confidential clients, as 557 secrets that are statically included as part of an app distributed to 558 multiple users cannot be considered confidential. For such clients, 559 the recommendations of Section 5.3.1 of [RFC6819] and Section 8.5 of 560 [RFC8252] apply. 562 5.6. Non-Visual Code Transmission 564 There is no requirement that the user code be displayed by the device 565 visually. Other methods of one-way communication can potentially be 566 used, such as text-to-speech audio, or Bluetooth Low Energy. To 567 mitigate an attack in which a malicious user can bootstrap their 568 credentials on a device not in their control, it is RECOMMENDED that 569 any chosen communication channel only be accessible by people in 570 close proximity. E.g., users who can see, or hear the device, or 571 within range of a short-range wireless signal. 573 6. Usability Considerations 575 This section is a non-normative discussion of usability 576 considerations. 578 6.1. User Code Recommendations 580 For many users, their nearest Internet-connected device will be their 581 mobile phone, and typically these devices offer input methods that 582 are more time consuming than a computer keyboard to change the case 583 or input numbers. To improve usability (improving entry speed, and 584 reducing retries), these limitations should be taken into account 585 when selecting the user-code character set. 587 One way to improve input speed is to restrict the character set to 588 case-insensitive A-Z characters, with no digits. These characters 589 can typically be entered on a mobile keyboard without using modifier 590 keys. Further removing vowels to avoid randomly creating words 591 results in the base-20 character set: "BCDFGHJKLMNPQRSTVWXZ". Dashes 592 or other punctuation may be included for readability. 594 An example user code following this guideline, with an entropy of 595 20^8: "WDJB-MJHT". 597 Pure numeric codes are also a good choice for usability, especially 598 for clients targeting locales where A-Z character keyboards are not 599 used, though their length needs to be longer to maintain a high 600 entropy. 602 An example numeric user code, with an entropy of 10^9: "019-450-730". 604 The server should ignore any characters like punctuation that are not 605 in the user-code character set. Provided that the character set 606 doesn't include characters of different case, the comparison should 607 be case insensitive. 609 6.2. Non-Browser User Interaction 611 Devices and authorization servers MAY negotiate an alternative code 612 transmission and user interaction method in addition to the one 613 described in Section 3.3. Such an alternative user interaction flow 614 could obviate the need for a browser and manual input of the code, 615 for example, by using Bluetooth to transmit the code to the 616 authorization server's companion app. Such interaction methods can 617 utilize this protocol, as ultimately, the user just needs to identify 618 the authorization session to the authorization server; however, user 619 interaction other than via the verification URI is outside the scope 620 of this specification. 622 7. IANA Considerations 624 7.1. OAuth URI Registration 626 This specification registers the following values in the IANA "OAuth 627 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 629 7.1.1. Registry Contents 631 o URN: urn:ietf:params:oauth:grant-type:device_code 632 o Common Name: Device flow grant type for OAuth 2.0 633 o Change controller: IESG 634 o Specification Document: Section 3.1 of [[ this specification ]] 636 7.2. OAuth Extensions Error Registration 638 This specification registers the following values in the IANA "OAuth 639 Extensions Error Registry" registry [IANA.OAuth.Parameters] 640 established by [RFC6749]. 642 7.2.1. Registry Contents 644 o Error name: authorization_pending 645 o Error usage location: Token endpoint response 646 o Related protocol extension: [[ this specification ]] 647 o Change controller: IETF 648 o Specification Document: Section 3.5 of [[ this specification ]] 650 o Error name: access_denied 651 o Error usage location: Token endpoint response 652 o Related protocol extension: [[ this specification ]] 653 o Change controller: IETF 654 o Specification Document: Section 3.5 of [[ this specification ]] 656 o Error name: slow_down 657 o Error usage location: Token endpoint response 658 o Related protocol extension: [[ this specification ]] 659 o Change controller: IETF 660 o Specification Document: Section 3.5 of [[ this specification ]] 662 o Error name: expired_token 663 o Error usage location: Token endpoint response 664 o Related protocol extension: [[ this specification ]] 665 o Change controller: IETF 666 o Specification Document: Section 3.5 of [[ this specification ]] 668 7.3. OAuth 2.0 Authorization Server Metadata 670 This specification registers the following values in the IANA "OAuth 671 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 672 established by [RFC8414]. 674 7.3.1. Registry Contents 676 o Metadata name: device_authorization_endpoint 677 o Metadata Description: The Device Authorization Endpoint. 678 o Change controller: IESG 679 o Specification Document: Section 4 of [[ this specification ]] 681 8. Normative References 683 [IANA.OAuth.Parameters] 684 IANA, "OAuth Parameters", 685 . 687 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 688 Requirement Levels", BCP 14, RFC 2119, 689 DOI 10.17487/RFC2119, March 1997, 690 . 692 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 693 RFC 6749, DOI 10.17487/RFC6749, October 2012, 694 . 696 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 697 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 698 . 700 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 701 Threat Model and Security Considerations", RFC 6819, 702 DOI 10.17487/RFC6819, January 2013, 703 . 705 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 706 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 707 . 709 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 710 Authorization Server Metadata", RFC 8414, 711 DOI 10.17487/RFC8414, June 2018, 712 . 714 Appendix A. Acknowledgements 716 The starting point for this document was the Internet-Draft draft- 717 recordon-oauth-v2-device, authored by David Recordon and Brent 718 Goldman, which itself was based on content in draft versions of the 719 OAuth 2.0 protocol specification removed prior to publication due to 720 a then lack of sufficient deployment expertise. Thank you to the 721 OAuth working group members who contributed to those earlier drafts. 723 This document was produced in the OAuth working group under the 724 chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with 725 Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as 726 Security Area Directors. 728 The following individuals contributed ideas, feedback, and wording 729 that shaped and formed the final specification: 731 Brian Campbell, Roshni Chandrashekhar, Eric Fazendin, Torsten 732 Lodderstedt, James Manger, Breno de Medeiros, Simon Moffatt, Stein 733 Myrseth, Justin Richer, Nat Sakimura, Andrew Sciberras, Marius 734 Scurtescu, Ken Wang, and Steven E. Wright. 736 Appendix B. Document History 738 [[ to be removed by the RFC Editor before publication as an RFC ]] 740 -11 742 o Updated reference to OAuth 2.0 Authorization Server Metadata. 744 -10 746 o Added a missing definition of access_denied for use on the token 747 endpoint. 748 o Corrected text documenting which error code should be returned for 749 expired tokens (it's "expired_token", not "invalid_grant"). 750 o Corrected section reference to RFC 8252 (the section numbers had 751 changed after the initial reference was made). 752 o Fixed line length of one diagram (was causing xml2rfc warnings). 753 o Added line breaks so the URN grant_type is presented on an 754 unbroken line. 755 o Typos fixed and other stylistic improvements. 757 -09 759 o Addressed review comments by Security Area Director Eric Rescorla 760 about the potential of a confused deputy attack. 762 -08 764 o Expanded the User Code Brute Forcing section to include more 765 detail on this attack. 767 -07 769 o Replaced the "user_code" URI parameter optimization with 770 verification_uri_complete following the IETF99 working group 771 discussion. 772 o Added security consideration about spying. 773 o Required that device_code not be shown. 774 o Added text regarding a minimum polling interval. 776 -06 778 o Clarified usage of the "user_code" URI parameter optimization 779 following the IETF98 working group discussion. 781 -05 783 o response_type parameter removed from authorization request. 784 o Added option for clients to include the user_code on the 785 verification URI. 786 o Clarified token expiry, and other nits. 788 -04 790 o Security & Usability sections. OAuth Discovery Metadata. 792 -03 794 o device_code is now a URN. Added IANA Considerations 796 -02 798 o Added token request & response specification. 800 -01 802 o Applied spelling and grammar corrections and added the Document 803 History appendix. 805 -00 807 o Initial working group draft based on draft-recordon-oauth- 808 v2-device. 810 Authors' Addresses 812 William Denniss 813 Google 814 1600 Amphitheatre Pkwy 815 Mountain View, CA 94043 816 USA 818 Email: wdenniss@google.com 819 URI: http://wdenniss.com/device-flow 820 John Bradley 821 Ping Identity 823 Email: ve7jtb@ve7jtb.com 824 URI: http://www.thread-safe.com/ 826 Michael B. Jones 827 Microsoft 829 Email: mbj@microsoft.com 830 URI: http://self-issued.info/ 832 Hannes Tschofenig 833 ARM Limited 834 Austria 836 Email: Hannes.Tschofenig@gmx.net 837 URI: http://www.tschofenig.priv.at