[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-wdenniss-incremental-auth) 00 01

OAuth Working Group                                           W. Denniss
Internet-Draft                                                    Google
Intended status: Standards Track                            July 3, 2017
Expires: January 4, 2018

                  OAuth 2.0 Incremental Authorization


   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.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   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 http://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 January 4, 2018.

Copyright Notice

   Copyright (c) 2017 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
   (http://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

Denniss                  Expires January 4, 2018                [Page 1]

Internet-Draft         OAuth 2.0 Incremental Auth              July 2017

   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   2
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   2
   4.  Incremental Auth for Confidential Clients . . . . . . . . . .   3
   5.  Incremental Auth for Public Clients . . . . . . . . . . . . .   3
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   4
     6.1.  OAuth Parameters Registry . . . . . . . . . . . . . . . .   4
   7.  Normative References  . . . . . . . . . . . . . . . . . . . .   5
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .   5
   Appendix B.  Document History . . . . . . . . . . . . . . . . . .   5
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   5

1.  Introduction

   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

2.  Notational Conventions

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

3.  Terminology

   In addition to the terms defined in referenced specifications, this
   document uses the following terms:

Denniss                  Expires January 4, 2018                [Page 2]

Internet-Draft         OAuth 2.0 Incremental Auth              July 2017

   "OAuth"  In this document, OAuth refers to OAuth 2.0 [RFC6749].

4.  Incremental Auth for Confidential Clients

   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

   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
   [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.

5.  Incremental Auth for Public Clients

   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 [RFC6749]), 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,

Denniss                  Expires January 4, 2018                [Page 3]

Internet-Draft         OAuth 2.0 Incremental Auth              July 2017

   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 [RFC6749].) using the following
   additional parameter:

   existing_grant  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.

6.  IANA Considerations

   This specification makes a registration request as follows:

6.1.  OAuth Parameters Registry

   This specification registers the following parameters in the IANA
   OAuth Parameters registry defined in OAuth 2.0 [RFC6749].

   o  Parameter name: include_granted_scopes

   o  Parameter usage location: authorization request

   o  Change controller: IESG

   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

Denniss                  Expires January 4, 2018                [Page 4]

Internet-Draft         OAuth 2.0 Incremental Auth              July 2017

7.  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,

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,

Appendix A.  Acknowledgements

   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.

Appendix B.  Document History

   [[ to be removed by the RFC Editor before publication as an RFC ]]


   o  Initial draft based on the implementation of incremental and
      "appcremental" auth at Google.

Author's Address

   William Denniss
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043

   Email: wdenniss@google.com
   URI:   http://wdenniss.com/incremental-auth

Denniss                  Expires January 4, 2018                [Page 5]

Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/