idnits 2.17.1 draft-ietf-oauth-incremental-authz-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 3, 2020) is 1426 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group W. Denniss 3 Internet-Draft Google 4 Intended status: Standards Track May 3, 2020 5 Expires: November 4, 2020 7 OAuth 2.0 Incremental Authorization 8 draft-ietf-oauth-incremental-authz-04 10 Abstract 12 OAuth 2.0 authorization requests that include every scope the client 13 might ever need can result in over-scoped authorization and a sub- 14 optimal end-user consent experience. This specification enhances the 15 OAuth 2.0 authorization protocol by adding incremental authorization, 16 the ability to request specific authorization scopes as needed, when 17 they're needed, removing the requirement to request every possible 18 scope that might be needed upfront. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on November 4, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 4. Incremental Auth for Confidential Clients . . . . . . . . . . 3 58 5. Incremental Auth for Public Clients . . . . . . . . . . . . . 4 59 6. Usability Considerations . . . . . . . . . . . . . . . . . . 4 60 6.1. Handling Denials . . . . . . . . . . . . . . . . . . . . 4 61 6.2. Handling Scope Reductions . . . . . . . . . . . . . . . . 5 62 7. Alternative Approaches . . . . . . . . . . . . . . . . . . . 5 63 7.1. Alternative for Public Clients . . . . . . . . . . . . . 6 64 7.2. Alternative for Confidential Clients . . . . . . . . . . 6 65 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6 66 8.1. Requesting Authorization In Context . . . . . . . . . . . 6 67 8.2. Preventing Overbroad Authorization Requests . . . . . . . 7 68 8.3. Authorization Correlation . . . . . . . . . . . . . . . . 7 69 8.4. Previously Granted Scopes . . . . . . . . . . . . . . . . 8 70 9. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 8 71 10. Security Considerations . . . . . . . . . . . . . . . . . . . 8 72 10.1. Public Client Impersonation . . . . . . . . . . . . . . 8 73 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 74 11.1. OAuth Parameters Registry . . . . . . . . . . . . . . . 9 75 11.2. OAuth Extensions Error Registration . . . . . . . . . . 9 76 11.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . 9 77 12. Normative References . . . . . . . . . . . . . . . . . . . . 10 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 80 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 82 1. Introduction 84 OAuth 2.0 clients may offer multiple features that require user 85 authorization, but commonly not every user will use each feature. 86 Without incremental authentication, applications need to either 87 request all the possible scopes they need upfront, potentially 88 resulting in a bad user experience, or track each authorization grant 89 separately, complicating development. 91 The goal of incremental authorization is to allow clients to request 92 just the scopes they need, when they need them, while allowing them 93 to store a single authorization grant for the user that contains the 94 sum of the scopes granted. Thus, each new authorization request 95 increments the scope of the authorization grant, without the client 96 needing to track a separate authorization grant for each group of 97 scopes. 99 2. Notational Conventions 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 103 "OPTIONAL" in this document are to be interpreted as described in Key 104 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 105 these words are used without being spelled in uppercase then they are 106 to be interpreted with their normal natural language meanings. 108 3. Terminology 110 In addition to the terms defined in referenced specifications, this 111 document uses the following terms: 113 "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. 115 4. Incremental Auth for Confidential Clients 117 For confidential clients, such as web servers that can keep secrets, 118 the authorization endpoint SHOULD treat scopes that the user already 119 granted differently on the consent user interface. Typically such 120 scopes are hidden for new authorization requests, or at least there 121 is an indication that the user already approved them. 123 By itself, this property of the authorization endpoint enables 124 incremental authorization. The client can track every scope they've 125 ever requested, and include those scopes on every new authorization 126 request. 128 To avoid the need for confidential clients to re-request already 129 authorized scopes, authorization servers MAY support an additional 130 "include_granted_scopes" parameter in the authorization request. 131 This parameter, enables the client to request tokens during the 132 authorization grant exchange that represent the full scope of the 133 user's grant to the application including any previous grants, 134 without the client needing to track the scopes directly. 136 The client indicates they wish the new authorization grant to include 137 previously granted scopes by sending the following additional 138 parameter in the OAuth 2.0 Authorization Request (Section 4.1.1 of 139 [RFC6749].) using the following additional parameter: 141 include_granted_scopes OPTIONAL. Either "true" or "false". When 142 "true", the authorization server SHOULD include previously granted 143 scopes for this client in the new authorization grant. 145 5. Incremental Auth for Public Clients 147 Unlike with confidential clients, it is NOT RECOMMEND to 148 automatically approve OAuth requests for public clients without user 149 consent (see Section 10.2 of OAuth 2.0 [RFC6749], and Section 8.6 of 150 OAuth 2.0 [RFC8252]), thus authorization grants shouldn't contain 151 previously authorized scopes in the manner described above for 152 confidential clients. 154 Public clients (and confidential clients using this technique) should 155 instead track the scopes for every authorization grant, and only 156 request yet to be granted scopes during incremental authorization. 157 In the past, this would result in multiple discrete authorization 158 grants that would need to be tracked. To enable incrementing a 159 single authorization grant for public clients, the client supplies 160 their existing refresh token during the authorization code exchange, 161 and receives new authorization tokens with the scope of the previous 162 and current authorization grants. 164 The client sends the previous refresh token in the OAuth 2.0 Access 165 Token Request (Section 4.1.3 of [RFC6749].) using the following 166 additional parameter: 168 existing_grant OPTIONAL. The refresh token from the existing 169 authorization grant. 171 When processing the token exchange, in addition to the normal 172 processing of such a request, the token endpoint MUST verify that 173 token provided in the "existing_grant" parameter is unexpired and 174 unrevoked, and was issued to the same client id and relates to the 175 same user as the current authorization grant. If this verification 176 succeeds, the new access and refresh tokens issued in the Access 177 Token Response (Section 4.1.4 of ) MUST include authorization for the 178 scopes in the previous grant, unless the authorization server is 179 exercising its prerogative to "fully or partially ignore the scope 180 requested by the client" per Section 3.3 of OAuth 2.0 [RFC6749]. 182 6. Usability Considerations 184 6.1. Handling Denials 186 A core principle of OAuth is that users may deny authorization 187 requests for any reason. This remains true for incremental 188 authorization requests. In the case of incremental authorization, 189 clients may already have a valid authorization and receive a denial 190 for an incremental authorization request (that is, an "access_denied" 191 error code as defined in Section 4.1.2.1 of OAuth 2.0 [RFC6749]). 192 Clients should SHOULD handle such errors gracefully and not discard 193 any existing authorization grants if the user denies an incremental 194 authorization request. Clients SHOULD NOT immediately request the 195 same incremental authorization again, as this may result in an 196 infinite denial loop (and the end-user feeling badgered). 198 6.2. Handling Scope Reductions 200 As specified by Section 5.1 of OAuth 2.0 [RFC6749], a successful 201 response may not always include all the scope that was asked for, a 202 fact indicated by the "scope" response parameter when it happens. 203 This is still true in the case of incremental auth. The success 204 response may include less scope than what was requested, or even less 205 scope than before the incremental authorization request (say, if the 206 user was given an opportunity to revise the grant down). Clients 207 MUST check for the "scope" parameter in success responses and react 208 accordingly. 210 For the purposes of an incremental auth request, a success response 211 to an incremental authorization request that contains the same scope 212 granted prior to the request being made, and an error response (for 213 example, in the case of a denial) can have the same effect: the 214 client retains a grant with the same scope as before. In the case of 215 the approved request but with the same scope, they have a new grant, 216 but with the same scope. In the case of the denied incremental 217 authorization request, they still have the old grant with the same 218 scope (although in some cases it may have been revoked or reduced in 219 scope out of band). 221 An incremental authorization request isn't the only time that scope 222 can be reduced for a grant. As specified by section 6 of OAuth 2.0 223 [RFC6749], scope can be reduced during a token refresh as well. So 224 it's a good practice for clients to retain the current scope of the 225 grant, update it during authorization, incremental authorization and 226 token refreshes, and take action at any time based on the current 227 scope by presenting an incremental authorization if a non-present 228 scope is needed. 230 7. Alternative Approaches 232 This non-normative section discusses some alternative ways to achieve 233 the incremental authorization result purely on the client side. 234 These options are somewhat more complex and burdensome to client 235 developers. 237 7.1. Alternative for Public Clients 239 It is possible for OAuth clients to maintain multiple authorizations 240 per user for feature-specific scopes without needing the feature 241 documented in this specification. For example, a public client (such 242 as a mobile app) could maintain an authorization for the contacts and 243 one for calendar, and store them separately. 245 This specification offers a convenience that a single authorization 246 grant can be managed that represents all the scope granted so far, 247 rather than needing to maintain multiple, however it does require 248 that all grants are made from a single end-user account (as 249 authorization servers cannot typically combine grants from multiple 250 users). Clients where users may wish to authorize separate end-user 251 accounts for different features should consider using the alternative 252 documented in this section. 254 7.2. Alternative for Confidential Clients 256 An alternative incremental auth design for confidential clients is to 257 ask for authorization scopes as they are needed and keep a running 258 record of all granted scopes. In this way each incremental 259 authorization request would include all scopes granted so far, plus 260 the new scope needed. Authorization servers can see the existing 261 scopes and only display the new scopes for approval (and likely to 262 inform the user of the existing grants). This approach can be 263 performed using RFC 6749 without additions, but requires the client 264 to keep track of every authorization grant. 266 Confidential clients can also use the alternative documented for 267 public clients in Section 7.1. 269 8. Privacy Considerations 271 8.1. Requesting Authorization In Context 273 The goal of incremental authorization is to enhance end-user privacy 274 by allowing clients to request only the authorization scopes needed 275 in the context of a particular user action, rather than asking for 276 ever possible scope upfront. For example, an app may offer calendar 277 and contacts integration, and an extension of OAuth like OpenID 278 Connect for sign-in. Such an app should first sign the user in with 279 just the scopes needed for that. If later the user interacts with 280 the calendar or contacts features then, and only then, should the 281 requires scopes be requested. By using this specification, apps can 282 improve the privacy choices of end-users by only requesting the 283 scopes they need in context. 285 Clients authorizing the user with an authorization server that 286 supports incremental auth SHOULD ask for the minimal authorization 287 scope for the user's current context, and use this specification to 288 add authorization scope as required. 290 8.2. Preventing Overbroad Authorization Requests 292 When this specification is implemented, clients should have no 293 technical reason to make overbroad authorization requests (i.e. 294 requesting every possible scope they might ever expect need, rather 295 than ones related to the user's current activity). To improve 296 privacy, it is therefore RECOMMENDED for authorization servers to 297 limit the authorization scope that can be requested in a single 298 authorization to what would reasonably be needed by a single feature. 299 The authorization server MAY deny such authorization requests with 300 the following error code. 302 overbroad_scope 303 The scope of the request is considered overbroad by the 304 authorization server. Consult the documentation of your 305 authorization server to determine acceptable scope combinations, 306 and consider using [[ This Specification ]] to perform incremental 307 authorization requests in the context that the scope is needed. 309 Determining what constitutes an overbroad request is the purview of 310 the authorization server. As an example, say an authorization 311 supported "calendar" and "mail" scopes to access a user's calendar 312 and inbox respectively. They may decide that their users should have 313 the chance to grant such requests in context through incremental 314 authorization, rather then all at once upfront, and deny the request 315 for being overly broad. 317 8.3. Authorization Correlation 319 Incremental authorization is designed for use-cases where it's the 320 same user authorizing each request, and thus all incremental 321 authorization grants are correlated to that one user (by being merged 322 into a single authorization grant). For applications where users may 323 wish to connect different user accounts for different features (e.g. 324 contacts from one account, and calendar from another) it is 325 RECOMMENDED to instead allow multiple unrelated authorizations, as 326 documented in Section 7.1. 328 The goal of this specification is to improve end-user privacy by 329 giving them more choice over which scopes they grant access to. 330 Previously many apps would request an overly large number of scopes 331 upfront (typically for all the features of the app, rather than the 332 subset that the user is currently wishing to use). The scopes in 333 such authorization grants are necessarily correlated with the same 334 user as they are contained in a single authorization grant. 335 Implementing this specification doesn't change that attribute, but it 336 does improve user privacy overall by empowering the user to grant 337 access in a more granular way. 339 8.4. Previously Granted Scopes 341 When the authorization server displays the list of scopes on page and 342 prompts the user to consent to sharing access, users may assume that 343 the displayed list of scopes on such a page is the full and complete 344 list being granted to the application. It may be desirable for such 345 a consent page to list previously granted scopes, provided that the 346 client is confidential, or one that cannot be impersonated. 348 9. Discovery Metadata 350 Support for the incremental authorization MAY be declared in the 351 OAuth 2.0 Authorization Server Metadata [RFC8414] with the following 352 metadata: 354 incremental_authz_types_supported 355 OPTIONAL. JSON array of OAuth 2.0 client types that are supported 356 for incremental authorization. The possible types are 357 "confidential", and "public". 359 Specifically, "confidential" indicates that the behavior documented 360 in Section 4 (Incremental Auth for Confidential Clients) is 361 supported, and "public" indicates that the behavior documented in 362 Section 5 (Incremental Auth for Public Clients) is supported. 364 A server which supports both forms of incremental auth documented in 365 this specification would declare support like so: 367 "incremental_authz_types_supported": ["confidential", "public"] 369 10. Security Considerations 371 10.1. Public Client Impersonation 373 As documented in Section 8.6 of RFC 8252 [RFC8252], some public 374 clients are susceptible to client impersonation, depending on the 375 type of redirect URI used. If the "include_granted_scopes" feature 376 documented in Section 4 is used by an impersonating client, it may 377 receive a greater authorization grant than the user specifically 378 approved for that client. For this reason, the 379 "include_granted_scopes" feature MUST NOT be enabled for such public 380 client requests. 382 Note that there is no such restriction on the use of "existing_grant" 383 feature documented in Section 5. While it is designed for public 384 clients, it MAY be supported for all client types. 386 11. IANA Considerations 388 This specification makes a registration request as follows: 390 11.1. OAuth Parameters Registry 392 This specification registers the following parameters in the IANA 393 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 395 o Parameter name: include_granted_scopes 397 o Parameter usage location: authorization request 399 o Change controller: IESG 401 o Specification document(s): this document 403 o Parameter name: existing_grant 405 o Parameter usage location: token request 407 o Change controller: IESG 409 o Specification document(s): this document 411 11.2. OAuth Extensions Error Registration 413 This specification registers the following values in the IANA "OAuth 414 Extensions Error Registry" registry [IANA.OAuth.Parameters] 415 established by [RFC6749]. 417 Name: overbroad_scope 418 Usage Location: authorization code grant error response 419 Protocol Extension: [[ This Specification ]] 420 Change Controller: IETF 421 Reference: Section 8.2 of [[ This Specification ]] 423 11.3. OAuth 2.0 Authorization Server Metadata 425 This specification registers the following values in the IANA "OAuth 426 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 427 established by [RFC8414]. 429 o Metadata Name: incremental_authz_types_supported 430 o Metadata Description: JSON array containing a list of client types 431 that support OAuth 2.0 Incremental Authorization [[ this 432 specification ]]. The possible types are "confidential", and 433 "public". 434 o Change controller: IESG 435 o Specification Document: Section 9 of [[ this specification ]] 437 12. Normative References 439 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 440 Requirement Levels", BCP 14, RFC 2119, 441 DOI 10.17487/RFC2119, March 1997, 442 . 444 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 445 RFC 6749, DOI 10.17487/RFC6749, October 2012, 446 . 448 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 449 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 450 . 452 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 453 Authorization Server Metadata", RFC 8414, 454 DOI 10.17487/RFC8414, June 2018, 455 . 457 [IANA.OAuth.Parameters] 458 IANA, "OAuth Parameters", 459 . 461 Appendix A. Acknowledgements 463 This document was produced in the OAuth working group under the 464 chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with 465 Benjamin Kaduk, and Eric Rescorla serving as Security Area Directors. 467 The following individuals contributed ideas, feedback, and wording 468 that shaped and formed the final specification: 470 Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, Breno de 471 Medeiros, Naveen Agarwal, Brian Campbell, and Aaron Parecki. 473 Appendix B. Document History 475 [[ to be removed by the RFC Editor before publication as an RFC ]] 477 01 478 o Changed a SHOULD to a MUST in Section 5 regarding the protocol 479 behavior of incremental auth for public clients, while clarifying 480 that the authorization server retains the prerogative to do 481 whatever it wants. 483 o Defined an OAuth Metadata entry. 485 00 487 o Now a working group draft. 489 draft-wdenniss-oauth-incremental-auth-01 491 o Added usability, privacy, and security considerations. 493 o Documented alternative approaches. 495 draft-wdenniss-oauth-incremental-auth-00 497 o Initial draft based on the implementation of incremental and 498 "appcremental" auth at Google. 500 Author's Address 502 William Denniss 503 Google 504 1600 Amphitheatre Pkwy 505 Mountain View, CA 94043 506 USA 508 Email: wdenniss@google.com 509 URI: https://wdenniss.com/incremental-auth