idnits 2.17.1 draft-wdenniss-oauth-incremental-auth-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 3, 2017) is 2482 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: 1 error (**), 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 July 3, 2017 5 Expires: January 4, 2018 7 OAuth 2.0 Incremental Authorization 8 draft-wdenniss-oauth-incremental-auth-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 http://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 January 4, 2018. 37 Copyright Notice 39 Copyright (c) 2017 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 (http://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 . . . . . . . . . . . . . . . . . . . 2 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 57 4. Incremental Auth for Confidential Clients . . . . . . . . . . 3 58 5. Incremental Auth for Public Clients . . . . . . . . . . . . . 3 59 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 60 6.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 4 61 7. Normative References . . . . . . . . . . . . . . . . . . . . 5 62 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 5 63 Appendix B. Document History . . . . . . . . . . . . . . . . . . 5 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 66 1. Introduction 68 OAuth 2.0 clients may offer multiple features that requiring user 69 authorization, but commonly not every user will use each feature. 70 Without incremental authentication, applications need to either 71 request all the possible scopes they need upfront, potentially 72 resulting in a bad user experience, or track each authorization grant 73 separately, complicating development. 75 The goal of incremental authorization is to allow clients to request 76 just the scopes they need, when they need them, while allowing them 77 to store a single authorization grant for the user that contains the 78 sum of the scopes granted. Thus, each new authorization request 79 increments the scope of the authorization grant, without the client 80 needing to track a separate authorization grant for each group of 81 scopes. 83 2. Notational Conventions 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 87 "OPTIONAL" in this document are to be interpreted as described in Key 88 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 89 these words are used without being spelled in uppercase then they are 90 to be interpreted with their normal natural language meanings. 92 3. Terminology 94 In addition to the terms defined in referenced specifications, this 95 document uses the following terms: 97 "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. 99 4. Incremental Auth for Confidential Clients 101 For confidential clients, such as web servers that can keep secrets, 102 the authorization endpoint SHOULD treat scopes that the user already 103 granted differently on the consent user interface. Typically such 104 scopes are hidden for new authorization requests, or at least there 105 is an indication that the user already approved them. 107 By itself, this property of the authorization endpoint enables 108 incremental authorization. The client can track every scope they've 109 ever requested, and include those scopes on every new authorization 110 request. 112 To avoid the need for confidential clients to re-request already 113 authorized scopes, authorization servers MAY support an additional 114 "include_granted_scopes" parameter in the authorization request. 115 This parameter, enables the client to request tokens during the 116 authorization grant exchange that represent the full scope of the 117 user's grant to the application including any previous grants, 118 without the app needing to track the scopes directly. 120 The client indicates they wish the new authorization grant to include 121 previously granted scopes by sending the following additional 122 parameter in the OAuth 2.0 Authorization Request (Section 4.1.1 of 123 [RFC6749].) using the following additional parameter: 125 include_granted_scopes OPTIONAL. Either "true" or "false". When 126 "true", the authorization server SHOULD include previously granted 127 scopes for this client in the new authorization grant. 129 5. Incremental Auth for Public Clients 131 Unlike with confidential clients, it is NOT RECOMMEND to 132 automatically approve OAuth requests for public clients without user 133 consent (see Section 10.2 of OAuth 2.0 [RFC6749]), thus authorization 134 grants shouldn't contain previously authorized scopes in the manner 135 described above for confidential clients. 137 Public clients (and confidential clients using this technique) should 138 instead track the scopes for every authorization grant, and only 139 request yet to be granted scopes during incremental authorization. 140 In the past, this would result in multiple discrete authorization 141 grants that would need to be tracked. To enable incrementing a 142 single authorization grant for public clients, the client supplies 143 their existing refresh token during the authorization code exchange, 144 and receives new authorization tokens with the scope of the previous 145 and current authorization grants. 147 The client sends the previous refresh token in the OAuth 2.0 Access 148 Token Request (Section 4.1.3 of [RFC6749].) using the following 149 additional parameter: 151 existing_grant OPTIONAL. The refresh token from the existing 152 authorization grant. 154 When processing the token exchange, in addition to the normal 155 processing of such a request, the token endpoint MUST verify that 156 token provided in the "existing_grant" parameter is unexpired and 157 unrevoked, and was issued to the same client id and relates to the 158 same user as the current authorization grant. If this verification 159 succeeds, the new refresh token issued in the Access Token Response 160 (Section 4.1.4 of ) SHOULD include authorization for the scopes in 161 the previous grant. 163 6. IANA Considerations 165 This specification makes a registration request as follows: 167 6.1. OAuth Parameters Registry 169 This specification registers the following parameters in the IANA 170 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 172 o Parameter name: include_granted_scopes 174 o Parameter usage location: authorization request 176 o Change controller: IESG 178 o Specification document(s): this document 180 o Parameter name: existing_grant 182 o Parameter usage location: token request 184 o Change controller: IESG 186 o Specification document(s): this document 188 7. Normative References 190 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 191 Requirement Levels", BCP 14, RFC 2119, 192 DOI 10.17487/RFC2119, March 1997, 193 . 195 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 196 RFC 6749, DOI 10.17487/RFC6749, October 2012, 197 . 199 Appendix A. Acknowledgements 201 The following individuals contributed ideas, feedback, and wording 202 that shaped and formed the final specification: 204 Yanna Wu, Marius Scurtescu, Jason Huang, Nicholas Watson, and Breno 205 de Medeiros. 207 Appendix B. Document History 209 [[ to be removed by the RFC Editor before publication as an RFC ]] 211 -00 213 o Initial draft based on the implementation of incremental and 214 "appcremental" auth at Google. 216 Author's Address 218 William Denniss 219 Google 220 1600 Amphitheatre Pkwy 221 Mountain View, CA 94043 222 USA 224 Email: wdenniss@google.com 225 URI: http://wdenniss.com/incremental-auth