idnits 2.17.00 (12 Aug 2021) /tmp/idnits45374/draft-ietf-oauth-device-flow-02.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document date (July 8, 2016) is 2142 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) No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 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 S. Myrseth 5 Expires: January 9, 2017 ForgeRock 6 J. Bradley 7 Ping Identity 8 M. Jones 9 Microsoft 10 H. Tschofenig 11 ARM Limited 12 July 8, 2016 14 OAuth 2.0 Device Flow 15 draft-ietf-oauth-device-flow-02 17 Abstract 19 The device flow is suitable for OAuth 2.0 clients executing on 20 devices that do not have an easy data-entry method (e.g., game 21 consoles, TVs, picture frames, and media hubs), but where the end- 22 user has separate access to a user-agent on another computer or 23 device (e.g., desktop computer, a laptop, a smart phone, or a 24 tablet). 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 9, 2017. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3.1. Device Authorization Request . . . . . . . . . . . . . . 4 64 3.2. Device Authorization Response . . . . . . . . . . . . . . 5 65 3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 6 66 3.4. Device Token Request . . . . . . . . . . . . . . . . . . 6 67 3.5. Device Token Response . . . . . . . . . . . . . . . . . . 7 68 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 69 5. Normative References . . . . . . . . . . . . . . . . . . . . 8 70 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 71 Appendix B. Document History . . . . . . . . . . . . . . . . . . 8 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 74 1. Introduction 76 The device flow is suitable for clients executing on devices that do 77 not have an easy data-entry method and where the client is incapable 78 of receiving incoming requests from the authorization server 79 (incapable of acting as an HTTP server). 81 Instead of interacting with the end-user's user-agent, the client 82 instructs the end-user to use another computer or device and connect 83 to the authorization server to approve the access request. Since the 84 client cannot receive incoming requests, it polls the authorization 85 server repeatedly until the end-user completes the approval process. 87 Note that this device flow does not utilize the client secret. 89 +----------+ +----------------+ 90 | |>---(A)-- Client Identifier --->| | 91 | | | | 92 | |<---(B)-- Verification Code, --<| | 93 | | User Code, | | 94 | | & Verification URI | | 95 | Device | | | 96 | Client | Client Identifier & | | 97 | |>---(E)-- Verification Code --->| | 98 | | polling... | | 99 | |>---(E)-- Verification Code --->| | 100 | | | Authorization | 101 | |<---(F)-- Access Token --------<| Server | 102 +----------+ (w/ Optional Refresh Token) | | 103 v | | 104 : | | 105 (C) User Code & Verification URI | | 106 : | | 107 v | | 108 +----------+ | | 109 | End-user | | | 110 | at |<---(D)-- User authenticates -->| | 111 | Browser | | | 112 +----------+ +----------------+ 114 Figure 1: Device Flow. 116 The device flow illustrated in Figure 1 includes the following steps: 118 (A) The client requests access from the authorization server and 119 includes its client identifier in the request. 121 (B) The authorization server issues a verification code, an end- 122 user code, and provides the end-user verification URI. 124 (C) The client instructs the end-user to use its user-agent 125 (elsewhere) and visit the provided end-user verification URI. The 126 client provides the end-user with the end-user code to enter in 127 order to grant access. 129 (D) The authorization server authenticates the end-user (via the 130 user-agent) and prompts the end-user to grant the client's access 131 request. If the end-user agrees to the client's access request, 132 the end-user enters the end-user code provided by the client. The 133 authorization server validates the end-user code provided by the 134 end-user. 136 (E) While the end-user authorizes (or denies) the client's request 137 (D), the client repeatedly polls the authorization server to find 138 out if the end-user completed the end-user authorization step. 139 The client includes the verification code and its client 140 identifier. 142 (F) Assuming the end-user granted access, the authorization server 143 validates the verification code provided by the client and 144 responds back with the access token. 146 2. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 150 "OPTIONAL" in this document are to be interpreted as described in 151 [RFC2119]. 153 Device Endpoint: 155 The authorization server's endpoint capable of issuing 156 verification codes, user codes, and verification URLs. 158 Device Verification Code: 160 A short-lived token representing an authorization session. 162 End-User Verification Code: 164 A short-lived token which the device displays to the end user, is 165 entered by the end-user on the authorization server, and is thus 166 used to bind the device to the end-user. 168 3. Specification 170 3.1. Device Authorization Request 172 The client initiates the flow by requesting a set of verification 173 codes from the authorization server by making an HTTP "POST" request 174 to the device endpoint. The client constructs a request URI by 175 adding the following parameters to the request: 177 response_type: 179 REQUIRED. The parameter value MUST be set to "device_code". 181 client_id: 183 REQUIRED. The client identifier as described in Section 2.2 of 184 [RFC6749]. 186 scope: 188 OPTIONAL. The scope of the access request as described by 189 Section 3.3 of [RFC6749]. 191 For example, the client makes the following HTTPS request (line 192 breaks are for display purposes only): 194 POST /token HTTP/1.1 195 Host: server.example.com 196 Content-Type: application/x-www-form-urlencoded 198 response_type=device_code&client_id=s6BhdRkqt3 200 3.2. Device Authorization Response 202 In response, the authorization server generates a verification code 203 and an end-user code and includes them in the HTTP response body 204 using the "application/json" format with a 200 status code (OK). The 205 response contains the following parameters: 207 device_code 209 REQUIRED. The verification code. 211 user_code 213 REQUIRED. The end-user verification code. 215 verification_uri 217 REQUIRED. The end-user verification URI on the authorization 218 server. The URI should be short and easy to remember as end- 219 users will be asked to manually type it into their user-agent. 221 expires_in 223 OPTIONAL. The duration in seconds of the verification code 224 lifetime. 226 interval 228 OPTIONAL. The minimum amount of time in seconds that the client 229 SHOULD wait between polling requests to the token endpoint. 231 For example: 233 HTTP/1.1 200 OK 234 Content-Type: application/json 235 Cache-Control: no-store 237 { 238 "device_code":"74tq5miHKB", 239 "user_code":"94248", 240 "verification_uri":"http://www.example.com/device", 241 "interval"=5 242 } 244 3.3. User Instruction 246 After receiving a successful Authorization Response, the client 247 displays the end-user code and the end-user verification URI to the 248 end-user, and instructs the end-user to visit the URI using a user- 249 agent and enter the end-user code. 251 The end-user manually types the provided verification URI and 252 authenticates with the authorization server. The authorization 253 server prompts the end-user to authorize the client's request by 254 entering the end-user code provided by the client. Once the end-user 255 approves or denies the request, the authorization server informs the 256 end-user to return to the device for further instructions. 258 3.4. Device Token Request 260 As the user is authorizing the request on secondary device which may 261 not have a way to communicate to the original device, the client 262 polls the token endpoint until the end-user grants or denies the 263 request, or the device code expires. 265 The client polls at reasonable interval which MUST NOT exceed the 266 minimum interval provided by the authorization server via the 267 "interval" parameter (if provided). 269 The client makes a request to the token endpoint by sending the 270 following parameters using the "application/x-www-form-urlencoded" 271 format per Appendix B with a character encoding of UTF-8 in the HTTP 272 request entity-body: 274 grant_type 276 REQUIRED. Value MUST be set to "device_code". 278 device_code 279 REQUIRED. The device verification code, "device_code" from the 280 Device Authorization Response, defined in Section 3.2. 282 client_id 284 REQUIRED, if the client is not authenticating with the 285 authorization server as described in Section 3.2.1. of [RFC6749] 287 For example, the client makes the following HTTPS request (line 288 breaks are for display purposes only): 290 POST /token HTTP/1.1 291 Host: server.example.com 292 Content-Type: application/x-www-form-urlencoded 294 grant_type=device_code&device_code=pxDoJ3Bt9WVMTXfDATLkxJ9u 295 &client_id=459691054427 297 Note that unlike the Access Token Request for the authorization_code 298 grant type defined in Section 4.1.3 of [RFC6749] the "redirect_uri" 299 parameter is NOT REQUIRED as part of this request. 301 If the client was issued client credentials (or assigned other 302 authentication requirements), the client MUST authenticate with the 303 authorization server as described in Section 3.2.1 of [RFC6749]. 305 3.5. Device Token Response 307 If the user has approved the grant, the token endpoint responds with 308 a success response defined in Section 5.1 of [RFC6749] otherwise, it 309 responds with an error, as defined in Section 5.2 of [RFC6749]. 311 In addition to the error codes defined in Section 5.2 of [RFC6749], 312 the following error codes are specific for the device flow: 314 authorization_pending 316 The authorization request is still pending as the end-user hasn't 317 yet visited the authorization server and entered their 318 verification code. 320 slow_down 322 The client is polling too quickly and should back off at a 323 reasonable rate. 325 expired_token 327 The device_code has expired. The client will need to make a new 328 Device Authorization Request. 330 The error code "authorization_pending" and "slow_down" are considered 331 soft errors. The the client should continue to poll when receiving 332 "authorization_pending" errors, reducing the interval if a 333 "slow_down" error is received. Other error codes are considered hard 334 errors, the client should stop polling and react accordingly, for 335 example, by displaying an error to the user. 337 4. Security Considerations 339 TBD 341 5. Normative References 343 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 344 Requirement Levels", BCP 14, RFC 2119, 345 DOI 10.17487/RFC2119, March 1997, 346 . 348 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 349 RFC 6749, DOI 10.17487/RFC6749, October 2012, 350 . 352 Appendix A. Acknowledgements 354 The -00 version of this document was based on draft-recordon-oauth- 355 v2-device edited by David Recordon and Brent Goldman. The content of 356 that document was initially part of the OAuth 2.0 protocol 357 specification but was later removed due to the lack of sufficient 358 deployment expertise at that time. We would therefore also like to 359 thank the OAuth working group for their work on the initial content 360 of this specification through 2010. 362 Appendix B. Document History 364 [[ to be removed by the RFC Editor before publication as an RFC ]] 366 -01 368 o Applied spelling and grammar corrections and added the Document 369 History appendix. 371 -00 372 o Initial working group draft based on draft-recordon-oauth- 373 v2-device. 375 Authors' Addresses 377 William Denniss 378 Google 379 1600 Amphitheatre Pkwy 380 Mountain View, CA 94043 381 USA 383 Phone: +1 650-253-0000 384 Email: wdenniss@google.com 385 URI: http://google.com/ 387 Stein Myrseth 388 ForgeRock 389 Lysaker torg 2 390 Lysaker 1366 391 NORWAY 393 Email: stein.myrseth@forgerock.com 395 John Bradley 396 Ping Identity 398 Email: ve7jtb@ve7jtb.com 399 URI: http://www.thread-safe.com/ 401 Michael B. Jones 402 Microsoft 404 Email: mbj@microsoft.com 405 URI: http://self-issued.info/ 407 Hannes Tschofenig 408 ARM Limited 409 Austria 411 Email: Hannes.Tschofenig@gmx.net 412 URI: http://www.tschofenig.priv.at