idnits 2.17.00 (12 Aug 2021) /tmp/idnits45217/draft-recordon-oauth-v2-device-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 document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (Jul 2010) is 4327 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 (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Recordon, Ed. 3 Internet-Draft B. Goldman 4 Intended status: Standards Track Facebook 5 Expires: January 2, 2011 Jul 2010 7 OAuth 2.0 Device Profile 8 draft-recordon-oauth-v2-device-00 10 Abstract 12 The device profile is suitable for OAuth 2.0 clients executing on 13 devices which do not have an easy data-entry method (e.g. game 14 consoles or media hubs), but where the end-user has separate access 15 to a user-agent on another computer or device (e.g. home computer, a 16 laptop, or a smart phone). 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 2, 2011. 35 Copyright Notice 37 Copyright (c) 2010 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.4. Client Requests Authorization . . . . . . . . . . . . . . . 5 57 1.5. Client Requests Access Token . . . . . . . . . . . . . . . 7 58 1.6. Additional Error Responses . . . . . . . . . . . . . . . . 7 59 2. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 60 3. Normative References . . . . . . . . . . . . . . . . . . . . . 7 61 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 63 1. Introduction 65 1.1. Notational Conventions 67 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 68 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 69 document are to be interpreted as described in [RFC2119]. 71 1.2. Terminology 73 device endpoint 74 The authorization server's HTTP endpoint capable of issuing 75 verification codes, user codes, and verification URLs. 77 device verification code 78 A short-lived token representing an authorization session. 80 end-user verificition code 81 A short-lived token which the device displays to the end user, 82 is entered by the end-user on the authorization sever, and is 83 thus used to bind the device to the end-user. 85 1.3. Overview 87 The device profile is suitable for clients executing on devices which 88 do not have an easy data-entry method (e.g. game consoles or media 89 hubs), but where the end-user has separate access to a user-agent on 90 another computer or device (e.g. home computer, a laptop, or a smart 91 phone). The client is incapable of receiving incoming requests from 92 the authorization server (incapable of acting as an HTTP server). 94 Instead of interacting with the end-user's user-agent, the client 95 instructs the end-user to use another computer or device and connect 96 to the authorization server to approve the access request. Since the 97 client cannot receive incoming requests, it polls the authorization 98 server repeatedly until the end-user completes the approval process. 100 This device flow does not utilize the client secret since the client 101 executables reside on a local device which makes the client secret 102 accessible and exploitable. 104 +----------+ +----------------+ 105 | |>---(A)-- Client Identifier --->| | 106 | | | | 107 | |<---(B)-- Verification Code, --<| | 108 | | User Code, | | 109 | | & Verification URI | | 110 | Device | | | 111 | Client | Client Identifier & | | 112 | |>---(E)-- Verification Code --->| | 113 | | ... | | 114 | |>---(E)---> | | 115 | | | Authorization | 116 | |<---(F)-- Access Token --------<| Server | 117 +----------+ (w/ Optional Refresh Token) | | 118 v | | 119 : | | 120 (C) User Code & Verification URI | | 121 : | | 122 v | | 123 +----------+ | | 124 | End-user | | | 125 | at |<---(D)-- User authenticates -->| | 126 | Browser | | | 127 +----------+ +----------------+ 129 Figure 1: Device Flow 131 The device flow illustrated in Figure 1 includes the following steps: 133 (A) The client requests access from the authorization server and 134 includes its client identifier in the request. 136 (B) The authorization server issues a verification code, an end-user 137 code, and provides the end-user verification URI. 139 (C) The client instructs the end-user to use its user-agent 140 (elsewhere) and visit the provided end-user verification URI. 141 The client provides the end-user with the end-user code to enter 142 in order to grant access. 144 (D) The authorization server authenticates the end-user (via the 145 user-agent) and prompts the end-user to grant the client's 146 access request. If the end-user agrees to the client's access 147 request, the end-user enters the end-user code provided by the 148 client. The authorization server validates the end-user code 149 provided by the end-user. 151 (E) While the end-user authorizes (or denies) the client's request 152 (D), the client repeatedly polls the authorization server to 153 find out if the end-user completed the end-user authorization 154 step. The client includes the verification code and its client 155 identifier. 157 (F) Assuming the end-user granted access, the authorization server 158 validates the verification code provided by the client and 159 responds back with the access token. 161 1.4. Client Requests Authorization 163 The client initiates the flow by requesting a set of verification 164 codes from the authorization server by making an HTTP "POST" request 165 to the device endpoint. The client constructs a request URI by 166 adding the following parameters to the request: 168 response_type 169 REQUIRED. The parameter value MUST be set to "device_code". 171 client_id 172 REQUIRED. The client identifier as described in Section 2 of 173 [I-D.ietf.oauth-v2]. 175 scope 176 OPTIONAL. The scope of the access request expressed as a list 177 of space-delimited strings. The value of the "scope" parameter 178 is defined by the authorization server. If the value contains 179 multiple space-delimited strings, their order does not matter, 180 and each string adds an additional access range to the 181 requested scope. 183 For example, the client makes the following HTTPS request (line 184 breaks are for display purposes only): 186 POST /token HTTP/1.1 187 Host: server.example.com 188 Content-Type: application/x-www-form-urlencoded 190 response_type=device_code&client_id=s6BhdRkqt3 192 In response, the authorization server generates a verification code 193 and an end-user code and includes them in the HTTP response body 194 using the "application/json" format with a 200 status code (OK). The 195 response contains the following parameters: 197 device_code 198 REQUIRED. The verification code. 200 user_code 201 REQUIRED. The end-user verification code. 203 verification_uri 204 REQUIRED. The end-user verification URI on the authorization 205 server. The URI should be short and easy to remember as end- 206 users will be asked to manually type it into their user-agent. 208 expires_in 209 OPTIONAL. The duration in seconds of the verification code 210 lifetime. 212 interval 213 OPTIONAL. The minimum amount of time in seconds that the 214 client SHOULD wait between polling requests to the token 215 endpoint. 217 For example: 219 HTTP/1.1 200 OK 220 Content-Type: application/json 221 Cache-Control: no-store 223 { 224 "device_code":"74tq5miHKB", 225 "user_code":"94248", 226 "verification_uri":"http://www.example.com/device", 227 "interval"=5 228 } 230 The client displays the end-user code and the end-user verification 231 URI to the end-user, and instructs the end-user to visit the URI 232 using a user-agent and enter the end-user code. 234 The end-user manually types the provided verification URI and 235 authenticates with the authorization server. The authorization 236 server prompts the end-user to authorize the client's request by 237 entering the end-user code provided by the client. Once the end-user 238 approves or denies the request, the authorization server informs the 239 end-user to return to the device for further instructions. 241 1.5. Client Requests Access Token 243 Since the client is unable to receive incoming requests from the 244 authorization server, it polls the authorization server repeatedly 245 until the end-user grants or denies the request, or the verification 246 code expires. 248 The client makes the following request at an arbitrary but reasonable 249 interval which MUST NOT exceed the minimum interval rate provided by 250 the authorization server (if present via the "interval" parameter). 251 Alternatively, the client MAY provide a user interface for the end- 252 user to manually inform it when authorization was granted. 254 The client requests an access token by making an HTTP "POST" request 255 to the token endpoint as described in Section 4.1.1 of 256 [I-D.ietf.oauth-v2]. The "redirect_uri" parameter is NOT REQUIRED as 257 part of this request. 259 1.6. Additional Error Responses 261 The following error responses are defined in addition to those within 262 Section 4.3.1 of [I-D.ietf.oauth-v2]. 264 authorization_pending 265 The authorization request is still pending as the end-user 266 hasn't yet visited the authorization server and entered their 267 verification code. 269 slow_down 270 The client is polling too quickly and should back off at a 271 reasonable rate. 273 2. Security Considerations 275 Length of codes (Google has done some research here). 277 3. Normative References 279 [I-D.ietf.oauth-v2] 280 Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The 281 OAuth 2.0 Protocol", Jun 2010. 283 [RFC2119] Bradner, B., "Key words for use in RFCs to Indicate 284 Requirement Levels", BCP 14, RFC 2119. 286 Authors' Addresses 288 David Recordon (editor) 289 Facebook 291 Email: davidrecordon@facebook.com 293 Brent Goldman 294 Facebook 296 Email: brent@facebook.com