draft-ietf-oauth-incremental-authz-03.txt   draft-ietf-oauth-incremental-authz-04.txt 
OAuth Working Group W. Denniss OAuth Working Group W. Denniss
Internet-Draft Google Internet-Draft Google
Intended status: Standards Track November 4, 2019 Intended status: Standards Track May 3, 2020
Expires: May 7, 2020 Expires: November 4, 2020
OAuth 2.0 Incremental Authorization OAuth 2.0 Incremental Authorization
draft-ietf-oauth-incremental-authz-03 draft-ietf-oauth-incremental-authz-04
Abstract Abstract
OAuth 2.0 authorization requests that include every scope the client OAuth 2.0 authorization requests that include every scope the client
might ever need can result in over-scoped authorization and a sub- might ever need can result in over-scoped authorization and a sub-
optimal end-user consent experience. This specification enhances the optimal end-user consent experience. This specification enhances the
OAuth 2.0 authorization protocol by adding incremental authorization, OAuth 2.0 authorization protocol by adding incremental authorization,
the ability to request specific authorization scopes as needed, when the ability to request specific authorization scopes as needed, when
they're needed, removing the requirement to request every possible they're needed, removing the requirement to request every possible
scope that might be needed upfront. scope that might be needed upfront.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 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. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 16 skipping to change at page 2, line 16
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Incremental Auth for Confidential Clients . . . . . . . . . . 3 4. Incremental Auth for Confidential Clients . . . . . . . . . . 3
5. Incremental Auth for Public Clients . . . . . . . . . . . . . 4 5. Incremental Auth for Public Clients . . . . . . . . . . . . . 4
6. Usability Considerations . . . . . . . . . . . . . . . . . . 4 6. Usability Considerations . . . . . . . . . . . . . . . . . . 4
6.1. Handling Denials . . . . . . . . . . . . . . . . . . . . 4 6.1. Handling Denials . . . . . . . . . . . . . . . . . . . . 4
6.2. Handling Scope Reductions . . . . . . . . . . . . . . . . 5
7. Alternative Approaches . . . . . . . . . . . . . . . . . . . 5 7. Alternative Approaches . . . . . . . . . . . . . . . . . . . 5
7.1. Alternative for Public Clients . . . . . . . . . . . . . 5 7.1. Alternative for Public Clients . . . . . . . . . . . . . 6
7.2. Alternative for Confidential Clients . . . . . . . . . . 5 7.2. Alternative for Confidential Clients . . . . . . . . . . 6
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 5 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6
8.1. Requesting Authorization In Context . . . . . . . . . . . 5 8.1. Requesting Authorization In Context . . . . . . . . . . . 6
8.2. Preventing Overbroad Authorization Requests . . . . . . . 6 8.2. Preventing Overbroad Authorization Requests . . . . . . . 7
8.3. Authorization Correlation . . . . . . . . . . . . . . . . 6 8.3. Authorization Correlation . . . . . . . . . . . . . . . . 7
9. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 6 8.4. Previously Granted Scopes . . . . . . . . . . . . . . . . 8
10. Security Considerations . . . . . . . . . . . . . . . . . . . 7 9. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 8
10.1. Public Client Impersonation . . . . . . . . . . . . . . 7 10. Security Considerations . . . . . . . . . . . . . . . . . . . 8
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 10.1. Public Client Impersonation . . . . . . . . . . . . . . 8
11.1. OAuth Parameters Registry . . . . . . . . . . . . . . . 7 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
11.2. OAuth 2.0 Authorization Server Metadata . . . . . . . . 8 11.1. OAuth Parameters Registry . . . . . . . . . . . . . . . 9
12. Normative References . . . . . . . . . . . . . . . . . . . . 8 11.2. OAuth Extensions Error Registration . . . . . . . . . . 9
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 11.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . 9
Appendix B. Document History . . . . . . . . . . . . . . . . . . 9 12. Normative References . . . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
Appendix B. Document History . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
OAuth 2.0 clients may offer multiple features that require user OAuth 2.0 clients may offer multiple features that require user
authorization, but commonly not every user will use each feature. authorization, but commonly not every user will use each feature.
Without incremental authentication, applications need to either Without incremental authentication, applications need to either
request all the possible scopes they need upfront, potentially request all the possible scopes they need upfront, potentially
resulting in a bad user experience, or track each authorization grant resulting in a bad user experience, or track each authorization grant
separately, complicating development. separately, complicating development.
skipping to change at page 3, line 40 skipping to change at page 3, line 42
incremental authorization. The client can track every scope they've incremental authorization. The client can track every scope they've
ever requested, and include those scopes on every new authorization ever requested, and include those scopes on every new authorization
request. request.
To avoid the need for confidential clients to re-request already To avoid the need for confidential clients to re-request already
authorized scopes, authorization servers MAY support an additional authorized scopes, authorization servers MAY support an additional
"include_granted_scopes" parameter in the authorization request. "include_granted_scopes" parameter in the authorization request.
This parameter, enables the client to request tokens during the This parameter, enables the client to request tokens during the
authorization grant exchange that represent the full scope of the authorization grant exchange that represent the full scope of the
user's grant to the application including any previous grants, 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 The client indicates they wish the new authorization grant to include
previously granted scopes by sending the following additional previously granted scopes by sending the following additional
parameter in the OAuth 2.0 Authorization Request (Section 4.1.1 of parameter in the OAuth 2.0 Authorization Request (Section 4.1.1 of
[RFC6749].) using the following additional parameter: [RFC6749].) using the following additional parameter:
include_granted_scopes OPTIONAL. Either "true" or "false". When include_granted_scopes OPTIONAL. Either "true" or "false". When
"true", the authorization server SHOULD include previously granted "true", the authorization server SHOULD include previously granted
scopes for this client in the new authorization grant. scopes for this client in the new authorization grant.
skipping to change at page 5, line 9 skipping to change at page 5, line 9
authorization requests. In the case of incremental authorization, authorization requests. In the case of incremental authorization,
clients may already have a valid authorization and receive a denial clients may already have a valid authorization and receive a denial
for an incremental authorization request (that is, an "access_denied" 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]). 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 Clients should SHOULD handle such errors gracefully and not discard
any existing authorization grants if the user denies an incremental any existing authorization grants if the user denies an incremental
authorization request. Clients SHOULD NOT immediately request the authorization request. Clients SHOULD NOT immediately request the
same incremental authorization again, as this may result in an same incremental authorization again, as this may result in an
infinite denial loop (and the end-user feeling badgered). 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 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 7.1. Alternative for Public Clients
It is possible for OAuth clients to maintain multiple authorizations It is possible for OAuth clients to maintain multiple authorizations
per user for feature-specific scopes without needing the feature per user for feature-specific scopes without needing the feature
documented in this specification. For example, an app could maintain documented in this specification. For example, a public client (such
an authorization for the contacts and one for calendar, and store as a mobile app) could maintain an authorization for the contacts and
them separately. one for calendar, and store them separately.
This specification offers a convenience that a single authorization This specification offers a convenience that a single authorization
grant can be managed that represents all the scope granted so far, grant can be managed that represents all the scope granted so far,
rather than needing to maintain multiple, however it does require rather than needing to maintain multiple, however it does require
that all grants are made from a single end-user account (as that all grants are made from a single end-user account (as
authorization servers cannot typically combine grants from multiple 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 accounts for different features should consider using the alternative
documented above. documented in this section.
7.2. Alternative for Confidential Clients 7.2. Alternative for Confidential Clients
An alternative incremental auth design for confidential clients is to An alternative incremental auth design for confidential clients is to
ask for authorization scopes as they are needed and keep a running ask for authorization scopes as they are needed and keep a running
record of all granted scopes. In this way each incremental record of all granted scopes. In this way each incremental
authorization request would include all scopes granted so far, plus authorization request would include all scopes granted so far, plus
the new scope needed. Authorization servers can see the existing the new scope needed. Authorization servers can see the existing
scopes and only display the new scopes for approval (and likely to scopes and only display the new scopes for approval (and likely to
inform the user of the existing grants). This approach can be inform the user of the existing grants). This approach can be
skipping to change at page 6, line 20 skipping to change at page 7, line 14
Clients authorizing the user with an authorization server that Clients authorizing the user with an authorization server that
supports incremental auth SHOULD ask for the minimal authorization supports incremental auth SHOULD ask for the minimal authorization
scope for the user's current context, and use this specification to scope for the user's current context, and use this specification to
add authorization scope as required. add authorization scope as required.
8.2. Preventing Overbroad Authorization Requests 8.2. Preventing Overbroad Authorization Requests
When this specification is implemented, clients should have no When this specification is implemented, clients should have no
technical reason to make overbroad authorization requests (i.e. technical reason to make overbroad authorization requests (i.e.
requesting every possible scope, even ones they don't immediately requesting every possible scope they might ever expect need, rather
need). It is therefore RECOMMENDED for authorization servers to 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 limit the authorization scope that can be requested in a single
authorization to what would reasonably be needed by a single feature. 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 8.3. Authorization Correlation
Incremental authorization is designed for use-cases where it's the Incremental authorization is designed for use-cases where it's the
same user authorizing each request, and thus all incremental same user authorizing each request, and thus all incremental
authorization grants are correlated to that one user (by being merged authorization grants are correlated to that one user (by being merged
into a single authorization grant). For applications where users may into a single authorization grant). For applications where users may
wish to connect different user accounts for different features (e.g. wish to connect different user accounts for different features (e.g.
contacts from one account, and calendar from another) it is contacts from one account, and calendar from another) it is
RECOMMENDED to instead allow multiple unrelated authorizations, as RECOMMENDED to instead allow multiple unrelated authorizations, as
skipping to change at page 6, line 47 skipping to change at page 8, line 10
giving them more choice over which scopes they grant access to. giving them more choice over which scopes they grant access to.
Previously many apps would request an overly large number of scopes Previously many apps would request an overly large number of scopes
upfront (typically for all the features of the app, rather than the upfront (typically for all the features of the app, rather than the
subset that the user is currently wishing to use). The scopes in subset that the user is currently wishing to use). The scopes in
such authorization grants are necessarily correlated with the same such authorization grants are necessarily correlated with the same
user as they are contained in a single authorization grant. user as they are contained in a single authorization grant.
Implementing this specification doesn't change that attribute, but it Implementing this specification doesn't change that attribute, but it
does improve user privacy overall by empowering the user to grant does improve user privacy overall by empowering the user to grant
access in a more granular way. 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 9. Discovery Metadata
Support for the incremental authorization MAY be declared in the Support for the incremental authorization MAY be declared in the
OAuth 2.0 Authorization Server Metadata [RFC8414] with the following OAuth 2.0 Authorization Server Metadata [RFC8414] with the following
metadata: metadata:
incremental_authz_types_supported incremental_authz_types_supported
OPTIONAL. JSON array of OAuth 2.0 client types that are supported OPTIONAL. JSON array of OAuth 2.0 client types that are supported
for incremental authorization. The possible types, defined by for incremental authorization. The possible types are
Section 2.1 of RFC6749, are "public", "confidential". "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. Security Considerations
10.1. Public Client Impersonation 10.1. Public Client Impersonation
As documented in Section 8.6 of RFC 8252 [RFC8252], some public As documented in Section 8.6 of RFC 8252 [RFC8252], some public
clients are susceptible to client impersonation, depending on the clients are susceptible to client impersonation, depending on the
type of redirect URI used. If the "include_granted_scopes" feature type of redirect URI used. If the "include_granted_scopes" feature
documented in Section 4 is used by an impersonating client, it may documented in Section 4 is used by an impersonating client, it may
receive a greater authorization grant than the user specifically receive a greater authorization grant than the user specifically
skipping to change at page 8, line 5 skipping to change at page 9, line 34
o Specification document(s): this document o Specification document(s): this document
o Parameter name: existing_grant o Parameter name: existing_grant
o Parameter usage location: token request o Parameter usage location: token request
o Change controller: IESG o Change controller: IESG
o Specification document(s): this document 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 This specification registers the following values in the IANA "OAuth
2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters]
established by [RFC8414]. established by [RFC8414].
o Metadata Name: incremental_authz_types_supported o Metadata Name: incremental_authz_types_supported
o Metadata Description: JSON array containing a list of client types o Metadata Description: JSON array containing a list of client types
that support OAuth 2.0 Incremental Authorization [[ this that support OAuth 2.0 Incremental Authorization [[ this
specification ]]. The possible types, defined by Section 2.1 of specification ]]. The possible types are "confidential", and
RFC6749, are "public", "confidential". "public".
o Change controller: IESG o Change controller: IESG
o Specification Document: Section 9 of [[ this specification ]] o Specification Document: Section 9 of [[ this specification ]]
12. Normative References 12. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 9, line 5 skipping to change at page 10, line 44
Appendix A. Acknowledgements Appendix A. Acknowledgements
This document was produced in the OAuth working group under the This document was produced in the OAuth working group under the
chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig with
Benjamin Kaduk, and Eric Rescorla serving as Security Area Directors. Benjamin Kaduk, and Eric Rescorla serving as Security Area Directors.
The following individuals contributed ideas, feedback, and wording The following individuals contributed ideas, feedback, and wording
that shaped and formed the final specification: that shaped and formed the final specification:
Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, and Breno Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, Breno de
de Medeiros. Medeiros, Naveen Agarwal, Brian Campbell, and Aaron Parecki.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
01 01
o Changed a SHOULD to a MUST in Section 5 regarding the protocol o Changed a SHOULD to a MUST in Section 5 regarding the protocol
behavior of incremental auth for public clients, while clarifying behavior of incremental auth for public clients, while clarifying
that the authorization server retains the prerogative to do that the authorization server retains the prerogative to do
whatever it wants. whatever it wants.
o Defined an OAuth Metadata entry. o Defined an OAuth Metadata entry.
00 00
o Now a working group draft. o Now a working group draft.
 End of changes. 20 change blocks. 
37 lines changed or deleted 125 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/