idnits 2.17.1 draft-ietf-oauth-incremental-authz-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 : ---------------------------------------------------------------------------- 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, 2019) is 1792 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, 2019 5 Expires: November 4, 2019 7 OAuth 2.0 Incremental Authorization 8 draft-ietf-oauth-incremental-authz-02 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, 2019. 37 Copyright Notice 39 Copyright (c) 2019 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 7. Alternative Approaches . . . . . . . . . . . . . . . . . . . 5 62 7.1. Alternative for Public Clients . . . . . . . . . . . . . 5 63 7.2. Alternative for Confidential Clients . . . . . . . . . . 5 64 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 5 65 8.1. Requesting Authorization In Context . . . . . . . . . . . 5 66 8.2. Preventing Overbroad Authorization Requests . . . . . . . 6 67 8.3. Authorization Correlation . . . . . . . . . . . . . . . . 6 68 9. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 6 69 10. Security Considerations . . . . . . . . . . . . . . . . . . . 7 70 10.1. Public Client Impersonation . . . . . . . . . . . . . . 7 71 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 72 11.1. OAuth Parameters Registry . . . . . . . . . . . . . . . 7 73 11.2. OAuth 2.0 Authorization Server Metadata . . . . . . . . 8 74 12. Normative References . . . . . . . . . . . . . . . . . . . . 8 75 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 76 Appendix B. Document History . . . . . . . . . . . . . . . . . . 9 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 79 1. Introduction 81 OAuth 2.0 clients may offer multiple features that require user 82 authorization, but commonly not every user will use each feature. 83 Without incremental authentication, applications need to either 84 request all the possible scopes they need upfront, potentially 85 resulting in a bad user experience, or track each authorization grant 86 separately, complicating development. 88 The goal of incremental authorization is to allow clients to request 89 just the scopes they need, when they need them, while allowing them 90 to store a single authorization grant for the user that contains the 91 sum of the scopes granted. Thus, each new authorization request 92 increments the scope of the authorization grant, without the client 93 needing to track a separate authorization grant for each group of 94 scopes. 96 2. Notational Conventions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in Key 101 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 102 these words are used without being spelled in uppercase then they are 103 to be interpreted with their normal natural language meanings. 105 3. Terminology 107 In addition to the terms defined in referenced specifications, this 108 document uses the following terms: 110 "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. 112 4. Incremental Auth for Confidential Clients 114 For confidential clients, such as web servers that can keep secrets, 115 the authorization endpoint SHOULD treat scopes that the user already 116 granted differently on the consent user interface. Typically such 117 scopes are hidden for new authorization requests, or at least there 118 is an indication that the user already approved them. 120 By itself, this property of the authorization endpoint enables 121 incremental authorization. The client can track every scope they've 122 ever requested, and include those scopes on every new authorization 123 request. 125 To avoid the need for confidential clients to re-request already 126 authorized scopes, authorization servers MAY support an additional 127 "include_granted_scopes" parameter in the authorization request. 128 This parameter, enables the client to request tokens during the 129 authorization grant exchange that represent the full scope of the 130 user's grant to the application including any previous grants, 131 without the app needing to track the scopes directly. 133 The client indicates they wish the new authorization grant to include 134 previously granted scopes by sending the following additional 135 parameter in the OAuth 2.0 Authorization Request (Section 4.1.1 of 136 [RFC6749].) using the following additional parameter: 138 include_granted_scopes OPTIONAL. Either "true" or "false". When 139 "true", the authorization server SHOULD include previously granted 140 scopes for this client in the new authorization grant. 142 5. Incremental Auth for Public Clients 144 Unlike with confidential clients, it is NOT RECOMMEND to 145 automatically approve OAuth requests for public clients without user 146 consent (see Section 10.2 of OAuth 2.0 [RFC6749], and Section 8.6 of 147 OAuth 2.0 [RFC8252]), thus authorization grants shouldn't contain 148 previously authorized scopes in the manner described above for 149 confidential clients. 151 Public clients (and confidential clients using this technique) should 152 instead track the scopes for every authorization grant, and only 153 request yet to be granted scopes during incremental authorization. 154 In the past, this would result in multiple discrete authorization 155 grants that would need to be tracked. To enable incrementing a 156 single authorization grant for public clients, the client supplies 157 their existing refresh token during the authorization code exchange, 158 and receives new authorization tokens with the scope of the previous 159 and current authorization grants. 161 The client sends the previous refresh token in the OAuth 2.0 Access 162 Token Request (Section 4.1.3 of [RFC6749].) using the following 163 additional parameter: 165 existing_grant OPTIONAL. The refresh token from the existing 166 authorization grant. 168 When processing the token exchange, in addition to the normal 169 processing of such a request, the token endpoint MUST verify that 170 token provided in the "existing_grant" parameter is unexpired and 171 unrevoked, and was issued to the same client id and relates to the 172 same user as the current authorization grant. If this verification 173 succeeds, the new access and refresh tokens issued in the Access 174 Token Response (Section 4.1.4 of ) MUST include authorization for the 175 scopes in the previous grant, unless the authorization server is 176 exercising its prerogative to "fully or partially ignore the scope 177 requested by the client" per Section 3.3 of OAuth 2.0 [RFC6749]. 179 6. Usability Considerations 181 6.1. Handling Denials 183 A core principle of OAuth is that users may deny authorization 184 requests for any reason. This remains true for incremental 185 authorization requests. In the case of incremental authorization, 186 clients may already have a valid authorization and receive a denial 187 for an incremental authorization request (that is, an "access_denied" 188 error code as defined in Section 4.1.2.1 of OAuth 2.0 [RFC6749]). 189 Clients should SHOULD handle such errors gracefully and not discard 190 any existing authorization grants if the user denies an incremental 191 authorization request. Clients SHOULD NOT immediately request the 192 same incremental authorization again, as this may result in an 193 infinite denial loop (and the end-user feeling badgered). 195 7. Alternative Approaches 197 7.1. Alternative for Public Clients 199 It is possible for OAuth clients to maintain multiple authorizations 200 per user for feature-specific scopes without needing the feature 201 documented in this specification. For example, an app could maintain 202 an authorization for the contacts and one for calendar, and store 203 them separately. 205 This specification offers a convenience that a single authorization 206 grant can be managed that represents all the scope granted so far, 207 rather than needing to maintain multiple, however it does require 208 that all grants are made from a single end-user account (as 209 authorization servers cannot typically combine grants from multiple 210 users). Apps where users may wish to authorize separate end-user 211 accounts for different features should consider using the alternative 212 documented above. 214 7.2. Alternative for Confidential Clients 216 An alternative incremental auth design for confidential clients is to 217 ask for authorization scopes as they are needed and keep a running 218 record of all granted scopes. In this way each incremental 219 authorization request would include all scopes granted so far, plus 220 the new scope needed. Authorization servers can see the existing 221 scopes and only display the new scopes for approval (and likely to 222 inform the user of the existing grants). This approach can be 223 performed using RFC 6749 without additions, but requires the client 224 to keep track of every authorization grant. 226 Confidential clients can also use the alternative documented for 227 public clients in Section 7.1. 229 8. Privacy Considerations 231 8.1. Requesting Authorization In Context 233 The goal of incremental authorization is to enhance end-user privacy 234 by allowing clients to request only the authorization scopes needed 235 in the context of a particular user action, rather than asking for 236 ever possible scope upfront. For example, an app may offer calendar 237 and contacts integration, and an extension of OAuth like OpenID 238 Connect for sign-in. Such an app should first sign the user in with 239 just the scopes needed for that. If later the user interacts with 240 the calendar or contacts features then, and only then, should the 241 requires scopes be requested. By using this specification, apps can 242 improve the privacy choices of end-users by only requesting the 243 scopes they need in context. 245 Clients authorizing the user with an authorization server that 246 supports incremental auth SHOULD ask for the minimal authorization 247 scope for the user's current context, and use this specification to 248 add authorization scope as required. 250 8.2. Preventing Overbroad Authorization Requests 252 When this specification is implemented, clients should have no 253 technical reason to make overbroad authorization requests (i.e. 254 requesting every possible scope, even ones they don't immediately 255 need). It is therefore RECOMMENDED for authorization servers to 256 limit the authorization scope that can be requested in a single 257 authorization to what would reasonably be needed by a single feature. 259 8.3. Authorization Correlation 261 Incremental authorization is designed for use-cases where it's the 262 same user authorizing each request, and thus all incremental 263 authorization grants are correlated to that one user (by being merged 264 into a single authorization grant). For applications where users may 265 wish to connect different user accounts for different features (e.g. 266 contacts from one account, and calendar from another) it is 267 RECOMMENDED to instead allow multiple unrelated authorizations, as 268 documented in Section 7.1. 270 The goal of this specification is to improve end-user privacy by 271 giving them more choice over which scopes they grant access to. 272 Previously many apps would request an overly large number of scopes 273 upfront (typically for all the features of the app, rather than the 274 subset that the user is currently wishing to use). The scopes in 275 such authorization grants are necessarily correlated with the same 276 user as they are contained in a single authorization grant. 277 Implementing this specification doesn't change that attribute, but it 278 does improve user privacy overall by empowering the user to grant 279 access in a more granular way. 281 9. Discovery Metadata 283 Support for the incremental authorization MAY be declared in the 284 OAuth 2.0 Authorization Server Metadata [RFC8414] with the following 285 metadata: 287 incremental_authz_types_supported 288 OPTIONAL. JSON array of OAuth 2.0 client types that are supported 289 for incremental authorization. The possible types, defined by 290 Section 2.1 of RFC6749, are "public", "confidential". 292 10. Security Considerations 294 10.1. Public Client Impersonation 296 As documented in Section 8.6 of RFC 8252 [RFC8252], some public 297 clients are susceptible to client impersonation, depending on the 298 type of redirect URI used. If the "include_granted_scopes" feature 299 documented in Section 4 is used by an impersonating client, it may 300 receive a greater authorization grant than the user specifically 301 approved for that client. For this reason, the 302 "include_granted_scopes" feature MUST NOT be enabled for such public 303 client requests. 305 Note that there is no such restriction on the use of "existing_grant" 306 feature documented in Section 5. While it is designed for public 307 clients, it MAY be supported for all client types. 309 11. IANA Considerations 311 This specification makes a registration request as follows: 313 11.1. OAuth Parameters Registry 315 This specification registers the following parameters in the IANA 316 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 318 o Parameter name: include_granted_scopes 320 o Parameter usage location: authorization request 322 o Change controller: IESG 324 o Specification document(s): this document 326 o Parameter name: existing_grant 328 o Parameter usage location: token request 330 o Change controller: IESG 332 o Specification document(s): this document 334 11.2. OAuth 2.0 Authorization Server Metadata 336 This specification registers the following values in the IANA "OAuth 337 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 338 established by [RFC8414]. 340 o Metadata Name: incremental_authz_types_supported 341 o Metadata Description: JSON array containing a list of client types 342 that support OAuth 2.0 Incremental Authorization [[ this 343 specification ]]. The possible types, defined by Section 2.1 of 344 RFC6749, are "public", "confidential". 345 o Change controller: IESG 346 o Specification Document: Section 9 of [[ this specification ]] 348 12. Normative References 350 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 351 Requirement Levels", BCP 14, RFC 2119, 352 DOI 10.17487/RFC2119, March 1997, 353 . 355 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 356 RFC 6749, DOI 10.17487/RFC6749, October 2012, 357 . 359 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 360 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 361 . 363 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 364 Authorization Server Metadata", RFC 8414, 365 DOI 10.17487/RFC8414, June 2018, 366 . 368 [IANA.OAuth.Parameters] 369 IANA, "OAuth Parameters", 370 . 372 Appendix A. Acknowledgements 374 This document was produced in the OAuth working group under the 375 chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with 376 Benjamin Kaduk, and Eric Rescorla serving as Security Area Directors. 378 The following individuals contributed ideas, feedback, and wording 379 that shaped and formed the final specification: 381 Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, and Breno 382 de Medeiros. 384 Appendix B. Document History 386 [[ to be removed by the RFC Editor before publication as an RFC ]] 388 01 390 o Changed a SHOULD to a MUST in Section 5 regarding the protocol 391 behavior of incremental auth for public clients, while clarifying 392 that the authorization server retains the prerogative to do 393 whatever it wants. 395 o Defined an OAuth Metadata entry. 397 00 399 o Now a working group draft. 401 draft-wdenniss-oauth-incremental-auth-01 403 o Added usability, privacy, and security considerations. 405 o Documented alternative approaches. 407 draft-wdenniss-oauth-incremental-auth-00 409 o Initial draft based on the implementation of incremental and 410 "appcremental" auth at Google. 412 Author's Address 414 William Denniss 415 Google 416 1600 Amphitheatre Pkwy 417 Mountain View, CA 94043 418 USA 420 Email: wdenniss@google.com 421 URI: https://wdenniss.com/incremental-auth