idnits 2.17.1 draft-ietf-oauth-reciprocal-02.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 (July 03, 2019) is 1758 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 271, but no explicit reference was found in the text Summary: 1 error (**), 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 July 03, 2019 4 Intended status: Standards Track 5 Expires: January 4, 2020 7 Reciprocal OAuth 8 draft-ietf-oauth-reciprocal-02 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 January 4, 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 1.1. Terminology 75 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 76 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 77 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 78 [RFC2119]. 80 2. Reciprocol Protocol Flow 81 Party A Party B 82 +---------------+ +---------------+ 83 | |--(A)- Authorization Request ->| Resource | 84 | | | Owner B | 85 | |<-(B)-- Authorization Grant ---| | 86 | | +---------------+ 87 | Client A | 88 | | +---------------+ 89 | |--(C)-- Authorization Grant -->| | 90 | | | Authorization | 91 | |<-(D)---- Access Token B ------| Server B | 92 | | Reciprocol Request | | 93 +---------------+ +---------------+ 94 | 95 Reciprocol Request 96 V 97 +---------------+ +---------------+ 98 | Resource | | Authorization | 99 | Owner A |--(E)--- Reciprocol Grant ---->| Server B | 100 | | Access Token B | | 101 +---------------+ +---------------+ 102 | 103 Reciprocol Grant 104 V 105 +---------------+ +---------------+ 106 | |<-(F)--- Reciprocol Grant -----| | 107 | Authorization | | Client B | 108 | Server A |--(G)---- Access Token A ----->| | 109 +---------------+ +---------------+ 111 Figure 1: Abstract Reciprocol Protocol Flow 113 The reciprocol authorization between party A and party B are 114 abstractly represented in Figure 1 and includes the following steps: 116 o (A - C) are the same as in [RFC6749] 1.2 118 o (D) Party B optionally includes the reciprocol scope in the 119 response. 120 See Section 2.1 for details. 122 o (E) Party A sends the reciprocol authorization grant to party B. 123 See Section 2.2.2 for details. 125 o (F) Party B requests an access token, mirroring step (B) 127 o (G) Party A issues an access token, mirroring step (C) 129 2.1. Reciprocal Scope Request 131 When party B is providing an access token response per [RFC6749] 132 4.1.4, 4.2.1, 4.3.3 or 4.4.3, party B MAY include an additional query 133 component in the redirection URI to indicate the scope requested in 134 the reciprocal grant: 136 reciprocal OPTIONAL 137 The scope of party B's reciprocal access request per [RFC6749] 3.3. 139 If party B does not provide a reciprocal parameter in the access 140 token response, the reciprocal scope will be a value previously 141 preconfigured by party A and party B. 143 If an authorization code grant access token response per [RFC6749] 144 4.1.4, an example successful response (with extra line breaks for 145 display purposes only): 147 HTTP/1.1 200 OK 148 Content-Type: application/json;charset=UTF-8 149 Cache-Control: no-store 150 Pragma: no-cache 152 { 153 "access_token":"2YotnFZFEjr1zCsicMWpAA", 154 "token_type":"example", 155 "expires_in":3600, 156 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 157 "reciprocal":"example_scope", 158 "example_parameter":"example_value" 159 } 161 If an authorization code grant access token response per [RFC6749] 162 4.2.2, an example successful response (with extra line breaks for 163 display purposes only): 165 HTTP/1.1 302 Found 166 Location: http://example.com/cb# 167 access_token=2YotnFZFEjr1zCsicMWpAA& 168 state=xyz& 169 token_type=example& 170 expires_in=3600& 171 reciprocal="example_scope" 173 When party B is providing an authorization response per [RFC6749] 174 4.1.2, party B MAY include an additional query component in the 175 redirection URI to indicate the scope requested in the reciprocal 176 grant. 178 reciprocal OPTIONAL. The scope of party B's reciprocal access 179 request per [RFC6749] 3.3. 181 If party B does not provide a reciprocal parameter in the 182 authorization response, the reciprocal scope will be a value 183 previously preconfigured by party A and party B. 185 2.2. Reciprocal Authorization Flow 187 The reciprocal authorization flow starts after the client (party A) 188 has obtained an access token from the authorization server (party B) 189 per [RFC6749] 4.1 Authorization Code Grant. 191 2.2.1. User Consent 193 Party A obtains consent from the user to grant Party B access to 194 protected resources at party A. The consent represents the scopes 195 requested by party B from party A per Section 2.1. 197 2.2.2. Reciprocal Authorization Code 199 Party A generates an authorization code representing the access 200 granted to party B by the user. Party A then makes a request to 201 party B's token endpoint authenticating per [RFC6749] 2.3 and sending 202 the following parameters using the "application/x-www-form- 203 urlencoded" format per [RFC6749] Appendix B with a character encoding 204 of UTF-8 in the HTTP request entity-body: 206 grant_type REQUIRED 207 Value MUST be set to "urn:ietf:params:oauth:grant-type:reciprocal". 209 code REQUIRED 210 the authorization code generated by party A. 212 client_id REQUIRED 213 party A'a client ID. 215 access_token REQUIRED the access token obtained from Party B. Used 216 by Party B to identify which user authorization is being requested. 218 For example, the client makes the following HTTP request using TLS 219 (with extra line breaks for display purposes only): 221 POST /token HTTP/1.1 222 Host: server.example.com 223 Authorization: Basic ej4hsyfishwssjdusisdhkjsdksusdhjkjsdjk 224 Content-Type: application/x-www-form-urlencoded 226 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3reciprocal 227 &code=hasdyubasdjahsbdkjbasd 228 &client_id=example.com 229 &access_token=sadadojsadlkjasdkljxxlkjdas 231 Party B MUST verify the authentication provided by Party A per 232 [RFC6749] 2.3 234 Party B MUST then verify the access token was granted to the client 235 identified by the client_id. 237 Party B MUST respond with either an HTTP 200 (OK) response if the 238 request is valid, or an HTTP 400 "Bad Request" if it is not. 240 Party B then plays the role of the client to make an access token 241 request per [RFC6749] 4.1.3. 243 3. Authorization Update Flow 245 After the initial authorization, the user may add or remove scopes 246 available to the client at the authorization server. For example, 247 the user may grant additional scopes to the client using a voice 248 interface, or revoke some scopes. The authorization server can 249 update the client with the new authorization by sending a new 250 authorization code per Section 2.2.2. 252 4. IANA Considerations 254 TBD. 256 5. Acknowledgements 258 TBD. 260 6. Normative References 262 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 263 Requirement Levels", BCP 14, RFC 2119, 264 DOI 10.17487/RFC2119, March 1997, 265 . 267 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 268 RFC 6749, DOI 10.17487/RFC6749, October 2012, 269 . 271 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 272 Framework: Bearer Token Usage", RFC 6750, 273 DOI 10.17487/RFC6750, October 2012, 274 . 276 Appendix A. Document History 278 A.1. draft-ietf-oauth-reciprical-00 280 o Initial version. 282 A.2. draft-ietf-oauth-reciprical-01 284 o Changed reciprocal scope request to be in access token response 285 rather than authorization request 287 A.3. draft-ietf-oauth-reciprical-02 289 o Added in diagram to clarify protocol flow 291 Author's Address 293 Dick Hardt 295 Email: dick.hardt@gmail.com