Google

1600 Amphitheatre Pkwy Mountain View CA 94043 USA wdenniss@google.com http://wdenniss.com/incremental-auth

Security OAuth Working Group 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.

OAuth 2.0 clients may offer multiple features that requiring 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. The goal of incremental authorization is to allow clients to request just the scopes they need, when they need them, while allowing them to store a single authorization grant for the user that contains the sum of the scopes granted. Thus, each new authorization request increments the scope of the authorization grant, without the client needing to track a separate authorization grant for each group of scopes.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels . If these words are used without being spelled in uppercase then they are to be interpreted with their normal natural language meanings.

In addition to the terms defined in referenced specifications, this document uses the following terms: In this document, OAuth refers to OAuth 2.0.

For confidential clients, such as web servers that can keep secrets, the authorization endpoint SHOULD treat scopes that the user already granted differently on the consent user interface. Typically such scopes are hidden for new authorization requests, or at least there is an indication that the user already approved them. By itself, this property of the authorization endpoint enables 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. 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 .) using the following additional parameter: OPTIONAL. Either "true" or "false". When "true", the authorization server SHOULD include previously granted scopes for this client in the new authorization grant.

Unlike with confidential clients, it is NOT RECOMMEND to automatically approve OAuth requests for public clients without user consent (see Section 10.2 of OAuth 2.0), thus authorization grants shouldn't contain previously authorized scopes in the manner described above for confidential clients. Public clients (and confidential clients using this technique) should instead track the scopes for every authorization grant, and only request yet to be granted scopes during incremental authorization. In the past, this would result in multiple discrete authorization grants that would need to be tracked. To enable incrementing a single authorization grant for public clients, the client supplies their existing refresh token during the authorization code exchange, and receives new authorization tokens with the scope of the previous and current authorization grants. The client sends the previous refresh token in the OAuth 2.0 Access Token Request (Section 4.1.3 of .) using the following additional parameter: OPTIONAL. The refresh token from the existing authorization grant. When processing the token exchange, in addition to the normal processing of such a request, the token endpoint MUST verify that token provided in the "existing_grant" parameter is unexpired and unrevoked, and was issued to the same client id and relates to the same user as the current authorization grant. If this verification succeeds, the new refresh token issued in the Access Token Response (Section 4.1.4 of ) SHOULD include authorization for the scopes in the previous grant.

This specification makes a registration request as follows:

This specification registers the following parameters in the IANA OAuth Parameters registry defined in OAuth 2.0. Parameter name: include_granted_scopes Parameter usage location: authorization request Change controller: IESG Specification document(s): this document Parameter name: existing_grant Parameter usage location: token request Change controller: IESG Specification document(s): this document

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.

[[ to be removed by the RFC Editor before publication as an RFC ]] -00 Initial draft based on the implementation of incremental and "appcremental" auth at Google.