--- 1/draft-ietf-oauth-incremental-authz-03.txt 2020-05-03 16:13:09.665301187 -0700 +++ 2/draft-ietf-oauth-incremental-authz-04.txt 2020-05-03 16:13:09.693301899 -0700 @@ -1,18 +1,18 @@ OAuth Working Group W. Denniss Internet-Draft Google -Intended status: Standards Track November 4, 2019 -Expires: May 7, 2020 +Intended status: Standards Track May 3, 2020 +Expires: November 4, 2020 OAuth 2.0 Incremental Authorization - draft-ietf-oauth-incremental-authz-03 + draft-ietf-oauth-incremental-authz-04 Abstract OAuth 2.0 authorization requests that include every scope the client might ever need can result in over-scoped authorization and a sub- optimal end-user consent experience. This specification enhances the OAuth 2.0 authorization protocol by adding incremental authorization, the ability to request specific authorization scopes as needed, when they're needed, removing the requirement to request every possible scope that might be needed upfront. @@ -25,25 +25,25 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on May 7, 2020. + This Internet-Draft will expire on November 4, 2020. Copyright Notice - Copyright (c) 2019 IETF Trust and the persons identified as the + Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as @@ -51,37 +51,40 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Incremental Auth for Confidential Clients . . . . . . . . . . 3 5. Incremental Auth for Public Clients . . . . . . . . . . . . . 4 6. Usability Considerations . . . . . . . . . . . . . . . . . . 4 6.1. Handling Denials . . . . . . . . . . . . . . . . . . . . 4 + 6.2. Handling Scope Reductions . . . . . . . . . . . . . . . . 5 7. Alternative Approaches . . . . . . . . . . . . . . . . . . . 5 - 7.1. Alternative for Public Clients . . . . . . . . . . . . . 5 - 7.2. Alternative for Confidential Clients . . . . . . . . . . 5 - 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 5 - 8.1. Requesting Authorization In Context . . . . . . . . . . . 5 - 8.2. Preventing Overbroad Authorization Requests . . . . . . . 6 - 8.3. Authorization Correlation . . . . . . . . . . . . . . . . 6 - 9. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 6 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 7 - 10.1. Public Client Impersonation . . . . . . . . . . . . . . 7 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 - 11.1. OAuth Parameters Registry . . . . . . . . . . . . . . . 7 - 11.2. OAuth 2.0 Authorization Server Metadata . . . . . . . . 8 - 12. Normative References . . . . . . . . . . . . . . . . . . . . 8 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 - Appendix B. Document History . . . . . . . . . . . . . . . . . . 9 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 + 7.1. Alternative for Public Clients . . . . . . . . . . . . . 6 + 7.2. Alternative for Confidential Clients . . . . . . . . . . 6 + 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6 + 8.1. Requesting Authorization In Context . . . . . . . . . . . 6 + 8.2. Preventing Overbroad Authorization Requests . . . . . . . 7 + 8.3. Authorization Correlation . . . . . . . . . . . . . . . . 7 + 8.4. Previously Granted Scopes . . . . . . . . . . . . . . . . 8 + 9. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 8 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 8 + 10.1. Public Client Impersonation . . . . . . . . . . . . . . 8 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 + 11.1. OAuth Parameters Registry . . . . . . . . . . . . . . . 9 + 11.2. OAuth Extensions Error Registration . . . . . . . . . . 9 + 11.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . 9 + 12. Normative References . . . . . . . . . . . . . . . . . . . . 10 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 + Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 1. Introduction OAuth 2.0 clients may offer multiple features that require user authorization, but commonly not every user will use each feature. Without incremental authentication, applications need to either request all the possible scopes they need upfront, potentially resulting in a bad user experience, or track each authorization grant separately, complicating development. @@ -121,21 +124,21 @@ incremental authorization. The client can track every scope they've ever requested, and include those scopes on every new authorization request. To avoid the need for confidential clients to re-request already authorized scopes, authorization servers MAY support an additional "include_granted_scopes" parameter in the authorization request. This parameter, enables the client to request tokens during the authorization grant exchange that represent the full scope of the user's grant to the application including any previous grants, - without the app needing to track the scopes directly. + without the client needing to track the scopes directly. The client indicates they wish the new authorization grant to include previously granted scopes by sending the following additional parameter in the OAuth 2.0 Authorization Request (Section 4.1.1 of [RFC6749].) using the following additional parameter: include_granted_scopes OPTIONAL. Either "true" or "false". When "true", the authorization server SHOULD include previously granted scopes for this client in the new authorization grant. @@ -185,38 +188,75 @@ authorization requests. In the case of incremental authorization, clients may already have a valid authorization and receive a denial for an incremental authorization request (that is, an "access_denied" error code as defined in Section 4.1.2.1 of OAuth 2.0 [RFC6749]). Clients should SHOULD handle such errors gracefully and not discard any existing authorization grants if the user denies an incremental authorization request. Clients SHOULD NOT immediately request the same incremental authorization again, as this may result in an infinite denial loop (and the end-user feeling badgered). +6.2. Handling Scope Reductions + + As specified by Section 5.1 of OAuth 2.0 [RFC6749], a successful + response may not always include all the scope that was asked for, a + fact indicated by the "scope" response parameter when it happens. + This is still true in the case of incremental auth. The success + response may include less scope than what was requested, or even less + scope than before the incremental authorization request (say, if the + user was given an opportunity to revise the grant down). Clients + MUST check for the "scope" parameter in success responses and react + accordingly. + + For the purposes of an incremental auth request, a success response + to an incremental authorization request that contains the same scope + granted prior to the request being made, and an error response (for + example, in the case of a denial) can have the same effect: the + client retains a grant with the same scope as before. In the case of + the approved request but with the same scope, they have a new grant, + but with the same scope. In the case of the denied incremental + authorization request, they still have the old grant with the same + scope (although in some cases it may have been revoked or reduced in + scope out of band). + + An incremental authorization request isn't the only time that scope + can be reduced for a grant. As specified by section 6 of OAuth 2.0 + [RFC6749], scope can be reduced during a token refresh as well. So + it's a good practice for clients to retain the current scope of the + grant, update it during authorization, incremental authorization and + token refreshes, and take action at any time based on the current + scope by presenting an incremental authorization if a non-present + scope is needed. + 7. Alternative Approaches + This non-normative section discusses some alternative ways to achieve + the incremental authorization result purely on the client side. + These options are somewhat more complex and burdensome to client + developers. + 7.1. Alternative for Public Clients It is possible for OAuth clients to maintain multiple authorizations per user for feature-specific scopes without needing the feature - documented in this specification. For example, an app could maintain - an authorization for the contacts and one for calendar, and store - them separately. + documented in this specification. For example, a public client (such + as a mobile app) could maintain an authorization for the contacts and + one for calendar, and store them separately. This specification offers a convenience that a single authorization grant can be managed that represents all the scope granted so far, rather than needing to maintain multiple, however it does require that all grants are made from a single end-user account (as authorization servers cannot typically combine grants from multiple - users). Apps where users may wish to authorize separate end-user + users). Clients where users may wish to authorize separate end-user accounts for different features should consider using the alternative - documented above. + documented in this section. 7.2. Alternative for Confidential Clients An alternative incremental auth design for confidential clients is to ask for authorization scopes as they are needed and keep a running record of all granted scopes. In this way each incremental authorization request would include all scopes granted so far, plus the new scope needed. Authorization servers can see the existing scopes and only display the new scopes for approval (and likely to inform the user of the existing grants). This approach can be @@ -244,24 +284,42 @@ Clients authorizing the user with an authorization server that supports incremental auth SHOULD ask for the minimal authorization scope for the user's current context, and use this specification to add authorization scope as required. 8.2. Preventing Overbroad Authorization Requests When this specification is implemented, clients should have no technical reason to make overbroad authorization requests (i.e. - requesting every possible scope, even ones they don't immediately - need). It is therefore RECOMMENDED for authorization servers to + requesting every possible scope they might ever expect need, rather + than ones related to the user's current activity). To improve + privacy, it is therefore RECOMMENDED for authorization servers to limit the authorization scope that can be requested in a single authorization to what would reasonably be needed by a single feature. + The authorization server MAY deny such authorization requests with + the following error code. + + overbroad_scope + The scope of the request is considered overbroad by the + authorization server. Consult the documentation of your + authorization server to determine acceptable scope combinations, + and consider using [[ This Specification ]] to perform incremental + authorization requests in the context that the scope is needed. + + Determining what constitutes an overbroad request is the purview of + the authorization server. As an example, say an authorization + supported "calendar" and "mail" scopes to access a user's calendar + and inbox respectively. They may decide that their users should have + the chance to grant such requests in context through incremental + authorization, rather then all at once upfront, and deny the request + for being overly broad. 8.3. Authorization Correlation Incremental authorization is designed for use-cases where it's the same user authorizing each request, and thus all incremental authorization grants are correlated to that one user (by being merged into a single authorization grant). For applications where users may wish to connect different user accounts for different features (e.g. contacts from one account, and calendar from another) it is RECOMMENDED to instead allow multiple unrelated authorizations, as @@ -271,30 +329,49 @@ giving them more choice over which scopes they grant access to. Previously many apps would request an overly large number of scopes upfront (typically for all the features of the app, rather than the subset that the user is currently wishing to use). The scopes in such authorization grants are necessarily correlated with the same user as they are contained in a single authorization grant. Implementing this specification doesn't change that attribute, but it does improve user privacy overall by empowering the user to grant access in a more granular way. +8.4. Previously Granted Scopes + + When the authorization server displays the list of scopes on page and + prompts the user to consent to sharing access, users may assume that + the displayed list of scopes on such a page is the full and complete + list being granted to the application. It may be desirable for such + a consent page to list previously granted scopes, provided that the + client is confidential, or one that cannot be impersonated. + 9. Discovery Metadata Support for the incremental authorization MAY be declared in the OAuth 2.0 Authorization Server Metadata [RFC8414] with the following metadata: incremental_authz_types_supported OPTIONAL. JSON array of OAuth 2.0 client types that are supported - for incremental authorization. The possible types, defined by - Section 2.1 of RFC6749, are "public", "confidential". + for incremental authorization. The possible types are + "confidential", and "public". + + Specifically, "confidential" indicates that the behavior documented + in Section 4 (Incremental Auth for Confidential Clients) is + supported, and "public" indicates that the behavior documented in + Section 5 (Incremental Auth for Public Clients) is supported. + + A server which supports both forms of incremental auth documented in + this specification would declare support like so: + + "incremental_authz_types_supported": ["confidential", "public"] 10. Security Considerations 10.1. Public Client Impersonation As documented in Section 8.6 of RFC 8252 [RFC8252], some public clients are susceptible to client impersonation, depending on the type of redirect URI used. If the "include_granted_scopes" feature documented in Section 4 is used by an impersonating client, it may receive a greater authorization grant than the user specifically @@ -324,31 +401,43 @@ o Specification document(s): this document o Parameter name: existing_grant o Parameter usage location: token request o Change controller: IESG o Specification document(s): this document -11.2. OAuth 2.0 Authorization Server Metadata +11.2. OAuth Extensions Error Registration + + This specification registers the following values in the IANA "OAuth + Extensions Error Registry" registry [IANA.OAuth.Parameters] + established by [RFC6749]. + + Name: overbroad_scope + Usage Location: authorization code grant error response + Protocol Extension: [[ This Specification ]] + Change Controller: IETF + Reference: Section 8.2 of [[ This Specification ]] + +11.3. OAuth 2.0 Authorization Server Metadata This specification registers the following values in the IANA "OAuth 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [RFC8414]. o Metadata Name: incremental_authz_types_supported o Metadata Description: JSON array containing a list of client types that support OAuth 2.0 Incremental Authorization [[ this - specification ]]. The possible types, defined by Section 2.1 of - RFC6749, are "public", "confidential". + specification ]]. The possible types are "confidential", and + "public". o Change controller: IESG o Specification Document: Section 9 of [[ this specification ]] 12. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . @@ -371,29 +460,28 @@ Appendix A. Acknowledgements This document was produced in the OAuth working group under the chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with Benjamin Kaduk, and Eric Rescorla serving as Security Area Directors. The following individuals contributed ideas, feedback, and wording that shaped and formed the final specification: - Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, and Breno - de Medeiros. + Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, Breno de + Medeiros, Naveen Agarwal, Brian Campbell, and Aaron Parecki. Appendix B. Document History [[ to be removed by the RFC Editor before publication as an RFC ]] 01 - o Changed a SHOULD to a MUST in Section 5 regarding the protocol behavior of incremental auth for public clients, while clarifying that the authorization server retains the prerogative to do whatever it wants. o Defined an OAuth Metadata entry. 00 o Now a working group draft.