idnits 2.17.1 draft-parecki-oauth-client-intermediary-metadata-03.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.) ** There are 2 instances of too long lines in the document, the longest one being 10 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 date (February 22, 2021) is 1159 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) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Downref: Normative reference to an Experimental RFC: RFC 7592 Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Open Authentication Protocol A. Parecki 3 Internet-Draft Okta 4 Intended status: Standards Track February 22, 2021 5 Expires: August 26, 2021 7 OAuth 2.0 Client Intermediary Metadata 8 draft-parecki-oauth-client-intermediary-metadata-03 10 Abstract 12 This specification defines a mechanism for including information 13 about additional parties involved in an OAuth transaction by adding a 14 new section to the OAuth 2.0 Dynamic Client Registration request, as 15 well as requires that authorization servers surface this information 16 to users during an OAuth transaction. 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 https://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 August 26, 2021. 35 Copyright Notice 37 Copyright (c) 2021 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 (https://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 1. Introduction 52 In some applications of OAuth, there may be multiple legal entities 53 which have access to or process data retrieved by an OAuth client. 54 In the traditional OAuth model, a "client_id" represents only a 55 single application, and so the OAuth consent screen lists just one 56 third party: the OAuth client. 58 In this situation, in order to comply with various local laws and 59 regulations, the user needs to be informed by the authorization 60 server of the list of entities that will have access to their data 61 after authorizing the client. 63 The existing Dynamic Client Registration ([RFC7591]) specification 64 lacks a mechanism for communicating a list of additional parties that 65 may have access to the user's data. 67 This specification extends [RFC7591] and [RFC7592] to define a 68 mechanism for including information about the additional parties 69 involved in an OAuth transaction by including information about the 70 additional intermediaries into the Dynamic Client Registration 71 request. This specification also defines requirements of the OAuth 72 authorization server to present this information about the additional 73 parties in the OAuth consent screen during an OAuth transaction. 75 2. Notational Conventions 77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 79 "OPTIONAL" in this document are to be interpreted as described in 80 [RFC2119]. 82 Unless otherwise noted, all the protocol parameter names and values 83 are case sensitive. 85 3. Terminology 87 In addition to the terms defined in referenced specifications, this 88 document uses the following terms: 90 "OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749]. 92 "Client": "Client" has the same definition as in OAuth 2.0, but is 93 worth pointing out that the client in this context may be operated 94 by a different legal entity than is described by the client name. 96 "Intermediary": One or more entities that the user's data will pass 97 through or be shared with by using the OAuth client. This 98 information is voluntarily provided by the OAuth client, and is 99 typically enforced by a business relationship between the 100 organization providing the Client and the organization providing 101 the Resource Server. 103 4. Client Intermediary Metadata 105 Registered client intermediaries have a set of metadata values 106 associated with the client identifier of the client that represents 107 them in the OAuth transaction, such as a user-visible name, logo, and 108 URL. 110 Like the OAuth client metadata defined in [RFC7591] and [RFC7592], 111 these metadata values are used in the following ways: 113 o as input values to registration and update requests, and 115 o as output values in registration responses. 117 These values are used by the authorization server when displaying the 118 OAuth consent screen to the end user, to inform them of all the 119 additional parties that will be handling the user's data upon 120 approval. 122 The following metadata fields are defined by this specification. The 123 implementation and use of the fields is OPTIONAL unless stated 124 otherwise. All data member types (strings, arrays, numbers) are 125 defined in terms of their JSON ([RFC7159]) representations. 127 Some fields are expected to be displayed in the OAuth consent UI and 128 are designated accordingly. 130 "name" 132 REQUIRED. A human-readable name of intermediary party. 133 Authorization servers MUST display this field to the end user on the 134 OAuth consent screen. 136 "description" 138 OPTIONAL. A human-readable description of the intermediary. This is 139 not intended to be displayed in the OAuth consent screen. 141 "uri" 143 A URL string of a web page providing information about the 144 intermediary. If present, the authorization server SHOULD display 145 this URL to the end user in a clickable fashion. It is RECOMMENDED 146 that clients always send this field. The value of this field MUST 147 point to a valid web page. 149 "logo_uri" 151 A URL string that references a logo for this intermediary. If 152 present, the authorization server SHOULD display this image to the 153 end user in the OAuth consent screen. The value of this field MUST 154 be a valid image file. 156 "contacts" 158 Array of strings representing ways to contact people responsible for 159 this intermediary, typically email addresses or phone numbers. The 160 authorization server MAY display these to the end user in the OAuth 161 consent screen. See Section 6 of [RFC7591] for information on 162 Privacy Considerations. 164 5. Client Registration Endpoint 166 The client registration endpoint is described in Section 3 of 167 [RFC7591]. 169 Since this specification provides a mechanism for a client to assert 170 information about additional parties other than itself, the 171 registration endpoint MUST be protected by an OAuth 2.0 access token 172 obtained by the client. The method by which the initial access token 173 is obtained by the client or developer is out of scope of this 174 specification, but is likely to be obtained using the client 175 credentials grant or manual out-of-band registration. 177 5.1. Client Registration Request 179 This specification extends the client registration request defined in 180 [RFC7591]. 182 This operation registers a combination of client and one or more 183 intermediaries with an authorization server. The authorization 184 server assigns a unique client identifier (and optionally a client 185 secret) that represents the combination of all the entities described 186 in the registration request. 188 To register, the client or developer sends an HTTP POST as described 189 in Section 3.1 of [RFC7591], with an additional property named 190 "intermediaries" with a JSON array of objects of each intermediary's 191 registration information. The properties of the object are described 192 above in Section 4. 194 For example, the client could send the following registration request 195 to the client registration endpoint using its OAuth 2.0 access token 196 it has previously obtained using the client credentials grant. 198 The following is a non-normative example request: 200 POST /register HTTP/1.1 201 Content-Type: application/json 202 Accept: application/json 203 Host: server.example.com 204 Authorization: Bearer 8IGFGXKXZBV5LL38Y3X1 206 { 207 "client_name": "User-Recognizable App Name", 208 "redirect_uris": [ 209 "https://client.example.org/callback" 210 ], 211 "client_uri": "https://example.net/", 212 "logo_uri": "https://example.net/logo.png", 213 "contacts": [ 214 "support@example.net" 215 ], 216 "intermediaries": [ 217 { 218 "name": "Partner App Name", 219 "description": "An application that may also receive 220 this user's data when the user authorizes the client", 221 "uri": "https://partner.example/", 222 "logo_uri": "https://partner.example/logo.png", 223 "contacts": [ 224 "support@partner.example" 225 ] 226 } 227 ] 228 } 230 5.2. Client Registration Response 232 This specification extends the client information response defined in 233 [RFC7591] and [RFC7592]. 235 Upon a successful registration request, the authorization server 236 returns a client identifier for the combination of the client and any 237 intermediaries specified in the request. 239 In addition to the response fields defined in Section 3.2 of 240 [RFC7591] and Section 3 of [RFC7592], the response MUST also contain 241 all registered metadata about the intermediaries. The authorization 242 server MAY reject or replace any of the requested metadata values 243 submitted during the registration and substitute them with suitable 244 values. 246 The following is a non-normative example response of a successful 247 registration: 249 HTTP/1.1 201 Created 250 Content-Type: application/json 251 Cache-Control: no-store 252 Pragma: no-cache 254 { 255 "client_id": "V8tvEkZWhDAdxSaKGUJZ", 256 "client_secret": "SpsuwZIxnp8bBEhp5sk1EKiIKTZ4X4DKU", 257 "grant_types": ["authorization_code", "refresh_token"], 258 "token_endpoint_auth_method": "client_secret_basic", 259 "registration_client_uri": "https://server.example.com/client/tmzaAMkyWlH3", 260 "registration_access_token": "MphaAqDaZT86C93ENWRZcf3dfU2dW6POASo8dFXa", 261 "client_name": "User-Recognizable App Name", 262 "client_uri": "https://example.net/", 263 "redirect_uris": [ 264 "https://client.example.org/callback" 265 ], 266 "contacts": [ 267 "support@example.net" 268 ], 269 "intermediaries": [ 270 { 271 "name": "Partner App Name", 272 "description": "An application that may also receive 273 this user's data when the user authorizes the client", 274 "uri": "https://partner.example/", 275 "logo_uri": "https://partner.example/logo.png", 276 "contacts": [ 277 "support@partner.example" 278 ] 279 } 280 ] 281 } 283 The "registration_client_uri" and "registration_access_token" 284 properties are required in order to support updating and deleting 285 this client as described in [RFC7592]. 287 5.3. Client Read Request 289 This specification extends the client read request defined in 290 [RFC7592] to include the additional metadata properties in the 291 response that describe the intermediaries. No additional behavior is 292 prescribed by this specification. 294 5.4. Client Update Request 296 This specification extends the client update request defined in 297 [RFC7592] to be able to update the additional metadata properties 298 that describe the intermediaries. 300 The additional properties are provided in the update request in the 301 same format as in the initial registration request. 303 Since these values were asserted by the client in the initial 304 registration, there is no need to prescribe any additional security 305 model around the ability to update them, even though these represent 306 additional parties. 308 5.5. Client Delete Request 310 No new behavior is prescribed for delete requests beyond that defined 311 in [RFC7592]. 313 6. Providing Intermediaty Details in the Authorization Request 315 When the authorization server begins a request from an OAuth client 316 identifier that has been registered with additional intermediary 317 information, it MUST display the additional parties in the consent UI 318 visible to the end user. 320 The authorization server chooses how best to display the additional 321 information, but it MUST include at least the name of the 322 intermediaries and client, and SHOULD include the logo of each as 323 well. 325 7. Security Considerations 327 As this extends [RFC7591], all security considerations from that 328 draft apply here as well. 330 Specifically, if the authorization server supports open client 331 registration without any authentication, it must be extremely careful 332 with any URLs received in the registration request such as 333 "logo_uri", "tos_uri", and "uri", as these values may be displayed to 334 end users. [RFC7591] recommends requiring that these URIs have a 335 matching host and scheme as the defined "redirect_uri"s, and that 336 they are resolvable URIs. See section 5 of [RFC7591] for more 337 details. 339 8. Acknowledgements 341 The author would like to thank Ryan Christiansen and Preston 342 McFarland for their initial contributions of the concepts behind this 343 specification. The author would also like to thank Don Cardinal, 344 Ryan Christiansen and Preston McFarland for their reviews of this 345 specification, as well as Anil Mahalaha and other members of the 346 Financial Data Exchange working group. Additionally the work of the 347 OAuth Working Group on the referenced and related specifications that 348 this specification builds upon is much appreciated. 350 9. Normative References 352 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 353 Requirement Levels", BCP 14, RFC 2119, 354 DOI 10.17487/RFC2119, March 1997, 355 . 357 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 358 RFC 6749, DOI 10.17487/RFC6749, October 2012, 359 . 361 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 362 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 363 2014, . 365 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 366 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 367 RFC 7591, DOI 10.17487/RFC7591, July 2015, 368 . 370 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 371 "OAuth 2.0 Dynamic Client Registration Management 372 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 373 . 375 Author's Address 377 Aaron Parecki 378 Okta 380 Email: aaron@parecki.com 381 URI: https://aaronparecki.com