idnits 2.17.1 draft-ietf-oauth-device-flow-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 33 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The 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 18, 2016) is 2836 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 Summary: 2 errors (**), 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 19, 2017 ForgeRock 6 J. Bradley 7 Ping Identity 8 M. Jones 9 Microsoft 10 H. Tschofenig 11 ARM Limited 12 July 18, 2016 14 OAuth 2.0 Device Flow 15 draft-ietf-oauth-device-flow-03 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 19, 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. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 69 4.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 8 70 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 71 4.2. OAuth Extensions Error Registration . . . . . . . . . . . 8 72 4.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 74 6. Normative References . . . . . . . . . . . . . . . . . . . . 9 75 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 76 Appendix B. Document History . . . . . . . . . . . . . . . . . . 9 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 79 1. Introduction 81 The device flow is suitable for clients executing on devices that do 82 not have an easy data-entry method and where the client is incapable 83 of receiving incoming requests from the authorization server 84 (incapable of acting as an HTTP server). 86 Instead of interacting with the end-user's user-agent, the client 87 instructs the end-user to use another computer or device and connect 88 to the authorization server to approve the access request. Since the 89 client cannot receive incoming requests, it polls the authorization 90 server repeatedly until the end-user completes the approval process. 92 Note that this device flow does not utilize the client secret. 94 +----------+ +----------------+ 95 | |>---(A)-- Client Identifier --->| | 96 | | | | 97 | |<---(B)-- Verification Code, --<| | 98 | | User Code, | | 99 | | & Verification URI | | 100 | Device | | | 101 | Client | Client Identifier & | | 102 | |>---(E)-- Verification Code --->| | 103 | | polling... | | 104 | |>---(E)-- Verification Code --->| | 105 | | | Authorization | 106 | |<---(F)-- Access Token --------<| Server | 107 +----------+ (w/ Optional Refresh Token) | | 108 v | | 109 : | | 110 (C) User Code & Verification URI | | 111 : | | 112 v | | 113 +----------+ | | 114 | End-user | | | 115 | at |<---(D)-- User authenticates -->| | 116 | Browser | | | 117 +----------+ +----------------+ 119 Figure 1: Device Flow. 121 The device flow illustrated in Figure 1 includes the following steps: 123 (A) The client requests access from the authorization server and 124 includes its client identifier in the request. 126 (B) The authorization server issues a verification code, an end- 127 user code, and provides the end-user verification URI. 129 (C) The client instructs the end-user to use its user-agent 130 (elsewhere) and visit the provided end-user verification URI. The 131 client provides the end-user with the end-user code to enter in 132 order to grant access. 134 (D) The authorization server authenticates the end-user (via the 135 user-agent) and prompts the end-user to grant the client's access 136 request. If the end-user agrees to the client's access request, 137 the end-user enters the end-user code provided by the client. The 138 authorization server validates the end-user code provided by the 139 end-user. 141 (E) While the end-user authorizes (or denies) the client's request 142 (D), the client repeatedly polls the authorization server to find 143 out if the end-user completed the end-user authorization step. 144 The client includes the verification code and its client 145 identifier. 147 (F) Assuming the end-user granted access, the authorization server 148 validates the verification code provided by the client and 149 responds back with the access token. 151 2. Terminology 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 155 "OPTIONAL" in this document are to be interpreted as described in 156 [RFC2119]. 158 Device Endpoint: 160 The authorization server's endpoint capable of issuing 161 verification codes, user codes, and verification URLs. 163 Device Verification Code: 165 A short-lived token representing an authorization session. 167 End-User Verification Code: 169 A short-lived token which the device displays to the end user, is 170 entered by the end-user on the authorization server, and is thus 171 used to bind the device to the end-user. 173 3. Specification 175 3.1. Device Authorization Request 177 The client initiates the flow by requesting a set of verification 178 codes from the authorization server by making an HTTP "POST" request 179 to the device endpoint. The client constructs a request URI by 180 adding the following parameters to the request: 182 response_type: 184 REQUIRED. The parameter value MUST be set to "device_code". 186 client_id: 188 REQUIRED. The client identifier as described in Section 2.2 of 189 [RFC6749]. 191 scope: 193 OPTIONAL. The scope of the access request as described by 194 Section 3.3 of [RFC6749]. 196 For example, the client makes the following HTTPS request (line 197 breaks are for display purposes only): 199 POST /token HTTP/1.1 200 Host: server.example.com 201 Content-Type: application/x-www-form-urlencoded 203 response_type=device_code&client_id=s6BhdRkqt3 205 3.2. Device Authorization Response 207 In response, the authorization server generates a verification code 208 and an end-user code and includes them in the HTTP response body 209 using the "application/json" format with a 200 status code (OK). The 210 response contains the following parameters: 212 device_code 214 REQUIRED. The verification code. 216 user_code 218 REQUIRED. The end-user verification code. 220 verification_uri 222 REQUIRED. The end-user verification URI on the authorization 223 server. The URI should be short and easy to remember as end- 224 users will be asked to manually type it into their user-agent. 226 expires_in 228 OPTIONAL. The duration in seconds of the verification code 229 lifetime. 231 interval 233 OPTIONAL. The minimum amount of time in seconds that the client 234 SHOULD wait between polling requests to the token endpoint. 236 For example: 238 HTTP/1.1 200 OK 239 Content-Type: application/json 240 Cache-Control: no-store 242 { 243 "device_code":"74tq5miHKB", 244 "user_code":"94248", 245 "verification_uri":"http://www.example.com/device", 246 "interval"=5 247 } 249 3.3. User Instruction 251 After receiving a successful Authorization Response, the client 252 displays the end-user code and the end-user verification URI to the 253 end-user, and instructs the end-user to visit the URI using a user- 254 agent and enter the end-user code. 256 The end-user manually types the provided verification URI and 257 authenticates with the authorization server. The authorization 258 server prompts the end-user to authorize the client's request by 259 entering the end-user code provided by the client. Once the end-user 260 approves or denies the request, the authorization server informs the 261 end-user to return to the device for further instructions. 263 3.4. Device Token Request 265 As the user is authorizing the request on secondary device which may 266 not have a way to communicate to the original device, the client 267 polls the token endpoint until the end-user grants or denies the 268 request, or the device code expires. 270 The client polls at reasonable interval which MUST NOT exceed the 271 minimum interval provided by the authorization server via the 272 "interval" parameter (if provided). 274 The client makes a request to the token endpoint by sending the 275 following parameters using the "application/x-www-form-urlencoded" 276 format per Appendix B with a character encoding of UTF-8 in the HTTP 277 request entity-body: 279 grant_type 281 REQUIRED. Value MUST be set to "urn:ietf:params:oauth:grant- 282 type:device_code". 284 device_code 286 REQUIRED. The device verification code, "device_code" from the 287 Device Authorization Response, defined in Section 3.2. 289 client_id 291 REQUIRED, if the client is not authenticating with the 292 authorization server as described in Section 3.2.1. of [RFC6749] 294 For example, the client makes the following HTTPS request (line 295 breaks are for display purposes only): 297 POST /token HTTP/1.1 298 Host: server.example.com 299 Content-Type: application/x-www-form-urlencoded 301 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=pxDoJ3Bt9WVMTXfDATLkxJ9u 302 &client_id=459691054427 304 Note that unlike the Access Token Request for the authorization_code 305 grant type defined in Section 4.1.3 of [RFC6749] the "redirect_uri" 306 parameter is NOT REQUIRED as part of this request. 308 If the client was issued client credentials (or assigned other 309 authentication requirements), the client MUST authenticate with the 310 authorization server as described in Section 3.2.1 of [RFC6749]. 312 3.5. Device Token Response 314 If the user has approved the grant, the token endpoint responds with 315 a success response defined in Section 5.1 of [RFC6749] otherwise, it 316 responds with an error, as defined in Section 5.2 of [RFC6749]. 318 In addition to the error codes defined in Section 5.2 of [RFC6749], 319 the following error codes are specific for the device flow: 321 authorization_pending 323 The authorization request is still pending as the end-user hasn't 324 yet visited the authorization server and entered their 325 verification code. 327 slow_down 328 The client is polling too quickly and should back off at a 329 reasonable rate. 331 expired_token 333 The device_code has expired. The client will need to make a new 334 Device Authorization Request. 336 The error code "authorization_pending" and "slow_down" are considered 337 soft errors. The the client should continue to poll when receiving 338 "authorization_pending" errors, reducing the interval if a 339 "slow_down" error is received. Other error codes are considered hard 340 errors, the client should stop polling and react accordingly, for 341 example, by displaying an error to the user. 343 4. IANA Considerations 345 4.1. OAuth URI Registration 347 This specification registers the following values in the IANA "OAuth 348 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 350 4.1.1. Registry Contents 352 o URN: urn:ietf:params:oauth:grant-type:device_code 353 o Common Name: Device flow grant type for OAuth 2.0 354 o Change controller: IESG 355 o Specification Document: Section 3.1 of [[ this specification ]] 357 4.2. OAuth Extensions Error Registration 359 This specification registers the following values in the IANA "OAuth 360 Extensions Error Registry" registry [IANA.OAuth.Parameters] 361 established by [RFC6749]. 363 4.2.1. Registry Contents 365 o Error name: authorization_pending 366 o Error usage location: Token endpoint response 367 o Related protocol extension: [[ this specification ]] 368 o Change controller: IETF 369 o Specification Document: Section 3.5 of [[ this specification ]] 371 o Error name: slow_down 372 o Error usage location: Token endpoint response 373 o Related protocol extension: [[ this specification ]] 374 o Change controller: IETF 375 o Specification Document: Section 3.5 of [[ this specification ]] 376 o Error name: expired_token 377 o Error usage location: Token endpoint response 378 o Related protocol extension: [[ this specification ]] 379 o Change controller: IETF 380 o Specification Document: Section 3.5 of [[ this specification ]] 382 5. Security Considerations 384 TBD 386 6. Normative References 388 [IANA.OAuth.Parameters] 389 IANA, "OAuth Parameters", 390 . 392 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 393 Requirement Levels", BCP 14, RFC 2119, 394 DOI 10.17487/RFC2119, March 1997, 395 . 397 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 398 RFC 6749, DOI 10.17487/RFC6749, October 2012, 399 . 401 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 402 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 403 . 405 Appendix A. Acknowledgements 407 The -00 version of this document was based on draft-recordon-oauth- 408 v2-device edited by David Recordon and Brent Goldman. The content of 409 that document was initially part of the OAuth 2.0 protocol 410 specification but was later removed due to the lack of sufficient 411 deployment expertise at that time. We would therefore also like to 412 thank the OAuth working group for their work on the initial content 413 of this specification through 2010. 415 Appendix B. Document History 417 [[ to be removed by the RFC Editor before publication as an RFC ]] 419 -01 421 o Applied spelling and grammar corrections and added the Document 422 History appendix. 424 -00 426 o Initial working group draft based on draft-recordon-oauth- 427 v2-device. 429 Authors' Addresses 431 William Denniss 432 Google 433 1600 Amphitheatre Pkwy 434 Mountain View, CA 94043 435 USA 437 Phone: +1 650-253-0000 438 Email: wdenniss@google.com 439 URI: http://google.com/ 441 Stein Myrseth 442 ForgeRock 443 Lysaker torg 2 444 Lysaker 1366 445 NORWAY 447 Email: stein.myrseth@forgerock.com 449 John Bradley 450 Ping Identity 452 Email: ve7jtb@ve7jtb.com 453 URI: http://www.thread-safe.com/ 455 Michael B. Jones 456 Microsoft 458 Email: mbj@microsoft.com 459 URI: http://self-issued.info/ 461 Hannes Tschofenig 462 ARM Limited 463 Austria 465 Email: Hannes.Tschofenig@gmx.net 466 URI: http://www.tschofenig.priv.at