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