idnits 2.17.1 draft-ietf-oauth-reciprocal-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 a Security Considerations section. ** There is 1 instance of too long lines in the document, the longest one being 83 characters in excess of 72. 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 (October 19, 2018) is 2015 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 203, but no explicit reference was found in the text 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 Amazon 4 Intended status: Standards Track October 19, 2018 5 Expires: April 22, 2019 7 Reciprocal OAuth 8 draft-ietf-oauth-reciprocal-01 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 April 22, 2019. 36 Copyright Notice 38 Copyright (c) 2018 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. Reciprocal Scope Request 82 When party B is providing an access token response per [RFC6749] 83 4.1.4, 4.2.1, 4.3.3 or 4.4.3, party B MAY include an additional query 84 component in the redirection URI to indicate the scope requested in 85 the reciprocal grant. 87 reciprocal OPTIONAL. The scope of party B's reciprocal access 88 request per [RFC6749] 3.3. 90 If party B does not provide a reciprocal parameter in the access 91 token response, the reciprocal scope will be a value previously 92 preconfigured by party A and party B. 94 If an authorization code grant access token response per [RFC6749] 95 4.1.4, an example successful response: 97 HTTP/1.1 200 OK 98 Content-Type: application/json;charset=UTF-8 99 Cache-Control: no-store 100 Pragma: no-cache 102 { 103 "access_token":"2YotnFZFEjr1zCsicMWpAA", 104 "token_type":"example", 105 "expires_in":3600, 106 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 107 "reciprocal":"example_scope", 108 "example_parameter":"example_value" 109 } 111 If an authorization code grant access token response per [RFC6749] 112 4.2.2, an example successful response (with extra line breaks for 113 display purposes only): 115 HTTP/1.1 302 Found 116 Location: http://example.com/cb# 117 access_token=2YotnFZFEjr1zCsicMWpAA& 118 state=xyz&token_type=example& 119 expires_in=3600& 120 reciprocal="example_scope" 122 3. Reciprocal Authorization Flow 124 The reciprocal authorization flow starts after the client (party A) 125 has obtained an access token from the authorization server (party B) 126 per [RFC6749] 4.1 Authorization Code Grant. 128 3.1. User Consent 130 Party A obtains consent from the user to grant Party B access to 131 protected resources at party A. The consent represents the scopes 132 party B had preconfigured at party A. 134 3.2. Reciprocal Authorization Code 136 Party A generates an authorization code representing the access 137 granted to party B by the user. Party A then makes a request to 138 party B's token endpoint authenticating per [RFC6749] 2.3 and sending 139 the following parameters using the "application/x-www-form- 140 urlencoded" format per [RFC6749] Appendix B with a character encoding 141 of UTF-8 in the HTTP request entity-body: 143 grant_type REQUIRED. Value MUST be set to 144 "urn:ietf:params:oauth:grant-type:reciprocal". 146 code REQUIRED. The authorization code generated by party A. 148 client_id REQUIRED, party A'a client ID. 150 access_token REQUIRED, the access token obtained from Party B. Used 151 to provide user context. 153 For example, the client makes the following HTTP request using TLS 154 (with extra line breaks for display purposes only): 156 POST /token HTTP/1.1 157 Host: server.example.com 158 Authorization: Basic ej4hsyfishwssjdusisdhkjsdksusdhjkjsdjk 159 Content-Type: application/x-www-form-urlencoded 161 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3reciprocal&code=hasdyubasdjahsbdkjbasd&client_id=example.com&access_token=sadadojsadlkjasdkljxxlkjdas 163 Party B MUST verify the authentication provided by Party A per 164 [RFC6749] 2.3 166 Party B MUST then verify the access token was granted to the client 167 identified by the client_id. 169 Party B MUST respond with either an HTTP 200 (OK) response if the 170 request is valid, or an HTTP 400 "Bad Request" if it is not. 172 Party B then plays the role of the client to make an access token 173 request per [RFC6749] 4.1.3. 175 4. Authorization Update Flow 177 After the initial authorization, the user may add or remove scopes 178 available to the client at the authorization server. For example, 179 the user may grant additional scopes to the client using a voice 180 interface, or revoke some scopes. The authorization server can 181 update the client with the new authorization by sending a new 182 authorization code per 3.2. 184 5. IANA Considerations 186 TBD. 188 6. Acknowledgements 190 TBD. 192 7. Normative References 194 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 195 Requirement Levels", BCP 14, RFC 2119, 196 DOI 10.17487/RFC2119, March 1997, 197 . 199 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 200 RFC 6749, DOI 10.17487/RFC6749, October 2012, 201 . 203 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 204 Framework: Bearer Token Usage", RFC 6750, 205 DOI 10.17487/RFC6750, October 2012, 206 . 208 Appendix A. Document History 210 A.1. draft-ietf-oauth-reciprical-00 212 o Initial version. 214 A.2. draft-ietf-oauth-reciprical-01 216 o changed reciprocal scope request to be in access token response 217 rather than authorization request 219 Author's Address 221 Dick Hardt 222 Amazon 224 Email: dick.hardt@gmail.com