idnits 2.17.1 draft-ietf-oauth-device-flow-00.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 (February 17, 2016) is 2984 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: August 20, 2016 Forgerock 6 J. Bradley 7 Ping Identity 8 M. Jones 9 Microsoft 10 H. Tschofenig 11 ARM Limited 12 February 17, 2016 14 OAuth 2.0 Device Flow 15 draft-ietf-oauth-device-flow-00 17 Abstract 19 The device flow is suitable for OAuth 2.0 clients executing on 20 devices which 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 Note: This version of the document is a continuation of an earlier, 27 long expired draft. The content of the expired draft has been copied 28 almost unmodified. The goal of the work on this document is to 29 capture deployment experience. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on August 20, 2016. 48 Copyright Notice 50 Copyright (c) 2016 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Client Requests Authorization . . . . . . . . . . . . . . 4 69 3.2. Client Requests Access Token . . . . . . . . . . . . . . 6 70 3.3. Additional Error Responses . . . . . . . . . . . . . . . 6 71 4. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 7 72 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 74 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 77 1. Introduction 79 The device flow is suitable for clients executing on devices which do 80 not have an easy data-entry method and where the client is incapable 81 of receiving incoming requests from the authorization server 82 (incapable of acting as an HTTP server). 84 Instead of interacting with the end-user's user-agent, the client 85 instructs the end-user to use another computer or device and connect 86 to the authorization server to approve the access request. Since the 87 client cannot receive incoming requests, it polls the authorization 88 server repeatedly until the end-user completes the approval process. 90 Note that this device flow does not utilize the client secret. 92 +----------+ +----------------+ 93 | |>---(A)-- Client Identifier --->| | 94 | | | | 95 | |<---(B)-- Verification Code, --<| | 96 | | User Code, | | 97 | | & Verification URI | | 98 | Device | | | 99 | Client | Client Identifier & | | 100 | |>---(E)-- Verification Code --->| | 101 | | ... | | 102 | |>---(E)---> | | 103 | | | Authorization | 104 | |<---(F)-- Access Token --------<| Server | 105 +----------+ (w/ Optional Refresh Token) | | 106 v | | 107 : | | 108 (C) User Code & Verification URI | | 109 : | | 110 v | | 111 +----------+ | | 112 | End-user | | | 113 | at |<---(D)-- User authenticates -->| | 114 | Browser | | | 115 +----------+ +----------------+ 117 Figure 1: Device Flow. 119 The device flow illustrated in Figure 1 includes the following steps: 121 (A) The client requests access from the authorization server and 122 includes its client identifier in the request. 124 (B) The authorization server issues a verification code, an end- 125 user code, and provides the end-user verification URI. 127 (C) The client instructs the end-user to use its user-agent 128 (elsewhere) and visit the provided end-user verification URI. The 129 client provides the end-user with the end-user code to enter in 130 order to grant access. 132 (D) The authorization server authenticates the end-user (via the 133 user-agent) and prompts the end-user to grant the client's access 134 request. If the end-user agrees to the client's access request, 135 the end-user enters the end-user code provided by the client. The 136 authorization server validates the end-user code provided by the 137 end-user. 139 (E) While the end-user authorizes (or denies) the client's request 140 (D), the client repeatedly polls the authorization server to find 141 out if the end-user completed the end-user authorization step. 142 The client includes the verification code and its client 143 identifier. 145 (F) Assuming the end-user granted access, the authorization server 146 validates the verification code provided by the client and 147 responds back with the access token. 149 2. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 153 "OPTIONAL" in this document are to be interpreted as described in 154 [RFC2119]. 156 Device Endpoint: 158 The authorization server's endpoint capable of issuing 159 verification codes, user codes, and verification URLs. 161 Device Verification Code: 163 A short-lived token representing an authorization session. 165 End-User Verification Code: 167 A short-lived token which the device displays to the end user, is 168 entered by the end-user on the authorization sever, and is thus 169 used to bind the device to the end-user. 171 3. Specification 173 3.1. Client Requests Authorization 175 The client initiates the flow by requesting a set of verification 176 codes from the authorization server by making an HTTP "POST" request 177 to the device endpoint. The client constructs a request URI by 178 adding the following parameters to the request: 180 response_type: 182 REQUIRED. The parameter value MUST be set to "device_code". 184 client_id: 186 REQUIRED. The client identifier as described in Section 2.2 of 187 [RFC6749]. 189 scope: 191 OPTIONAL. The scope of the access request as described by 192 Section 3.3 of [RFC6749]. 194 For example, the client makes the following HTTPS request (line 195 breaks are for display purposes only): 197 POST /token HTTP/1.1 198 Host: server.example.com 199 Content-Type: application/x-www-form-urlencoded 201 response_type=device_code&client_id=s6BhdRkqt3 203 In response, the authorization server generates a verification code 204 and an end-user code and includes them in the HTTP response body 205 using the "application/json" format with a 200 status code (OK). The 206 response contains the following parameters: 208 device_code 210 REQUIRED. The verification code. 212 user_code 214 REQUIRED. The end-user verification code. 216 verification_uri 218 REQUIRED. The end-user verification URI on the authorization 219 server. The URI should be short and easy to remember as end- 220 users will be asked to manually type it into their user-agent. 222 expires_in 224 OPTIONAL. The duration in seconds of the verification code 225 lifetime. 227 interval 229 OPTIONAL. The minimum amount of time in seconds that the client 230 SHOULD wait between polling requests to the token endpoint. 232 For example: 234 HTTP/1.1 200 OK 235 Content-Type: application/json 236 Cache-Control: no-store 238 { 239 "device_code":"74tq5miHKB", 240 "user_code":"94248", 241 "verification_uri":"http://www.example.com/device", 242 "interval"=5 243 } 245 The client displays the end-user code and the end-user verification 246 URI to the end-user, and instructs the end-user to visit the URI 247 using a user-agent and enter the end-user code. 249 The end-user manually types the provided verification URI and 250 authenticates with the authorization server. The authorization 251 server prompts the end-user to authorize the client's request by 252 entering the end-user code provided by the client. Once the end-user 253 approves or denies the request, the authorization server informs the 254 end-user to return to the device for further instructions. 256 3.2. Client Requests Access Token 258 Since the client is unable to receive incoming requests from the 259 authorization server, it polls the authorization server repeatedly 260 until the end-user grants or denies the request, or the verification 261 code expires. 263 The client makes the following request at an arbitrary but reasonable 264 interval which MUST NOT exceed the minimum interval rate provided by 265 the authorization server (if present via the "interval" parameter). 266 Alternatively, the client MAY provide a user interface for the end- 267 user to manually inform it when authorization was granted. 269 The client requests an access token by making an HTTP "POST" request 270 to the token endpoint as described in Section 4.1.1 of [RFC6749] . 271 The "redirect_uri" parameter is NOT REQUIRED as part of this request. 273 3.3. Additional Error Responses 275 The following error responses are defined in addition to those within 276 Section 4.2.2.1. of [RFC6749]: 278 authorization_pending 279 The authorization request is still pending as the end-user hasn't 280 yet visited the authorization server and entered their 281 verification code. 283 slow_down 285 The client is polling too quickly and should back off at a 286 reasonable rate. 288 4. Contributors 290 The -00 version of this document is based on a previous edited by 291 David Recordon and Brent Goldman. The content of that document was 292 initially part of the OAuth 2.0 protocol specificaiton but was later 293 removed due to the lack of sufficient deployment expertise at that 294 time. We would therefore also like to thank the OAuth working group 295 for their work on this document around 2010. 297 5. Acknowledgements 299 Add your name here. 301 6. Security Considerations 303 TBD 305 7. Normative References 307 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 308 Requirement Levels", BCP 14, RFC 2119, 309 DOI 10.17487/RFC2119, March 1997, 310 . 312 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 313 RFC 6749, DOI 10.17487/RFC6749, October 2012, 314 . 316 Authors' Addresses 318 William Denniss 319 Google 320 1600 Amphitheatre Pkwy 321 Mountain View, CA 94043 322 USA 324 Phone: +1 650-253-0000 325 Email: wdenniss@google.com 326 URI: http://google.com/ 327 Stein Myrseth 328 Forgerock 329 Lysaker torg 2 330 Lysaker 1366 331 NORWAY 333 Email: stein.myrseth@forgerock.com 335 John Bradley 336 Ping Identity 338 Email: ve7jtb@ve7jtb.com 339 URI: http://www.thread-safe.com/ 341 Michael B. Jones 342 Microsoft 344 Email: mbj@microsoft.com 345 URI: http://self-issued.info/ 347 Hannes Tschofenig 348 ARM Limited 349 Austria 351 Email: Hannes.Tschofenig@gmx.net 352 URI: http://www.tschofenig.priv.at