idnits 2.17.1 draft-ietf-oauth-reciprocal-04.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 a Security Considerations section. 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 document date (August 01, 2019) is 1729 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) == Unused Reference: 'RFC6750' is defined on line 313, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 6755 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group D. Hardt 3 Internet-Draft August 01, 2019 4 Intended status: Standards Track 5 Expires: February 2, 2020 7 Reciprocal OAuth 8 draft-ietf-oauth-reciprocal-04 10 Abstract 12 There are times when a user has a pair of protected resources that 13 would like to request access to each other. While OAuth flows 14 typically enable the user to grant a client access to a protected 15 resource, granting the inverse access requires an additional flow. 16 Reciprocal OAuth enables a more seamless experience for the user to 17 grant access to a pair of protected resources. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on February 2, 2020. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 1. Introduction 53 In the usual three legged, authorization code grant, the OAuth flow 54 enables a resource owner (user) to enable a client (party A) to be 55 granted authorization to access a protected resource (party B). If 56 party A also has a protected resource that the user would like to let 57 party B access, then a second complete OAuth flow, but in the reverse 58 direction, must be performed. In practice, this is a complicated 59 user experience as the user is at Party A, but the OAuth flow needs 60 to start from Party B. This requires the second flow to send the 61 user back to party B, which then sends the user to Party A as the 62 first step in the flow. At the end, the user is at Party B, even 63 though the original flow started at Party A. 65 Reciprocal OAuth simplifies the user experience by eliminating the 66 redirections in the second OAuth flow. After the intial OAuth flow, 67 party A obtains consent from the user to grant party B access to a 68 protected resource at party A, and then passes an authorization code 69 to party B using the access token party A obtained from party B to 70 provide party B the context of the user. Party B then exchanges the 71 authorization code for an access token per the usual OAuth flow. 73 For example, a user would like their voice assistant (party A) and 74 music service (party B) to work together. The voice assistant wants 75 to call the music service to play music, and the music service wants 76 to call the voice assistant with music information to present to the 77 user. The user starts the OAuth flow at the voice assistant, and is 78 redirected to the music service. The music services obtains consent 79 from the user and the redirects back to the voice assistant. At this 80 point the voice assistant is able to obtain an access token for the 81 music service. The voice assistant can the get consent from the user 82 to authorize the music service to access the voice assistant, and 83 then the voice assistant can create an authorization code and send it 84 to the music service, which then exchanges the authorization code for 85 an access token, all without further user interaction. Note that 86 either the voice assistant or the music service can initiate the 87 flow, so that either can prompt the user for the two parties to work 88 together. 90 1.1. Terminology 92 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 93 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 94 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 95 [RFC2119]. 97 2. reciprocal Protocol Flow 99 Party A Party B 100 +---------------+ +---------------+ 101 | |--(A)- Authorization Request ->| Resource | 102 | | | Owner B | 103 | |<-(B)-- Authorization Grant ---| | 104 | | +---------------+ 105 | Client A | 106 | | +---------------+ 107 | |--(C)-- Authorization Grant -->| | 108 | | | Authorization | 109 | |<-(D)---- Access Token B ------| Server B | 110 | | reciprocal Request | | 111 +---------------+ +---------------+ 112 | 113 reciprocal Request 114 V 115 +---------------+ +---------------+ 116 | Resource | | Authorization | 117 | Owner A |--(E)--- reciprocal Grant ---->| Server B | 118 | | Access Token B | | 119 +---------------+ +---------------+ 120 | 121 reciprocal Grant 122 V 123 +---------------+ +---------------+ 124 | |<-(F)--- reciprocal Grant -----| | 125 | Authorization | | Client B | 126 | Server A |--(G)---- Access Token A ----->| | 127 +---------------+ +---------------+ 129 Figure 1: Abstract reciprocal Protocol Flow 131 The reciprocal authorization between party A and party B are 132 abstractly represented in Figure 1 and includes the following steps: 134 o (A - C) are the same as in [RFC6749] 1.2 136 o (D) Party B optionally includes the reciprocal scope in the 137 response. See Section 2.1 for details. 139 o (E) Party A sends the reciprocal authorization grant to party B. 140 See Section 2.2.2 for details. 142 o (F) Party B requests an access token, mirroring step (B) 144 o (G) Party A issues an access token, mirroring step (C) 145 Note that Resource Owner A and Resource Owner B are the respective 146 resource owner interaction systems controlled by the same owner. 148 2.1. Reciprocal Scope Request 150 When party B is providing an access token response per [RFC6749] 151 4.1.4, 4.2.1, 4.3.3 or 4.4.3, party B MAY include an additional query 152 component in the redirection URI to indicate the scope requested in 153 the reciprocal grant: 155 reciprocal OPTIONAL 156 The scope of party B's reciprocal access request per [RFC6749] 3.3. 158 If party B does not provide a reciprocal parameter in the access 159 token response, the reciprocal scope will be a value previously 160 preconfigured by party A and party B. 162 If an authorization code grant access token response per [RFC6749] 163 4.1.4, an example successful response (with extra line breaks for 164 display purposes only): 166 HTTP/1.1 200 OK 167 Content-Type: application/json;charset=UTF-8 168 Cache-Control: no-store 169 Pragma: no-cache 171 { 172 "access_token":"2YotnFZFEjr1zCsicMWpAA", 173 "token_type":"example", 174 "expires_in":3600, 175 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 176 "reciprocal":"example_scope", 177 "example_parameter":"example_value" 178 } 180 If an authorization code grant access token response per [RFC6749] 181 4.2.2, an example successful response (with extra line breaks for 182 display purposes only): 184 HTTP/1.1 302 Found 185 Location: http://example.com/cb# 186 access_token=2YotnFZFEjr1zCsicMWpAA& 187 state=xyz& 188 token_type=example& 189 expires_in=3600& 190 reciprocal="example_scope" 192 When party B is providing an authorization response per [RFC6749] 193 4.1.2, party B MAY include an additional query component in the 194 redirection URI to indicate the scope requested in the reciprocal 195 grant. 197 reciprocal OPTIONAL. The scope of party B's reciprocal access 198 request per [RFC6749] 3.3. 200 If party B does not provide a reciprocal parameter in the 201 authorization response, the reciprocal scope will be a value 202 previously preconfigured by party A and party B. 204 2.2. Reciprocal Authorization Flow 206 The reciprocal authorization flow starts after the client (party A) 207 has obtained an access token from the authorization server (party B) 208 per [RFC6749] 4.1 Authorization Code Grant. 210 2.2.1. User Consent 212 Party A obtains consent from the user to grant Party B access to 213 protected resources at party A. The consent represents the scopes 214 requested by party B from party A per Section 2.1. 216 2.2.2. Reciprocal Authorization Code 218 Party A generates an authorization code representing the access 219 granted to party B by the user. Party A then makes a request to 220 party B's token endpoint authenticating per [RFC6749] 2.3 and sending 221 the following parameters using the "application/x-www-form- 222 urlencoded" format per [RFC6749] Appendix B with a character encoding 223 of UTF-8 in the HTTP request entity-body: 225 grant_type REQUIRED 226 Value MUST be set to "urn:ietf:params:oauth:grant-type:reciprocal". 228 code REQUIRED 229 the authorization code generated by party A. 231 client_id REQUIRED 232 party A'a client ID. 234 access_token REQUIRED the access token obtained from Party B. Used 235 by Party B to identify which user authorization is being requested. 237 For example, the client makes the following HTTP request using TLS 238 (with extra line breaks for display purposes only): 240 POST /token HTTP/1.1 241 Host: server.example.com 242 Authorization: Basic ej4hsyfishwssjdusisdhkjsdksusdhjkjsdjk 243 Content-Type: application/x-www-form-urlencoded 245 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3reciprocal 246 &code=hasdyubasdjahsbdkjbasd 247 &client_id=example.com 248 &access_token=sadadojsadlkjasdkljxxlkjdas 250 Party B MUST verify the authentication provided by Party A per 251 [RFC6749] 2.3 253 Party B MUST then verify the access token was granted to the client 254 identified by the client_id. 256 Party B MUST respond with either an HTTP 200 (OK) response if the 257 request is valid, or an HTTP 400 "Bad Request" if it is not. 259 Party B then plays the role of the client to make an access token 260 request per [RFC6749] 4.1.3. 262 3. Authorization Update Flow 264 After the initial authorization, the user may add or remove scopes 265 available to the client at the authorization server. For example, 266 the user may grant additional scopes to the client using a voice 267 interface, or revoke some scopes. The authorization server can 268 update the client with the new authorization by sending a new 269 authorization code per Section 2.2.2. 271 4. IANA Considerations 273 4.1. Registration of reciprocal 275 This section registers the value "reciprocal" in the IANA "OAuth 276 Parameters" registry established by "The OAuth 2.0 Authorization 277 Framework" [RFC6749]. 279 o Parameter Name: reciprocal 281 o Parameter usage location: token response 283 o Change Controller: IESG 285 o Specification Document: Section Section 2.1 of this document 287 4.2. Sub-Namespace Registration of urn:ietf:params:oauth:grant- 288 type:reciprocal 290 This section registers the value "grant-type:reciprocal" in the IANA 291 "OAuth URI" registry established by "An IETF URN Sub-Namespace for 292 OAuth" [RFC6755]. 294 o URN: urn:ietf:params:oauth:grant-type:reciprocal 296 o Common Name: reciprocal grant for OAuth 2.0 298 o Change Controller: IESG 300 o Specification Document: Section Section 2.2.2 of this document 302 5. Normative References 304 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 305 Requirement Levels", BCP 14, RFC 2119, 306 DOI 10.17487/RFC2119, March 1997, 307 . 309 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 310 RFC 6749, DOI 10.17487/RFC6749, October 2012, 311 . 313 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 314 Framework: Bearer Token Usage", RFC 6750, 315 DOI 10.17487/RFC6750, October 2012, 316 . 318 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 319 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 320 . 322 Appendix A. Document History 324 A.1. draft-ietf-oauth-reciprocal-00 326 o Initial version. 328 A.2. draft-ietf-oauth-reciprocal-01 330 o Changed reciprocal scope request to be in access token response 331 rather than authorization request 333 A.3. draft-ietf-oauth-reciprocal-02 335 o Added in diagram to clarify protocol flow 337 A.4. draft-ietf-oauth-reciprocal-03 339 o fixed spelling of reciprocal 341 o added example use case in introduction 343 o resource owner is the same in Party A and Party B 345 A.5. draft-ietf-oauth-reciprocal-04 347 o completed IANA section 349 Author's Address 351 Dick Hardt 353 Email: dick.hardt@gmail.com