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