idnits 2.17.1 draft-parecki-oauth-client-intermediary-metadata-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 a Security Considerations section. ** 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 (August 29, 2019) is 1695 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: 5 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 August 29, 2019 5 Expires: March 1, 2020 7 OAuth 2.0 Client Intermediary Metadata 8 draft-parecki-oauth-client-intermediary-metadata-00 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 March 1, 2020. 35 Copyright Notice 37 Copyright (c) 2019 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, an OAuth client is acting on behalf of 53 one or more intermediary or user-facing applications, and is not the 54 entity that the user has an established relationship with. In the 55 traditional OAuth model, a client_id represents only one application, 56 and so the consent screen lists just one third party: the OAuth 57 client. In these cases, it is not appropriate to list only the 58 actual OAuth client or only the user-facing application. Listing 59 only the actual OAuth client would be confusing to the user, since 60 the user does not have a relationship with this entity. Listing only 61 the user-facing application would be inaccurate and misrepresent the 62 situation, since the user would be unaware that their data is 63 actually being handled by additional parties. 65 This specification extends [RFC7591] and [RFC7592] to define a 66 mechanism for including information about the additional parties 67 involved in an OAuth transaction by including information about the 68 additional intermediaries as well as the user-facing application into 69 the Dynamic Client Registration request. This specification also 70 defines requirements of the OAuth authorization server to present 71 this information about the additional parties in the OAuth consent 72 screen during an OAuth transaction. 74 2. Notational Conventions 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 78 "OPTIONAL" in this document are to be interpreted as described in 79 [RFC2119]. 81 Unless otherwise noted, all the protocol parameter names and values 82 are case sensitive. 84 3. Terminology 86 In addition to the terms defined in referenced specifications, this 87 document uses the following terms: 89 "OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749]. 91 "End User Application (EUA)": The software that the end user 92 interacts with and has a relationship with, which is not the same 93 as the OAuth client interacting with the Resource Server. 95 "Intermediary": One or more entities that the user's data will pass 96 through or be shared with by using the OAuth client. This 97 information is voluntarily provided by the OAuth client, and is 98 typically enforced by a business relationship between the 99 organization providing the Client and the organization providing 100 the Resource Server. 102 "Client": "Client" has the same definition as in OAuth 2.0, but is 103 worth pointing out explicitly here that the client in this case is 104 requesting and obtaining permission from the user to access their 105 resources while acting on behalf of the End User Application. 107 4. End User Application and Intermediary Metadata 109 Registered end user applications, as well as intermediaries, have a 110 set of metadata values associated with the client identifier of the 111 client that represents them in the OAuth transaction, such as a user- 112 visible name, logo, and URL. 114 Like the OAuth client metadata defined in [RFC7591] and [RFC7592], 115 these metadata values are used in the following ways: 117 o as input values to registration and update requests, and 119 o as output values in registration responses. 121 These values are used by the authorization server when displaying the 122 OAuth consent screen to the end user, to inform them of all the 123 additional parties that will be handling the user's data upon 124 approval. 126 The following metadata fields are defined by this specification. The 127 implementation and use of the fields is OPTIONAL unless stated 128 otherwise. All data member types (strings, arrays, numbers) are 129 defined in terms of their JSON ([RFC7159]) representations. 131 Some fields are expected to be displayed in the OAuth consent UI and 132 are designated accordingly. 134 "name" 136 REQUIRED. A human-readable name of the end user application or 137 intermediary. Authorization servers MUST display this field to the 138 end user on the OAuth consent screen. 140 "description" 142 REQUIRED. A human-readable description of the end user application 143 or intermediary. This is not intended to be displayed in the OAuth 144 consent screen. 146 "uri" 148 A URL string of a web page providing information about the end user 149 application or intermediary. If present, the authorization server 150 SHOULD display this URL to the end user in a clickable fashion. It 151 is RECOMMENDED that clients always send this field. The value of 152 this field MUST point to a valid web page. 154 "logo_uri" 156 A URL string that references a logo for this end user application or 157 intermediary. If present, the authorization server SHOULD display 158 this image to the end user in the OAuth consent screen. The value of 159 this field MUST be a valid image file. 161 "contacts" 163 Array of strings representing ways to contact people responsible for 164 this end user application or intermediary, typically email addresses 165 or phone numbers. The authorization server MAY display these to the 166 end user in the OAuth consent screen. See Section 6 of [RFC7591] for 167 information on Privacy Considerations. 169 5. Client Registration Endpoint 171 The client registration endpoint is described in Section 3 of 172 [RFC7591]. 174 Since this specification provides a mechanism for a client to assert 175 user information about additional parties other than itself, the 176 registration endpoint MUST be protected by an OAuth 2.0 access token 177 obtained by the client. The method by which the initial access token 178 is obtained by the client or developer is out of scope of this 179 specification, but is likely to be obtained using the client 180 credentials grant. 182 5.1. Client Registration Request 184 This specification extends the client registration request defined in 185 [RFC7591]. 187 This operation registers a combination of client, end user 188 application, and optionally one or more intermediaries with an 189 authorization server. The authorization server assigns a unique 190 client identifier (and optionally a client secret) that represents 191 the combination of all the entities described in the registration 192 request. 194 To register, the client or developer sends an HTTP POST as described 195 in Section 3.1 of [RFC7591], with an additional property named 196 "end_user_application" containing a JSON object with the end user 197 application registration information, and optionally a property named 198 "intermediaries" with a JSON array of objects of each intermediary's 199 registration information. 201 For example, the client could send the following registration request 202 to the client registration endpoint using its OAuth 2.0 access token 203 it has previously obtained using the client credentials grant. 205 The following is a non-normative example request: 207 POST /register HTTP/1.1 208 Content-Type: application/json 209 Accept: application/json 210 Host: server.example.com 211 Authorization: Bearer 8IGFGXKXZBV5LL38Y3X1 213 { 214 "client_name": "My Example Client", 215 "redirect_uris": [ 216 "https://client.example.org/callback" 217 ], 218 "logo_uri": "https://client.example.org/logo.png", 219 "end_user_application": { 220 "name": "User-Recognizable App Name", 221 "description": "This application is what the user 222 is interacting with in their browser", 223 "uri": "https://example.net/", 224 "logo_uri": "https://example.net/logo.png", 225 "contacts": [ 226 "support@example.net" 227 ] 228 }, 229 "intermediaries": [ 230 { 231 "name": "Partner App Name", 232 "description": "An application that may also receive 233 this user's data when the user authorizes the client", 234 "uri": "https://partner.example/", 235 "logo_uri": "https://partner.example/logo.png", 236 "contacts": [ 237 "support@partner.example" 238 ] 239 } 240 ] 241 } 243 5.2. Client Registration Response 245 This specification extends the client information response defined in 246 [RFC7591] and [RFC7592]. 248 Upon a successful registration request, the authorization server 249 returns a client identifier for the combination of the client, end 250 user application, and any intermediaries specified in the request. 252 In addition to the response fields defined in Section 3.2 of 253 [RFC7591] and Section 3 of [RFC7592], the response MUST also contain 254 all registered metadata about the end user application and any 255 intermediaries. The authorization server MAY reject or replace any 256 of the requested metadata values submitted during the registration 257 and substitute them with suitable values. 259 The following is a non-normative example response of a successful 260 registration: 262 HTTP/1.1 201 Created 263 Content-Type: application/json 264 Cache-Control: no-store 265 Pragma: no-cache 267 { 268 "client_id": "V8tvEkZWhDAdxSaKGUJZ", 269 "client_secret": "SpsuwZIxnp8bBEhp5sk1EKiIKTZ4X4DKU", 270 "grant_types": ["authorization_code", "refresh_token"], 271 "token_endpoint_auth_method": "client_secret_basic", 272 "registration_client_uri": "https://server.example.com/client/tmzaAMkyWlH3", 273 "registration_access_token": "MphaAqDaZT86C93ENWRZcf3dfU2dW6POASo8dFXa", 274 "client_name": "My Example Client", 275 "redirect_uris": [ 276 "https://client.example.org/callback" 277 ], 278 "logo_uri": "https://client.example.org/logo.png", 279 "end_user_application": { 280 "name": "User-Recognizable App Name", 281 "description": "This application is what the user is interacting 282 with in their browser", 283 "uri": "https://example.net/", 284 "logo_uri": "https://example.net/logo.png", 285 "contacts": [ 286 "support@example.net" 287 ] 288 }, 289 "intermediaries": [ 290 { 291 "name": "Partner App Name", 292 "description": "An application that may also receive 293 this user's data when the user authorizes the client", 294 "uri": "https://partner.example/", 295 "logo_uri": "https://partner.example/logo.png", 296 "contacts": [ 297 "support@partner.example" 298 ] 299 } 300 ] 301 } 303 The "registration_client_uri" and "registration_access_token" 304 properties are required in order to support updating and deleting 305 this client as described in [RFC7592]. 307 5.3. Client Read Request 309 This specification extends the client read request defined in 310 [RFC7592] to include the additional metadata properties in the 311 response that describe the end user application and intermediaries. 312 No additional behavior is prescribed by this specification. 314 5.4. Client Update Request 316 This specification extends the client update request defined in 317 [RFC7592] to be able to update the additional metadata properties 318 that describe the end user application and intermediaries. 320 The additional properties are provided in the update request in the 321 same format as in the initial registration request. 323 Since these values were asserted by the client in the initial 324 registration, there is no need to prescribe any additional security 325 model around the ability to update them, even though these represent 326 additional parties. 328 5.5. Client Delete Request 330 No new behavior is prescribed for delete requests beyond that defined 331 in [RFC7592]. 333 6. Providing End-User Application Details in the Authorization Request 335 When the authorization server begins a request from an OAuth client 336 identifier that has been registered with additional end user 337 application or intermediary information, it MUST display the 338 additional parties in the consent UI visible to the end user. 340 The authorization server MAY choose to emphasize or make the end user 341 application information the primary information displayed in the 342 consent screen. This is because the end user application is likely 343 the most recognizable entity to the end user, and the end user may 344 not be aware that it is actually a different organization's OAuth 345 client that is the one making requests for the user's data. 347 The authorization server chooses how best to display the additional 348 information, but it MUST include at least the name of the end user 349 application, intermediaries, and client, and SHOULD include the logo 350 of each as well. 352 Once an access token has been issued to this client, the client uses 353 the access token to make requests at the resource server on behalf of 354 the specific end user application on behalf of the end user. 356 7. Acknowledgements 358 The authors would like to thank Ryan Christiansen and Preston 359 McFarland for their initial contributions of the concepts behind this 360 specification. The authors would also like to thank the OAuth 361 Working Group for their work on the referenced and related 362 specifications that this specification builds upon. 364 8. Normative References 366 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 367 Requirement Levels", BCP 14, RFC 2119, 368 DOI 10.17487/RFC2119, March 1997, 369 . 371 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 372 RFC 6749, DOI 10.17487/RFC6749, October 2012, 373 . 375 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 376 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 377 2014, . 379 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 380 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 381 RFC 7591, DOI 10.17487/RFC7591, July 2015, 382 . 384 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 385 "OAuth 2.0 Dynamic Client Registration Management 386 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 387 . 389 Author's Address 391 Aaron Parecki 392 Okta 394 Email: aaron@parecki.com 395 URI: https://aaronparecki.com