idnits 2.17.1 draft-parecki-oauth-v2-1-01.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 : ---------------------------------------------------------------------------- ** There are 22 instances of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (8 March 2020) is 1504 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) == Missing Reference: 'A-Z' is mentioned on line 1109, but not defined == Missing Reference: '0-9' is mentioned on line 1109, but not defined == Outdated reference: A later version (-25) exists of draft-ietf-oauth-security-topics-14 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-17) exists of draft-ietf-oauth-browser-based-apps-05 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-01 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 8 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track A. Parecki 5 Expires: 9 September 2020 Okta 6 T. Lodderstedt 7 yes.com 8 8 March 2020 10 The OAuth 2.1 Authorization Framework 11 draft-parecki-oauth-v2-1-01 13 Abstract 15 The OAuth 2.1 authorization framework enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and the HTTP service, or by allowing the 19 third-party application to obtain access on its own behalf. This 20 specification replaces and obsoletes the OAuth 2.0 Authorization 21 Framework described in RFC 6749. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 9 September 2020. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 7 59 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 60 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . 8 61 1.3.2. Client Credentials . . . . . . . . . . . . . . . . . 8 62 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 63 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 64 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 11 65 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 11 66 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 11 67 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 12 68 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 12 69 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13 70 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 14 71 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 14 72 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 73 2.3.2. Other Authorization Methods . . . . . . . . . . . . . 16 74 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 16 75 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 16 76 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 77 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 17 78 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 18 79 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 80 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 20 81 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 21 82 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22 83 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 22 84 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 23 85 4.1.2. Authorization Response . . . . . . . . . . . . . . . 26 86 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 29 87 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 30 88 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 30 89 4.2.1. Authorization Request and Response . . . . . . . . . 31 90 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 31 91 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 32 92 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 32 93 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 33 94 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 33 95 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 34 96 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 36 97 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 38 98 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 39 99 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 39 100 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 39 101 7.2.2. The WWW-Authenticate Response Header Field . . . . . 41 102 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 43 103 7.3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 43 104 7.4. Access Token Security Considerations . . . . . . . . . . 44 105 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 44 106 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 45 107 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 46 108 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 47 109 7.4.5. Access Token Privilege Restriction . . . . . . . . . 48 110 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 48 111 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 48 112 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 49 113 8.3. Defining New Authorization Grant Types . . . . . . . . . 49 114 8.4. Defining New Authorization Endpoint Response Types . . . 49 115 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 50 116 9. Security Considerations . . . . . . . . . . . . . . . . . . . 50 117 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 51 118 9.1.1. Client Authentication of Native Apps . . . . . . . . 51 119 9.2. Registration of Native App Clients . . . . . . . . . . . 52 120 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 52 121 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 53 122 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 53 123 9.4.1. Access Token Privilege Restriction . . . . . . . . . 54 124 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 54 125 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 55 126 9.6. Protecting Redirect-Based Flows . . . . . . . . . . . . . 55 127 9.6.1. Loopback Redirect Considerations in Native Apps . . . 56 128 9.7. Authorization Codes . . . . . . . . . . . . . . . . . . . 56 129 9.8. Request Confidentiality . . . . . . . . . . . . . . . . . 57 130 9.9. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 58 131 9.10. Credentials-Guessing Attacks . . . . . . . . . . . . . . 58 132 9.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 58 133 9.12. Fake External User-Agents in Native Apps . . . . . . . . 59 134 9.13. Malicious External User-Agents in Native Apps . . . . . . 59 135 9.14. Cross-Site Request Forgery . . . . . . . . . . . . . . . 59 136 9.15. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 60 137 9.16. Code Injection and Input Validation . . . . . . . . . . . 61 138 9.17. Open Redirectors . . . . . . . . . . . . . . . . . . . . 61 139 9.17.1. Client as Open Redirector . . . . . . . . . . . . . 61 140 9.17.2. Authorization Server as Open Redirector . . . . . . 62 141 9.18. Authorization Server Mix-Up Mitigation in Native Apps . . 62 142 9.19. Embedded User Agents in Native Apps . . . . . . . . . . . 63 143 9.20. Other Recommendations . . . . . . . . . . . . . . . . . . 63 144 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 64 145 10.1. Using Inter-App URI Communication for OAuth in Native 146 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 65 147 10.2. Initiating the Authorization Request from a Native 148 App . . . . . . . . . . . . . . . . . . . . . . . . . . 65 149 10.3. Receiving the Authorization Response in a Native App . . 66 150 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 66 151 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 67 152 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 68 153 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 68 154 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 69 155 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 156 13.1. OAuth Access Token Types Registry . . . . . . . . . . . 69 157 13.1.1. Registration Template . . . . . . . . . . . . . . . 70 158 13.1.2. Initial Registry Contents . . . . . . . . . . . . . 70 159 13.2. OAuth Parameters Registry . . . . . . . . . . . . . . . 71 160 13.2.1. Registration Template . . . . . . . . . . . . . . . 71 161 13.2.2. Initial Registry Contents . . . . . . . . . . . . . 72 162 13.3. OAuth Authorization Endpoint Response Types Registry . . 74 163 13.3.1. Registration Template . . . . . . . . . . . . . . . 75 164 13.3.2. Initial Registry Contents . . . . . . . . . . . . . 75 165 13.4. OAuth Extensions Error Registry . . . . . . . . . . . . 76 166 13.4.1. Registration Template . . . . . . . . . . . . . . . 76 167 13.4.2. Initial Registry Contents . . . . . . . . . . . . . 77 168 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 169 14.1. Normative References . . . . . . . . . . . . . . . . . . 77 170 14.2. Informative References . . . . . . . . . . . . . . . . . 80 171 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 82 172 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 83 173 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 83 174 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 83 175 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 83 176 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 83 177 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 84 178 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 84 179 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 84 180 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 84 181 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 84 182 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 84 183 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 84 184 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 85 185 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 85 186 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 85 187 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 85 188 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 85 189 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 85 190 Appendix B. Use of application/x-www-form-urlencoded Media 191 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 86 192 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 86 193 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 195 1. Introduction 197 In the traditional client-server authentication model, the client 198 requests an access-restricted resource (protected resource) on the 199 server by authenticating with the server using the resource owner's 200 credentials. In order to provide third-party applications access to 201 restricted resources, the resource owner shares its credentials with 202 the third party. This creates several problems and limitations: 204 * Third-party applications are required to store the resource 205 owner's credentials for future use, typically a password in clear- 206 text. 208 * Servers are required to support password authentication, despite 209 the security weaknesses inherent in passwords. 211 * Third-party applications gain overly broad access to the resource 212 owner's protected resources, leaving resource owners without any 213 ability to restrict duration or access to a limited subset of 214 resources. 216 * Resource owners cannot revoke access to an individual third party 217 without revoking access to all third parties, and must do so by 218 changing the third party's password. 220 * Compromise of any third-party application results in compromise of 221 the end-user's password and all of the data protected by that 222 password. 224 OAuth addresses these issues by introducing an authorization layer 225 and separating the role of the client from that of the resource 226 owner. In OAuth, the client requests access to resources controlled 227 by the resource owner and hosted by the resource server, and is 228 issued a different set of credentials than those of the resource 229 owner. 231 Instead of using the resource owner's credentials to access protected 232 resources, the client obtains an access token - a string denoting a 233 specific scope, lifetime, and other access attributes. Access tokens 234 are issued to third-party clients by an authorization server with the 235 approval of the resource owner. The client uses the access token to 236 access the protected resources hosted by the resource server. 238 For example, an end-user (resource owner) can grant a printing 239 service (client) access to her protected photos stored at a photo- 240 sharing service (resource server), without sharing her username and 241 password with the printing service. Instead, she authenticates 242 directly with a server trusted by the photo-sharing service 243 (authorization server), which issues the printing service delegation- 244 specific credentials (access token). 246 This specification is designed for use with HTTP ([RFC2616]). The 247 use of OAuth over any protocol other than HTTP is out of scope. 249 Since the publication of the OAuth 2.0 Authorization Framework 250 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 251 Native Apps ([RFC8252]), OAuth Security Best Current Practice 252 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 253 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 254 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 255 updated with ([I-D.ietf-oauth-security-topics]). This Standards 256 Track specification consolidates the information in all of these 257 documents and removes features that have been found to be insecure in 258 [I-D.ietf-oauth-security-topics]. 260 1.1. Roles 262 OAuth defines four roles: 264 "resource owner": An entity capable of granting access to a 265 protected resource. When the resource owner is a person, it is 266 referred to as an end-user. This is sometimes abbreviated as 267 "RO". 269 "resource server": The server hosting the protected resources, 270 capable of accepting and responding to protected resource requests 271 using access tokens. This is sometimes abbreviated as "RS". 273 "client": An application making protected resource requests on 274 behalf of the resource owner and with its authorization. The term 275 "client" does not imply any particular implementation 276 characteristics (e.g., whether the application executes on a 277 server, a desktop, or other devices). 279 "authorization server": The server issuing access tokens to the 280 client after successfully authenticating the resource owner and 281 obtaining authorization. This is sometimes abbreviated as "AS". 283 The interaction between the authorization server and resource server 284 is beyond the scope of this specification. The authorization server 285 may be the same server as the resource server or a separate entity. 286 A single authorization server may issue access tokens accepted by 287 multiple resource servers. 289 1.2. Protocol Flow 291 +--------+ +---------------+ 292 | |--(1)- Authorization Request ->| Resource | 293 | | | Owner | 294 | |<-(2)-- Authorization Grant ---| | 295 | | +---------------+ 296 | | 297 | | +---------------+ 298 | |--(3)-- Authorization Grant -->| Authorization | 299 | Client | | Server | 300 | |<-(4)----- Access Token -------| | 301 | | +---------------+ 302 | | 303 | | +---------------+ 304 | |--(5)----- Access Token ------>| Resource | 305 | | | Server | 306 | |<-(6)--- Protected Resource ---| | 307 +--------+ +---------------+ 309 Figure 1: Abstract Protocol Flow 311 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 312 interaction between the four roles and includes the following steps: 314 1. The client requests authorization from the resource owner. The 315 authorization request can be made directly to the resource owner 316 (as shown), or preferably indirectly via the authorization server 317 as an intermediary. 319 2. The client receives an authorization grant, which is a credential 320 representing the resource owner's authorization, expressed using 321 one of two grant types defined in this specification or using an 322 extension grant type. The authorization grant type depends on 323 the method used by the client to request authorization and the 324 types supported by the authorization server. 326 3. The client requests an access token by authenticating with the 327 authorization server and presenting the authorization grant. 329 4. The authorization server authenticates the client and validates 330 the authorization grant, and if valid, issues an access token. 332 5. The client requests the protected resource from the resource 333 server and authenticates by presenting the access token. 335 6. The resource server validates the access token, and if valid, 336 serves the request. 338 The preferred method for the client to obtain an authorization grant 339 from the resource owner (depicted in steps (1) and (2)) is to use the 340 authorization server as an intermediary, which is illustrated in 341 Figure 3 in Section 4.1. 343 1.3. Authorization Grant 345 An authorization grant is a credential representing the resource 346 owner's authorization (to access its protected resources) used by the 347 client to obtain an access token. This specification defines two 348 grant types - authorization code and client credentials - as well as 349 an extensibility mechanism for defining additional types. 351 1.3.1. Authorization Code 353 The authorization code is obtained by using an authorization server 354 as an intermediary between the client and resource owner. Instead of 355 requesting authorization directly from the resource owner, the client 356 directs the resource owner to an authorization server (via its user- 357 agent as defined in [RFC2616]), which in turn directs the resource 358 owner back to the client with the authorization code. 360 Before directing the resource owner back to the client with the 361 authorization code, the authorization server authenticates the 362 resource owner and obtains authorization. Because the resource owner 363 only authenticates with the authorization server, the resource 364 owner's credentials are never shared with the client. 366 The authorization code provides a few important security benefits, 367 such as the ability to authenticate the client, as well as the 368 transmission of the access token directly to the client without 369 passing it through the resource owner's user-agent and potentially 370 exposing it to others, including the resource owner. 372 1.3.2. Client Credentials 374 The client credentials (or other forms of client authentication) can 375 be used as an authorization grant when the authorization scope is 376 limited to the protected resources under the control of the client, 377 or to protected resources previously arranged with the authorization 378 server. Client credentials are used as an authorization grant 379 typically when the client is acting on its own behalf (the client is 380 also the resource owner) or is requesting access to protected 381 resources based on an authorization previously arranged with the 382 authorization server. 384 1.4. Access Token 386 Access tokens are credentials used to access protected resources. An 387 access token is a string representing an authorization issued to the 388 client. The string is usually opaque to the client. Tokens 389 represent specific scopes and durations of access, granted by the 390 resource owner, and enforced by the resource server and authorization 391 server. 393 The token may denote an identifier used to retrieve the authorization 394 information or may self-contain the authorization information in a 395 verifiable manner (i.e., a token string consisting of some data and a 396 signature). Additional authentication credentials, which are beyond 397 the scope of this specification, may be required in order for the 398 client to use a token. 400 The access token provides an abstraction layer, replacing different 401 authorization constructs (e.g., username and password) with a single 402 token understood by the resource server. This abstraction enables 403 issuing access tokens more restrictive than the authorization grant 404 used to obtain them, as well as removing the resource server's need 405 to understand a wide range of authentication methods. 407 Access tokens can have different formats, structures, and methods of 408 utilization (e.g., cryptographic properties) based on the resource 409 server security requirements. Access token attributes and the 410 methods used to access protected resources may be extended beyond 411 what is described in this specification. 413 1.5. Refresh Token 415 Refresh tokens are credentials used to obtain access tokens. Refresh 416 tokens are issued to the client by the authorization server and are 417 used to obtain a new access token when the current access token 418 becomes invalid or expires, or to obtain additional access tokens 419 with identical or narrower scope (access tokens may have a shorter 420 lifetime and fewer permissions than authorized by the resource 421 owner). Issuing a refresh token is optional at the discretion of the 422 authorization server. If the authorization server issues a refresh 423 token, it is included when issuing an access token (i.e., step (4) in 424 Figure 2). 426 A refresh token is a string representing the authorization granted to 427 the client by the resource owner. The string is usually opaque to 428 the client. The token denotes an identifier used to retrieve the 429 authorization information. Unlike access tokens, refresh tokens are 430 intended for use only with authorization servers and are never sent 431 to resource servers. 433 +--------+ +---------------+ 434 | |--(1)------- Authorization Grant --------->| | 435 | | | | 436 | |<-(2)----------- Access Token -------------| | 437 | | & Refresh Token | | 438 | | | | 439 | | +----------+ | | 440 | |--(3)---- Access Token ---->| | | | 441 | | | | | | 442 | |<-(4)- Protected Resource --| Resource | | Authorization | 443 | Client | | Server | | Server | 444 | |--(5)---- Access Token ---->| | | | 445 | | | | | | 446 | |<-(6)- Invalid Token Error -| | | | 447 | | +----------+ | | 448 | | | | 449 | |--(7)----------- Refresh Token ----------->| | 450 | | | | 451 | |<-(8)----------- Access Token -------------| | 452 +--------+ & Optional Refresh Token +---------------+ 454 Figure 2: Refreshing an Expired Access Token 456 The flow illustrated in Figure 2 includes the following steps: 458 1. The client requests an access token by authenticating with the 459 authorization server and presenting an authorization grant. 461 2. The authorization server authenticates the client and validates 462 the authorization grant, and if valid, issues an access token and 463 a refresh token. 465 3. The client makes a protected resource request to the resource 466 server by presenting the access token. 468 4. The resource server validates the access token, and if valid, 469 serves the request. 471 5. Steps (3) and (4) repeat until the access token expires. If the 472 client knows the access token expired, it skips to step (7); 473 otherwise, it makes another protected resource request. 475 6. Since the access token is invalid, the resource server returns an 476 invalid token error. 478 7. The client requests a new access token by authenticating with the 479 authorization server and presenting the refresh token. The 480 client authentication requirements are based on the client type 481 and on the authorization server policies. 483 8. The authorization server authenticates the client and validates 484 the refresh token, and if valid, issues a new access token (and, 485 optionally, a new refresh token). 487 Steps (3), (4), (5), and (6) are outside the scope of this 488 specification, as described in Section 7. 490 1.6. TLS Version 492 Whenever Transport Layer Security (TLS) is used by this 493 specification, the appropriate version (or versions) of TLS will vary 494 over time, based on the widespread deployment and known security 495 vulnerabilities. At the time of this writing, At the time of this 496 writing, TLS version 1.3 [RFC8446] is the most recent version. 498 Implementations MAY also support additional transport-layer security 499 mechanisms that meet their security requirements. 501 1.7. HTTP Redirections 503 This specification makes extensive use of HTTP redirections, in which 504 the client or the authorization server directs the resource owner's 505 user-agent to another destination. While the examples in this 506 specification show the use of the HTTP 302 status code, any other 507 method available via the user-agent to accomplish this redirection is 508 allowed and is considered to be an implementation detail. 510 1.8. Interoperability 512 OAuth 2.1 provides a rich authorization framework with well-defined 513 security properties. However, as a rich and highly extensible 514 framework with many optional components, on its own, this 515 specification is likely to produce a wide range of non-interoperable 516 implementations. 518 In addition, this specification leaves a few required components 519 partially or fully undefined (e.g., client registration, 520 authorization server capabilities, endpoint discovery). Without 521 these components, clients must be manually and specifically 522 configured against a specific authorization server and resource 523 server in order to interoperate. 525 This framework was designed with the clear expectation that future 526 work will define prescriptive profiles and extensions necessary to 527 achieve full web-scale interoperability. 529 1.9. Notational Conventions 531 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 532 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 533 specification are to be interpreted as described in [RFC2119]. 535 This specification uses the Augmented Backus-Naur Form (ABNF) 536 notation of [RFC5234]. Additionally, the rule URI-reference is 537 included from "Uniform Resource Identifier (URI): Generic Syntax" 538 [RFC3986]. 540 Certain security-related terms are to be understood in the sense 541 defined in [RFC4949]. These terms include, but are not limited to, 542 "attack", "authentication", "authorization", "certificate", 543 "confidentiality", "credential", "encryption", "identity", "sign", 544 "signature", "trust", "validate", and "verify". 546 Unless otherwise noted, all the protocol parameter names and values 547 are case sensitive. 549 2. Client Registration 551 Before initiating the protocol, the client registers with the 552 authorization server. The means through which the client registers 553 with the authorization server are beyond the scope of this 554 specification but typically involve end-user interaction with an HTML 555 registration form. 557 Client registration does not require a direct interaction between the 558 client and the authorization server. When supported by the 559 authorization server, registration can rely on other means for 560 establishing trust and obtaining the required client properties 561 (e.g., redirection URI, client type). For example, registration can 562 be accomplished using a self-issued or third-party-issued assertion, 563 or by the authorization server performing client discovery using a 564 trusted channel. 566 When registering a client, the client developer SHALL: 568 * specify the client type as described in Section 2.1, 570 * provide its client redirection URIs as described in Section 3.1.2, 571 and 573 * include any other information required by the authorization server 574 (e.g., application name, website, description, logo image, the 575 acceptance of legal terms). 577 2.1. Client Types 579 Clients are identified at the authorization server by a "client_id". 580 It is, for example, used by the authorization server to determine the 581 set of redirect URIs this client can use. 583 Clients requiring a higher level of confidence in their identity by 584 the authorization server use credentials to authenticate with the 585 authorization server. Such credentials are either issued by the 586 authorization server or registered by the developer of the client 587 with the authorization server. 589 OAuth 2.1 defines two client types: 591 "confidential": Clients that have credentials are designated as 592 "confidential clients" 594 "public": Clients without credentials are called "public clients" 596 Confidential clients MUST take precautions to prevent leakage and 597 abuse of their credentials. 599 Authorization servers SHOULD consider the level of confidence in a 600 client's identity when deciding whether they allow such a client 601 access to more critical functions, such as the client credentials 602 grant type. 604 A client may be implemented as a distributed set of components, each 605 with a different client type and security context (e.g., a 606 distributed client with both a confidential server-based component 607 and a public browser-based component). If the authorization server 608 does not provide support for such clients or does not provide 609 guidance with regard to their registration, the client SHOULD 610 register each component as a separate client. 612 This specification has been designed around the following client 613 profiles: 615 "web application": A web application is a confidential client 616 running on a web server. Resource owners access the client via an 617 HTML user interface rendered in a user-agent on the device used by 618 the resource owner. The client credentials as well as any access 619 token issued to the client are stored on the web server and are 620 not exposed to or accessible by the resource owner. 622 "browser-based application": A browser-based application is a public 623 client in which the client code is downloaded from a web server 624 and executes within a user-agent (e.g., web browser) on the device 625 used by the resource owner. Protocol data and credentials are 626 easily accessible (and often visible) to the resource owner. 627 Since such applications reside within the user-agent, they can 628 make seamless use of the user-agent capabilities when requesting 629 authorization. 631 "native application": A native application is a public client 632 installed and executed on the device used by the resource owner. 633 Protocol data and credentials are accessible to the resource 634 owner. It is assumed that any client authentication credentials 635 included in the application can be extracted. On the other hand, 636 dynamically issued credentials such as access tokens or refresh 637 tokens can receive an acceptable level of protection. At a 638 minimum, these credentials are protected from hostile servers with 639 which the application may interact. On some platforms, these 640 credentials might be protected from other applications residing on 641 the same device. 643 2.2. Client Identifier 645 The authorization server issues the registered client a client 646 identifier - a unique string representing the registration 647 information provided by the client. The client identifier is not a 648 secret; it is exposed to the resource owner and MUST NOT be used 649 alone for client authentication. The client identifier is unique to 650 the authorization server. 652 The client identifier string size is left undefined by this 653 specification. The client should avoid making assumptions about the 654 identifier size. The authorization server SHOULD document the size 655 of any identifier it issues. 657 Authorization servers SHOULD NOT allow clients to influence their 658 "client_id" or "sub" value or any other claim if that can cause 659 confusion with a genuine resource owner. 661 2.3. Client Authentication 663 If the client type is confidential, the client and authorization 664 server establish a client authentication method suitable for the 665 security requirements of the authorization server. The authorization 666 server MAY accept any form of client authentication meeting its 667 security requirements. 669 Confidential clients are typically issued (or establish) a set of 670 client credentials used for authenticating with the authorization 671 server (e.g., password, public/private key pair). 673 Authorization servers SHOULD use client authentication if possible. 675 It is RECOMMENDED to use asymmetric (public-key based) methods for 676 client authentication such as mTLS [RFC8705] or "private_key_jwt" 677 [OpenID]. When asymmetric methods for client authentication are 678 used, authorization servers do not need to store sensitive symmetric 679 keys, making these methods more robust against a number of attacks. 681 The authorization server MAY establish a client authentication method 682 with public clients. However, the authorization server MUST NOT rely 683 on public client authentication for the purpose of identifying the 684 client. 686 The client MUST NOT use more than one authentication method in each 687 request. 689 2.3.1. Client Password 691 Clients in possession of a client password MAY use the HTTP Basic 692 authentication scheme as defined in [RFC2617] to authenticate with 693 the authorization server. The client identifier is encoded using the 694 "application/x-www-form-urlencoded" encoding algorithm per 695 Appendix B, and the encoded value is used as the username; the client 696 password is encoded using the same algorithm and used as the 697 password. The authorization server MUST support the HTTP Basic 698 authentication scheme for authenticating clients that were issued a 699 client password. 701 For example (with extra line breaks for display purposes only): 703 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 705 Alternatively, the authorization server MAY support including the 706 client credentials in the request-body using the following 707 parameters: 709 "client_id": REQUIRED. The client identifier issued to the client 710 during the registration process described by Section 2.2. 712 "client_secret": REQUIRED. The client secret. The client MAY omit 713 the parameter if the client secret is an empty string. 715 Including the client credentials in the request-body using the two 716 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 717 to directly utilize the HTTP Basic authentication scheme (or other 718 password-based HTTP authentication schemes). The parameters can only 719 be transmitted in the request-body and MUST NOT be included in the 720 request URI. 722 For example, a request to refresh an access token (Section 6) using 723 the body parameters (with extra line breaks for display purposes 724 only): 726 POST /token HTTP/1.1 727 Host: server.example.com 728 Content-Type: application/x-www-form-urlencoded 730 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 731 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 733 The authorization server MUST require the use of TLS as described in 734 Section 1.6 when sending requests using password authentication. 736 Since this client authentication method involves a password, the 737 authorization server MUST protect any endpoint utilizing it against 738 brute force attacks. 740 2.3.2. Other Authorization Methods 742 The authorization server MAY support any suitable HTTP authentication 743 scheme matching its security requirements. When using other 744 authentication methods, the authorization server MUST define a 745 mapping between the client identifier (registration record) and 746 authentication scheme. 748 2.4. Unregistered Clients 750 This specification does not exclude the use of unregistered clients. 751 However, the use of such clients is beyond the scope of this 752 specification and requires additional security analysis and review of 753 its interoperability impact. 755 3. Protocol Endpoints 757 The authorization process utilizes two authorization server endpoints 758 (HTTP resources): 760 * Authorization endpoint - used by the client to obtain 761 authorization from the resource owner via user-agent redirection. 763 * Token endpoint - used by the client to exchange an authorization 764 grant for an access token, typically with client authentication. 766 As well as one client endpoint: 768 * Redirection endpoint - used by the authorization server to return 769 responses containing authorization credentials to the client via 770 the resource owner user-agent. 772 Not every authorization grant type utilizes both endpoints. 773 Extension grant types MAY define additional endpoints as needed. 775 3.1. Authorization Endpoint 777 The authorization endpoint is used to interact with the resource 778 owner and obtain an authorization grant. The authorization server 779 MUST first verify the identity of the resource owner. The way in 780 which the authorization server authenticates the resource owner 781 (e.g., username and password login, session cookies) is beyond the 782 scope of this specification. 784 The means through which the client obtains the location of the 785 authorization endpoint are beyond the scope of this specification, 786 but the location is typically provided in the service documentation. 788 The endpoint URI MAY include an "application/x-www-form-urlencoded" 789 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 790 which MUST be retained when adding additional query parameters. The 791 endpoint URI MUST NOT include a fragment component. 793 Since requests to the authorization endpoint result in user 794 authentication and the transmission of clear-text credentials (in the 795 HTTP response), the authorization server MUST require the use of TLS 796 as described in Section 1.6 when sending requests to the 797 authorization endpoint. 799 The authorization server MUST support the use of the HTTP "GET" 800 method [RFC2616] for the authorization endpoint and MAY support the 801 use of the "POST" method as well. 803 Parameters sent without a value MUST be treated as if they were 804 omitted from the request. The authorization server MUST ignore 805 unrecognized request parameters. Request and response parameters 806 MUST NOT be included more than once. 808 3.1.1. Response Type 810 The authorization endpoint is used by the authorization code flow. 811 The client informs the authorization server of the desired response 812 type using the following parameter: 814 "response_type": REQUIRED. The value MUST be "code" for requesting 815 an authorization code as described by Section 4.1.1, or a 816 registered extension value as described by Section 8.4. 818 Extension response types MAY contain a space-delimited (%x20) list of 819 values, where the order of values does not matter (e.g., response 820 type "a b" is the same as "b a"). The meaning of such composite 821 response types is defined by their respective specifications. 823 If an authorization request is missing the "response_type" parameter, 824 or if the response type is not understood, the authorization server 825 MUST return an error response as described in Section 4.1.2.1. 827 3.1.2. Redirection Endpoint 829 After completing its interaction with the resource owner, the 830 authorization server directs the resource owner's user-agent back to 831 the client. The authorization server redirects the user-agent to the 832 client's redirection endpoint previously established with the 833 authorization server during the client registration process. 835 The authorization server MUST compare the two URIs using simple 836 string comparison as defined in [RFC3986], Section 6.2.1. 838 The redirection endpoint URI MUST be an absolute URI as defined by 839 [RFC3986] Section 4.3. The endpoint URI MAY include an "application/ 840 x-www-form-urlencoded" formatted (per Appendix B) query component 841 ([RFC3986] Section 3.4), which MUST be retained when adding 842 additional query parameters. The endpoint URI MUST NOT include a 843 fragment component. 845 3.1.2.1. Endpoint Request Confidentiality 847 The redirection endpoint SHOULD require the use of TLS as described 848 in Section 1.6 when the requested response type is "code", or when 849 the redirection request will result in the transmission of sensitive 850 credentials over an open network. This specification does not 851 mandate the use of TLS because at the time of this writing, requiring 852 clients to deploy TLS is a significant hurdle for many client 853 developers. If TLS is not available, the authorization server SHOULD 854 warn the resource owner about the insecure endpoint prior to 855 redirection (e.g., display a message during the authorization 856 request). 858 Lack of transport-layer security can have a severe impact on the 859 security of the client and the protected resources it is authorized 860 to access. The use of transport-layer security is particularly 861 critical when the authorization process is used as a form of 862 delegated end-user authentication by the client (e.g., third-party 863 sign-in service). 865 3.1.2.2. Registration Requirements 867 The authorization server MUST require all clients to register their 868 redirection endpoint prior to utilizing the authorization endpoint. 870 The authorization server SHOULD require the client to provide the 871 complete redirection URI (the client MAY use the "state" request 872 parameter to achieve per-request customization). 874 The authorization server MAY allow the client to register multiple 875 redirection endpoints. 877 Lack of a redirection URI registration requirement can enable an 878 attacker to use the authorization endpoint as an open redirector as 879 described in Section 9.17. 881 3.1.2.3. Dynamic Configuration 883 If multiple redirection URIs have been registered the client MUST 884 include a redirection URI with the authorization request using the 885 "redirect_uri" request parameter. 887 When a redirection URI is included in an authorization request, the 888 authorization server MUST compare and match the value received 889 against at least one of the registered redirection URIs (or URI 890 components) as defined in [RFC3986] Section 6, if any redirection 891 URIs were registered. If the client registration included the full 892 redirection URI, the authorization server MUST compare the two URIs 893 using simple string comparison as defined in [RFC3986] Section 6.2.1. 895 3.1.2.4. Invalid Endpoint 897 If an authorization request fails validation due to a missing, 898 invalid, or mismatching redirection URI, the authorization server 899 SHOULD inform the resource owner of the error and MUST NOT 900 automatically redirect the user-agent to the invalid redirection URI. 902 3.1.2.5. Endpoint Content 904 The redirection request to the client's endpoint typically results in 905 an HTML document response, processed by the user-agent. If the HTML 906 response is served directly as the result of the redirection request, 907 any script included in the HTML document will execute with full 908 access to the redirection URI and the credentials it contains. 910 The client SHOULD NOT include any third-party scripts (e.g., third- 911 party analytics, social plug-ins, ad networks) in the redirection 912 endpoint response. Instead, it SHOULD extract the credentials from 913 the URI and redirect the user-agent again to another endpoint without 914 exposing the credentials (in the URI or elsewhere). If third-party 915 scripts are included, the client MUST ensure that its own scripts 916 (used to extract and remove the credentials from the URI) will 917 execute first. 919 3.2. Token Endpoint 921 The token endpoint is used by the client to obtain an access token by 922 presenting its authorization grant or refresh token. 924 The means through which the client obtains the location of the token 925 endpoint are beyond the scope of this specification, but the location 926 is typically provided in the service documentation. 928 The endpoint URI MAY include an "application/x-www-form-urlencoded" 929 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 930 which MUST be retained when adding additional query parameters. The 931 endpoint URI MUST NOT include a fragment component. 933 Since requests to the token endpoint result in the transmission of 934 clear-text credentials (in the HTTP request and response), the 935 authorization server MUST require the use of TLS as described in 936 Section 1.6 when sending requests to the token endpoint. 938 The client MUST use the HTTP "POST" method when making access token 939 requests. 941 Parameters sent without a value MUST be treated as if they were 942 omitted from the request. The authorization server MUST ignore 943 unrecognized request parameters. Request and response parameters 944 MUST NOT be included more than once. 946 3.2.1. Client Authentication 948 Confidential clients or other clients issued client credentials MUST 949 authenticate with the authorization server as described in 950 Section 2.3 when making requests to the token endpoint. Client 951 authentication is used for: 953 * Enforcing the binding of refresh tokens and authorization codes to 954 the client they were issued to. Client authentication is critical 955 when an authorization code is transmitted to the redirection 956 endpoint over an insecure channel or when the redirection URI has 957 not been registered in full. 959 * Recovering from a compromised client by disabling the client or 960 changing its credentials, thus preventing an attacker from abusing 961 stolen refresh tokens. Changing a single set of client 962 credentials is significantly faster than revoking an entire set of 963 refresh tokens. 965 * Implementing authentication management best practices, which 966 require periodic credential rotation. Rotation of an entire set 967 of refresh tokens can be challenging, while rotation of a single 968 set of client credentials is significantly easier. 970 A client MAY use the "client_id" request parameter to identify itself 971 when sending requests to the token endpoint. In the 972 "authorization_code" "grant_type" request to the token endpoint, an 973 unauthenticated client MUST send its "client_id" to prevent itself 974 from inadvertently accepting a code intended for a client with a 975 different "client_id". This protects the client from substitution of 976 the authentication code. (It provides no additional security for the 977 protected resource.) 979 3.3. Access Token Scope 981 The authorization and token endpoints allow the client to specify the 982 scope of the access request using the "scope" request parameter. In 983 turn, the authorization server uses the "scope" response parameter to 984 inform the client of the scope of the access token issued. 986 The value of the scope parameter is expressed as a list of space- 987 delimited, case-sensitive strings. The strings are defined by the 988 authorization server. If the value contains multiple space-delimited 989 strings, their order does not matter, and each string adds an 990 additional access range to the requested scope. 992 scope = scope-token *( SP scope-token ) 993 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 995 The authorization server MAY fully or partially ignore the scope 996 requested by the client, based on the authorization server policy or 997 the resource owner's instructions. If the issued access token scope 998 is different from the one requested by the client, the authorization 999 server MUST include the "scope" response parameter to inform the 1000 client of the actual scope granted. 1002 If the client omits the scope parameter when requesting 1003 authorization, the authorization server MUST either process the 1004 request using a pre-defined default value or fail the request 1005 indicating an invalid scope. The authorization server SHOULD 1006 document its scope requirements and default value (if defined). 1008 4. Obtaining Authorization 1010 To request an access token, the client obtains authorization from the 1011 resource owner. The authorization is expressed in the form of an 1012 authorization grant, which the client uses to request the access 1013 token. OAuth defines two grant types: authorization code and client 1014 credentials. It also provides an extension mechanism for defining 1015 additional grant types. 1017 4.1. Authorization Code Grant 1019 The authorization code grant type is used to obtain both access 1020 tokens and refresh tokens. 1022 Since this is a redirection-based flow, the client must be capable of 1023 interacting with the resource owner's user-agent (typically a web 1024 browser) and capable of receiving incoming requests (via redirection) 1025 from the authorization server. 1027 +----------+ 1028 | Resource | 1029 | Owner | 1030 | | 1031 +----------+ 1032 ^ 1033 | 1034 (2) 1035 +----|-----+ Client Identifier +---------------+ 1036 | -+----(1)-- & Redirection URI ---->| | 1037 | User- | | Authorization | 1038 | Agent -+----(2)-- User authenticates --->| Server | 1039 | | | | 1040 | -+----(3)-- Authorization Code ---<| | 1041 +-|----|---+ +---------------+ 1042 | | ^ v 1043 (1) (3) | | 1044 | | | | 1045 ^ v | | 1046 +---------+ | | 1047 | |>---(4)-- Authorization Code ---------' | 1048 | Client | & Redirection URI | 1049 | | | 1050 | |<---(5)----- Access Token -------------------' 1051 +---------+ (w/ Optional Refresh Token) 1053 Note: The lines illustrating steps (1), (2), and (3) are broken into 1054 two parts as they pass through the user-agent. 1056 Figure 3: Authorization Code Flow 1058 The flow illustrated in Figure 3 includes the following steps: 1060 (1) The client initiates the flow by directing the resource owner's 1061 user-agent to the authorization endpoint. The client includes its 1062 client identifier, requested scope, local state, PKCE code challenge, 1063 and a redirection URI to which the authorization server will send the 1064 user-agent back once access is granted (or denied). 1066 (2) The authorization server authenticates the resource owner (via 1067 the user-agent) and establishes whether the resource owner grants or 1068 denies the client's access request. 1070 (3) Assuming the resource owner grants access, the authorization 1071 server redirects the user-agent back to the client using the 1072 redirection URI provided earlier (in the request or during client 1073 registration). The redirection URI includes an authorization code 1074 and any local state provided by the client earlier. 1076 (4) The client requests an access token from the authorization 1077 server's token endpoint by including the authorization code received 1078 in the previous step, and including its code verifier. When making 1079 the request, the client authenticates with the authorization server 1080 if it can. The client includes the redirection URI used to obtain 1081 the authorization code for verification. 1083 (5) The authorization server authenticates the client when possible, 1084 validates the authorization code, validates the code verifier, and 1085 ensures that the redirection URI received matches the URI used to 1086 redirect the client in step (C). If valid, the authorization server 1087 responds back with an access token and, optionally, a refresh token. 1089 4.1.1. Authorization Request 1091 To begin the authorization request, the client builds the 1092 authorization request URI by adding parameters to the authorization 1093 server's authorization endpoint URI. 1095 Clients use a unique secret per authorization request to protect 1096 against code injection and CSRF attacks. The client first generates 1097 this secret, which it can later use along with the authorization code 1098 to prove that the application using the authorization code is the 1099 same application that requested it. This practice is known as 1100 "Proof-Key for Code Exchange", or PKCE, after the OAuth 2.0 extension 1101 ([RFC7636]) where it was originally developed. 1103 4.1.1.1. Client Creates a PKCE Code Verifier 1105 The client first creates a PKCE code verifier, "code_verifier", for 1106 each Authorization Request, in the following manner: 1108 code_verifier = high-entropy cryptographic random STRING using the 1109 unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"` 1110 from Section 2.3 of {{RFC3986}}, with a minimum length of 43 characters 1111 and a maximum length of 128 characters. 1113 ABNF for "code_verifier" is as follows. 1115 code-verifier = 43*128unreserved 1116 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1117 ALPHA = %x41-5A / %x61-7A 1118 DIGIT = %x30-39 1120 NOTE: The code verifier SHOULD have enough entropy to make it 1121 impractical to guess the value. It is RECOMMENDED that the output of 1122 a suitable random number generator be used to create a 32-octet 1123 sequence. The octet sequence is then base64url-encoded to produce a 1124 43-octet URL-safe string to use as the code verifier. 1126 4.1.1.2. Client Creates the PKCE Code Challenge 1128 The client then creates a PKCE code challenge derived from the code 1129 verifier by using one of the following transformations on the code 1130 verifier: 1132 plain 1133 code_challenge = code_verifier 1135 S256 1136 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1138 If the client is capable of using "S256", it MUST use "S256", as 1139 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1140 permitted to use "plain" only if they cannot support "S256" for some 1141 technical reason and know via out-of-band configuration that the 1142 server supports "plain". 1144 The plain transformation is for compatibility with existing 1145 deployments and for constrained environments that can't use the S256 1146 transformation. 1148 ABNF for "code_challenge" is as follows. 1150 code-challenge = 43*128unreserved 1151 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1152 ALPHA = %x41-5A / %x61-7A 1153 DIGIT = %x30-39 1155 4.1.1.3. Client Initiates the Authorization Request 1157 The client constructs the request URI by adding the following 1158 parameters to the query component of the authorization endpoint URI 1159 using the "application/x-www-form-urlencoded" format, per Appendix B: 1161 "response_type": REQUIRED. Value MUST be set to "code". 1163 "client_id": REQUIRED. The client identifier as described in 1164 Section 2.2. 1166 "code_challenge": REQUIRED. Code challenge. 1168 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1169 present in the request. Code verifier transformation method is 1170 "S256" or "plain". 1172 "redirect_uri": OPTIONAL. As described in Section 3.1.2. 1174 "scope": OPTIONAL. The scope of the access request as described by 1175 Section 3.3. 1177 "state": OPTIONAL. An opaque value used by the client to maintain 1178 state between the request and callback. The authorization server 1179 includes this value when redirecting the user-agent back to the 1180 client. 1182 The client directs the resource owner to the constructed URI using an 1183 HTTP redirection response, or by other means available to it via the 1184 user-agent. 1186 For example, the client directs the user-agent to make the following 1187 HTTP request using TLS (with extra line breaks for display purposes 1188 only): 1190 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1191 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1192 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1193 &code_challenge_method=S256 HTTP/1.1 1194 Host: server.example.com 1196 The authorization server validates the request to ensure that all 1197 required parameters are present and valid. If the request is valid, 1198 the authorization server authenticates the resource owner and obtains 1199 an authorization decision (by asking the resource owner or by 1200 establishing approval via other means). 1202 When a decision is established, the authorization server directs the 1203 user-agent to the provided client redirection URI using an HTTP 1204 redirection response, or by other means available to it via the user- 1205 agent. 1207 4.1.2. Authorization Response 1209 If the resource owner grants the access request, the authorization 1210 server issues an authorization code and delivers it to the client by 1211 adding the following parameters to the query component of the 1212 redirection URI using the "application/x-www-form-urlencoded" format, 1213 per Appendix B: 1215 "code": REQUIRED. The authorization code generated by the 1216 authorization server. The authorization code MUST expire shortly 1217 after it is issued to mitigate the risk of leaks. A maximum 1218 authorization code lifetime of 10 minutes is RECOMMENDED. The 1219 client MUST NOT use the authorization code more than once. If an 1220 authorization code is used more than once, the authorization 1221 server MUST deny the request and SHOULD revoke (when possible) all 1222 tokens previously issued based on that authorization code. The 1223 authorization code is bound to the client identifier and 1224 redirection URI. 1226 "state": REQUIRED if the "state" parameter was present in the client 1227 authorization request. The exact value received from the client. 1229 For example, the authorization server redirects the user-agent by 1230 sending the following HTTP response: 1232 HTTP/1.1 302 Found 1233 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1234 &state=xyz 1236 The client MUST ignore unrecognized response parameters. The 1237 authorization code string size is left undefined by this 1238 specification. The client should avoid making assumptions about code 1239 value sizes. The authorization server SHOULD document the size of 1240 any value it issues. 1242 When the server issues the authorization code in the authorization 1243 response, it MUST associate the "code_challenge" and 1244 "code_challenge_method" values with the authorization code so it can 1245 be verified later. 1247 Typically, the "code_challenge" and "code_challenge_method" values 1248 are stored in encrypted form in the "code" itself but could 1249 alternatively be stored on the server associated with the code. The 1250 server MUST NOT include the "code_challenge" value in client requests 1251 in a form that other entities can extract. 1253 The exact method that the server uses to associate the 1254 "code_challenge" with the issued "code" is out of scope for this 1255 specification. 1257 4.1.2.1. Error Response 1259 If the request fails due to a missing, invalid, or mismatching 1260 redirection URI, or if the client identifier is missing or invalid, 1261 the authorization server SHOULD inform the resource owner of the 1262 error and MUST NOT automatically redirect the user-agent to the 1263 invalid redirection URI. 1265 If the client does not send the "code_challenge" in the request, the 1266 authorization endpoint MUST return the authorization error response 1267 with the "error" value set to "invalid_request". The 1268 "error_description" or the response of "error_uri" SHOULD explain the 1269 nature of error, e.g., code challenge required. 1271 If the server supporting PKCE does not support the requested 1272 transformation, the authorization endpoint MUST return the 1273 authorization error response with "error" value set to 1274 "invalid_request". The "error_description" or the response of 1275 "error_uri" SHOULD explain the nature of error, e.g., transform 1276 algorithm not supported. 1278 If the resource owner denies the access request or if the request 1279 fails for reasons other than a missing or invalid redirection URI, 1280 the authorization server informs the client by adding the following 1281 parameters to the query component of the redirection URI using the 1282 "application/x-www-form-urlencoded" format, per Appendix B: 1284 "error": REQUIRED. A single ASCII [USASCII] error code from the 1285 following: 1287 "invalid_request": The request is missing a required parameter, 1288 includes an invalid parameter value, includes a parameter more 1289 than once, or is otherwise malformed. 1291 "unauthorized_client": The client is not authorized to request an 1292 authorization code using this method. 1294 "access_denied": The resource owner or authorization server 1295 denied the request. 1297 "unsupported_response_type": The authorization server does not 1298 support obtaining an authorization code using this method. 1300 "invalid_scope": The requested scope is invalid, unknown, or 1301 malformed. 1303 "server_error": The authorization server encountered an 1304 unexpected condition that prevented it from fulfilling the 1305 request. (This error code is needed because a 500 Internal 1306 Server Error HTTP status code cannot be returned to the client 1307 via an HTTP redirect.) 1309 "temporarily_unavailable": The authorization server is currently 1310 unable to handle the request due to a temporary overloading or 1311 maintenance of the server. (This error code is needed because 1312 a 503 Service Unavailable HTTP status code cannot be returned 1313 to the client via an HTTP redirect.) 1315 Values for the "error" parameter MUST NOT include characters 1316 outside the set %x20-21 / %x23-5B / %x5D-7E. 1318 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1319 providing additional information, used to assist the client 1320 developer in understanding the error that occurred. Values for 1321 the "error_description" parameter MUST NOT include characters 1322 outside the set %x20-21 / %x23-5B / %x5D-7E. 1324 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1325 with information about the error, used to provide the client 1326 developer with additional information about the error. Values for 1327 the "error_uri" parameter MUST conform to the URI-reference syntax 1328 and thus MUST NOT include characters outside the set %x21 / 1329 %x23-5B / %x5D-7E. 1331 "state": REQUIRED if a "state" parameter was present in the client 1332 authorization request. The exact value received from the client. 1334 For example, the authorization server redirects the user-agent by 1335 sending the following HTTP response: 1337 HTTP/1.1 302 Found 1338 Location: https://client.example.com/cb?error=access_denied&state=xyz 1340 4.1.3. Access Token Request 1342 The client makes a request to the token endpoint by sending the 1343 following parameters using the "application/x-www-form-urlencoded" 1344 format per Appendix B with a character encoding of UTF-8 in the HTTP 1345 request entity-body: 1347 "grant_type": REQUIRED. Value MUST be set to "authorization_code". 1349 "code": REQUIRED. The authorization code received from the 1350 authorization server. 1352 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1353 included in the authorization request as described in 1354 Section 4.1.1, and their values MUST be identical. 1356 "client_id": REQUIRED, if the client is not authenticating with the 1357 authorization server as described in Section 3.2.1. 1359 "code_verifier": REQUIRED. Code verifier 1361 If the client type is confidential or the client was issued client 1362 credentials (or assigned other authentication requirements), the 1363 client MUST authenticate with the authorization server as described 1364 in Section 3.2.1. 1366 For example, the client makes the following HTTP request using TLS 1367 (with extra line breaks for display purposes only): 1369 POST /token HTTP/1.1 1370 Host: server.example.com 1371 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1372 Content-Type: application/x-www-form-urlencoded 1374 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1375 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1376 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1378 The authorization server MUST: 1380 * require client authentication for confidential clients or for any 1381 client that was issued client credentials (or with other 1382 authentication requirements), 1384 * authenticate the client if client authentication is included, 1386 * ensure that the authorization code was issued to the authenticated 1387 confidential client, or if the client is public, ensure that the 1388 code was issued to "client_id" in the request, 1390 * verify that the authorization code is valid, 1392 * verify the "code_verifier" by calculating the code challenge from 1393 the received "code_verifier" and comparing it with the previously 1394 associated "code_challenge", after first transforming it according 1395 to the "code_challenge_method" method specified by the client, and 1397 * ensure that the "redirect_uri" parameter is present if the 1398 "redirect_uri" parameter was included in the initial authorization 1399 request as described in Section 4.1.1, and if included ensure that 1400 their values are identical. 1402 4.1.4. Access Token Response 1404 If the access token request is valid and authorized, the 1405 authorization server issues an access token and optional refresh 1406 token as described in Section 5.1. If the request client 1407 authentication failed or is invalid, the authorization server returns 1408 an error response as described in Section 5.2. 1410 An example successful response: 1412 HTTP/1.1 200 OK 1413 Content-Type: application/json;charset=UTF-8 1414 Cache-Control: no-store 1415 Pragma: no-cache 1417 { 1418 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1419 "token_type": "Bearer", 1420 "expires_in": 3600, 1421 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 1422 "example_parameter": "example_value" 1423 } 1425 4.2. Client Credentials Grant 1427 The client can request an access token using only its client 1428 credentials (or other supported means of authentication) when the 1429 client is requesting access to the protected resources under its 1430 control, or those of another resource owner that have been previously 1431 arranged with the authorization server (the method of which is beyond 1432 the scope of this specification). 1434 The client credentials grant type MUST only be used by confidential 1435 clients. 1437 +---------+ +---------------+ 1438 | | | | 1439 | |>--(A)- Client Authentication --->| Authorization | 1440 | Client | | Server | 1441 | |<--(B)---- Access Token ---------<| | 1442 | | | | 1443 +---------+ +---------------+ 1445 Figure 4: Client Credentials Flow 1447 The flow illustrated in Figure 4 includes the following steps: 1449 (A) The client authenticates with the authorization server and 1450 requests an access token from the token endpoint. 1452 (B) The authorization server authenticates the client, and if valid, 1453 issues an access token. 1455 4.2.1. Authorization Request and Response 1457 Since the client authentication is used as the authorization grant, 1458 no additional authorization request is needed. 1460 4.2.2. Access Token Request 1462 The client makes a request to the token endpoint by adding the 1463 following parameters using the "application/x-www-form-urlencoded" 1464 format per Appendix B with a character encoding of UTF-8 in the HTTP 1465 request entity-body: 1467 "grant_type": REQUIRED. Value MUST be set to "client_credentials". 1469 "scope": OPTIONAL. The scope of the access request as described by 1470 Section 3.3. 1472 The client MUST authenticate with the authorization server as 1473 described in Section 3.2.1. 1475 For example, the client makes the following HTTP request using 1476 transport-layer security (with extra line breaks for display purposes 1477 only): 1479 POST /token HTTP/1.1 1480 Host: server.example.com 1481 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1482 Content-Type: application/x-www-form-urlencoded 1484 grant_type=client_credentials 1486 The authorization server MUST authenticate the client. 1488 4.2.3. Access Token Response 1490 If the access token request is valid and authorized, the 1491 authorization server issues an access token as described in 1492 Section 5.1. A refresh token SHOULD NOT be included. If the request 1493 failed client authentication or is invalid, the authorization server 1494 returns an error response as described in Section 5.2. 1496 An example successful response: 1498 HTTP/1.1 200 OK 1499 Content-Type: application/json;charset=UTF-8 1500 Cache-Control: no-store 1501 Pragma: no-cache 1503 { 1504 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1505 "token_type": "Bearer", 1506 "expires_in": 3600, 1507 "example_parameter": "example_value" 1508 } 1510 4.3. Extension Grants 1512 The client uses an extension grant type by specifying the grant type 1513 using an absolute URI (defined by the authorization server) as the 1514 value of the "grant_type" parameter of the token endpoint, and by 1515 adding any additional parameters necessary. 1517 For example, to request an access token using a Security Assertion 1518 Markup Language (SAML) 2.0 assertion grant type as defined by 1519 [RFC7522], the client could make the following HTTP request using TLS 1520 (with extra line breaks for display purposes only): 1522 POST /token HTTP/1.1 1523 Host: server.example.com 1524 Content-Type: application/x-www-form-urlencoded 1526 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1527 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1528 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1530 If the access token request is valid and authorized, the 1531 authorization server issues an access token and optional refresh 1532 token as described in Section 5.1. If the request failed client 1533 authentication or is invalid, the authorization server returns an 1534 error response as described in Section 5.2. 1536 5. Issuing an Access Token 1538 If the access token request is valid and authorized, the 1539 authorization server issues an access token and optional refresh 1540 token as described in Section 5.1. If the request failed client 1541 authentication or is invalid, the authorization server returns an 1542 error response as described in Section 5.2. 1544 5.1. Successful Response 1546 The authorization server issues an access token and optional refresh 1547 token, and constructs the response by adding the following parameters 1548 to the entity-body of the HTTP response with a 200 (OK) status code: 1550 "access_token": REQUIRED. The access token issued by the 1551 authorization server. 1553 "token_type": REQUIRED. The type of the token issued as described 1554 in Section 7.1. Value is case insensitive. 1556 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1557 token. For example, the value "3600" denotes that the access 1558 token will expire in one hour from the time the response was 1559 generated. If omitted, the authorization server SHOULD provide 1560 the expiration time via other means or document the default value. 1562 "refresh_token": OPTIONAL. The refresh token, which can be used to 1563 obtain new access tokens using the same authorization grant as 1564 described in Section 6. 1566 "scope": OPTIONAL, if identical to the scope requested by the 1567 client; otherwise, REQUIRED. The scope of the access token as 1568 described by Section 3.3. 1570 The parameters are included in the entity-body of the HTTP response 1571 using the "application/json" media type as defined by [RFC4627]. The 1572 parameters are serialized into a JavaScript Object Notation (JSON) 1573 structure by adding each parameter at the highest structure level. 1574 Parameter names and string values are included as JSON strings. 1575 Numerical values are included as JSON numbers. The order of 1576 parameters does not matter and can vary. 1578 The authorization server MUST include the HTTP "Cache-Control" 1579 response header field [RFC2616] with a value of "no-store" in any 1580 response containing tokens, credentials, or other sensitive 1581 information, as well as the "Pragma" response header field [RFC2616] 1582 with a value of "no-cache". 1584 For example: 1586 HTTP/1.1 200 OK 1587 Content-Type: application/json;charset=UTF-8 1588 Cache-Control: no-store 1589 Pragma: no-cache 1591 { 1592 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1593 "token_type":"Bearer", 1594 "expires_in":3600, 1595 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1596 "example_parameter":"example_value" 1597 } 1599 The client MUST ignore unrecognized value names in the response. The 1600 sizes of tokens and other values received from the authorization 1601 server are left undefined. The client should avoid making 1602 assumptions about value sizes. The authorization server SHOULD 1603 document the size of any value it issues. 1605 5.2. Error Response 1607 The authorization server responds with an HTTP 400 (Bad Request) 1608 status code (unless specified otherwise) and includes the following 1609 parameters with the response: 1611 The authorization server responds with an HTTP 400 (Bad Request) 1612 status code (unless specified otherwise) and includes the following 1613 parameters with the response: 1615 "error": REQUIRED. A single ASCII [USASCII] error code from the 1616 following: 1618 "invalid_request": The request is missing a required parameter, 1619 includes an unsupported parameter value (other than grant 1620 type), repeats a parameter, includes multiple credentials, 1621 utilizes more than one mechanism for authenticating the client, 1622 or is otherwise malformed. 1624 "invalid_client": Client authentication failed (e.g., unknown 1625 client, no client authentication included, or unsupported 1626 authentication method). The authorization server MAY return an 1627 HTTP 401 (Unauthorized) status code to indicate which HTTP 1628 authentication schemes are supported. If the client attempted 1629 to authenticate via the "Authorization" request header field, 1630 the authorization server MUST respond with an HTTP 401 1631 (Unauthorized) status code and include the "WWW-Authenticate" 1632 response header field matching the authentication scheme used 1633 by the client. 1635 "invalid_grant": The provided authorization grant (e.g., 1636 authorization code, resource owner credentials) or refresh 1637 token is invalid, expired, revoked, does not match the 1638 redirection URI used in the authorization request, or was 1639 issued to another client. 1641 "unauthorized_client": The authenticated client is not authorized 1642 to use this authorization grant type. 1644 "unsupported_grant_type": The authorization grant type is not 1645 supported by the authorization server. 1647 "invalid_scope": The requested scope is invalid, unknown, 1648 malformed, or exceeds the scope granted by the resource owner. 1650 Values for the "error" parameter MUST NOT include characters 1651 outside the set %x20-21 / %x23-5B / %x5D-7E. 1653 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1654 providing additional information, used to assist the client 1655 developer in understanding the error that occurred. Values for 1656 the "error_description" parameter MUST NOT include characters 1657 outside the set %x20-21 / %x23-5B / %x5D-7E. 1659 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1660 with information about the error, used to provide the client 1661 developer with additional information about the error. Values for 1662 the "error_uri" parameter MUST conform to the URI-reference syntax 1663 and thus MUST NOT include characters outside the set %x21 / 1664 %x23-5B / %x5D-7E. 1666 The parameters are included in the entity-body of the HTTP response 1667 using the "application/json" media type as defined by [RFC4627]. The 1668 parameters are serialized into a JSON structure by adding each 1669 parameter at the highest structure level. Parameter names and string 1670 values are included as JSON strings. Numerical values are included 1671 as JSON numbers. The order of parameters does not matter and can 1672 vary. 1674 For example: 1676 HTTP/1.1 400 Bad Request 1677 Content-Type: application/json;charset=UTF-8 1678 Cache-Control: no-store 1679 Pragma: no-cache 1681 { 1682 "error":"invalid_request" 1683 } 1685 6. Refreshing an Access Token 1687 Authorization servers SHOULD determine, based on a risk assessment, 1688 whether to issue refresh tokens to a certain client. If the 1689 authorization server decides not to issue refresh tokens, the client 1690 MAY refresh access tokens by utilizing other grant types, such as the 1691 authorization code grant type. In such a case, the authorization 1692 server may utilize cookies and persistent grants to optimize the user 1693 experience. 1695 If refresh tokens are issued, those refresh tokens MUST be bound to 1696 the scope and resource servers as consented by the resource owner. 1697 This is to prevent privilege escalation by the legitimate client and 1698 reduce the impact of refresh token leakage. 1700 If the authorization server issued a refresh token to the client, the 1701 client makes a refresh request to the token endpoint by adding the 1702 following parameters using the "application/x-www-form-urlencoded" 1703 format per Appendix B with a character encoding of UTF-8 in the HTTP 1704 request entity-body: 1706 "grant_type": REQUIRED. Value MUST be set to "refresh_token". 1708 "refresh_token": REQUIRED. The refresh token issued to the client. 1710 "scope": OPTIONAL. The scope of the access request as described by 1711 Section 3.3. The requested scope MUST NOT include any scope not 1712 originally granted by the resource owner, and if omitted is 1713 treated as equal to the scope originally granted by the resource 1714 owner. 1716 Because refresh tokens are typically long-lasting credentials used to 1717 request additional access tokens, the refresh token is bound to the 1718 client to which it was issued. If the client type is confidential or 1719 the client was issued client credentials (or assigned other 1720 authentication requirements), the client MUST authenticate with the 1721 authorization server as described in Section 3.2.1. 1723 For example, the client makes the following HTTP request using 1724 transport-layer security (with extra line breaks for display purposes 1725 only): 1727 POST /token HTTP/1.1 1728 Host: server.example.com 1729 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1730 Content-Type: application/x-www-form-urlencoded 1732 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1734 The authorization server MUST: 1736 * require client authentication for confidential clients or for any 1737 client that was issued client credentials (or with other 1738 authentication requirements), 1740 * authenticate the client if client authentication is included and 1741 ensure that the refresh token was issued to the authenticated 1742 client, and 1744 * validate the refresh token. 1746 Authorization server MUST utilize one of these methods to detect 1747 refresh token replay by malicious actors for public clients: 1749 * _Sender-constrained refresh tokens:_ the authorization server 1750 cryptographically binds the refresh token to a certain client 1751 instance by utilizing [I-D.ietf-oauth-token-binding] or [RFC8705]. 1753 * _Refresh token rotation:_ the authorization server issues a new 1754 refresh token with every access token refresh response. The 1755 previous refresh token is invalidated but information about the 1756 relationship is retained by the authorization server. If a 1757 refresh token is compromised and subsequently used by both the 1758 attacker and the legitimate client, one of them will present an 1759 invalidated refresh token, which will inform the authorization 1760 server of the breach. The authorization server cannot determine 1761 which party submitted the invalid refresh token, but it will 1762 revoke the active refresh token. This stops the attack at the 1763 cost of forcing the legitimate client to obtain a fresh 1764 authorization grant. 1766 Implementation note: the grant to which a refresh token belongs 1767 may be encoded into the refresh token itself. This can enable an 1768 authorization server to efficiently determine the grant to which a 1769 refresh token belongs, and by extension, all refresh tokens that 1770 need to be revoked. Authorization servers MUST ensure the 1771 integrity of the refresh token value in this case, for example, 1772 using signatures. 1774 If valid and authorized, the authorization server issues an access 1775 token as described in Section 5.1. If the request failed 1776 verification or is invalid, the authorization server returns an error 1777 response as described in Section 5.2. 1779 The authorization server MAY issue a new refresh token, in which case 1780 the client MUST discard the old refresh token and replace it with the 1781 new refresh token. The authorization server MAY revoke the old 1782 refresh token after issuing a new refresh token to the client. If a 1783 new refresh token is issued, the refresh token scope MUST be 1784 identical to that of the refresh token included by the client in the 1785 request. 1787 Authorization servers MAY revoke refresh tokens automatically in case 1788 of a security event, such as: 1790 * password change 1792 * logout at the authorization server 1794 Refresh tokens SHOULD expire if the client has been inactive for some 1795 time, i.e., the refresh token has not been used to obtain fresh 1796 access tokens for some time. The expiration time is at the 1797 discretion of the authorization server. It might be a global value 1798 or determined based on the client policy or the grant associated with 1799 the refresh token (and its sensitivity). 1801 7. Accessing Protected Resources 1803 The client accesses protected resources by presenting the access 1804 token to the resource server. The resource server MUST validate the 1805 access token and ensure that it has not expired and that its scope 1806 covers the requested resource. The methods used by the resource 1807 server to validate the access token (as well as any error responses) 1808 are beyond the scope of this specification but generally involve an 1809 interaction or coordination between the resource server and the 1810 authorization server. 1812 The method in which the client utilizes the access token to 1813 authenticate with the resource server depends on the type of access 1814 token issued by the authorization server. Typically, it involves 1815 using the HTTP "Authorization" request header field [RFC2617] with an 1816 authentication scheme defined by the specification of the access 1817 token type used, such as "Bearer", defined below. 1819 7.1. Access Token Types 1821 The access token type provides the client with the information 1822 required to successfully utilize the access token to make a protected 1823 resource request (along with type-specific attributes). The client 1824 MUST NOT use an access token if it does not understand the token 1825 type. 1827 For example, the "Bearer" token type defined in this specification is 1828 utilized by simply including the access token string in the request: 1830 GET /resource/1 HTTP/1.1 1831 Host: example.com 1832 Authorization: Bearer mF_9.B5f-4.1JqM 1834 The above example is provided for illustration purposes only. 1836 Each access token type definition specifies the additional attributes 1837 (if any) sent to the client together with the "access_token" response 1838 parameter. It also defines the HTTP authentication method used to 1839 include the access token when making a protected resource request. 1841 7.2. Bearer Tokens 1843 A Bearer Token is a security token with the property that any party 1844 in possession of the token (a "bearer") can use the token in any way 1845 that any other party in possession of it can. Using a bearer token 1846 does not require a bearer to prove possession of cryptographic key 1847 material (proof-of-possession). 1849 Bearer tokens may be extended to include proof-of-possession 1850 techniques by other specifications. 1852 7.2.1. Authenticated Requests 1854 This section defines two methods of sending Bearer tokens in resource 1855 requetss to resource servers. Clients MUST NOT use more than one 1856 method to transmit the token in each request. 1858 7.2.1.1. Authorization Request Header Field 1860 When sending the access token in the "Authorization" request header 1861 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 1862 authentication scheme to transmit the access token. 1864 For example: 1866 GET /resource HTTP/1.1 1867 Host: server.example.com 1868 Authorization: Bearer mF_9.B5f-4.1JqM 1870 The syntax of the "Authorization" header field for this scheme 1871 follows the usage of the Basic scheme defined in Section 2 of 1872 [RFC2617]. Note that, as with Basic, it does not conform to the 1873 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1874 with the general authentication framework in HTTP 1.1 Authentication 1875 [RFC7235], although it does not follow the preferred practice 1876 outlined therein in order to reflect existing deployments. The 1877 syntax for Bearer credentials is as follows: 1879 b64token = 1*( ALPHA / DIGIT / 1880 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1881 credentials = "Bearer" 1*SP b64token 1883 Clients SHOULD make authenticated requests with a bearer token using 1884 the "Authorization" request header field with the "Bearer" HTTP 1885 authorization scheme. Resource servers MUST support this method. 1887 7.2.1.2. Form-Encoded Body Parameter 1889 When sending the access token in the HTTP request entity-body, the 1890 client adds the access token to the request-body using the 1891 "access_token" parameter. The client MUST NOT use this method unless 1892 all of the following conditions are met: 1894 * The HTTP request entity-header includes the "Content-Type" header 1895 field set to "application/x-www-form-urlencoded". 1897 * The entity-body follows the encoding requirements of the 1898 "application/x-www-form-urlencoded" content-type as defined by 1899 HTML 4.01 [W3C.REC-html401-19991224]. 1901 * The HTTP request entity-body is single-part. 1903 * The content to be encoded in the entity-body MUST consist entirely 1904 of ASCII [USASCII] characters. 1906 * The HTTP request method is one for which the request-body has 1907 defined semantics. In particular, this means that the "GET" 1908 method MUST NOT be used. 1910 The entity-body MAY include other request-specific parameters, in 1911 which case the "access_token" parameter MUST be properly separated 1912 from the request-specific parameters using "&" character(s) (ASCII 1913 code 38). 1915 For example, the client makes the following HTTP request using 1916 transport-layer security: 1918 POST /resource HTTP/1.1 1919 Host: server.example.com 1920 Content-Type: application/x-www-form-urlencoded 1922 access_token=mF_9.B5f-4.1JqM 1924 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1925 except in application contexts where participating clients do not 1926 have access to the "Authorization" request header field. Resource 1927 servers MAY support this method. 1929 7.2.2. The WWW-Authenticate Response Header Field 1931 If the protected resource request does not include authentication 1932 credentials or does not contain an access token that enables access 1933 to the protected resource, the resource server MUST include the HTTP 1934 "WWW-Authenticate" response header field; it MAY include it in 1935 response to other conditions as well. The "WWW-Authenticate" header 1936 field uses the framework defined by HTTP/1.1 [RFC2617]. 1938 All challenges defined by this specification MUST use the auth-scheme 1939 value "Bearer". This scheme MUST be followed by one or more auth- 1940 param values. The auth-param attributes used or defined by this 1941 specification are as follows. Other auth-param attributes MAY be 1942 used as well. 1944 A "realm" attribute MAY be included to indicate the scope of 1945 protection in the manner described in HTTP/1.1 [RFC2617]. The 1946 "realm" attribute MUST NOT appear more than once. 1948 The "scope" attribute is defined in Section 3.3. The "scope" 1949 attribute is a space-delimited list of case-sensitive scope values 1950 indicating the required scope of the access token for accessing the 1951 requested resource. "scope" values are implementation defined; there 1952 is no centralized registry for them; allowed values are defined by 1953 the authorization server. The order of "scope" values is not 1954 significant. In some cases, the "scope" value will be used when 1955 requesting a new access token with sufficient scope of access to 1956 utilize the protected resource. Use of the "scope" attribute is 1957 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 1958 "scope" value is intended for programmatic use and is not meant to be 1959 displayed to end-users. 1961 Two example scope values follow; these are taken from the OpenID 1962 Connect [OpenID.Messages] and the Open Authentication Technology 1963 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 1964 OAuth 2.0 use cases, respectively: 1966 scope="openid profile email" 1967 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 1969 If the protected resource request included an access token and failed 1970 authentication, the resource server SHOULD include the "error" 1971 attribute to provide the client with the reason why the access 1972 request was declined. The parameter value is described in 1973 Section 7.3.1. In addition, the resource server MAY include the 1974 "error_description" attribute to provide developers a human-readable 1975 explanation that is not meant to be displayed to end-users. It also 1976 MAY include the "error_uri" attribute with an absolute URI 1977 identifying a human-readable web page explaining the error. The 1978 "error", "error_description", and "error_uri" attributes MUST NOT 1979 appear more than once. 1981 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 1982 include characters outside the set %x21 / %x23-5B / %x5D-7E for 1983 representing scope values and %x20 for delimiters between scope 1984 values. Values for the "error" and "error_description" attributes 1985 (specified in Appendixes A.7 and A.8) MUST NOT include characters 1986 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 1987 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 1988 the URI-reference syntax and thus MUST NOT include characters outside 1989 the set %x21 / %x23-5B / %x5D-7E. 1991 For example, in response to a protected resource request without 1992 authentication: 1994 HTTP/1.1 401 Unauthorized 1995 WWW-Authenticate: Bearer realm="example" 1997 And in response to a protected resource request with an 1998 authentication attempt using an expired access token: 2000 HTTP/1.1 401 Unauthorized 2001 WWW-Authenticate: Bearer realm="example", 2002 error="invalid_token", 2003 error_description="The access token expired" 2005 7.3. Error Response 2007 If a resource access request fails, the resource server SHOULD inform 2008 the client of the error. While the specifics of such error responses 2009 are beyond the scope of this specification, this document establishes 2010 a common registry in Section 13.4 for error values to be shared among 2011 OAuth token authentication schemes. 2013 New authentication schemes designed primarily for OAuth token 2014 authentication SHOULD define a mechanism for providing an error 2015 status code to the client, in which the error values allowed are 2016 registered in the error registry established by this specification. 2018 Such schemes MAY limit the set of valid error codes to a subset of 2019 the registered values. If the error code is returned using a named 2020 parameter, the parameter name SHOULD be "error". 2022 Other schemes capable of being used for OAuth token authentication, 2023 but not primarily designed for that purpose, MAY bind their error 2024 values to the registry in the same manner. 2026 New authentication schemes MAY choose to also specify the use of the 2027 "error_description" and "error_uri" parameters to return error 2028 information in a manner parallel to their usage in this 2029 specification. 2031 7.3.1. Error Codes 2033 When a request fails, the resource server responds using the 2034 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2035 includes one of the following error codes in the response: 2037 "invalid_request": The request is missing a required parameter, 2038 includes an unsupported parameter or parameter value, repeats the 2039 same parameter, uses more than one method for including an access 2040 token, or is otherwise malformed. The resource server SHOULD 2041 respond with the HTTP 400 (Bad Request) status code. 2043 "invalid_token": The access token provided is expired, revoked, 2044 malformed, or invalid for other reasons. The resource SHOULD 2045 respond with the HTTP 401 (Unauthorized) status code. The client 2046 MAY request a new access token and retry the protected resource 2047 request. 2049 "insufficient_scope": The request requires higher privileges than 2050 provided by the access token. The resource server SHOULD respond 2051 with the HTTP 403 (Forbidden) status code and MAY include the 2052 "scope" attribute with the scope necessary to access the protected 2053 resource. 2055 If the request lacks any authentication information (e.g., the client 2056 was unaware that authentication is necessary or attempted using an 2057 unsupported authentication method), the resource server SHOULD NOT 2058 include an error code or other error information. 2060 For example: 2062 HTTP/1.1 401 Unauthorized 2063 WWW-Authenticate: Bearer realm="example" 2065 7.4. Access Token Security Considerations 2067 7.4.1. Security Threats 2069 The following list presents several common threats against protocols 2070 utilizing some form of tokens. This list of threats is based on NIST 2071 Special Publication 800-63 [NIST800-63]. 2073 7.4.1.1. Token manufacture/modification 2075 An attacker may generate a bogus token or modify the token contents 2076 (such as the authentication or attribute statements) of an existing 2077 token, causing the resource server to grant inappropriate access to 2078 the client. For example, an attacker may modify the token to extend 2079 the validity period; a malicious client may modify the assertion to 2080 gain access to information that they should not be able to view. 2082 7.4.1.2. Token disclosure 2084 Tokens may contain authentication and attribute statements that 2085 include sensitive information. 2087 7.4.1.3. Token redirect 2089 An attacker uses a token generated for consumption by one resource 2090 server to gain access to a different resource server that mistakenly 2091 believes the token to be for it. 2093 7.4.1.4. Token replay 2095 An attacker attempts to use a token that has already been used with 2096 that resource server in the past. 2098 7.4.2. Threat Mitigation 2100 A large range of threats can be mitigated by protecting the contents 2101 of the token by using a digital signature. Alternatively, a bearer 2102 token can contain a reference to authorization information, rather 2103 than encoding the information directly. Such references MUST be 2104 infeasible for an attacker to guess; using a reference may require an 2105 extra interaction between a server and the token issuer to resolve 2106 the reference to the authorization information. The mechanics of 2107 such an interaction are not defined by this specification. 2109 This document does not specify the encoding or the contents of the 2110 token; hence, detailed recommendations about the means of 2111 guaranteeing token integrity protection are outside the scope of this 2112 document. The token integrity protection MUST be sufficient to 2113 prevent the token from being modified. 2115 To deal with token redirect, it is important for the authorization 2116 server to include the identity of the intended recipients (the 2117 audience), typically a single resource server (or a list of resource 2118 servers), in the token. Restricting the use of the token to a 2119 specific scope is also RECOMMENDED. 2121 The authorization server MUST implement TLS. Which version(s) ought 2122 to be implemented will vary over time and will depend on the 2123 widespread deployment and known security vulnerabilities at the time 2124 of implementation. 2126 To protect against token disclosure, confidentiality protection MUST 2127 be applied using TLS with a ciphersuite that provides confidentiality 2128 and integrity protection. This requires that the communication 2129 interaction between the client and the authorization server, as well 2130 as the interaction between the client and the resource server, 2131 utilize confidentiality and integrity protection. Since TLS is 2132 mandatory to implement and to use with this specification, it is the 2133 preferred approach for preventing token disclosure via the 2134 communication channel. For those cases where the client is prevented 2135 from observing the contents of the token, token encryption MUST be 2136 applied in addition to the usage of TLS protection. As a further 2137 defense against token disclosure, the client MUST validate the TLS 2138 certificate chain when making requests to protected resources, 2139 including checking the Certificate Revocation List (CRL) [RFC5280]. 2141 Cookies are typically transmitted in the clear. Thus, any 2142 information contained in them is at risk of disclosure. Therefore, 2143 Bearer tokens MUST NOT be stored in cookies that can be sent in the 2144 clear, as any information in them is at risk of disclosure. See 2145 "HTTP State Management Mechanism" [RFC6265] for security 2146 considerations about cookies. 2148 In some deployments, including those utilizing load balancers, the 2149 TLS connection to the resource server terminates prior to the actual 2150 server that provides the resource. This could leave the token 2151 unprotected between the front-end server where the TLS connection 2152 terminates and the back-end server that provides the resource. In 2153 such deployments, sufficient measures MUST be employed to ensure 2154 confidentiality of the token between the front-end and back-end 2155 servers; encryption of the token is one such possible measure. 2157 To deal with token capture and replay, the following recommendations 2158 are made: First, the lifetime of the token MUST be limited; one means 2159 of achieving this is by putting a validity time field inside the 2160 protected part of the token. Note that using short-lived (one hour 2161 or less) tokens reduces the impact of them being leaked. Second, 2162 confidentiality protection of the exchanges between the client and 2163 the authorization server and between the client and the resource 2164 server MUST be applied. As a consequence, no eavesdropper along the 2165 communication path is able to observe the token exchange. 2166 Consequently, such an on-path adversary cannot replay the token. 2167 Furthermore, when presenting the token to a resource server, the 2168 client MUST verify the identity of that resource server, as per 2169 Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST 2170 validate the TLS certificate chain when making these requests to 2171 protected resources. Presenting the token to an unauthenticated and 2172 unauthorized resource server or failing to validate the certificate 2173 chain will allow adversaries to steal the token and gain unauthorized 2174 access to protected resources. 2176 7.4.3. Summary of Recommendations 2178 7.4.3.1. Safeguard bearer tokens 2180 Client implementations MUST ensure that bearer tokens are not leaked 2181 to unintended parties, as they will be able to use them to gain 2182 access to protected resources. This is the primary security 2183 consideration when using bearer tokens and underlies all the more 2184 specific recommendations that follow. 2186 7.4.3.2. Validate TLS certificate chains 2188 The client MUST validate the TLS certificate chain when making 2189 requests to protected resources. Failing to do so may enable DNS 2190 hijacking attacks to steal the token and gain unintended access. 2192 7.4.3.3. Always use TLS (https) 2194 Clients MUST always use TLS (https) or equivalent transport security 2195 when making requests with bearer tokens. Failing to do so exposes 2196 the token to numerous attacks that could give attackers unintended 2197 access. 2199 7.4.3.4. Don't store bearer tokens in HTTP cookies 2201 Implementations MUST NOT store bearer tokens within cookies that can 2202 be sent in the clear (which is the default transmission mode for 2203 cookies). Implementations that do store bearer tokens in cookies 2204 MUST take precautions against cross-site request forgery. 2206 7.4.3.5. Issue short-lived bearer tokens 2208 Token servers SHOULD issue short-lived (one hour or less) bearer 2209 tokens, particularly when issuing tokens to clients that run within a 2210 web browser or other environments where information leakage may 2211 occur. Using short-lived bearer tokens can reduce the impact of them 2212 being leaked. 2214 7.4.3.6. Issue scoped bearer tokens 2216 Token servers SHOULD issue bearer tokens that contain an audience 2217 restriction, scoping their use to the intended relying party or set 2218 of relying parties. 2220 7.4.3.7. Don't pass bearer tokens in page URLs 2222 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2223 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2224 message headers or message bodies for which confidentiality measures 2225 are taken. Browsers, web servers, and other software may not 2226 adequately secure URLs in the browser history, web server logs, and 2227 other data structures. If bearer tokens are passed in page URLs, 2228 attackers might be able to steal them from the history data, logs, or 2229 other unsecured locations. 2231 7.4.4. Token Replay Prevention 2233 A sender-constrained access token scopes the applicability of an 2234 access token to a certain sender. This sender is obliged to 2235 demonstrate knowledge of a certain secret as prerequisite for the 2236 acceptance of that token at the recipient (e.g., a resource server). 2238 Authorization and resource servers SHOULD use mechanisms for sender- 2239 constrained access tokens to prevent token replay as described in 2240 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2241 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2243 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2244 terminated at an intermediary, refer to Section 4.11 of 2245 [I-D.ietf-oauth-security-topics] for further security advice. 2247 7.4.5. Access Token Privilege Restriction 2249 The privileges associated with an access token SHOULD be restricted 2250 to the minimum required for the particular application or use case. 2251 This prevents clients from exceeding the privileges authorized by the 2252 resource owner. It also prevents users from exceeding their 2253 privileges authorized by the respective security policy. Privilege 2254 restrictions also help to reduce the impact of access token leakage. 2256 In particular, access tokens SHOULD be restricted to certain resource 2257 servers (audience restriction), preferably to a single resource 2258 server. To put this into effect, the authorization server associates 2259 the access token with certain resource servers and every resource 2260 server is obliged to verify, for every request, whether the access 2261 token sent with that request was meant to be used for that particular 2262 resource server. If not, the resource server MUST refuse to serve 2263 the respective request. Clients and authorization servers MAY 2264 utilize the parameters "scope" or "resource" as specified in this 2265 document and [I-D.ietf-oauth-resource-indicators], respectively, to 2266 determine the resource server they want to access. 2268 Additionally, access tokens SHOULD be restricted to certain resources 2269 and actions on resource servers or resources. To put this into 2270 effect, the authorization server associates the access token with the 2271 respective resource and actions and every resource server is obliged 2272 to verify, for every request, whether the access token sent with that 2273 request was meant to be used for that particular action on the 2274 particular resource. If not, the resource server must refuse to 2275 serve the respective request. Clients and authorization servers MAY 2276 utilize the parameter "scope" and "authorization_details" as 2277 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2278 actions. 2280 8. Extensibility 2282 8.1. Defining Access Token Types 2284 Access token types can be defined in one of two ways: registered in 2285 the Access Token Types registry (following the procedures in 2286 Section 13.1), or by using a unique absolute URI as its name. 2288 Types utilizing a URI name SHOULD be limited to vendor-specific 2289 implementations that are not commonly applicable, and are specific to 2290 the implementation details of the resource server where they are 2291 used. 2293 All other types MUST be registered. Type names MUST conform to the 2294 type-name ABNF. If the type definition includes a new HTTP 2295 authentication scheme, the type name SHOULD be identical to the HTTP 2296 authentication scheme name (as defined by [RFC2617]). The token type 2297 "example" is reserved for use in examples. 2299 type-name = 1*name-char 2300 name-char = "-" / "." / "_" / DIGIT / ALPHA 2302 8.2. Defining New Endpoint Parameters 2304 New request or response parameters for use with the authorization 2305 endpoint or the token endpoint are defined and registered in the 2306 OAuth Parameters registry following the procedure in Section 13.2. 2308 Parameter names MUST conform to the param-name ABNF, and parameter 2309 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2310 to the syntax of an existing parameter). 2312 param-name = 1*name-char 2313 name-char = "-" / "." / "_" / DIGIT / ALPHA 2315 Unregistered vendor-specific parameter extensions that are not 2316 commonly applicable and that are specific to the implementation 2317 details of the authorization server where they are used SHOULD 2318 utilize a vendor-specific prefix that is not likely to conflict with 2319 other registered values (e.g., begin with 'companyname_'). 2321 8.3. Defining New Authorization Grant Types 2323 New authorization grant types can be defined by assigning them a 2324 unique absolute URI for use with the "grant_type" parameter. If the 2325 extension grant type requires additional token endpoint parameters, 2326 they MUST be registered in the OAuth Parameters registry as described 2327 by Section 13.2. 2329 8.4. Defining New Authorization Endpoint Response Types 2331 New response types for use with the authorization endpoint are 2332 defined and registered in the Authorization Endpoint Response Types 2333 registry following the procedure in Section 13.3. Response type 2334 names MUST conform to the response-type ABNF. 2336 response-type = response-name *( SP response-name ) 2337 response-name = 1*response-char 2338 response-char = "_" / DIGIT / ALPHA 2340 If a response type contains one or more space characters (%x20), it 2341 is compared as a space-delimited list of values in which the order of 2342 values does not matter. Only one order of values can be registered, 2343 which covers all other arrangements of the same set of values. 2345 For example, an extension can define and register the "code 2346 other_token" response type. Once registered, the same combination 2347 cannot be registered as "other_token code", but both values can be 2348 used to denote the same response type. 2350 8.5. Defining Additional Error Codes 2352 In cases where protocol extensions (i.e., access token types, 2353 extension parameters, or extension grant types) require additional 2354 error codes to be used with the authorization code grant error 2355 response (Section 4.1.2.1), the token error response (Section 5.2), 2356 or the resource access error response (Section 7.3), such error codes 2357 MAY be defined. 2359 Extension error codes MUST be registered (following the procedures in 2360 Section 13.4) if the extension they are used in conjunction with is a 2361 registered access token type, a registered endpoint parameter, or an 2362 extension grant type. Error codes used with unregistered extensions 2363 MAY be registered. 2365 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2366 an identifying name when possible. For example, an error identifying 2367 an invalid value set to the extension parameter "example" SHOULD be 2368 named "example_invalid". 2370 error = 1*error-char 2371 error-char = %x20-21 / %x23-5B / %x5D-7E 2373 9. Security Considerations 2375 As a flexible and extensible framework, OAuth's security 2376 considerations depend on many factors. The following sections 2377 provide implementers with security guidelines focused on the three 2378 client profiles described in Section 2.1: web application, browser- 2379 based application, and native application. 2381 A comprehensive OAuth security model and analysis, as well as 2382 background for the protocol design, is provided by [RFC6819] and 2383 [I-D.ietf-oauth-security-topics]. 2385 9.1. Client Authentication 2387 Authorization servers SHOULD use client authentication if possible. 2389 It is RECOMMENDED to use asymmetric (public-key based) methods for 2390 client authentication such as mTLS [RFC8705] or "private_key_jwt" 2391 [OpenID]. When asymmetric methods for client authentication are 2392 used, authorization servers do not need to store sensitive symmetric 2393 keys, making these methods more robust against a number of attacks. 2395 Authorization server MUST only rely on client authentication if the 2396 process of issuance/registration and distribution of the underlying 2397 credentials ensures their confidentiality. 2399 When client authentication is not possible, the authorization server 2400 SHOULD employ other means to validate the client's identity - for 2401 example, by requiring the registration of the client redirection URI 2402 or enlisting the resource owner to confirm identity. A valid 2403 redirection URI is not sufficient to verify the client's identity 2404 when asking for resource owner authorization but can be used to 2405 prevent delivering credentials to a counterfeit client after 2406 obtaining resource owner authorization. 2408 The authorization server must consider the security implications of 2409 interacting with unauthenticated clients and take measures to limit 2410 the potential exposure of other credentials (e.g., refresh tokens) 2411 issued to such clients. 2413 The privileges an authorization server associates with a certain 2414 client identity MUST depend on the assessment of the overall process 2415 for client identification and client credential lifecycle management. 2416 For example, authentication of a dynamically registered client just 2417 ensures the authorization server it is talking to the same client 2418 again. In contrast, if there is a web application whose developer's 2419 identity was verified, who signed a contract and is issued a client 2420 secret that is only used in a secure backend service, the 2421 authorization server might allow this client to access more sensible 2422 services or to use the client credential grant type. 2424 9.1.1. Client Authentication of Native Apps 2426 Secrets that are statically included as part of an app distributed to 2427 multiple users should not be treated as confidential secrets, as one 2428 user may inspect their copy and learn the shared secret. For this 2429 reason, it is NOT RECOMMENDED for authorization servers to require 2430 client authentication of public native apps clients using a shared 2431 secret, as this serves little value beyond client identification 2432 which is already provided by the "client_id" request parameter. 2434 Authorization servers that still require a statically included shared 2435 secret for native app clients MUST treat the client as a public 2436 client (as defined in Section 2.1), and not accept the secret as 2437 proof of the client's identity. Without additional measures, such 2438 clients are subject to client impersonation (see Section 9.3.1). 2440 9.2. Registration of Native App Clients 2442 Except when using a mechanism like Dynamic Client Registration 2443 [RFC7591] to provision per-instance secrets, native apps are 2444 classified as public clients, as defined in Section 2.1; they MUST be 2445 registered with the authorization server as such. Authorization 2446 servers MUST record the client type in the client registration 2447 details in order to identify and process requests accordingly. 2449 Authorization servers MUST require clients to register their complete 2450 redirect URI (including the path component) and reject authorization 2451 requests that specify a redirect URI that doesn't exactly match the 2452 one that was registered; the exception is loopback redirects, where 2453 an exact match is required except for the port URI component. 2455 For private-use URI scheme-based redirects, authorization servers 2456 SHOULD enforce the requirement in Section 10.3.1 that clients use 2457 schemes that are reverse domain name based. At a minimum, any 2458 private-use URI scheme that doesn't contain a period character (".") 2459 SHOULD be rejected. 2461 In addition to the collision-resistant properties, requiring a URI 2462 scheme based on a domain name that is under the control of the app 2463 can help to prove ownership in the event of a dispute where two apps 2464 claim the same private-use URI scheme (where one app is acting 2465 maliciously). For example, if two apps claimed "com.example.app", 2466 the owner of "example.com" could petition the app store operator to 2467 remove the counterfeit app. Such a petition is harder to prove if a 2468 generic URI scheme was used. 2470 Authorization servers MAY request the inclusion of other platform- 2471 specific information, such as the app package or bundle name, or 2472 other information that may be useful for verifying the calling app's 2473 identity on operating systems that support such functions. 2475 9.3. Client Impersonation 2477 A malicious client can impersonate another client and obtain access 2478 to protected resources if the impersonated client fails to, or is 2479 unable to, keep its client credentials confidential. 2481 The authorization server MUST authenticate the client whenever 2482 possible. If the authorization server cannot authenticate the client 2483 due to the client's nature, the authorization server MUST require the 2484 registration of any redirection URI used for receiving authorization 2485 responses and SHOULD utilize other means to protect resource owners 2486 from such potentially malicious clients. For example, the 2487 authorization server can engage the resource owner to assist in 2488 identifying the client and its origin. 2490 The authorization server SHOULD enforce explicit resource owner 2491 authentication and provide the resource owner with information about 2492 the client and the requested authorization scope and lifetime. It is 2493 up to the resource owner to review the information in the context of 2494 the current client and to authorize or deny the request. 2496 The authorization server SHOULD NOT process repeated authorization 2497 requests automatically (without active resource owner interaction) 2498 without authenticating the client or relying on other measures to 2499 ensure that the repeated request comes from the original client and 2500 not an impersonator. 2502 9.3.1. Impersonation of Native Apps 2504 As stated above, the authorization server SHOULD NOT process 2505 authorization requests automatically without user consent or 2506 interaction, except when the identity of the client can be assured. 2507 This includes the case where the user has previously approved an 2508 authorization request for a given client id - unless the identity of 2509 the client can be proven, the request SHOULD be processed as if no 2510 previous request had been approved. 2512 Measures such as claimed "https" scheme redirects MAY be accepted by 2513 authorization servers as identity proof. Some operating systems may 2514 offer alternative platform-specific identity features that MAY be 2515 accepted, as appropriate. 2517 9.4. Access Tokens 2519 Access token credentials (as well as any confidential access token 2520 attributes) MUST be kept confidential in transit and storage, and 2521 only shared among the authorization server, the resource servers the 2522 access token is valid for, and the client to whom the access token is 2523 issued. Access token credentials MUST only be transmitted using TLS 2524 as described in Section 1.6 with server authentication as defined by 2525 [RFC2818]. 2527 The authorization server MUST ensure that access tokens cannot be 2528 generated, modified, or guessed to produce valid access tokens by 2529 unauthorized parties. 2531 9.4.1. Access Token Privilege Restriction 2533 The client SHOULD request access tokens with the minimal scope 2534 necessary. The authorization server SHOULD take the client identity 2535 into account when choosing how to honor the requested scope and MAY 2536 issue an access token with less rights than requested. 2538 The privileges associated with an access token SHOULD be restricted 2539 to the minimum required for the particular application or use case. 2540 This prevents clients from exceeding the privileges authorized by the 2541 resource owner. It also prevents users from exceeding their 2542 privileges authorized by the respective security policy. Privilege 2543 restrictions also help to reduce the impact of access token leakage. 2545 In particular, access tokens SHOULD be restricted to certain resource 2546 servers (audience restriction), preferably to a single resource 2547 server. To put this into effect, the authorization server associates 2548 the access token with certain resource servers and every resource 2549 server is obliged to verify, for every request, whether the access 2550 token sent with that request was meant to be used for that particular 2551 resource server. If not, the resource server MUST refuse to serve 2552 the respective request. Clients and authorization servers MAY 2553 utilize the parameters "scope" or "resource" as specified in 2554 [RFC8707], respectively, to determine the resource server they want 2555 to access. 2557 9.4.2. Access Token Replay Prevention 2559 Additionally, access tokens SHOULD be restricted to certain resources 2560 and actions on resource servers or resources. To put this into 2561 effect, the authorization server associates the access token with the 2562 respective resource and actions and every resource server is obliged 2563 to verify, for every request, whether the access token sent with that 2564 request was meant to be used for that particular action on the 2565 particular resource. If not, the resource server must refuse to 2566 serve the respective request. Clients and authorization servers MAY 2567 utilize the parameter "scope" and "authorization_details" as 2568 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2569 actions. 2571 Authorization and resource servers SHOULD use mechanisms for sender- 2572 constrained access tokens to prevent token replay as described in 2573 (#pop_tokens). A sender-constrained access token scopes the 2574 applicability of an access token to a certain sender. This sender is 2575 obliged to demonstrate knowledge of a certain secret as prerequisite 2576 for the acceptance of that token at the recipient (e.g., a resource 2577 server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2578 RECOMMENDED. 2580 9.5. Refresh Tokens 2582 Authorization servers MAY issue refresh tokens to clients. 2584 Refresh tokens MUST be kept confidential in transit and storage, and 2585 shared only among the authorization server and the client to whom the 2586 refresh tokens were issued. The authorization server MUST maintain 2587 the binding between a refresh token and the client to whom it was 2588 issued. Refresh tokens MUST only be transmitted using TLS as 2589 described in Section 1.6 with server authentication as defined by 2590 [RFC2818]. 2592 The authorization server MUST verify the binding between the refresh 2593 token and client identity whenever the client identity can be 2594 authenticated. When client authentication is not possible, the 2595 authorization server MUST issue sender-constrained refresh tokens or 2596 use refresh token rotation as described in 2597 (#refresh_token_protection). 2599 The authorization server MUST ensure that refresh tokens cannot be 2600 generated, modified, or guessed to produce valid refresh tokens by 2601 unauthorized parties. 2603 9.6. Protecting Redirect-Based Flows 2605 When comparing client redirect URIs against pre-registered URIs, 2606 authorization servers MUST utilize exact string matching. This 2607 measure contributes to the prevention of leakage of authorization 2608 codes and access tokens (see (#insufficient_uri_validation)). It can 2609 also help to detect mix-up attacks (see (#mix_up)). 2611 Clients MUST NOT expose URLs that forward the user's browser to 2612 arbitrary URIs obtained from a query parameter ("open redirector"). 2613 Open redirectors can enable exfiltration of authorization codes and 2614 access tokens, see (#open_redirector_on_client). 2616 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2617 context, CSRF refers to requests to the redirection endpoint that do 2618 not originate at the authorization server, but a malicious third 2619 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2620 have ensured that the authorization server supports PKCE MAY rely the 2621 CSRF protection provided by PKCE. In OpenID Connect flows, the 2622 "nonce" parameter provides CSRF protection. Otherwise, one-time use 2623 CSRF tokens carried in the "state" parameter that are securely bound 2624 to the user agent MUST be used for CSRF protection (see 2625 (#csrf_countermeasures)). 2627 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2628 process redirect responses of the authorization server they sent the 2629 respective request to and from the same user agent this authorization 2630 request was initiated with. Clients MUST store the authorization 2631 server they sent an authorization request to and bind this 2632 information to the user agent and check that the authorization 2633 request was received from the correct authorization server. Clients 2634 MUST ensure that the subsequent token request, if applicable, is sent 2635 to the same authorization server. Clients SHOULD use distinct 2636 redirect URIs for each authorization server as a means to identify 2637 the authorization server a particular response came from. 2639 An AS that redirects a request potentially containing user 2640 credentials MUST avoid forwarding these user credentials accidentally 2641 (see (#redirect_307) for details). 2643 9.6.1. Loopback Redirect Considerations in Native Apps 2645 Loopback interface redirect URIs use the "http" scheme (i.e., without 2646 Transport Layer Security (TLS)). This is acceptable for loopback 2647 interface redirect URIs as the HTTP request never leaves the device. 2649 Clients should open the network port only when starting the 2650 authorization request and close it once the response is returned. 2652 Clients should listen on the loopback network interface only, in 2653 order to avoid interference by other network actors. 2655 While redirect URIs using localhost (i.e., 2656 "http://localhost:{port}/{path}") function similarly to loopback IP 2657 redirects described in Section 10.3.3, the use of "localhost" is NOT 2658 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2659 rather than "localhost" avoids inadvertently listening on network 2660 interfaces other than the loopback interface. It is also less 2661 susceptible to client-side firewalls and misconfigured host name 2662 resolution on the user's device. 2664 9.7. Authorization Codes 2666 The transmission of authorization codes MUST be made over a secure 2667 channel, and the client MUST require the use of TLS with its 2668 redirection URI if the URI identifies a network resource. Since 2669 authorization codes are transmitted via user-agent redirections, they 2670 could potentially be disclosed through user-agent history and HTTP 2671 referrer headers. 2673 Authorization codes MUST be short lived and single-use. If the 2674 authorization server observes multiple attempts to exchange an 2675 authorization code for an access token, the authorization server 2676 SHOULD attempt to revoke all refresh and access tokens already 2677 granted based on the compromised authorization code. 2679 If the client can be authenticated, the authorization servers MUST 2680 authenticate the client and ensure that the authorization code was 2681 issued to the same client. 2683 Clients MUST prevent injection (replay) of authorization codes into 2684 the authorization response by attackers. The use of PKCE is 2685 RECOMMENDED to this end. The OpenID Connect "nonce" parameter and ID 2686 Token Claim [OpenID] MAY be used as well. The PKCE challenge or 2687 OpenID Connect "nonce" MUST be transaction-specific and securely 2688 bound to the client and the user agent in which the transaction was 2689 started. 2691 Note: although PKCE so far was designed as a mechanism to protect 2692 native apps, this advice applies to all kinds of OAuth clients, 2693 including web applications. 2695 When using PKCE, clients SHOULD use PKCE code challenge methods that 2696 do not expose the PKCE verifier in the authorization request. 2697 Otherwise, attackers that can read the authorization request (cf. 2698 Attacker A4 in (#secmodel)) can break the security provided by PKCE. 2699 Currently, "S256" is the only such method. 2701 Authorization servers MUST support PKCE. 2703 Authorization servers MUST provide a way to detect their support for 2704 PKCE. To this end, they MUST either (a) publish the element 2705 "code_challenge_methods_supported" in their AS metadata ([RFC8418]) 2706 containing the supported PKCE challenge methods (which can be used by 2707 the client to detect PKCE support) or (b) provide a deployment- 2708 specific way to ensure or determine PKCE support by the AS. 2710 9.8. Request Confidentiality 2712 Access tokens, refresh tokens, authorization codes, and client 2713 credentials MUST NOT be transmitted in the clear. 2715 The "state" and "scope" parameters SHOULD NOT include sensitive 2716 client or resource owner information in plain text, as they can be 2717 transmitted over insecure channels or stored insecurely. 2719 9.9. Ensuring Endpoint Authenticity 2721 In order to prevent man-in-the-middle attacks, the authorization 2722 server MUST require the use of TLS with server authentication as 2723 defined by [RFC2818] for any request sent to the authorization and 2724 token endpoints. The client MUST validate the authorization server's 2725 TLS certificate as defined by [RFC6125] and in accordance with its 2726 requirements for server identity authentication. 2728 9.10. Credentials-Guessing Attacks 2730 The authorization server MUST prevent attackers from guessing access 2731 tokens, authorization codes, refresh tokens, resource owner 2732 passwords, and client credentials. 2734 The probability of an attacker guessing generated tokens (and other 2735 credentials not intended for handling by end-users) MUST be less than 2736 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2738 The authorization server MUST utilize other means to protect 2739 credentials intended for end-user usage. 2741 9.11. Phishing Attacks 2743 Wide deployment of this and similar protocols may cause end-users to 2744 become inured to the practice of being redirected to websites where 2745 they are asked to enter their passwords. If end-users are not 2746 careful to verify the authenticity of these websites before entering 2747 their credentials, it will be possible for attackers to exploit this 2748 practice to steal resource owners' passwords. 2750 Service providers should attempt to educate end-users about the risks 2751 phishing attacks pose and should provide mechanisms that make it easy 2752 for end-users to confirm the authenticity of their sites. Client 2753 developers should consider the security implications of how they 2754 interact with the user-agent (e.g., external, embedded), and the 2755 ability of the end-user to verify the authenticity of the 2756 authorization server. 2758 To reduce the risk of phishing attacks, the authorization servers 2759 MUST require the use of TLS on every endpoint used for end-user 2760 interaction. 2762 9.12. Fake External User-Agents in Native Apps 2764 The native app that is initiating the authorization request has a 2765 large degree of control over the user interface and can potentially 2766 present a fake external user-agent, that is, an embedded user-agent 2767 made to appear as an external user-agent. 2769 When all good actors are using external user-agents, the advantage is 2770 that it is possible for security experts to detect bad actors, as 2771 anyone faking an external user-agent is provably bad. On the other 2772 hand, if good and bad actors alike are using embedded user-agents, 2773 bad actors don't need to fake anything, making them harder to detect. 2774 Once a malicious app is detected, it may be possible to use this 2775 knowledge to blacklist the app's signature in malware scanning 2776 software, take removal action (in the case of apps distributed by app 2777 stores) and other steps to reduce the impact and spread of the 2778 malicious app. 2780 Authorization servers can also directly protect against fake external 2781 user-agents by requiring an authentication factor only available to 2782 true external user-agents. 2784 Users who are particularly concerned about their security when using 2785 in-app browser tabs may also take the additional step of opening the 2786 request in the full browser from the in-app browser tab and complete 2787 the authorization there, as most implementations of the in-app 2788 browser tab pattern offer such functionality. 2790 9.13. Malicious External User-Agents in Native Apps 2792 If a malicious app is able to configure itself as the default handler 2793 for "https" scheme URIs in the operating system, it will be able to 2794 intercept authorization requests that use the default browser and 2795 abuse this position of trust for malicious ends such as phishing the 2796 user. 2798 This attack is not confined to OAuth; a malicious app configured in 2799 this way would present a general and ongoing risk to the user beyond 2800 OAuth usage by native apps. Many operating systems mitigate this 2801 issue by requiring an explicit user action to change the default 2802 handler for "http" and "https" scheme URIs. 2804 9.14. Cross-Site Request Forgery 2806 An attacker might attempt to inject a request to the redirect URI of 2807 the legitimate client on the victim's device, e.g., to cause the 2808 client to access resources under the attacker's control. This is a 2809 variant of an attack known as Cross-Site Request Forgery (CSRF). 2811 The traditional countermeasure are CSRF tokens that are bound to the 2812 user agent and passed in the "state" parameter to the authorization 2813 server as described in [RFC6819]. The same protection is provided by 2814 PKCE or the OpenID Connect "nonce" value. 2816 When using PKCE instead of "state" or "nonce" for CSRF protection, it 2817 is important to note that: 2819 * Clients MUST ensure that the AS supports PKCE before using PKCE 2820 for CSRF protection. If an authorization server does not support 2821 PKCE, "state" or "nonce" MUST be used for CSRF protection. 2823 * If "state" is used for carrying application state, and integrity 2824 of its contents is a concern, clients MUST protect "state" against 2825 tampering and swapping. This can be achieved by binding the 2826 contents of state to the browser session and/or signed/encrypted 2827 state values [I-D.bradley-oauth-jwt-encoded-state]. 2829 AS therefore MUST provide a way to detect their support for PKCE 2830 either via AS metadata according to [RFC8414] or provide a 2831 deployment-specific way to ensure or determine PKCE support. 2833 9.15. Clickjacking 2835 As described in Section 4.4.1.9 of [RFC6819], the authorization 2836 request is susceptible to clickjacking. An attacker can use this 2837 vector to obtain the user's authentication credentials, change the 2838 scope of access granted to the client, and potentially access the 2839 user's resources. 2841 Authorization servers MUST prevent clickjacking attacks. Multiple 2842 countermeasures are described in [RFC6819], including the use of the 2843 X-Frame-Options HTTP response header field and frame-busting 2844 JavaScript. In addition to those, authorization servers SHOULD also 2845 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2847 To be effective, CSP must be used on the authorization endpoint and, 2848 if applicable, other endpoints used to authenticate the user and 2849 authorize the client (e.g., the device authorization endpoint, login 2850 pages, error pages, etc.). This prevents framing by unauthorized 2851 origins in user agents that support CSP. The client MAY permit being 2852 framed by some other origin than the one used in its redirection 2853 endpoint. For this reason, authorization servers SHOULD allow 2854 administrators to configure allowed origins for particular clients 2855 and/or for clients to register these dynamically. 2857 Using CSP allows authorization servers to specify multiple origins in 2858 a single response header field and to constrain these using flexible 2859 patterns (see [CSP-2] for details). Level 2 of this standard 2860 provides a robust mechanism for protecting against clickjacking by 2861 using policies that restrict the origin of frames (using "frame- 2862 ancestors") together with those that restrict the sources of scripts 2863 allowed to execute on an HTML page (by using "script-src"). A non- 2864 normative example of such a policy is shown in the following listing: 2866 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 2867 https://ext.example.org:8000 Content-Security-Policy: script-src 2868 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 2870 Because some user agents do not support [CSP-2], this technique 2871 SHOULD be combined with others, including those described in 2872 [RFC6819], unless such legacy user agents are explicitly unsupported 2873 by the authorization server. Even in such cases, additional 2874 countermeasures SHOULD still be employed. 2876 9.16. Code Injection and Input Validation 2878 A code injection attack occurs when an input or otherwise external 2879 variable is used by an application unsanitized and causes 2880 modification to the application logic. This may allow an attacker to 2881 gain access to the application device or its data, cause denial of 2882 service, or introduce a wide range of malicious side-effects. 2884 The authorization server and client MUST sanitize (and validate when 2885 possible) any value received - in particular, the value of the 2886 "state" and "redirect_uri" parameters. 2888 9.17. Open Redirectors 2890 The following attacks can occur when an AS or client has an open 2891 redirector. An open redirector is an endpoint that forwards a user's 2892 browser to an arbitrary URI obtained from a query parameter. 2894 9.17.1. Client as Open Redirector 2896 Clients MUST NOT expose open redirectors. Attackers may use open 2897 redirectors to produce URLs pointing to the client and utilize them 2898 to exfiltrate authorization codes and access tokens, as described in 2899 (#redir_uri_open_redir). Another abuse case is to produce URLs that 2900 appear to point to the client. This might trick users into trusting 2901 the URL and follow it in their browser. This can be abused for 2902 phishing. 2904 In order to prevent open redirection, clients should only redirect if 2905 the target URLs are whitelisted or if the origin and integrity of a 2906 request can be authenticated. Countermeasures against open 2907 redirection are described by OWASP [owasp_redir]. 2909 9.17.2. Authorization Server as Open Redirector 2911 Just as with clients, attackers could try to utilize a user's trust 2912 in the authorization server (and its URL in particular) for 2913 performing phishing attacks. OAuth authorization servers regularly 2914 redirect users to other web sites (the clients), but must do so in a 2915 safe way. 2917 Section 4.1.2.1 already prevents open redirects by stating that the 2918 AS MUST NOT automatically redirect the user agent in case of an 2919 invalid combination of "client_id" and "redirect_uri". 2921 However, an attacker could also utilize a correctly registered 2922 redirect URI to perform phishing attacks. The attacker could, for 2923 example, register a client via dynamic client registration [RFC7591] 2924 and intentionally send an erroneous authorization request, e.g., by 2925 using an invalid scope value, thus instructing the AS to redirect the 2926 user agent to its phishing site. 2928 The AS MUST take precautions to prevent this threat. Based on its 2929 risk assessment, the AS needs to decide whether it can trust the 2930 redirect URI and SHOULD only automatically redirect the user agent if 2931 it trusts the redirect URI. If the URI is not trusted, the AS MAY 2932 inform the user and rely on the user to make the correct decision. 2934 9.18. Authorization Server Mix-Up Mitigation in Native Apps 2936 (TODO: merge this with the regular mix-up section when it is brought 2937 in) 2939 To protect against a compromised or malicious authorization server 2940 attacking another authorization server used by the same app, it is 2941 REQUIRED that a unique redirect URI is used for each authorization 2942 server used by the app (for example, by varying the path component), 2943 and that authorization responses are rejected if the redirect URI 2944 they were received on doesn't match the redirect URI in an outgoing 2945 authorization request. 2947 The native app MUST store the redirect URI used in the authorization 2948 request with the authorization session data (i.e., along with "state" 2949 and other related data) and MUST verify that the URI on which the 2950 authorization response was received exactly matches it. 2952 The requirement of Section 9.2, specifically that authorization 2953 servers reject requests with URIs that don't match what was 2954 registered, is also required to prevent such attacks. 2956 9.19. Embedded User Agents in Native Apps 2958 Embedded user-agents are a technically possible method for 2959 authorizing native apps. These embedded user-agents are unsafe for 2960 use by third parties to the authorization server by definition, as 2961 the app that hosts the embedded user-agent can access the user's full 2962 authentication credential, not just the OAuth authorization grant 2963 that was intended for the app. 2965 In typical web-view-based implementations of embedded user-agents, 2966 the host application can record every keystroke entered in the login 2967 form to capture usernames and passwords, automatically submit forms 2968 to bypass user consent, and copy session cookies and use them to 2969 perform authenticated actions as the user. 2971 Even when used by trusted apps belonging to the same party as the 2972 authorization server, embedded user-agents violate the principle of 2973 least privilege by having access to more powerful credentials than 2974 they need, potentially increasing the attack surface. 2976 Encouraging users to enter credentials in an embedded user-agent 2977 without the usual address bar and visible certificate validation 2978 features that browsers have makes it impossible for the user to know 2979 if they are signing in to the legitimate site; even when they are, it 2980 trains them that it's OK to enter credentials without validating the 2981 site first. 2983 Aside from the security concerns, embedded user-agents do not share 2984 the authentication state with other apps or the browser, requiring 2985 the user to log in for every authorization request, which is often 2986 considered an inferior user experience. 2988 9.20. Other Recommendations 2990 Authorization servers SHOULD NOT allow clients to influence their 2991 "client_id" or "sub" value or any other claim if that can cause 2992 confusion with a genuine resource owner (see 2993 (#client_impersonating)). 2995 10. Native Applications 2997 Native applications are clients installed and executed on the device 2998 used by the resource owner (i.e., desktop application, native mobile 2999 application). Native applications require special consideration 3000 related to security, platform capabilities, and overall end-user 3001 experience. 3003 The authorization endpoint requires interaction between the client 3004 and the resource owner's user-agent. The best current practice is to 3005 perform the OAuth authorization request in an external user-agent 3006 (typically the browser) rather than an embedded user-agent (such as 3007 one implemented with web-views). 3009 The native application can capture the response from the 3010 authorization server using a redirection URI with a scheme registered 3011 with the operating system to invoke the client as the handler, manual 3012 copy-and-paste of the credentials, running a local web server, 3013 installing a user-agent extension, or by providing a redirection URI 3014 identifying a server-hosted resource under the client's control, 3015 which in turn makes the response available to the native application. 3017 Previously, it was common for native apps to use embedded user-agents 3018 (commonly implemented with web-views) for OAuth authorization 3019 requests. That approach has many drawbacks, including the host app 3020 being able to copy user credentials and cookies as well as the user 3021 needing to authenticate from scratch in each app. See Section 9.19 3022 for a deeper analysis of the drawbacks of using embedded user-agents 3023 for OAuth. 3025 Native app authorization requests that use the browser are more 3026 secure and can take advantage of the user's authentication state. 3027 Being able to use the existing authentication session in the browser 3028 enables single sign-on, as users don't need to authenticate to the 3029 authorization server each time they use a new app (unless required by 3030 the authorization server policy). 3032 Supporting authorization flows between a native app and the browser 3033 is possible without changing the OAuth protocol itself, as the OAuth 3034 authorization request and response are already defined in terms of 3035 URIs. This encompasses URIs that can be used for inter-app 3036 communication. Some OAuth server implementations that assume all 3037 clients are confidential web clients will need to add an 3038 understanding of public native app clients and the types of redirect 3039 URIs they use to support this best practice. 3041 10.1. Using Inter-App URI Communication for OAuth in Native Apps 3043 Just as URIs are used for OAuth on the web to initiate the 3044 authorization request and return the authorization response to the 3045 requesting website, URIs can be used by native apps to initiate the 3046 authorization request in the device's browser and return the response 3047 to the requesting native app. 3049 By adopting the same methods used on the web for OAuth, benefits seen 3050 in the web context like the usability of a single sign-on session and 3051 the security of a separate authentication context are likewise gained 3052 in the native app context. Reusing the same approach also reduces 3053 the implementation complexity and increases interoperability by 3054 relying on standards-based web flows that are not specific to a 3055 particular platform. 3057 Native apps MUST use an external user-agent to perform OAuth 3058 authorization requests. This is achieved by opening the 3059 authorization request in the browser (detailed in Section 10.2) and 3060 using a redirect URI that will return the authorization response back 3061 to the native app (defined in Section 10.3). 3063 10.2. Initiating the Authorization Request from a Native App 3065 Native apps needing user authorization create an authorization 3066 request URI with the authorization code grant type per Section 4.1 3067 using a redirect URI capable of being received by the native app. 3069 The function of the redirect URI for a native app authorization 3070 request is similar to that of a web-based authorization request. 3071 Rather than returning the authorization response to the OAuth 3072 client's server, the redirect URI used by a native app returns the 3073 response to the app. Several options for a redirect URI that will 3074 return the authorization response to the native app in different 3075 platforms are documented in Section 10.3. Any redirect URI that 3076 allows the app to receive the URI and inspect its parameters is 3077 viable. 3079 After constructing the authorization request URI, the app uses 3080 platform-specific APIs to open the URI in an external user-agent. 3081 Typically, the external user-agent used is the default browser, that 3082 is, the application configured for handling "http" and "https" scheme 3083 URIs on the system; however, different browser selection criteria and 3084 other categories of external user-agents MAY be used. 3086 This best practice focuses on the browser as the RECOMMENDED external 3087 user-agent for native apps. An external user-agent designed 3088 specifically for user authorization and capable of processing 3089 authorization requests and responses like a browser MAY also be used. 3090 Other external user-agents, such as a native app provided by the 3091 authorization server may meet the criteria set out in this best 3092 practice, including using the same redirection URI properties, but 3093 their use is out of scope for this specification. 3095 Some platforms support a browser feature known as "in-app browser 3096 tabs", where an app can present a tab of the browser within the app 3097 context without switching apps, but still retain key benefits of the 3098 browser such as a shared authentication state and security context. 3099 On platforms where they are supported, it is RECOMMENDED, for 3100 usability reasons, that apps use in-app browser tabs for the 3101 authorization request. 3103 10.3. Receiving the Authorization Response in a Native App 3105 There are several redirect URI options available to native apps for 3106 receiving the authorization response from the browser, the 3107 availability and user experience of which varies by platform. 3109 To fully support native apps, authorization servers MUST offer at 3110 least the three redirect URI options described in the following 3111 subsections to native apps. Native apps MAY use whichever redirect 3112 option suits their needs best, taking into account platform-specific 3113 implementation details. 3115 10.3.1. Private-Use URI Scheme Redirection 3117 Many mobile and desktop computing platforms support inter-app 3118 communication via URIs by allowing apps to register private-use URI 3119 schemes (sometimes colloquially referred to as "custom URL schemes") 3120 like "com.example.app". When the browser or another app attempts to 3121 load a URI with a private-use URI scheme, the app that registered it 3122 is launched to handle the request. 3124 To perform an authorization request with a private-use URI scheme 3125 redirect, the native app launches the browser with a standard 3126 authorization request, but one where the redirection URI utilizes a 3127 private-use URI scheme it registered with the operating system. 3129 When choosing a URI scheme to associate with the app, apps MUST use a 3130 URI scheme based on a domain name under their control, expressed in 3131 reverse order, as recommended by Section 3.8 of [RFC7595] for 3132 private-use URI schemes. 3134 For example, an app that controls the domain name "app.example.com" 3135 can use "com.example.app" as their scheme. Some authorization 3136 servers assign client identifiers based on domain names, for example, 3137 "client1234.usercontent.example.net", which can also be used as the 3138 domain name for the scheme when reversed in the same manner. A 3139 scheme such as "myapp", however, would not meet this requirement, as 3140 it is not based on a domain name. 3142 When there are multiple apps by the same publisher, care must be 3143 taken so that each scheme is unique within that group. On platforms 3144 that use app identifiers based on reverse-order domain names, those 3145 identifiers can be reused as the private-use URI scheme for the OAuth 3146 redirect to help avoid this problem. 3148 Following the requirements of Section 3.2 of [RFC3986], as there is 3149 no naming authority for private-use URI scheme redirects, only a 3150 single slash ("/") appears after the scheme component. A complete 3151 example of a redirect URI utilizing a private-use URI scheme is: 3153 com.example.app:/oauth2redirect/example-provider 3155 When the authorization server completes the request, it redirects to 3156 the client's redirection URI as it would normally. As the 3157 redirection URI uses a private-use URI scheme, it results in the 3158 operating system launching the native app, passing in the URI as a 3159 launch parameter. Then, the native app uses normal processing for 3160 the authorization response. 3162 10.3.2. Claimed "https" Scheme URI Redirection 3164 Some operating systems allow apps to claim "https" scheme [RFC7230] 3165 URIs in the domains they control. When the browser encounters a 3166 claimed URI, instead of the page being loaded in the browser, the 3167 native app is launched with the URI supplied as a launch parameter. 3169 Such URIs can be used as redirect URIs by native apps. They are 3170 indistinguishable to the authorization server from a regular web- 3171 based client redirect URI. An example is: 3173 https://app.example.com/oauth2redirect/example-provider 3175 As the redirect URI alone is not enough to distinguish public native 3176 app clients from confidential web clients, it is REQUIRED in 3177 Section 9.2 that the client type be recorded during client 3178 registration to enable the server to determine the client type and 3179 act accordingly. 3181 App-claimed "https" scheme redirect URIs have some advantages 3182 compared to other native app redirect options in that the identity of 3183 the destination app is guaranteed to the authorization server by the 3184 operating system. For this reason, native apps SHOULD use them over 3185 the other options where possible. 3187 10.3.3. Loopback Interface Redirection 3189 Native apps that are able to open a port on the loopback network 3190 interface without needing special permissions (typically, those on 3191 desktop operating systems) can use the loopback interface to receive 3192 the OAuth redirect. 3194 Loopback redirect URIs use the "http" scheme and are constructed with 3195 the loopback IP literal and whatever port the client is listening on. 3197 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3198 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3199 IPv4 loopback interface with a randomly assigned port: 3201 http://127.0.0.1:51004/oauth2redirect/example-provider 3203 An example redirect using the IPv6 loopback interface with a randomly 3204 assigned port: 3206 http://[::1]:61023/oauth2redirect/example-provider 3208 The authorization server MUST allow any port to be specified at the 3209 time of the request for loopback IP redirect URIs, to accommodate 3210 clients that obtain an available ephemeral port from the operating 3211 system at the time of the request. 3213 Clients SHOULD NOT assume that the device supports a particular 3214 version of the Internet Protocol. It is RECOMMENDED that clients 3215 attempt to bind to the loopback interface using both IPv4 and IPv6 3216 and use whichever is available. 3218 11. Browser-Based Apps 3220 Browser-based apps are are clients that run in a web browser, 3221 typically written in JavaScript, also known as "single-page apps". 3222 These types of apps have particular security considerations similar 3223 to native apps. 3225 TODO: Bring in the normative text of the browser-based apps BCP when 3226 it is finalized. 3228 12. Differences from OAuth 2.0 3230 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3231 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3232 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3233 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3234 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3235 ([RFC6750]). 3237 Where a later draft updates or obsoletes functionality found in the 3238 original [RFC6749], that functionality in this draft is updated with 3239 the normative changes described in a later draft, or removed 3240 entirely. 3242 A non-normative list of changes from OAuth 2.0 is listed below: 3244 * The authorization code grant is extended with the functionality 3245 from PKCE ([RFC7636]) such that the only method of using the 3246 authorization code grant according to this specification requires 3247 the addition of the PKCE mechanism 3249 * Redirect URIs must be compared using exact string matching as per 3250 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3252 * The Implicit grant ("response_type=token") is omitted from this 3253 specification as per Section 2.1.2 of 3254 [I-D.ietf-oauth-security-topics] 3256 * The Resource Owner Password Credentials grant is omitted from this 3257 specification as per Section 2.4 of 3258 [I-D.ietf-oauth-security-topics] 3260 * Bearer token usage omits the use of bearer tokens in the query 3261 string of URIs as per Section 4.3.2 of 3262 [I-D.ietf-oauth-security-topics] 3264 * Refresh tokens must either be sender-constrained or one-time use 3265 as per Section 4.12.2 of [I-D.ietf-oauth-security-topics] 3267 13. IANA Considerations 3269 13.1. OAuth Access Token Types Registry 3271 This specification establishes the OAuth Access Token Types registry. 3273 Access token types are registered with a Specification Required 3274 ([RFC5226]) after a two-week review period on the oauth-ext- 3275 review@ietf.org mailing list, on the advice of one or more Designated 3276 Experts. However, to allow for the allocation of values prior to 3277 publication, the Designated Expert(s) may approve registration once 3278 they are satisfied that such a specification will be published. 3280 Registration requests must be sent to the oauth-ext-review@ietf.org 3281 mailing list for review and comment, with an appropriate subject 3282 (e.g., "Request for access token type: example"). 3284 Within the review period, the Designated Expert(s) will either 3285 approve or deny the registration request, communicating this decision 3286 to the review list and IANA. Denials should include an explanation 3287 and, if applicable, suggestions as to how to make the request 3288 successful. 3290 IANA must only accept registry updates from the Designated Expert(s) 3291 and should direct all requests for registration to the review mailing 3292 list. 3294 13.1.1. Registration Template 3296 Type name: The name requested (e.g., "example"). 3298 Additional Token Endpoint Response Parameters: Additional response 3299 parameters returned together with the "access_token" parameter. 3300 New parameters MUST be separately registered in the OAuth 3301 Parameters registry as described by Section 13.2. 3303 HTTP Authentication Scheme(s): The HTTP authentication scheme 3304 name(s), if any, used to authenticate protected resource requests 3305 using access tokens of this type. 3307 Change controller: For Standards Track RFCs, state "IETF". For 3308 others, give the name of the responsible party. Other details 3309 (e.g., postal address, email address, home page URI) may also be 3310 included. 3312 Specification document(s): Reference to the document(s) that specify 3313 the parameter, preferably including a URI that can be used to 3314 retrieve a copy of the document(s). An indication of the relevant 3315 sections may also be included but is not required. 3317 13.1.2. Initial Registry Contents 3319 The OAuth Access Token Types registry's initial contents are: 3321 * Type name: Bearer 3323 * Additional Token Endpoint Response Parameters: (none) 3324 * HTTP Authentication Scheme(s): Bearer 3326 * Change controller: IETF 3328 * Specification document(s): OAuth 2.1 3330 13.2. OAuth Parameters Registry 3332 This specification establishes the OAuth Parameters registry. 3334 Additional parameters for inclusion in the authorization endpoint 3335 request, the authorization endpoint response, the token endpoint 3336 request, or the token endpoint response are registered with a 3337 Specification Required ([RFC5226]) after a two-week review period on 3338 the oauth-ext-review@ietf.org mailing list, on the advice of one or 3339 more Designated Experts. However, to allow for the allocation of 3340 values prior to publication, the Designated Expert(s) may approve 3341 registration once they are satisfied that such a specification will 3342 be published. 3344 Registration requests must be sent to the oauth-ext-review@ietf.org 3345 mailing list for review and comment, with an appropriate subject 3346 (e.g., "Request for parameter: example"). 3348 Within the review period, the Designated Expert(s) will either 3349 approve or deny the registration request, communicating this decision 3350 to the review list and IANA. Denials should include an explanation 3351 and, if applicable, suggestions as to how to make the request 3352 successful. 3354 IANA must only accept registry updates from the Designated Expert(s) 3355 and should direct all requests for registration to the review mailing 3356 list. 3358 13.2.1. Registration Template 3360 Parameter name: The name requested (e.g., "example"). 3362 Parameter usage location: The location(s) where parameter can be 3363 used. The possible locations are authorization request, 3364 authorization response, token request, or token response. 3366 Change controller: For Standards Track RFCs, state "IETF". For 3367 others, give the name of the responsible party. Other details 3368 (e.g., postal address, email address, home page URI) may also be 3369 included. 3371 Specification document(s): Reference to the document(s) that specify 3372 the parameter, preferably including a URI that can be used to 3373 retrieve a copy of the document(s). An indication of the relevant 3374 sections may also be included but is not required. 3376 13.2.2. Initial Registry Contents 3378 The OAuth Parameters registry's initial contents are: 3380 * Parameter name: client_id 3382 * Parameter usage location: authorization request, token request 3384 * Change controller: IETF 3386 * Specification document(s): RFC 6749 3388 * Parameter name: client_secret 3390 * Parameter usage location: token request 3392 * Change controller: IETF 3394 * Specification document(s): RFC 6749 3396 * Parameter name: response_type 3398 * Parameter usage location: authorization request 3400 * Change controller: IETF 3402 * Specification document(s): RFC 6749 3404 * Parameter name: redirect_uri 3406 * Parameter usage location: authorization request, token request 3408 * Change controller: IETF 3410 * Specification document(s): RFC 6749 3412 * Parameter name: scope 3414 * Parameter usage location: authorization request, authorization 3415 response, token request, token response 3417 * Change controller: IETF 3418 * Specification document(s): RFC 6749 3420 * Parameter name: state 3422 * Parameter usage location: authorization request, authorization 3423 response 3425 * Change controller: IETF 3427 * Specification document(s): RFC 6749 3429 * Parameter name: code 3431 * Parameter usage location: authorization response, token request 3433 * Change controller: IETF 3435 * Specification document(s): RFC 6749 3437 * Parameter name: error_description 3439 * Parameter usage location: authorization response, token response 3441 * Change controller: IETF 3443 * Specification document(s): RFC 6749 3445 * Parameter name: error_uri 3447 * Parameter usage location: authorization response, token response 3449 * Change controller: IETF 3451 * Specification document(s): RFC 6749 3453 * Parameter name: grant_type 3455 * Parameter usage location: token request 3457 * Change controller: IETF 3459 * Specification document(s): RFC 6749 3461 * Parameter name: access_token 3463 * Parameter usage location: authorization response, token response 3465 * Change controller: IETF 3466 * Specification document(s): RFC 6749 3468 * Parameter name: token_type 3470 * Parameter usage location: authorization response, token response 3472 * Change controller: IETF 3474 * Specification document(s): RFC 6749 3476 * Parameter name: expires_in 3478 * Parameter usage location: authorization response, token response 3480 * Change controller: IETF 3482 * Specification document(s): RFC 6749 3484 * Parameter name: username 3486 * Parameter usage location: token request 3488 * Change controller: IETF 3490 * Specification document(s): RFC 6749 3492 * Parameter name: password 3494 * Parameter usage location: token request 3496 * Change controller: IETF 3498 * Specification document(s): RFC 6749 3500 * Parameter name: refresh_token 3502 * Parameter usage location: token request, token response 3504 * Change controller: IETF 3506 * Specification document(s): RFC 6749 3508 13.3. OAuth Authorization Endpoint Response Types Registry 3510 This specification establishes the OAuth Authorization Endpoint 3511 Response Types registry. 3513 Additional response types for use with the authorization endpoint are 3514 registered with a Specification Required ([RFC5226]) after a two-week 3515 review period on the oauth-ext-review@ietf.org mailing list, on the 3516 advice of one or more Designated Experts. However, to allow for the 3517 allocation of values prior to publication, the Designated Expert(s) 3518 may approve registration once they are satisfied that such a 3519 specification will be published. 3521 Registration requests must be sent to the oauth-ext-review@ietf.org 3522 mailing list for review and comment, with an appropriate subject 3523 (e.g., "Request for response type: example"). 3525 Within the review period, the Designated Expert(s) will either 3526 approve or deny the registration request, communicating this decision 3527 to the review list and IANA. Denials should include an explanation 3528 and, if applicable, suggestions as to how to make the request 3529 successful. 3531 IANA must only accept registry updates from the Designated Expert(s) 3532 and should direct all requests for registration to the review mailing 3533 list. 3535 13.3.1. Registration Template 3537 Response type name: The name requested (e.g., "example"). 3539 Change controller: For Standards Track RFCs, state "IETF". For 3540 others, give the name of the responsible party. Other details 3541 (e.g., postal address, email address, home page URI) may also be 3542 included. 3544 Specification document(s): Reference to the document(s) that specify 3545 the type, preferably including a URI that can be used to retrieve 3546 a copy of the document(s). An indication of the relevant sections 3547 may also be included but is not required. 3549 13.3.2. Initial Registry Contents 3551 The OAuth Authorization Endpoint Response Types registry's initial 3552 contents are: 3554 * Response type name: code 3556 * Change controller: IETF 3558 * Specification document(s): RFC 6749 3560 13.4. OAuth Extensions Error Registry 3562 This specification establishes the OAuth Extensions Error registry. 3564 Additional error codes used together with other protocol extensions 3565 (i.e., extension grant types, access token types, or extension 3566 parameters) are registered with a Specification Required ([RFC5226]) 3567 after a two-week review period on the oauth-ext-review@ietf.org 3568 mailing list, on the advice of one or more Designated Experts. 3569 However, to allow for the allocation of values prior to publication, 3570 the Designated Expert(s) may approve registration once they are 3571 satisfied that such a specification will be published. 3573 Registration requests must be sent to the oauth-ext-review@ietf.org 3574 mailing list for review and comment, with an appropriate subject 3575 (e.g., "Request for error code: example"). 3577 Within the review period, the Designated Expert(s) will either 3578 approve or deny the registration request, communicating this decision 3579 to the review list and IANA. Denials should include an explanation 3580 and, if applicable, suggestions as to how to make the request 3581 successful. 3583 IANA must only accept registry updates from the Designated Expert(s) 3584 and should direct all requests for registration to the review mailing 3585 list. 3587 13.4.1. Registration Template 3589 Error name: The name requested (e.g., "example"). Values for the 3590 error name MUST NOT include characters outside the set %x20-21 / 3591 %x23-5B / %x5D-7E. 3593 Error usage location: The location(s) where the error can be used. 3594 The possible locations are authorization code grant error response 3595 (Section 4.1.2.1), token error response (Section 5.2), or resource 3596 access error response (Section 7.3). 3598 Related protocol extension: The name of the extension grant type, 3599 access token type, or extension parameter that the error code is 3600 used in conjunction with. 3602 Change controller: For Standards Track RFCs, state "IETF". For 3603 others, give the name of the responsible party. Other details 3604 (e.g., postal address, email address, home page URI) may also be 3605 included. 3607 Specification document(s): Reference to the document(s) that specify 3608 the error code, preferably including a URI that can be used to 3609 retrieve a copy of the document(s). An indication of the relevant 3610 sections may also be included but is not required. 3612 13.4.2. Initial Registry Contents 3614 The OAuth Error registry's initial contents are: 3616 * Error name: invalid_request 3618 * Error usage location: Resource access error response 3620 * Change controller: IETF 3622 * Specification document(s): OAuth 2.1 3624 * Error name: invalid_token 3626 * Error usage location: Resource access error response 3628 * Change controller: IETF 3630 * Specification document(s): OAuth 2.1 3632 * Error name: insufficient_scope 3634 * Error usage location: Resource access error response 3636 * Change controller: IETF 3638 * Specification document(s): OAuth 2.1 3640 14. References 3642 14.1. Normative References 3644 [I-D.ietf-oauth-security-topics] 3645 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3646 "OAuth 2.0 Security Best Current Practice", Work in 3647 Progress, Internet-Draft, draft-ietf-oauth-security- 3648 topics-14, 10 February 2020, . 3651 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3652 Requirement Levels", BCP 14, RFC 2119, 3653 DOI 10.17487/RFC2119, March 1997, 3654 . 3656 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3657 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3658 Transfer Protocol -- HTTP/1.1", RFC 2616, 3659 DOI 10.17487/RFC2616, June 1999, 3660 . 3662 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3663 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3664 Authentication: Basic and Digest Access Authentication", 3665 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3666 . 3668 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3669 DOI 10.17487/RFC2818, May 2000, 3670 . 3672 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3673 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3674 2003, . 3676 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3677 Resource Identifier (URI): Generic Syntax", STD 66, 3678 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3679 . 3681 [RFC4627] Crockford, D., "The application/json Media Type for 3682 JavaScript Object Notation (JSON)", RFC 4627, 3683 DOI 10.17487/RFC4627, July 2006, 3684 . 3686 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3687 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3688 . 3690 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3691 IANA Considerations Section in RFCs", RFC 5226, 3692 DOI 10.17487/RFC5226, May 2008, 3693 . 3695 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3696 Specifications: ABNF", STD 68, RFC 5234, 3697 DOI 10.17487/RFC5234, January 2008, 3698 . 3700 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3701 Housley, R., and W. Polk, "Internet X.509 Public Key 3702 Infrastructure Certificate and Certificate Revocation List 3703 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3704 . 3706 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3707 Verification of Domain-Based Application Service Identity 3708 within Internet Public Key Infrastructure Using X.509 3709 (PKIX) Certificates in the Context of Transport Layer 3710 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3711 2011, . 3713 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3714 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3715 . 3717 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3718 Framework: Bearer Token Usage", RFC 6750, 3719 DOI 10.17487/RFC6750, October 2012, 3720 . 3722 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3723 and Registration Procedures for URI Schemes", BCP 35, 3724 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3725 . 3727 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3728 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3729 . 3731 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3732 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3733 . 3735 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3736 Standard Code for Information Interchange, ANSI X3.4", 3737 1986. 3739 [W3C.REC-html401-19991224] 3740 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3741 Specification", World Wide Web Consortium Recommendation 3742 REC-html401-19991224, 24 December 1999, 3743 . 3745 [W3C.REC-xml-20081126] 3746 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3747 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3748 Edition)", World Wide Web Consortium Recommendation REC- 3749 xml-20081126, 26 November 2008, 3750 . 3752 14.2. Informative References 3754 [CSP-2] "Content Security Policy Level 2", December 2016, 3755 . 3757 [I-D.bradley-oauth-jwt-encoded-state] 3758 Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding 3759 claims in the OAuth 2 state parameter using a JWT", Work 3760 in Progress, Internet-Draft, draft-bradley-oauth-jwt- 3761 encoded-state-09, 4 November 2018, . 3765 [I-D.ietf-oauth-browser-based-apps] 3766 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3767 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3768 browser-based-apps-05, 28 February 2020, 3769 . 3772 [I-D.ietf-oauth-rar] 3773 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3774 Rich Authorization Requests", Work in Progress, Internet- 3775 Draft, draft-ietf-oauth-rar-01, 19 February 2020, 3776 . 3779 [I-D.ietf-oauth-resource-indicators] 3780 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3781 Indicators for OAuth 2.0", Work in Progress, Internet- 3782 Draft, draft-ietf-oauth-resource-indicators-08, 11 3783 September 2019, . 3786 [I-D.ietf-oauth-token-binding] 3787 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 3788 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3789 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3790 . 3793 [NIST800-63] 3794 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3795 Gupta, S., and E. Nabbus, "NIST Special Publication 3796 800-63-1, INFORMATION SECURITY", December 2011, 3797 . 3799 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3800 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3801 and B. Boyer, "Online Multimedia Authorization Protocol: 3802 An Industry Standard for Authorized Access to Internet 3803 Multimedia Resources", April 2012, 3804 . 3806 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3807 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3808 . 3810 [OpenID.Messages] 3811 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3812 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3813 June 2012, . 3816 [owasp_redir] 3817 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3818 Forwards", 2020, 3819 . 3822 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3823 DOI 10.17487/RFC6265, April 2011, 3824 . 3826 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3827 Threat Model and Security Considerations", RFC 6819, 3828 DOI 10.17487/RFC6819, January 2013, 3829 . 3831 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3832 Protocol (HTTP/1.1): Message Syntax and Routing", 3833 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3834 . 3836 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3837 Protocol (HTTP/1.1): Authentication", RFC 7235, 3838 DOI 10.17487/RFC7235, June 2014, 3839 . 3841 [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security 3842 Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 3843 Client Authentication and Authorization Grants", RFC 7522, 3844 DOI 10.17487/RFC7522, May 2015, 3845 . 3847 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3848 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3849 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3850 . 3852 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3853 for Code Exchange by OAuth Public Clients", RFC 7636, 3854 DOI 10.17487/RFC7636, September 2015, 3855 . 3857 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3858 Authorization Server Metadata", RFC 8414, 3859 DOI 10.17487/RFC8414, June 2018, 3860 . 3862 [RFC8418] Housley, R., "Use of the Elliptic Curve Diffie-Hellman Key 3863 Agreement Algorithm with X25519 and X448 in the 3864 Cryptographic Message Syntax (CMS)", RFC 8418, 3865 DOI 10.17487/RFC8418, August 2018, 3866 . 3868 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3869 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3870 and Certificate-Bound Access Tokens", RFC 8705, 3871 DOI 10.17487/RFC8705, February 2020, 3872 . 3874 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3875 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3876 February 2020, . 3878 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3880 This section provides Augmented Backus-Naur Form (ABNF) syntax 3881 descriptions for the elements defined in this specification using the 3882 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3883 code points [W3C.REC-xml-20081126]; these characters are typically 3884 encoded in UTF-8. Elements are presented in the order first defined. 3886 Some of the definitions that follow use the "URI-reference" 3887 definition from [RFC3986]. 3889 Some of the definitions that follow use these common definitions: 3891 VSCHAR = %x20-7E 3892 NQCHAR = %x21 / %x23-5B / %x5D-7E 3893 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3894 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3895 %xE000-FFFD / %x10000-10FFFF 3897 (The UNICODECHARNOCRLF definition is based upon the Char definition 3898 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3899 Return and Linefeed characters.) 3901 A.1. "client_id" Syntax 3903 The "client_id" element is defined in Section 2.3.1: 3905 client-id = *VSCHAR 3907 A.2. "client_secret" Syntax 3909 The "client_secret" element is defined in Section 2.3.1: 3911 client-secret = *VSCHAR 3913 A.3. "response_type" Syntax 3915 The "response_type" element is defined in Section 3.1.1 and 3916 Section 8.4: 3918 response-type = response-name *( SP response-name ) 3919 response-name = 1*response-char 3920 response-char = "_" / DIGIT / ALPHA 3922 A.4. "scope" Syntax 3924 The "scope" element is defined in Section 3.3: 3926 scope = scope-token *( SP scope-token ) 3927 scope-token = 1*NQCHAR 3929 A.5. "state" Syntax 3931 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3932 Section 4.1.2.1: 3934 state = 1*VSCHAR 3936 A.6. "redirect_uri" Syntax 3938 The "redirect_uri" element is defined in Section 4.1.1, and 3939 Section 4.1.3: 3941 redirect-uri = URI-reference 3943 A.7. "error" Syntax 3945 The "error" element is defined in Sections Section 4.1.2.1, 3946 Section 5.2, 7.2, and 8.5: 3948 error = 1*NQSCHAR 3950 A.8. "error_description" Syntax 3952 The "error_description" element is defined in Sections 3953 Section 4.1.2.1, Section 5.2, and Section 7.3: 3955 error-description = 1*NQSCHAR 3957 A.9. "error_uri" Syntax 3959 The "error_uri" element is defined in Sections Section 4.1.2.1, 3960 Section 5.2, and 7.2: 3962 error-uri = URI-reference 3964 A.10. "grant_type" Syntax 3966 The "grant_type" element is defined in Sections Section 4.1.3, 3967 Section 4.2.3, Section 4.2.2, Section 4.3, and Section 6: 3969 grant-type = grant-name / URI-reference 3970 grant-name = 1*name-char 3971 name-char = "-" / "." / "_" / DIGIT / ALPHA 3973 A.11. "code" Syntax 3975 The "code" element is defined in Section 4.1.3: 3977 code = 1*VSCHAR 3979 A.12. "access_token" Syntax 3981 The "access_token" element is defined in Section 4.2.3 and 3982 Section 5.1: 3984 access-token = 1*VSCHAR 3986 A.13. "token_type" Syntax 3988 The "token_type" element is defined in Section 5.1, and Section 8.1: 3990 token-type = type-name / URI-reference 3991 type-name = 1*name-char 3992 name-char = "-" / "." / "_" / DIGIT / ALPHA 3994 A.14. "expires_in" Syntax 3996 The "expires_in" element is defined in Section 5.1: 3998 expires-in = 1*DIGIT 4000 A.15. "refresh_token" Syntax 4002 The "refresh_token" element is defined in Section 5.1 and Section 6: 4004 refresh-token = 1*VSCHAR 4006 A.16. Endpoint Parameter Syntax 4008 The syntax for new endpoint parameters is defined in Section 8.2: 4010 param-name = 1*name-char 4011 name-char = "-" / "." / "_" / DIGIT / ALPHA 4013 A.17. "code_verifier" Syntax 4015 ABNF for "code_verifier" is as follows. 4017 code-verifier = 43*128unreserved 4018 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 4019 ALPHA = %x41-5A / %x61-7A 4020 DIGIT = %x30-39 4022 A.18. "code_challenge" Syntax 4024 ABNF for "code_challenge" is as follows. 4026 code-challenge = 43*128unreserved 4027 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 4028 ALPHA = %x41-5A / %x61-7A 4029 DIGIT = %x30-39 4031 Appendix B. Use of application/x-www-form-urlencoded Media Type 4033 At the time of publication of this specification, the "application/x- 4034 www-form-urlencoded" media type was defined in Section 17.13.4 of 4035 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 4036 Types registry (http://www.iana.org/assignments/media-types 4037 (http://www.iana.org/assignments/media-types)). Furthermore, that 4038 definition is incomplete, as it does not consider non-US-ASCII 4039 characters. 4041 To address this shortcoming when generating payloads using this media 4042 type, names and values MUST be encoded using the UTF-8 character 4043 encoding scheme [RFC3629] first; the resulting octet sequence then 4044 needs to be further encoded using the escaping rules defined in 4045 [W3C.REC-html401-19991224]. 4047 When parsing data from a payload using this media type, the names and 4048 values resulting from reversing the name/value encoding consequently 4049 need to be treated as octet sequences, to be decoded using the UTF-8 4050 character encoding scheme. 4052 For example, the value consisting of the six Unicode code points (1) 4053 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 4054 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 4055 SIGN) would be encoded into the octet sequence below (using 4056 hexadecimal notation): 4058 20 25 26 2B C2 A3 E2 82 AC 4060 and then represented in the payload as: 4062 +%25%26%2B%C2%A3%E2%82%AC 4064 Appendix C. Acknowledgements 4066 TBD 4068 Authors' Addresses 4070 Dick Hardt 4071 SignIn.Org 4073 Email: dick.hardt@gmail.com 4075 Aaron Parecki 4076 Okta 4077 Email: aaron@parecki.com 4078 URI: https://aaronparecki.com 4080 Torsten Lodderstedt 4081 yes.com 4083 Email: torsten@lodderstedt.net