idnits 2.17.1 draft-ietf-oauth-device-flow-01.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 (March 3, 2016) is 2970 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: September 4, 2016 ForgeRock 6 J. Bradley 7 Ping Identity 8 M. Jones 9 Microsoft 10 H. Tschofenig 11 ARM Limited 12 March 3, 2016 14 OAuth 2.0 Device Flow 15 draft-ietf-oauth-device-flow-01 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 September 4, 2016. 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. Client Requests Authorization . . . . . . . . . . . . . . 4 64 3.2. Client Requests Access Token . . . . . . . . . . . . . . 6 65 3.3. Additional Error Responses . . . . . . . . . . . . . . . 6 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 67 5. Normative References . . . . . . . . . . . . . . . . . . . . 7 68 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7 69 Appendix B. Document History . . . . . . . . . . . . . . . . . . 7 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 72 1. Introduction 74 The device flow is suitable for clients executing on devices that do 75 not have an easy data-entry method and where the client is incapable 76 of receiving incoming requests from the authorization server 77 (incapable of acting as an HTTP server). 79 Instead of interacting with the end-user's user-agent, the client 80 instructs the end-user to use another computer or device and connect 81 to the authorization server to approve the access request. Since the 82 client cannot receive incoming requests, it polls the authorization 83 server repeatedly until the end-user completes the approval process. 85 Note that this device flow does not utilize the client secret. 87 +----------+ +----------------+ 88 | |>---(A)-- Client Identifier --->| | 89 | | | | 90 | |<---(B)-- Verification Code, --<| | 91 | | User Code, | | 92 | | & Verification URI | | 93 | Device | | | 94 | Client | Client Identifier & | | 95 | |>---(E)-- Verification Code --->| | 96 | | ... | | 97 | |>---(E)---> | | 98 | | | Authorization | 99 | |<---(F)-- Access Token --------<| Server | 100 +----------+ (w/ Optional Refresh Token) | | 101 v | | 102 : | | 103 (C) User Code & Verification URI | | 104 : | | 105 v | | 106 +----------+ | | 107 | End-user | | | 108 | at |<---(D)-- User authenticates -->| | 109 | Browser | | | 110 +----------+ +----------------+ 112 Figure 1: Device Flow. 114 The device flow illustrated in Figure 1 includes the following steps: 116 (A) The client requests access from the authorization server and 117 includes its client identifier in the request. 119 (B) The authorization server issues a verification code, an end- 120 user code, and provides the end-user verification URI. 122 (C) The client instructs the end-user to use its user-agent 123 (elsewhere) and visit the provided end-user verification URI. The 124 client provides the end-user with the end-user code to enter in 125 order to grant access. 127 (D) The authorization server authenticates the end-user (via the 128 user-agent) and prompts the end-user to grant the client's access 129 request. If the end-user agrees to the client's access request, 130 the end-user enters the end-user code provided by the client. The 131 authorization server validates the end-user code provided by the 132 end-user. 134 (E) While the end-user authorizes (or denies) the client's request 135 (D), the client repeatedly polls the authorization server to find 136 out if the end-user completed the end-user authorization step. 137 The client includes the verification code and its client 138 identifier. 140 (F) Assuming the end-user granted access, the authorization server 141 validates the verification code provided by the client and 142 responds back with the access token. 144 2. Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 148 "OPTIONAL" in this document are to be interpreted as described in 149 [RFC2119]. 151 Device Endpoint: 153 The authorization server's endpoint capable of issuing 154 verification codes, user codes, and verification URLs. 156 Device Verification Code: 158 A short-lived token representing an authorization session. 160 End-User Verification Code: 162 A short-lived token which the device displays to the end user, is 163 entered by the end-user on the authorization sever, and is thus 164 used to bind the device to the end-user. 166 3. Specification 168 3.1. Client Requests Authorization 170 The client initiates the flow by requesting a set of verification 171 codes from the authorization server by making an HTTP "POST" request 172 to the device endpoint. The client constructs a request URI by 173 adding the following parameters to the request: 175 response_type: 177 REQUIRED. The parameter value MUST be set to "device_code". 179 client_id: 181 REQUIRED. The client identifier as described in Section 2.2 of 182 [RFC6749]. 184 scope: 186 OPTIONAL. The scope of the access request as described by 187 Section 3.3 of [RFC6749]. 189 For example, the client makes the following HTTPS request (line 190 breaks are for display purposes only): 192 POST /token HTTP/1.1 193 Host: server.example.com 194 Content-Type: application/x-www-form-urlencoded 196 response_type=device_code&client_id=s6BhdRkqt3 198 In response, the authorization server generates a verification code 199 and an end-user code and includes them in the HTTP response body 200 using the "application/json" format with a 200 status code (OK). The 201 response contains the following parameters: 203 device_code 205 REQUIRED. The verification code. 207 user_code 209 REQUIRED. The end-user verification code. 211 verification_uri 213 REQUIRED. The end-user verification URI on the authorization 214 server. The URI should be short and easy to remember as end- 215 users will be asked to manually type it into their user-agent. 217 expires_in 219 OPTIONAL. The duration in seconds of the verification code 220 lifetime. 222 interval 224 OPTIONAL. The minimum amount of time in seconds that the client 225 SHOULD wait between polling requests to the token endpoint. 227 For example: 229 HTTP/1.1 200 OK 230 Content-Type: application/json 231 Cache-Control: no-store 233 { 234 "device_code":"74tq5miHKB", 235 "user_code":"94248", 236 "verification_uri":"http://www.example.com/device", 237 "interval"=5 238 } 240 The client displays the end-user code and the end-user verification 241 URI to the end-user, and instructs the end-user to visit the URI 242 using a user-agent and enter the end-user code. 244 The end-user manually types the provided verification URI and 245 authenticates with the authorization server. The authorization 246 server prompts the end-user to authorize the client's request by 247 entering the end-user code provided by the client. Once the end-user 248 approves or denies the request, the authorization server informs the 249 end-user to return to the device for further instructions. 251 3.2. Client Requests Access Token 253 Since the client is unable to receive incoming requests from the 254 authorization server, it polls the authorization server repeatedly 255 until the end-user grants or denies the request, or the verification 256 code expires. 258 The client makes the following request at an arbitrary but reasonable 259 interval which MUST NOT exceed the minimum interval rate provided by 260 the authorization server (if present via the "interval" parameter). 261 Alternatively, the client MAY provide a user interface for the end- 262 user to manually inform it when authorization was granted. 264 The client requests an access token by making an HTTP "POST" request 265 to the token endpoint as described in Section 4.1.1 of [RFC6749] . 266 The "redirect_uri" parameter is NOT REQUIRED as part of this request. 268 3.3. Additional Error Responses 270 The following error responses are defined in addition to those within 271 Section 4.2.2.1. of [RFC6749]: 273 authorization_pending 274 The authorization request is still pending as the end-user hasn't 275 yet visited the authorization server and entered their 276 verification code. 278 slow_down 280 The client is polling too quickly and should back off at a 281 reasonable rate. 283 4. Security Considerations 285 TBD 287 5. Normative References 289 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 290 Requirement Levels", BCP 14, RFC 2119, 291 DOI 10.17487/RFC2119, March 1997, 292 . 294 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 295 RFC 6749, DOI 10.17487/RFC6749, October 2012, 296 . 298 Appendix A. Acknowledgements 300 The -00 version of this document was based on draft-recordon-oauth- 301 v2-device edited by David Recordon and Brent Goldman. The content of 302 that document was initially part of the OAuth 2.0 protocol 303 specification but was later removed due to the lack of sufficient 304 deployment expertise at that time. We would therefore also like to 305 thank the OAuth working group for their work on the initial content 306 of this specification through 2010. 308 Appendix B. Document History 310 [[ to be removed by the RFC Editor before publication as an RFC ]] 312 -01 314 o Applied spelling and grammar corrections and added the Document 315 History appendix. 317 -00 319 o Initial working group draft based on draft-recordon-oauth- 320 v2-device. 322 Authors' Addresses 324 William Denniss 325 Google 326 1600 Amphitheatre Pkwy 327 Mountain View, CA 94043 328 USA 330 Phone: +1 650-253-0000 331 Email: wdenniss@google.com 332 URI: http://google.com/ 334 Stein Myrseth 335 ForgeRock 336 Lysaker torg 2 337 Lysaker 1366 338 NORWAY 340 Email: stein.myrseth@forgerock.com 342 John Bradley 343 Ping Identity 345 Email: ve7jtb@ve7jtb.com 346 URI: http://www.thread-safe.com/ 348 Michael B. Jones 349 Microsoft 351 Email: mbj@microsoft.com 352 URI: http://self-issued.info/ 354 Hannes Tschofenig 355 ARM Limited 356 Austria 358 Email: Hannes.Tschofenig@gmx.net 359 URI: http://www.tschofenig.priv.at