idnits 2.17.1 draft-parecki-oauth-v2-1-02.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 date (24 April 2020) is 1460 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 1105, but not defined == Missing Reference: '0-9' is mentioned on line 1105, but not defined == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-15 ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-17) exists of draft-ietf-oauth-browser-based-apps-06 == 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 (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group D. Hardt 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track A. Parecki 5 Expires: 26 October 2020 Okta 6 T. Lodderstedt 7 yes.com 8 24 April 2020 10 The OAuth 2.1 Authorization Framework 11 draft-parecki-oauth-v2-1-02 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 26 October 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 . . . . . . . . . . . . . . . . . . 15 72 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 73 2.3.2. Other Authentication Methods . . . . . . . . . . . . 16 74 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 17 75 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 17 76 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 77 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18 78 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 18 79 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 80 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21 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 . . . . . . . . . . . . . . . . 24 85 4.1.2. Authorization Response . . . . . . . . . . . . . . . 27 86 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 29 87 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 31 88 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 31 89 4.2.1. Authorization Request and Response . . . . . . . . . 32 90 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 32 91 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 33 92 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 33 93 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 34 94 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 34 95 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 35 96 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 37 97 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 39 98 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 40 99 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 40 100 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 40 101 7.2.2. The WWW-Authenticate Response Header Field . . . . . 42 102 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 44 103 7.3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 44 104 7.4. Access Token Security Considerations . . . . . . . . . . 45 105 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 45 106 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 46 107 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 47 108 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 49 109 7.4.5. Access Token Privilege Restriction . . . . . . . . . 49 110 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 50 111 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 50 112 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 50 113 8.3. Defining New Authorization Grant Types . . . . . . . . . 50 114 8.4. Defining New Authorization Endpoint Response Types . . . 51 115 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 51 116 9. Security Considerations . . . . . . . . . . . . . . . . . . . 52 117 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 52 118 9.1.1. Client Authentication of Native Apps . . . . . . . . 53 119 9.2. Registration of Native App Clients . . . . . . . . . . . 53 120 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 54 121 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 55 122 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 55 123 9.4.1. Access Token Privilege Restriction . . . . . . . . . 55 124 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 56 125 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 56 126 9.6. Protecting Redirect-Based Flows . . . . . . . . . . . . . 57 127 9.6.1. Loopback Redirect Considerations in Native Apps . . . 58 128 9.6.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 58 129 9.7. Authorization Codes . . . . . . . . . . . . . . . . . . . 59 130 9.8. Request Confidentiality . . . . . . . . . . . . . . . . . 60 131 9.9. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 60 132 9.10. Credentials-Guessing Attacks . . . . . . . . . . . . . . 60 133 9.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 60 134 9.12. Fake External User-Agents in Native Apps . . . . . . . . 61 135 9.13. Malicious External User-Agents in Native Apps . . . . . . 61 136 9.14. Cross-Site Request Forgery . . . . . . . . . . . . . . . 62 137 9.15. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 62 138 9.16. Code Injection and Input Validation . . . . . . . . . . . 63 139 9.17. Open Redirectors . . . . . . . . . . . . . . . . . . . . 63 140 9.17.1. Client as Open Redirector . . . . . . . . . . . . . 64 141 9.17.2. Authorization Server as Open Redirector . . . . . . 64 142 9.18. Authorization Server Mix-Up Mitigation in Native Apps . . 64 143 9.19. Embedded User Agents in Native Apps . . . . . . . . . . . 65 144 9.20. Other Recommendations . . . . . . . . . . . . . . . . . . 66 146 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 66 147 10.1. Using Inter-App URI Communication for OAuth in Native 148 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 67 149 10.2. Initiating the Authorization Request from a Native 150 App . . . . . . . . . . . . . . . . . . . . . . . . . . 67 151 10.3. Receiving the Authorization Response in a Native App . . 68 152 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 68 153 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 69 154 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 70 155 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 71 156 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 71 157 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 158 13.1. OAuth Access Token Types Registry . . . . . . . . . . . 72 159 13.1.1. Registration Template . . . . . . . . . . . . . . . 72 160 13.1.2. Initial Registry Contents . . . . . . . . . . . . . 73 161 13.2. OAuth Parameters Registry . . . . . . . . . . . . . . . 73 162 13.2.1. Registration Template . . . . . . . . . . . . . . . 74 163 13.2.2. Initial Registry Contents . . . . . . . . . . . . . 74 164 13.3. OAuth Authorization Endpoint Response Types Registry . . 77 165 13.3.1. Registration Template . . . . . . . . . . . . . . . 77 166 13.3.2. Initial Registry Contents . . . . . . . . . . . . . 78 167 13.4. OAuth Extensions Error Registry . . . . . . . . . . . . 78 168 13.4.1. Registration Template . . . . . . . . . . . . . . . 78 169 13.4.2. Initial Registry Contents . . . . . . . . . . . . . 79 170 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 171 14.1. Normative References . . . . . . . . . . . . . . . . . . 79 172 14.2. Informative References . . . . . . . . . . . . . . . . . 82 173 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 84 174 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 85 175 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 85 176 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 85 177 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 85 178 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 85 179 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 86 180 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 86 181 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 86 182 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 86 183 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 86 184 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 86 185 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 87 186 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 87 187 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 87 188 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 87 189 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 87 190 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 87 191 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 87 192 Appendix B. Use of application/x-www-form-urlencoded Media 193 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 88 195 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 88 196 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 198 1. Introduction 200 In the traditional client-server authentication model, the client 201 requests an access-restricted resource (protected resource) on the 202 server by authenticating with the server using the resource owner's 203 credentials. In order to provide third-party applications access to 204 restricted resources, the resource owner shares its credentials with 205 the third party. This creates several problems and limitations: 207 * Third-party applications are required to store the resource 208 owner's credentials for future use, typically a password in clear- 209 text. 211 * Servers are required to support password authentication, despite 212 the security weaknesses inherent in passwords. 214 * Third-party applications gain overly broad access to the resource 215 owner's protected resources, leaving resource owners without any 216 ability to restrict duration or access to a limited subset of 217 resources. 219 * Resource owners cannot revoke access to an individual third party 220 without revoking access to all third parties, and must do so by 221 changing the third party's password. 223 * Compromise of any third-party application results in compromise of 224 the end-user's password and all of the data protected by that 225 password. 227 OAuth addresses these issues by introducing an authorization layer 228 and separating the role of the client from that of the resource 229 owner. In OAuth, the client requests access to resources controlled 230 by the resource owner and hosted by the resource server, and is 231 issued a different set of credentials than those of the resource 232 owner. 234 Instead of using the resource owner's credentials to access protected 235 resources, the client obtains an access token - a string denoting a 236 specific scope, lifetime, and other access attributes. Access tokens 237 are issued to third-party clients by an authorization server with the 238 approval of the resource owner. The client uses the access token to 239 access the protected resources hosted by the resource server. 241 For example, an end-user (resource owner) can grant a printing 242 service (client) access to her protected photos stored at a photo- 243 sharing service (resource server), without sharing her username and 244 password with the printing service. Instead, she authenticates 245 directly with a server trusted by the photo-sharing service 246 (authorization server), which issues the printing service delegation- 247 specific credentials (access token). 249 This specification is designed for use with HTTP ([RFC7230]). The 250 use of OAuth over any protocol other than HTTP is out of scope. 252 Since the publication of the OAuth 2.0 Authorization Framework 253 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 254 Native Apps ([RFC8252]), OAuth Security Best Current Practice 255 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 256 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 257 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 258 updated with ([I-D.ietf-oauth-security-topics]). This Standards 259 Track specification consolidates the information in all of these 260 documents and removes features that have been found to be insecure in 261 [I-D.ietf-oauth-security-topics]. 263 1.1. Roles 265 OAuth defines four roles: 267 "resource owner": An entity capable of granting access to a 268 protected resource. When the resource owner is a person, it is 269 referred to as an end-user. This is sometimes abbreviated as 270 "RO". 272 "resource server": The server hosting the protected resources, 273 capable of accepting and responding to protected resource requests 274 using access tokens. This is sometimes abbreviated as "RS". 276 "client": An application making protected resource requests on 277 behalf of the resource owner and with its authorization. The term 278 "client" does not imply any particular implementation 279 characteristics (e.g., whether the application executes on a 280 server, a desktop, or other devices). 282 "authorization server": The server issuing access tokens to the 283 client after successfully authenticating the resource owner and 284 obtaining authorization. This is sometimes abbreviated as "AS". 286 The interaction between the authorization server and resource server 287 is beyond the scope of this specification. The authorization server 288 may be the same server as the resource server or a separate entity. 289 A single authorization server may issue access tokens accepted by 290 multiple resource servers. 292 1.2. Protocol Flow 294 +--------+ +---------------+ 295 | |--(1)- Authorization Request ->| Resource | 296 | | | Owner | 297 | |<-(2)-- Authorization Grant ---| | 298 | | +---------------+ 299 | | 300 | | +---------------+ 301 | |--(3)-- Authorization Grant -->| Authorization | 302 | Client | | Server | 303 | |<-(4)----- Access Token -------| | 304 | | +---------------+ 305 | | 306 | | +---------------+ 307 | |--(5)----- Access Token ------>| Resource | 308 | | | Server | 309 | |<-(6)--- Protected Resource ---| | 310 +--------+ +---------------+ 312 Figure 1: Abstract Protocol Flow 314 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 315 interaction between the four roles and includes the following steps: 317 1. The client requests authorization from the resource owner. The 318 authorization request can be made directly to the resource owner 319 (as shown), or preferably indirectly via the authorization server 320 as an intermediary. 322 2. The client receives an authorization grant, which is a credential 323 representing the resource owner's authorization, expressed using 324 one of two grant types defined in this specification or using an 325 extension grant type. The authorization grant type depends on 326 the method used by the client to request authorization and the 327 types supported by the authorization server. 329 3. The client requests an access token by authenticating with the 330 authorization server and presenting the authorization grant. 332 4. The authorization server authenticates the client and validates 333 the authorization grant, and if valid, issues an access token. 335 5. The client requests the protected resource from the resource 336 server and authenticates by presenting the access token. 338 6. The resource server validates the access token, and if valid, 339 serves the request. 341 The preferred method for the client to obtain an authorization grant 342 from the resource owner (depicted in steps (1) and (2)) is to use the 343 authorization server as an intermediary, which is illustrated in 344 Figure 3 in Section 4.1. 346 1.3. Authorization Grant 348 An authorization grant is a credential representing the resource 349 owner's authorization (to access its protected resources) used by the 350 client to obtain an access token. This specification defines two 351 grant types - authorization code and client credentials - as well as 352 an extensibility mechanism for defining additional types. 354 1.3.1. Authorization Code 356 The authorization code is obtained by using an authorization server 357 as an intermediary between the client and resource owner. Instead of 358 requesting authorization directly from the resource owner, the client 359 directs the resource owner to an authorization server (via its user- 360 agent as defined in [RFC7231]), which in turn directs the resource 361 owner back to the client with the authorization code. 363 Before directing the resource owner back to the client with the 364 authorization code, the authorization server authenticates the 365 resource owner and obtains authorization. Because the resource owner 366 only authenticates with the authorization server, the resource 367 owner's credentials are never shared with the client. 369 The authorization code provides a few important security benefits, 370 such as the ability to authenticate the client, as well as the 371 transmission of the access token directly to the client without 372 passing it through the resource owner's user-agent and potentially 373 exposing it to others, including the resource owner. 375 1.3.2. Client Credentials 377 The client credentials (or other forms of client authentication) can 378 be used as an authorization grant when the authorization scope is 379 limited to the protected resources under the control of the client, 380 or to protected resources previously arranged with the authorization 381 server. Client credentials are used as an authorization grant 382 typically when the client is acting on its own behalf (the client is 383 also the resource owner) or is requesting access to protected 384 resources based on an authorization previously arranged with the 385 authorization server. 387 1.4. Access Token 389 Access tokens are credentials used to access protected resources. An 390 access token is a string representing an authorization issued to the 391 client. The string is usually opaque to the client. Tokens 392 represent specific scopes and durations of access, granted by the 393 resource owner, and enforced by the resource server and authorization 394 server. 396 The token may denote an identifier used to retrieve the authorization 397 information or may self-contain the authorization information in a 398 verifiable manner (i.e., a token string consisting of some data and a 399 signature). Additional authentication credentials, which are beyond 400 the scope of this specification, may be required in order for the 401 client to use a token. 403 The access token provides an abstraction layer, replacing different 404 authorization constructs (e.g., username and password) with a single 405 token understood by the resource server. This abstraction enables 406 issuing access tokens more restrictive than the authorization grant 407 used to obtain them, as well as removing the resource server's need 408 to understand a wide range of authentication methods. 410 Access tokens can have different formats, structures, and methods of 411 utilization (e.g., cryptographic properties) based on the resource 412 server security requirements. Access token attributes and the 413 methods used to access protected resources may be extended beyond 414 what is described in this specification. 416 1.5. Refresh Token 418 Refresh tokens are credentials used to obtain access tokens. Refresh 419 tokens are issued to the client by the authorization server and are 420 used to obtain a new access token when the current access token 421 becomes invalid or expires, or to obtain additional access tokens 422 with identical or narrower scope (access tokens may have a shorter 423 lifetime and fewer permissions than authorized by the resource 424 owner). Issuing a refresh token is optional at the discretion of the 425 authorization server. If the authorization server issues a refresh 426 token, it is included when issuing an access token (i.e., step (4) in 427 Figure 2). 429 A refresh token is a string representing the authorization granted to 430 the client by the resource owner. The string is usually opaque to 431 the client. The token denotes an identifier used to retrieve the 432 authorization information. Unlike access tokens, refresh tokens are 433 intended for use only with authorization servers and are never sent 434 to resource servers. 436 +--------+ +---------------+ 437 | |--(1)------- Authorization Grant --------->| | 438 | | | | 439 | |<-(2)----------- Access Token -------------| | 440 | | & Refresh Token | | 441 | | | | 442 | | +----------+ | | 443 | |--(3)---- Access Token ---->| | | | 444 | | | | | | 445 | |<-(4)- Protected Resource --| Resource | | Authorization | 446 | Client | | Server | | Server | 447 | |--(5)---- Access Token ---->| | | | 448 | | | | | | 449 | |<-(6)- Invalid Token Error -| | | | 450 | | +----------+ | | 451 | | | | 452 | |--(7)----------- Refresh Token ----------->| | 453 | | | | 454 | |<-(8)----------- Access Token -------------| | 455 +--------+ & Optional Refresh Token +---------------+ 457 Figure 2: Refreshing an Expired Access Token 459 The flow illustrated in Figure 2 includes the following steps: 461 1. The client requests an access token by authenticating with the 462 authorization server and presenting an authorization grant. 464 2. The authorization server authenticates the client and validates 465 the authorization grant, and if valid, issues an access token and 466 a refresh token. 468 3. The client makes a protected resource request to the resource 469 server by presenting the access token. 471 4. The resource server validates the access token, and if valid, 472 serves the request. 474 5. Steps (3) and (4) repeat until the access token expires. If the 475 client knows the access token expired, it skips to step (7); 476 otherwise, it makes another protected resource request. 478 6. Since the access token is invalid, the resource server returns an 479 invalid token error. 481 7. The client requests a new access token by authenticating with the 482 authorization server and presenting the refresh token. The 483 client authentication requirements are based on the client type 484 and on the authorization server policies. 486 8. The authorization server authenticates the client and validates 487 the refresh token, and if valid, issues a new access token (and, 488 optionally, a new refresh token). 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, TLS version 1.3 496 [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, 508 with the exception of HTTP 307, is allowed and is considered to be an 509 implementation detail. See Section 9.6.2 for details. 511 1.8. Interoperability 513 OAuth 2.1 provides a rich authorization framework with well-defined 514 security properties. However, as a rich and highly extensible 515 framework with many optional components, on its own, this 516 specification is likely to produce a wide range of non-interoperable 517 implementations. 519 In addition, this specification leaves a few required components 520 partially or fully undefined (e.g., client registration, 521 authorization server capabilities, endpoint discovery). Without 522 these components, clients must be manually and specifically 523 configured against a specific authorization server and resource 524 server in order to interoperate. 526 This framework was designed with the clear expectation that future 527 work will define prescriptive profiles and extensions necessary to 528 achieve full web-scale interoperability. 530 1.9. Notational Conventions 532 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 533 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 534 "OPTIONAL" in this document are to be interpreted as described in BCP 535 14 [RFC2119] [RFC8174] when, and only when, they appear in all 536 capitals, as shown here. 538 This specification uses the Augmented Backus-Naur Form (ABNF) 539 notation of [RFC5234]. Additionally, the rule URI-reference is 540 included from "Uniform Resource Identifier (URI): Generic Syntax" 541 [RFC3986]. 543 Certain security-related terms are to be understood in the sense 544 defined in [RFC4949]. These terms include, but are not limited to, 545 "attack", "authentication", "authorization", "certificate", 546 "confidentiality", "credential", "encryption", "identity", "sign", 547 "signature", "trust", "validate", and "verify". 549 Unless otherwise noted, all the protocol parameter names and values 550 are case sensitive. 552 2. Client Registration 554 Before initiating the protocol, the client registers with the 555 authorization server. The means through which the client registers 556 with the authorization server are beyond the scope of this 557 specification but typically involve end-user interaction with an HTML 558 registration form, or by using Dynamic Client Registration 559 ([RFC7591]). 561 Client registration does not require a direct interaction between the 562 client and the authorization server. When supported by the 563 authorization server, registration can rely on other means for 564 establishing trust and obtaining the required client properties 565 (e.g., redirection URI, client type). For example, registration can 566 be accomplished using a self-issued or third-party-issued assertion, 567 or by the authorization server performing client discovery using a 568 trusted channel. 570 When registering a client, the client developer SHALL: 572 * specify the client type as described in Section 2.1, 573 * provide its client redirection URIs as described in Section 3.1.2, 574 and 576 * include any other information required by the authorization server 577 (e.g., application name, website, description, logo image, the 578 acceptance of legal terms). 580 Dynamic Client Registration ([RFC7591]) defines a common general data 581 model for clients that may be used even with manual client 582 registration. 584 2.1. Client Types 586 Clients are identified at the authorization server by a "client_id". 587 It is, for example, used by the authorization server to determine the 588 set of redirect URIs this client can use. 590 Clients requiring a higher level of confidence in their identity by 591 the authorization server use credentials to authenticate with the 592 authorization server. Such credentials are either issued by the 593 authorization server or registered by the developer of the client 594 with the authorization server. 596 OAuth 2.1 defines two client types: 598 "confidential": Clients that have credentials are designated as 599 "confidential clients" 601 "public": Clients without credentials are called "public clients" 603 Confidential clients MUST take precautions to prevent leakage and 604 abuse of their credentials. 606 Authorization servers SHOULD consider the level of confidence in a 607 client's identity when deciding whether they allow such a client 608 access to more critical functions, such as the client credentials 609 grant type. 611 A client may be implemented as a distributed set of components, each 612 with a different client type and security context (e.g., a 613 distributed client with both a confidential server-based component 614 and a public browser-based component). If the authorization server 615 does not provide support for such clients or does not provide 616 guidance with regard to their registration, the client SHOULD 617 register each component as a separate client. 619 This specification has been designed around the following client 620 profiles: 622 "web application": A web application is a confidential client 623 running on a web server. Resource owners access the client via an 624 HTML user interface rendered in a user-agent on the device used by 625 the resource owner. The client credentials as well as any access 626 token issued to the client are stored on the web server and are 627 not exposed to or accessible by the resource owner. 629 "browser-based application": A browser-based application is a public 630 client in which the client code is downloaded from a web server 631 and executes within a user-agent (e.g., web browser) on the device 632 used by the resource owner. Protocol data and credentials are 633 easily accessible (and often visible) to the resource owner. 634 Since such applications reside within the user-agent, they can 635 make seamless use of the user-agent capabilities when requesting 636 authorization. 638 "native application": A native application is a public client 639 installed and executed on the device used by the resource owner. 640 Protocol data and credentials are accessible to the resource 641 owner. It is assumed that any client authentication credentials 642 included in the application can be extracted. On the other hand, 643 dynamically issued credentials such as access tokens or refresh 644 tokens can receive an acceptable level of protection. At a 645 minimum, these credentials are protected from hostile servers with 646 which the application may interact. On some platforms, these 647 credentials might be protected from other applications residing on 648 the same device. 650 2.2. Client Identifier 652 The authorization server issues the registered client a client 653 identifier - a unique string representing the registration 654 information provided by the client. The client identifier is not a 655 secret; it is exposed to the resource owner and MUST NOT be used 656 alone for client authentication. The client identifier is unique to 657 the authorization server. 659 The client identifier string size is left undefined by this 660 specification. The client should avoid making assumptions about the 661 identifier size. The authorization server SHOULD document the size 662 of any identifier it issues. 664 Authorization servers SHOULD NOT allow clients to influence their 665 "client_id" value in such a way that it may be confused with the 666 identifier of a genuine resource owner during subsequent protocol 667 interactions. 669 2.3. Client Authentication 671 If the client type is confidential, the client and authorization 672 server establish a client authentication method suitable for the 673 security requirements of the authorization server. The authorization 674 server MAY accept any form of client authentication meeting its 675 security requirements. 677 Confidential clients are typically issued (or establish) a set of 678 client credentials used for authenticating with the authorization 679 server (e.g., password, public/private key pair). 681 Authorization servers SHOULD use client authentication if possible. 683 It is RECOMMENDED to use asymmetric (public-key based) methods for 684 client authentication such as mTLS [RFC8705] or "private_key_jwt" 685 [OpenID]. When asymmetric methods for client authentication are 686 used, authorization servers do not need to store sensitive symmetric 687 keys, making these methods more robust against a number of attacks. 689 The authorization server MAY establish a client authentication method 690 with public clients. However, the authorization server MUST NOT rely 691 on public client authentication for the purpose of identifying the 692 client. 694 The client MUST NOT use more than one authentication method in each 695 request. 697 2.3.1. Client Password 699 Clients in possession of a client password, also known as a client 700 secret, MAY use the HTTP Basic authentication scheme as defined in 701 [RFC2617] to authenticate with the authorization server. The client 702 identifier is encoded using the "application/x-www-form-urlencoded" 703 encoding algorithm per Appendix B, and the encoded value is used as 704 the username; the client secret is encoded using the same algorithm 705 and used as the password. The authorization server MUST support the 706 HTTP Basic authentication scheme for authenticating clients that were 707 issued a client secret. 709 For example (with extra line breaks for display purposes only): 711 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 713 Alternatively, the authorization server MAY support including the 714 client credentials in the request-body using the following 715 parameters: 717 "client_id": REQUIRED. The client identifier issued to the client 718 during the registration process described by Section 2.2. 720 "client_secret": REQUIRED. The client secret. 722 Including the client credentials in the request-body using the two 723 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 724 to directly utilize the HTTP Basic authentication scheme (or other 725 password-based HTTP authentication schemes). The parameters can only 726 be transmitted in the request-body and MUST NOT be included in the 727 request URI. 729 For example, a request to refresh an access token (Section 6) using 730 the body parameters (with extra line breaks for display purposes 731 only): 733 POST /token HTTP/1.1 734 Host: server.example.com 735 Content-Type: application/x-www-form-urlencoded 737 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 738 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 740 The authorization server MUST require the use of TLS as described in 741 Section 1.6 when sending requests using password authentication. 743 Since this client authentication method involves a password, the 744 authorization server MUST protect any endpoint utilizing it against 745 brute force attacks. 747 2.3.2. Other Authentication Methods 749 The authorization server MAY support any suitable authentication 750 scheme matching its security requirements. When using other 751 authentication methods, the authorization server MUST define a 752 mapping between the client identifier (registration record) and 753 authentication scheme. 755 Some additional authentication methods are defined in the "OAuth 756 Token Endpoint Authentication Methods 757 (https://www.iana.org/assignments/oauth-parameters/oauth- 758 parameters.xhtml#token-endpoint-auth-method)" registry, and may be 759 useful as generic client authentication methods beyond the specific 760 use of protecting the token endpoint. 762 2.4. Unregistered Clients 764 This specification does not exclude the use of unregistered clients. 765 However, the use of such clients is beyond the scope of this 766 specification and requires additional security analysis and review of 767 its interoperability impact. 769 3. Protocol Endpoints 771 The authorization process utilizes two authorization server endpoints 772 (HTTP resources): 774 * Authorization endpoint - used by the client to obtain 775 authorization from the resource owner via user-agent redirection. 777 * Token endpoint - used by the client to exchange an authorization 778 grant for an access token, typically with client authentication. 780 As well as one client endpoint: 782 * Redirection endpoint - used by the authorization server to return 783 responses containing authorization credentials to the client via 784 the resource owner user-agent. 786 Not every authorization grant type utilizes both endpoints. 787 Extension grant types MAY define additional endpoints as needed. 789 3.1. Authorization Endpoint 791 The authorization endpoint is used to interact with the resource 792 owner and obtain an authorization grant. The authorization server 793 MUST first verify the identity of the resource owner. The way in 794 which the authorization server authenticates the resource owner 795 (e.g., username and password login, session cookies) is beyond the 796 scope of this specification. 798 The means through which the client obtains the location of the 799 authorization endpoint are beyond the scope of this specification, 800 but the location is typically provided in the service documentation, 801 or in the authorization server's metadata document ([RFC8414]). 803 The endpoint URI MAY include an "application/x-www-form-urlencoded" 804 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 805 which MUST be retained when adding additional query parameters. The 806 endpoint URI MUST NOT include a fragment component. 808 Since requests to the authorization endpoint result in user 809 authentication and the transmission of clear-text credentials (in the 810 HTTP response), the authorization server MUST require the use of TLS 811 as described in Section 1.6 when sending requests to the 812 authorization endpoint. 814 The authorization server MUST support the use of the HTTP "GET" 815 method [RFC7231] for the authorization endpoint and MAY support the 816 use of the "POST" method as well. 818 Parameters sent without a value MUST be treated as if they were 819 omitted from the request. The authorization server MUST ignore 820 unrecognized request parameters. Request and response parameters 821 defined by this specification MUST NOT be included more than once. 823 3.1.1. Response Type 825 The authorization endpoint is used by the authorization code flow. 826 The client informs the authorization server of the desired response 827 type using the following parameter: 829 "response_type": REQUIRED. The value MUST be "code" for requesting 830 an authorization code as described by Section 4.1.1, or a 831 registered extension value as described by Section 8.4. 833 Extension response types MAY contain a space-delimited (%x20) list of 834 values, where the order of values does not matter (e.g., response 835 type "a b" is the same as "b a"). The meaning of such composite 836 response types is defined by their respective specifications. 838 If an authorization request is missing the "response_type" parameter, 839 or if the response type is not understood, the authorization server 840 MUST return an error response as described in Section 4.1.2.1. 842 3.1.2. Redirection Endpoint 844 After completing its interaction with the resource owner, the 845 authorization server directs the resource owner's user-agent back to 846 the client. The authorization server redirects the user-agent to the 847 client's redirection endpoint previously established with the 848 authorization server during the client registration process. 850 The authorization server MUST compare the two URIs using simple 851 string comparison as defined in [RFC3986], Section 6.2.1. 853 The redirection endpoint URI MUST be an absolute URI as defined by 854 [RFC3986] Section 4.3. The endpoint URI MAY include an "application/ 855 x-www-form-urlencoded" formatted (per Appendix B) query component 856 ([RFC3986] Section 3.4), which MUST be retained when adding 857 additional query parameters. The endpoint URI MUST NOT include a 858 fragment component. 860 3.1.2.1. Endpoint Request Confidentiality 862 The redirection endpoint SHOULD require the use of TLS as described 863 in Section 1.6 when the requested response type is "code", or when 864 the redirection request will result in the transmission of sensitive 865 credentials over an open network. If TLS is not available, the 866 authorization server SHOULD warn the resource owner about the 867 insecure endpoint prior to redirection (e.g., display a message 868 during the authorization request). 870 Lack of transport-layer security can have a severe impact on the 871 security of the client and the protected resources it is authorized 872 to access. The use of transport-layer security is particularly 873 critical when the authorization process is used as a form of 874 delegated end-user authentication by the client (e.g., third-party 875 sign-in service). 877 3.1.2.2. Registration Requirements 879 The authorization server MUST require all clients to register their 880 redirection endpoint prior to utilizing the authorization endpoint. 882 The authorization server MUST require the client to provide one or 883 more complete redirection URIs. The client MAY use the "state" 884 request parameter to achieve per-request customization if needed. 886 The authorization server MAY allow the client to register multiple 887 redirection endpoints. 889 Lack of a redirection URI registration requirement can enable an 890 attacker to use the authorization endpoint as an open redirector as 891 described in Section 9.17. 893 3.1.2.3. Dynamic Configuration 895 If multiple redirection URIs have been registered the client MUST 896 include a redirection URI with the authorization request using the 897 "redirect_uri" request parameter. 899 3.1.2.4. Invalid Endpoint 901 If an authorization request fails validation due to a missing, 902 invalid, or mismatching redirection URI, the authorization server 903 SHOULD inform the resource owner of the error and MUST NOT 904 automatically redirect the user-agent to the invalid redirection URI. 906 3.1.2.5. Endpoint Content 908 The redirection request to the client's endpoint typically results in 909 an HTML document response, processed by the user-agent. If the HTML 910 response is served directly as the result of the redirection request, 911 any script included in the HTML document will execute with full 912 access to the redirection URI and the credentials it contains. 914 The client SHOULD NOT include any third-party scripts (e.g., third- 915 party analytics, social plug-ins, ad networks) in the redirection 916 endpoint response. Instead, it SHOULD extract the credentials from 917 the URI and redirect the user-agent again to another endpoint without 918 exposing the credentials (in the URI or elsewhere). If third-party 919 scripts are included, the client MUST ensure that its own scripts 920 (used to extract and remove the credentials from the URI) will 921 execute first. 923 3.2. Token Endpoint 925 The token endpoint is used by the client to obtain an access token by 926 presenting its authorization grant or refresh token. 928 The means through which the client obtains the location of the token 929 endpoint are beyond the scope of this specification, but the location 930 is typically provided in the service documentation, or in the 931 authorization server's metadata document ([RFC8414]). 933 The endpoint URI MAY include an "application/x-www-form-urlencoded" 934 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 935 which MUST be retained when adding additional query parameters. The 936 endpoint URI MUST NOT include a fragment component. 938 Since requests to the token endpoint result in the transmission of 939 clear-text credentials (in the HTTP request and response), the 940 authorization server MUST require the use of TLS as described in 941 Section 1.6 when sending requests to the token endpoint. 943 The client MUST use the HTTP "POST" method when making access token 944 requests. 946 Parameters sent without a value MUST be treated as if they were 947 omitted from the request. The authorization server MUST ignore 948 unrecognized request parameters. Request and response parameters 949 defined by this specification MUST NOT be included more than once. 951 3.2.1. Client Authentication 953 Confidential clients or other clients issued client credentials MUST 954 authenticate with the authorization server as described in 955 Section 2.3 when making requests to the token endpoint. Client 956 authentication is used for: 958 * Enforcing the binding of refresh tokens and authorization codes to 959 the client they were issued to. Client authentication is critical 960 when an authorization code is transmitted to the redirection 961 endpoint over an insecure channel. 963 * Recovering from a compromised client by disabling the client or 964 changing its credentials, thus preventing an attacker from abusing 965 stolen refresh tokens. Changing a single set of client 966 credentials is significantly faster than revoking an entire set of 967 refresh tokens. 969 * Implementing authentication management best practices, which 970 require periodic credential rotation. Rotation of an entire set 971 of refresh tokens can be challenging, while rotation of a single 972 set of client credentials is significantly easier. 974 3.3. Access Token Scope 976 The authorization and token endpoints allow the client to specify the 977 scope of the access request using the "scope" request parameter. In 978 turn, the authorization server uses the "scope" response parameter to 979 inform the client of the scope of the access token issued. 981 The value of the scope parameter is expressed as a list of space- 982 delimited, case-sensitive strings. The strings are defined by the 983 authorization server. If the value contains multiple space-delimited 984 strings, their order does not matter, and each string adds an 985 additional access range to the requested scope. 987 scope = scope-token *( SP scope-token ) 988 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 990 The authorization server MAY fully or partially ignore the scope 991 requested by the client, based on the authorization server policy or 992 the resource owner's instructions. If the issued access token scope 993 is different from the one requested by the client, the authorization 994 server MUST include the "scope" response parameter to inform the 995 client of the actual scope granted. 997 If the client omits the scope parameter when requesting 998 authorization, the authorization server MUST either process the 999 request using a pre-defined default value or fail the request 1000 indicating an invalid scope. The authorization server SHOULD 1001 document its scope requirements and default value (if defined). 1003 4. Obtaining Authorization 1005 To request an access token, the client obtains authorization from the 1006 resource owner. The authorization is expressed in the form of an 1007 authorization grant, which the client uses to request the access 1008 token. OAuth defines two grant types: authorization code and client 1009 credentials. It also provides an extension mechanism for defining 1010 additional grant types. 1012 4.1. Authorization Code Grant 1014 The authorization code grant type is used to obtain both access 1015 tokens and refresh tokens. 1017 Since this is a redirection-based flow, the client must be capable of 1018 interacting with the resource owner's user-agent (typically a web 1019 browser) and capable of receiving incoming requests (via redirection) 1020 from the authorization server. 1022 +----------+ 1023 | Resource | 1024 | Owner | 1025 | | 1026 +----------+ 1027 ^ 1028 | 1029 (2) 1030 +----|-----+ Client Identifier +---------------+ 1031 | -+----(1)-- & Redirection URI ---->| | 1032 | User- | | Authorization | 1033 | Agent -+----(2)-- User authenticates --->| Server | 1034 | | | | 1035 | -+----(3)-- Authorization Code ---<| | 1036 +-|----|---+ +---------------+ 1037 | | ^ v 1038 (1) (3) | | 1039 | | | | 1040 ^ v | | 1041 +---------+ | | 1042 | |>---(4)-- Authorization Code ---------' | 1043 | Client | & Redirection URI | 1044 | | | 1045 | |<---(5)----- Access Token -------------------' 1046 +---------+ (w/ Optional Refresh Token) 1048 Note: The lines illustrating steps (1), (2), and (3) are broken into 1049 two parts as they pass through the user-agent. 1051 Figure 3: Authorization Code Flow 1053 The flow illustrated in Figure 3 includes the following steps: 1055 (1) The client initiates the flow by directing the resource owner's 1056 user-agent to the authorization endpoint. The client includes its 1057 client identifier, PKCE code challenge, optional requested scope, 1058 optional local state, and a redirection URI to which the 1059 authorization server will send the user-agent back once access is 1060 granted (or denied). 1062 (2) The authorization server authenticates the resource owner (via 1063 the user-agent) and establishes whether the resource owner grants or 1064 denies the client's access request. 1066 (3) Assuming the resource owner grants access, the authorization 1067 server redirects the user-agent back to the client using the 1068 redirection URI provided earlier (in the request or during client 1069 registration). The redirection URI includes an authorization code 1070 and any local state provided by the client earlier. 1072 (4) The client requests an access token from the authorization 1073 server's token endpoint by including the authorization code received 1074 in the previous step, and including its code verifier. When making 1075 the request, the client authenticates with the authorization server 1076 if it can. The client includes the redirection URI used to obtain 1077 the authorization code for verification. 1079 (5) The authorization server authenticates the client when possible, 1080 validates the authorization code, validates the code verifier, and 1081 ensures that the redirection URI received matches the URI used to 1082 redirect the client in step (C). If valid, the authorization server 1083 responds back with an access token and, optionally, a refresh token. 1085 4.1.1. Authorization Request 1087 To begin the authorization request, the client builds the 1088 authorization request URI by adding parameters to the authorization 1089 server's authorization endpoint URI. 1091 Clients use a unique secret per authorization request to protect 1092 against code injection and CSRF attacks. The client first generates 1093 this secret, which it can later use along with the authorization code 1094 to prove that the application using the authorization code is the 1095 same application that requested it. This practice is known as 1096 "Proof-Key for Code Exchange", or PKCE, after the OAuth 2.0 extension 1097 ([RFC7636]) where it was originally developed. 1099 4.1.1.1. Client Creates a PKCE Code Verifier 1101 The client first creates a PKCE code verifier, "code_verifier", for 1102 each Authorization Request, in the following manner: 1104 code_verifier = high-entropy cryptographic random STRING using the 1105 unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"` 1106 from Section 2.3 of {{RFC3986}}, with a minimum length of 43 characters 1107 and a maximum length of 128 characters. 1109 ABNF for "code_verifier" is as follows. 1111 code-verifier = 43*128unreserved 1112 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1113 ALPHA = %x41-5A / %x61-7A 1114 DIGIT = %x30-39 1116 NOTE: The code verifier SHOULD have enough entropy to make it 1117 impractical to guess the value. It is RECOMMENDED that the output of 1118 a suitable random number generator be used to create a 32-octet 1119 sequence. The octet sequence is then base64url-encoded to produce a 1120 43-octet URL-safe string to use as the code verifier. 1122 4.1.1.2. Client Creates the PKCE Code Challenge 1124 The client then creates a PKCE code challenge derived from the code 1125 verifier by using one of the following transformations on the code 1126 verifier: 1128 plain 1129 code_challenge = code_verifier 1131 S256 1132 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1134 If the client is capable of using "S256", it MUST use "S256", as 1135 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1136 permitted to use "plain" only if they cannot support "S256" for some 1137 technical reason and know via out-of-band configuration or via 1138 Authorization Server Metadata ([RFC8414]) that the server supports 1139 "plain". 1141 The plain transformation is for compatibility with existing 1142 deployments and for constrained environments that can't use the S256 1143 transformation. 1145 ABNF for "code_challenge" is as follows. 1147 code-challenge = 43*128unreserved 1148 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1149 ALPHA = %x41-5A / %x61-7A 1150 DIGIT = %x30-39 1152 4.1.1.3. Client Initiates the Authorization Request 1154 The client constructs the request URI by adding the following 1155 parameters to the query component of the authorization endpoint URI 1156 using the "application/x-www-form-urlencoded" format, per Appendix B: 1158 "response_type": REQUIRED. Value MUST be set to "code". 1160 "client_id": REQUIRED. The client identifier as described in 1161 Section 2.2. 1163 "code_challenge": REQUIRED. Code challenge. 1165 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1166 present in the request. Code verifier transformation method is 1167 "S256" or "plain". 1169 "redirect_uri": OPTIONAL. As described in Section 3.1.2. 1171 "scope": OPTIONAL. The scope of the access request as described by 1172 Section 3.3. 1174 "state": OPTIONAL. An opaque value used by the client to maintain 1175 state between the request and callback. The authorization server 1176 includes this value when redirecting the user-agent back to the 1177 client. 1179 The client directs the resource owner to the constructed URI using an 1180 HTTP redirection response, or by other means available to it via the 1181 user-agent. 1183 For example, the client directs the user-agent to make the following 1184 HTTP request using TLS (with extra line breaks for display purposes 1185 only): 1187 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1188 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1189 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1190 &code_challenge_method=S256 HTTP/1.1 1191 Host: server.example.com 1193 The authorization server validates the request to ensure that all 1194 required parameters are present and valid. If the request is valid, 1195 the authorization server authenticates the resource owner and obtains 1196 an authorization decision (by asking the resource owner or by 1197 establishing approval via other means). 1199 When a decision is established, the authorization server directs the 1200 user-agent to the provided client redirection URI using an HTTP 1201 redirection response, or by other means available to it via the user- 1202 agent. 1204 4.1.2. Authorization Response 1206 If the resource owner grants the access request, the authorization 1207 server issues an authorization code and delivers it to the client by 1208 adding the following parameters to the query component of the 1209 redirection URI using the "application/x-www-form-urlencoded" format, 1210 per Appendix B: 1212 "code": REQUIRED. The authorization code generated by the 1213 authorization server. The authorization code MUST expire shortly 1214 after it is issued to mitigate the risk of leaks. A maximum 1215 authorization code lifetime of 10 minutes is RECOMMENDED. The 1216 client MUST NOT use the authorization code more than once. If an 1217 authorization code is used more than once, the authorization 1218 server MUST deny the request and SHOULD revoke (when possible) all 1219 tokens previously issued based on that authorization code. The 1220 authorization code is bound to the client identifier and 1221 redirection URI. 1223 "state": REQUIRED if the "state" parameter was present in the client 1224 authorization request. The exact value received from the client. 1226 For example, the authorization server redirects the user-agent by 1227 sending the following HTTP response: 1229 HTTP/1.1 302 Found 1230 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1231 &state=xyz 1233 The client MUST ignore unrecognized response parameters. The 1234 authorization code string size is left undefined by this 1235 specification. The client should avoid making assumptions about code 1236 value sizes. The authorization server SHOULD document the size of 1237 any value it issues. 1239 When the server issues the authorization code in the authorization 1240 response, it MUST associate the "code_challenge" and 1241 "code_challenge_method" values with the authorization code so it can 1242 be verified later. 1244 The "code_challenge" and "code_challenge_method" values may be stored 1245 in encrypted form in the "code" itself, but could alternatively be 1246 stored on the server associated with the code. The server MUST NOT 1247 include the "code_challenge" value in client requests in a form that 1248 other entities can extract. 1250 The exact method that the server uses to associate the 1251 "code_challenge" with the issued "code" is out of scope for this 1252 specification. 1254 4.1.2.1. Error Response 1256 If the request fails due to a missing, invalid, or mismatching 1257 redirection URI, or if the client identifier is missing or invalid, 1258 the authorization server SHOULD inform the resource owner of the 1259 error and MUST NOT automatically redirect the user-agent to the 1260 invalid redirection URI. 1262 If the client does not send the "code_challenge" in the request, the 1263 authorization endpoint MUST return the authorization error response 1264 with the "error" value set to "invalid_request". The 1265 "error_description" or the response of "error_uri" SHOULD explain the 1266 nature of error, e.g., code challenge required. 1268 If the server supporting PKCE does not support the requested 1269 transformation, the authorization endpoint MUST return the 1270 authorization error response with "error" value set to 1271 "invalid_request". The "error_description" or the response of 1272 "error_uri" SHOULD explain the nature of error, e.g., transform 1273 algorithm not supported. 1275 If the resource owner denies the access request or if the request 1276 fails for reasons other than a missing or invalid redirection URI, 1277 the authorization server informs the client by adding the following 1278 parameters to the query component of the redirection URI using the 1279 "application/x-www-form-urlencoded" format, per Appendix B: 1281 "error": REQUIRED. A single ASCII [USASCII] error code from the 1282 following: 1284 "invalid_request": The request is missing a required parameter, 1285 includes an invalid parameter value, includes a parameter more 1286 than once, or is otherwise malformed. 1288 "unauthorized_client": The client is not authorized to request an 1289 authorization code using this method. 1291 "access_denied": The resource owner or authorization server 1292 denied the request. 1294 "unsupported_response_type": The authorization server does not 1295 support obtaining an authorization code using this method. 1297 "invalid_scope": The requested scope is invalid, unknown, or 1298 malformed. 1300 "server_error": The authorization server encountered an 1301 unexpected condition that prevented it from fulfilling the 1302 request. (This error code is needed because a 500 Internal 1303 Server Error HTTP status code cannot be returned to the client 1304 via an HTTP redirect.) 1306 "temporarily_unavailable": The authorization server is currently 1307 unable to handle the request due to a temporary overloading or 1308 maintenance of the server. (This error code is needed because 1309 a 503 Service Unavailable HTTP status code cannot be returned 1310 to the client via an HTTP redirect.) 1312 Values for the "error" parameter MUST NOT include characters 1313 outside the set %x20-21 / %x23-5B / %x5D-7E. 1315 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1316 providing additional information, used to assist the client 1317 developer in understanding the error that occurred. Values for 1318 the "error_description" parameter MUST NOT include characters 1319 outside the set %x20-21 / %x23-5B / %x5D-7E. 1321 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1322 with information about the error, used to provide the client 1323 developer with additional information about the error. Values for 1324 the "error_uri" parameter MUST conform to the URI-reference syntax 1325 and thus MUST NOT include characters outside the set %x21 / 1326 %x23-5B / %x5D-7E. 1328 "state": REQUIRED if a "state" parameter was present in the client 1329 authorization request. The exact value received from the client. 1331 For example, the authorization server redirects the user-agent by 1332 sending the following HTTP response: 1334 HTTP/1.1 302 Found 1335 Location: https://client.example.com/cb?error=access_denied&state=xyz 1337 4.1.3. Access Token Request 1339 The client makes a request to the token endpoint by sending the 1340 following parameters using the "application/x-www-form-urlencoded" 1341 format per Appendix B with a character encoding of UTF-8 in the HTTP 1342 request entity-body: 1344 "grant_type": REQUIRED. Value MUST be set to "authorization_code". 1346 "code": REQUIRED. The authorization code received from the 1347 authorization server. 1349 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1350 included in the authorization request as described in 1351 Section 4.1.1, and their values MUST be identical. 1353 "client_id": REQUIRED, if the client is not authenticating with the 1354 authorization server as described in Section 3.2.1. 1356 "code_verifier": REQUIRED. Code verifier 1358 If the client type is confidential or the client was issued client 1359 credentials (or assigned other authentication requirements), the 1360 client MUST authenticate with the authorization server as described 1361 in Section 3.2.1. 1363 For example, the client makes the following HTTP request using TLS 1364 (with extra line breaks for display purposes only): 1366 POST /token HTTP/1.1 1367 Host: server.example.com 1368 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1369 Content-Type: application/x-www-form-urlencoded 1371 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1372 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1373 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1375 The authorization server MUST: 1377 * require client authentication for confidential clients or for any 1378 client that was issued client credentials (or with other 1379 authentication requirements), 1381 * authenticate the client if client authentication is included, 1383 * ensure that the authorization code was issued to the authenticated 1384 confidential client, or if the client is public, ensure that the 1385 code was issued to "client_id" in the request, 1387 * verify that the authorization code is valid, 1389 * verify the "code_verifier" by calculating the code challenge from 1390 the received "code_verifier" and comparing it with the previously 1391 associated "code_challenge", after first transforming it according 1392 to the "code_challenge_method" method specified by the client, and 1394 * ensure that the "redirect_uri" parameter is present if the 1395 "redirect_uri" parameter was included in the initial authorization 1396 request as described in Section 4.1.1.3, and if included ensure 1397 that their values are identical. 1399 4.1.4. Access Token Response 1401 If the access token request is valid and authorized, the 1402 authorization server issues an access token and optional refresh 1403 token as described in Section 5.1. If the request client 1404 authentication failed or is invalid, the authorization server returns 1405 an error response as described in Section 5.2. 1407 An example successful response: 1409 HTTP/1.1 200 OK 1410 Content-Type: application/json 1411 Cache-Control: no-store 1412 Pragma: no-cache 1414 { 1415 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1416 "token_type": "Bearer", 1417 "expires_in": 3600, 1418 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 1419 "example_parameter": "example_value" 1420 } 1422 4.2. Client Credentials Grant 1424 The client can request an access token using only its client 1425 credentials (or other supported means of authentication) when the 1426 client is requesting access to the protected resources under its 1427 control, or those of another resource owner that have been previously 1428 arranged with the authorization server (the method of which is beyond 1429 the scope of this specification). 1431 The client credentials grant type MUST only be used by confidential 1432 clients. 1434 +---------+ +---------------+ 1435 | | | | 1436 | |>--(A)- Client Authentication --->| Authorization | 1437 | Client | | Server | 1438 | |<--(B)---- Access Token ---------<| | 1439 | | | | 1440 +---------+ +---------------+ 1441 Figure 4: Client Credentials Flow 1443 The flow illustrated in Figure 4 includes the following steps: 1445 (A) The client authenticates with the authorization server and 1446 requests an access token from the token endpoint. 1448 (B) The authorization server authenticates the client, and if valid, 1449 issues an access token. 1451 4.2.1. Authorization Request and Response 1453 Since the client authentication is used as the authorization grant, 1454 no additional authorization request is needed. 1456 4.2.2. Access Token Request 1458 The client makes a request to the token endpoint by adding the 1459 following parameters using the "application/x-www-form-urlencoded" 1460 format per Appendix B with a character encoding of UTF-8 in the HTTP 1461 request entity-body: 1463 "grant_type": REQUIRED. Value MUST be set to "client_credentials". 1465 "scope": OPTIONAL. The scope of the access request as described by 1466 Section 3.3. 1468 The client MUST authenticate with the authorization server as 1469 described in Section 3.2.1. 1471 For example, the client makes the following HTTP request using 1472 transport-layer security (with extra line breaks for display purposes 1473 only): 1475 POST /token HTTP/1.1 1476 Host: server.example.com 1477 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1478 Content-Type: application/x-www-form-urlencoded 1480 grant_type=client_credentials 1482 The authorization server MUST authenticate the client. 1484 4.2.3. Access Token Response 1486 If the access token request is valid and authorized, the 1487 authorization server issues an access token as described in 1488 Section 5.1. A refresh token SHOULD NOT be included. If the request 1489 failed client authentication or is invalid, the authorization server 1490 returns an error response as described in Section 5.2. 1492 An example successful response: 1494 HTTP/1.1 200 OK 1495 Content-Type: application/json 1496 Cache-Control: no-store 1497 Pragma: no-cache 1499 { 1500 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1501 "token_type": "Bearer", 1502 "expires_in": 3600, 1503 "example_parameter": "example_value" 1504 } 1506 4.3. Extension Grants 1508 The client uses an extension grant type by specifying the grant type 1509 using an absolute URI (defined by the authorization server) as the 1510 value of the "grant_type" parameter of the token endpoint, and by 1511 adding any additional parameters necessary. 1513 For example, to request an access token using a Security Assertion 1514 Markup Language (SAML) 2.0 assertion grant type as defined by 1515 [RFC7522], the client could make the following HTTP request using TLS 1516 (with extra line breaks for display purposes only): 1518 POST /token HTTP/1.1 1519 Host: server.example.com 1520 Content-Type: application/x-www-form-urlencoded 1522 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1523 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1524 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1526 If the access token request is valid and authorized, the 1527 authorization server issues an access token and optional refresh 1528 token as described in Section 5.1. If the request failed client 1529 authentication or is invalid, the authorization server returns an 1530 error response as described in Section 5.2. 1532 5. Issuing an Access Token 1534 If the access token request is valid and authorized, the 1535 authorization server issues an access token and optional refresh 1536 token as described in Section 5.1. If the request failed client 1537 authentication or is invalid, the authorization server returns an 1538 error response as described in Section 5.2. 1540 5.1. Successful Response 1542 The authorization server issues an access token and optional refresh 1543 token, and constructs the response by adding the following parameters 1544 to the entity-body of the HTTP response with a 200 (OK) status code: 1546 "access_token": REQUIRED. The access token issued by the 1547 authorization server. 1549 "token_type": REQUIRED. The type of the token issued as described 1550 in Section 7.1. Value is case insensitive. 1552 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1553 token. For example, the value "3600" denotes that the access 1554 token will expire in one hour from the time the response was 1555 generated. If omitted, the authorization server SHOULD provide 1556 the expiration time via other means or document the default value. 1558 "refresh_token": OPTIONAL. The refresh token, which can be used to 1559 obtain new access tokens using the same authorization grant as 1560 described in Section 6. 1562 "scope": OPTIONAL, if identical to the scope requested by the 1563 client; otherwise, REQUIRED. The scope of the access token as 1564 described by Section 3.3. 1566 The parameters are included in the entity-body of the HTTP response 1567 using the "application/json" media type as defined by [RFC7159]. The 1568 parameters are serialized into a JavaScript Object Notation (JSON) 1569 structure by adding each parameter at the highest structure level. 1570 Parameter names and string values are included as JSON strings. 1571 Numerical values are included as JSON numbers. The order of 1572 parameters does not matter and can vary. 1574 The authorization server MUST include the HTTP "Cache-Control" 1575 response header field [RFC7234] with a value of "no-store" in any 1576 response containing tokens, credentials, or other sensitive 1577 information, as well as the "Pragma" response header field [RFC7234] 1578 with a value of "no-cache". 1580 For example: 1582 HTTP/1.1 200 OK 1583 Content-Type: application/json 1584 Cache-Control: no-store 1585 Pragma: no-cache 1587 { 1588 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1589 "token_type":"Bearer", 1590 "expires_in":3600, 1591 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1592 "example_parameter":"example_value" 1593 } 1595 The client MUST ignore unrecognized value names in the response. The 1596 sizes of tokens and other values received from the authorization 1597 server are left undefined. The client should avoid making 1598 assumptions about value sizes. The authorization server SHOULD 1599 document the size of any value it issues. 1601 5.2. Error Response 1603 The authorization server responds with an HTTP 400 (Bad Request) 1604 status code (unless specified otherwise) and includes the following 1605 parameters with the 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 "error": REQUIRED. A single ASCII [USASCII] error code from the 1612 following: 1614 "invalid_request": The request is missing a required parameter, 1615 includes an unsupported parameter value (other than grant 1616 type), repeats a parameter, includes multiple credentials, 1617 utilizes more than one mechanism for authenticating the client, 1618 or is otherwise malformed. 1620 "invalid_client": Client authentication failed (e.g., unknown 1621 client, no client authentication included, or unsupported 1622 authentication method). The authorization server MAY return an 1623 HTTP 401 (Unauthorized) status code to indicate which HTTP 1624 authentication schemes are supported. If the client attempted 1625 to authenticate via the "Authorization" request header field, 1626 the authorization server MUST respond with an HTTP 401 1627 (Unauthorized) status code and include the "WWW-Authenticate" 1628 response header field matching the authentication scheme used 1629 by the client. 1631 "invalid_grant": The provided authorization grant (e.g., 1632 authorization code, resource owner credentials) or refresh 1633 token is invalid, expired, revoked, does not match the 1634 redirection URI used in the authorization request, or was 1635 issued to another client. 1637 "unauthorized_client": The authenticated client is not authorized 1638 to use this authorization grant type. 1640 "unsupported_grant_type": The authorization grant type is not 1641 supported by the authorization server. 1643 "invalid_scope": The requested scope is invalid, unknown, 1644 malformed, or exceeds the scope granted by the resource owner. 1646 Values for the "error" parameter MUST NOT include characters 1647 outside the set %x20-21 / %x23-5B / %x5D-7E. 1649 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1650 providing additional information, used to assist the client 1651 developer in understanding the error that occurred. Values for 1652 the "error_description" parameter MUST NOT include characters 1653 outside the set %x20-21 / %x23-5B / %x5D-7E. 1655 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1656 with information about the error, used to provide the client 1657 developer with additional information about the error. Values for 1658 the "error_uri" parameter MUST conform to the URI-reference syntax 1659 and thus MUST NOT include characters outside the set %x21 / 1660 %x23-5B / %x5D-7E. 1662 The parameters are included in the entity-body of the HTTP response 1663 using the "application/json" media type as defined by [RFC7159]. The 1664 parameters are serialized into a JSON structure by adding each 1665 parameter at the highest structure level. Parameter names and string 1666 values are included as JSON strings. Numerical values are included 1667 as JSON numbers. The order of parameters does not matter and can 1668 vary. 1670 For example: 1672 HTTP/1.1 400 Bad Request 1673 Content-Type: application/json 1674 Cache-Control: no-store 1675 Pragma: no-cache 1677 { 1678 "error":"invalid_request" 1679 } 1681 6. Refreshing an Access Token 1683 Authorization servers SHOULD determine, based on a risk assessment, 1684 whether to issue refresh tokens to a certain client. If the 1685 authorization server decides not to issue refresh tokens, the client 1686 MAY refresh access tokens by utilizing other grant types, such as the 1687 authorization code grant type. In such a case, the authorization 1688 server may utilize cookies and persistent grants to optimize the user 1689 experience. 1691 If refresh tokens are issued, those refresh tokens MUST be bound to 1692 the scope and resource servers as consented by the resource owner. 1693 This is to prevent privilege escalation by the legitimate client and 1694 reduce the impact of refresh token leakage. 1696 If the authorization server issued a refresh token to the client, the 1697 client makes a refresh request to the token endpoint by adding the 1698 following parameters using the "application/x-www-form-urlencoded" 1699 format per Appendix B with a character encoding of UTF-8 in the HTTP 1700 request entity-body: 1702 "grant_type": REQUIRED. Value MUST be set to "refresh_token". 1704 "refresh_token": REQUIRED. The refresh token issued to the client. 1706 "scope": OPTIONAL. The scope of the access request as described by 1707 Section 3.3. The requested scope MUST NOT include any scope not 1708 originally granted by the resource owner, and if omitted is 1709 treated as equal to the scope originally granted by the resource 1710 owner. 1712 Because refresh tokens are typically long-lasting credentials used to 1713 request additional access tokens, the refresh token is bound to the 1714 client to which it was issued. If the client type is confidential or 1715 the client was issued client credentials (or assigned other 1716 authentication requirements), the client MUST authenticate with the 1717 authorization server as described in Section 3.2.1. 1719 For example, the client makes the following HTTP request using 1720 transport-layer security (with extra line breaks for display purposes 1721 only): 1723 POST /token HTTP/1.1 1724 Host: server.example.com 1725 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1726 Content-Type: application/x-www-form-urlencoded 1728 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1730 The authorization server MUST: 1732 * require client authentication for confidential clients or for any 1733 client that was issued client credentials (or with other 1734 authentication requirements), 1736 * authenticate the client if client authentication is included and 1737 ensure that the refresh token was issued to the authenticated 1738 client, and 1740 * validate the refresh token. 1742 Authorization server MUST utilize one of these methods to detect 1743 refresh token replay by malicious actors for public clients: 1745 * _Sender-constrained refresh tokens:_ the authorization server 1746 cryptographically binds the refresh token to a certain client 1747 instance by utilizing [I-D.ietf-oauth-token-binding] or [RFC8705]. 1749 * _Refresh token rotation:_ the authorization server issues a new 1750 refresh token with every access token refresh response. The 1751 previous refresh token is invalidated but information about the 1752 relationship is retained by the authorization server. If a 1753 refresh token is compromised and subsequently used by both the 1754 attacker and the legitimate client, one of them will present an 1755 invalidated refresh token, which will inform the authorization 1756 server of the breach. The authorization server cannot determine 1757 which party submitted the invalid refresh token, but it will 1758 revoke the active refresh token. This stops the attack at the 1759 cost of forcing the legitimate client to obtain a fresh 1760 authorization grant. 1762 Implementation note: the grant to which a refresh token belongs 1763 may be encoded into the refresh token itself. This can enable an 1764 authorization server to efficiently determine the grant to which a 1765 refresh token belongs, and by extension, all refresh tokens that 1766 need to be revoked. Authorization servers MUST ensure the 1767 integrity of the refresh token value in this case, for example, 1768 using signatures. 1770 If valid and authorized, the authorization server issues an access 1771 token as described in Section 5.1. If the request failed 1772 verification or is invalid, the authorization server returns an error 1773 response as described in Section 5.2. 1775 The authorization server MAY issue a new refresh token, in which case 1776 the client MUST discard the old refresh token and replace it with the 1777 new refresh token. The authorization server MAY revoke the old 1778 refresh token after issuing a new refresh token to the client. If a 1779 new refresh token is issued, the refresh token scope MUST be 1780 identical to that of the refresh token included by the client in the 1781 request. 1783 Authorization servers MAY revoke refresh tokens automatically in case 1784 of a security event, such as: 1786 * password change 1788 * logout at the authorization server 1790 Refresh tokens SHOULD expire if the client has been inactive for some 1791 time, i.e., the refresh token has not been used to obtain fresh 1792 access tokens for some time. The expiration time is at the 1793 discretion of the authorization server. It might be a global value 1794 or determined based on the client policy or the grant associated with 1795 the refresh token (and its sensitivity). 1797 7. Accessing Protected Resources 1799 The client accesses protected resources by presenting the access 1800 token to the resource server. The resource server MUST validate the 1801 access token and ensure that it has not expired and that its scope 1802 covers the requested resource. The methods used by the resource 1803 server to validate the access token (as well as any error responses) 1804 are beyond the scope of this specification but generally involve an 1805 interaction or coordination between the resource server and the 1806 authorization server. 1808 The method in which the client utilizes the access token to 1809 authenticate with the resource server depends on the type of access 1810 token issued by the authorization server. Typically, it involves 1811 using the HTTP "Authorization" request header field [RFC2617] with an 1812 authentication scheme defined by the specification of the access 1813 token type used, such as "Bearer", defined below. 1815 7.1. Access Token Types 1817 The access token type provides the client with the information 1818 required to successfully utilize the access token to make a protected 1819 resource request (along with type-specific attributes). The client 1820 MUST NOT use an access token if it does not understand the token 1821 type. 1823 For example, the "Bearer" token type defined in this specification is 1824 utilized by simply including the access token string in the request: 1826 GET /resource/1 HTTP/1.1 1827 Host: example.com 1828 Authorization: Bearer mF_9.B5f-4.1JqM 1830 The above example is provided for illustration purposes only. 1832 Each access token type definition specifies the additional attributes 1833 (if any) sent to the client together with the "access_token" response 1834 parameter. It also defines the HTTP authentication method used to 1835 include the access token when making a protected resource request. 1837 7.2. Bearer Tokens 1839 A Bearer Token is a security token with the property that any party 1840 in possession of the token (a "bearer") can use the token in any way 1841 that any other party in possession of it can. Using a bearer token 1842 does not require a bearer to prove possession of cryptographic key 1843 material (proof-of-possession). 1845 Bearer tokens may be extended to include proof-of-possession 1846 techniques by other specifications. 1848 7.2.1. Authenticated Requests 1850 This section defines two methods of sending Bearer tokens in resource 1851 requetss to resource servers. Clients MUST NOT use more than one 1852 method to transmit the token in each request. 1854 7.2.1.1. Authorization Request Header Field 1856 When sending the access token in the "Authorization" request header 1857 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 1858 authentication scheme to transmit the access token. 1860 For example: 1862 GET /resource HTTP/1.1 1863 Host: server.example.com 1864 Authorization: Bearer mF_9.B5f-4.1JqM 1866 The syntax of the "Authorization" header field for this scheme 1867 follows the usage of the Basic scheme defined in Section 2 of 1868 [RFC2617]. Note that, as with Basic, it does not conform to the 1869 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1870 with the general authentication framework in HTTP 1.1 Authentication 1871 [RFC7235], although it does not follow the preferred practice 1872 outlined therein in order to reflect existing deployments. The 1873 syntax for Bearer credentials is as follows: 1875 b64token = 1*( ALPHA / DIGIT / 1876 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1877 credentials = "Bearer" 1*SP b64token 1879 Clients SHOULD make authenticated requests with a bearer token using 1880 the "Authorization" request header field with the "Bearer" HTTP 1881 authorization scheme. Resource servers MUST support this method. 1883 7.2.1.2. Form-Encoded Body Parameter 1885 When sending the access token in the HTTP request entity-body, the 1886 client adds the access token to the request-body using the 1887 "access_token" parameter. The client MUST NOT use this method unless 1888 all of the following conditions are met: 1890 * The HTTP request entity-header includes the "Content-Type" header 1891 field set to "application/x-www-form-urlencoded". 1893 * The entity-body follows the encoding requirements of the 1894 "application/x-www-form-urlencoded" content-type as defined by 1895 HTML 4.01 [W3C.REC-html401-19991224]. 1897 * The HTTP request entity-body is single-part. 1899 * The content to be encoded in the entity-body MUST consist entirely 1900 of ASCII [USASCII] characters. 1902 * The HTTP request method is one for which the request-body has 1903 defined semantics. In particular, this means that the "GET" 1904 method MUST NOT be used. 1906 The entity-body MAY include other request-specific parameters, in 1907 which case the "access_token" parameter MUST be properly separated 1908 from the request-specific parameters using "&" character(s) (ASCII 1909 code 38). 1911 For example, the client makes the following HTTP request using 1912 transport-layer security: 1914 POST /resource HTTP/1.1 1915 Host: server.example.com 1916 Content-Type: application/x-www-form-urlencoded 1918 access_token=mF_9.B5f-4.1JqM 1920 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1921 except in application contexts where participating clients do not 1922 have access to the "Authorization" request header field. Resource 1923 servers MAY support this method. 1925 7.2.2. The WWW-Authenticate Response Header Field 1927 If the protected resource request does not include authentication 1928 credentials or does not contain an access token that enables access 1929 to the protected resource, the resource server MUST include the HTTP 1930 "WWW-Authenticate" response header field; it MAY include it in 1931 response to other conditions as well. The "WWW-Authenticate" header 1932 field uses the framework defined by HTTP/1.1 [RFC2617]. 1934 All challenges defined by this specification MUST use the auth-scheme 1935 value "Bearer". This scheme MUST be followed by one or more auth- 1936 param values. The auth-param attributes used or defined by this 1937 specification are as follows. Other auth-param attributes MAY be 1938 used as well. 1940 A "realm" attribute MAY be included to indicate the scope of 1941 protection in the manner described in HTTP/1.1 [RFC2617]. The 1942 "realm" attribute MUST NOT appear more than once. 1944 The "scope" attribute is defined in Section 3.3. The "scope" 1945 attribute is a space-delimited list of case-sensitive scope values 1946 indicating the required scope of the access token for accessing the 1947 requested resource. "scope" values are implementation defined; there 1948 is no centralized registry for them; allowed values are defined by 1949 the authorization server. The order of "scope" values is not 1950 significant. In some cases, the "scope" value will be used when 1951 requesting a new access token with sufficient scope of access to 1952 utilize the protected resource. Use of the "scope" attribute is 1953 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 1954 "scope" value is intended for programmatic use and is not meant to be 1955 displayed to end-users. 1957 Two example scope values follow; these are taken from the OpenID 1958 Connect [OpenID.Messages] and the Open Authentication Technology 1959 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 1960 OAuth 2.0 use cases, respectively: 1962 scope="openid profile email" 1963 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 1965 If the protected resource request included an access token and failed 1966 authentication, the resource server SHOULD include the "error" 1967 attribute to provide the client with the reason why the access 1968 request was declined. The parameter value is described in 1969 Section 7.3.1. In addition, the resource server MAY include the 1970 "error_description" attribute to provide developers a human-readable 1971 explanation that is not meant to be displayed to end-users. It also 1972 MAY include the "error_uri" attribute with an absolute URI 1973 identifying a human-readable web page explaining the error. The 1974 "error", "error_description", and "error_uri" attributes MUST NOT 1975 appear more than once. 1977 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 1978 include characters outside the set %x21 / %x23-5B / %x5D-7E for 1979 representing scope values and %x20 for delimiters between scope 1980 values. Values for the "error" and "error_description" attributes 1981 (specified in Appendixes A.7 and A.8) MUST NOT include characters 1982 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 1983 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 1984 the URI-reference syntax and thus MUST NOT include characters outside 1985 the set %x21 / %x23-5B / %x5D-7E. 1987 For example, in response to a protected resource request without 1988 authentication: 1990 HTTP/1.1 401 Unauthorized 1991 WWW-Authenticate: Bearer realm="example" 1993 And in response to a protected resource request with an 1994 authentication attempt using an expired access token: 1996 HTTP/1.1 401 Unauthorized 1997 WWW-Authenticate: Bearer realm="example", 1998 error="invalid_token", 1999 error_description="The access token expired" 2001 7.3. Error Response 2003 If a resource access request fails, the resource server SHOULD inform 2004 the client of the error. While the specifics of such error responses 2005 are beyond the scope of this specification, this document establishes 2006 a common registry in Section 13.4 for error values to be shared among 2007 OAuth token authentication schemes. 2009 New authentication schemes designed primarily for OAuth token 2010 authentication SHOULD define a mechanism for providing an error 2011 status code to the client, in which the error values allowed are 2012 registered in the error registry established by this specification. 2014 Such schemes MAY limit the set of valid error codes to a subset of 2015 the registered values. If the error code is returned using a named 2016 parameter, the parameter name SHOULD be "error". 2018 Other schemes capable of being used for OAuth token authentication, 2019 but not primarily designed for that purpose, MAY bind their error 2020 values to the registry in the same manner. 2022 New authentication schemes MAY choose to also specify the use of the 2023 "error_description" and "error_uri" parameters to return error 2024 information in a manner parallel to their usage in this 2025 specification. 2027 7.3.1. Error Codes 2029 When a request fails, the resource server responds using the 2030 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2031 includes one of the following error codes in the response: 2033 "invalid_request": The request is missing a required parameter, 2034 includes an unsupported parameter or parameter value, repeats the 2035 same parameter, uses more than one method for including an access 2036 token, or is otherwise malformed. The resource server SHOULD 2037 respond with the HTTP 400 (Bad Request) status code. 2039 "invalid_token": The access token provided is expired, revoked, 2040 malformed, or invalid for other reasons. The resource SHOULD 2041 respond with the HTTP 401 (Unauthorized) status code. The client 2042 MAY request a new access token and retry the protected resource 2043 request. 2045 "insufficient_scope": The request requires higher privileges than 2046 provided by the access token. The resource server SHOULD respond 2047 with the HTTP 403 (Forbidden) status code and MAY include the 2048 "scope" attribute with the scope necessary to access the protected 2049 resource. 2051 If the request lacks any authentication information (e.g., the client 2052 was unaware that authentication is necessary or attempted using an 2053 unsupported authentication method), the resource server SHOULD NOT 2054 include an error code or other error information. 2056 For example: 2058 HTTP/1.1 401 Unauthorized 2059 WWW-Authenticate: Bearer realm="example" 2061 7.4. Access Token Security Considerations 2063 7.4.1. Security Threats 2065 The following list presents several common threats against protocols 2066 utilizing some form of tokens. This list of threats is based on NIST 2067 Special Publication 800-63 [NIST800-63]. 2069 7.4.1.1. Token manufacture/modification 2071 An attacker may generate a bogus token or modify the token contents 2072 (such as the authentication or attribute statements) of an existing 2073 token, causing the resource server to grant inappropriate access to 2074 the client. For example, an attacker may modify the token to extend 2075 the validity period; a malicious client may modify the assertion to 2076 gain access to information that they should not be able to view. 2078 7.4.1.2. Token disclosure 2080 Tokens may contain authentication and attribute statements that 2081 include sensitive information. 2083 7.4.1.3. Token redirect 2085 An attacker uses a token generated for consumption by one resource 2086 server to gain access to a different resource server that mistakenly 2087 believes the token to be for it. 2089 7.4.1.4. Token replay 2091 An attacker attempts to use a token that has already been used with 2092 that resource server in the past. 2094 7.4.2. Threat Mitigation 2096 A large range of threats can be mitigated by protecting the contents 2097 of the token by using a digital signature. Alternatively, a bearer 2098 token can contain a reference to authorization information, rather 2099 than encoding the information directly. Such references MUST be 2100 infeasible for an attacker to guess; using a reference may require an 2101 extra interaction between a server and the token issuer to resolve 2102 the reference to the authorization information. The mechanics of 2103 such an interaction are not defined by this specification. 2105 This document does not specify the encoding or the contents of the 2106 token; hence, detailed recommendations about the means of 2107 guaranteeing token integrity protection are outside the scope of this 2108 document. The token integrity protection MUST be sufficient to 2109 prevent the token from being modified. 2111 To deal with token redirect, it is important for the authorization 2112 server to include the identity of the intended recipients (the 2113 audience), typically a single resource server (or a list of resource 2114 servers), in the token. Restricting the use of the token to a 2115 specific scope is also RECOMMENDED. 2117 The authorization server MUST implement TLS. Which version(s) ought 2118 to be implemented will vary over time and will depend on the 2119 widespread deployment and known security vulnerabilities at the time 2120 of implementation. 2122 To protect against token disclosure, confidentiality protection MUST 2123 be applied using TLS with a ciphersuite that provides confidentiality 2124 and integrity protection. This requires that the communication 2125 interaction between the client and the authorization server, as well 2126 as the interaction between the client and the resource server, 2127 utilize confidentiality and integrity protection. Since TLS is 2128 mandatory to implement and to use with this specification, it is the 2129 preferred approach for preventing token disclosure via the 2130 communication channel. For those cases where the client is prevented 2131 from observing the contents of the token, token encryption MUST be 2132 applied in addition to the usage of TLS protection. As a further 2133 defense against token disclosure, the client MUST validate the TLS 2134 certificate chain when making requests to protected resources, 2135 including checking the Certificate Revocation List (CRL) [RFC5280]. 2137 Cookies are typically transmitted in the clear. Thus, any 2138 information contained in them is at risk of disclosure. Therefore, 2139 Bearer tokens MUST NOT be stored in cookies that can be sent in the 2140 clear, as any information in them is at risk of disclosure. See 2141 "HTTP State Management Mechanism" [RFC6265] for security 2142 considerations about cookies. 2144 In some deployments, including those utilizing load balancers, the 2145 TLS connection to the resource server terminates prior to the actual 2146 server that provides the resource. This could leave the token 2147 unprotected between the front-end server where the TLS connection 2148 terminates and the back-end server that provides the resource. In 2149 such deployments, sufficient measures MUST be employed to ensure 2150 confidentiality of the token between the front-end and back-end 2151 servers; encryption of the token is one such possible measure. 2153 To deal with token capture and replay, the following recommendations 2154 are made: First, the lifetime of the token MUST be limited; one means 2155 of achieving this is by putting a validity time field inside the 2156 protected part of the token. Note that using short-lived (one hour 2157 or less) tokens reduces the impact of them being leaked. Second, 2158 confidentiality protection of the exchanges between the client and 2159 the authorization server and between the client and the resource 2160 server MUST be applied. As a consequence, no eavesdropper along the 2161 communication path is able to observe the token exchange. 2162 Consequently, such an on-path adversary cannot replay the token. 2163 Furthermore, when presenting the token to a resource server, the 2164 client MUST verify the identity of that resource server, as per 2165 Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST 2166 validate the TLS certificate chain when making these requests to 2167 protected resources. Presenting the token to an unauthenticated and 2168 unauthorized resource server or failing to validate the certificate 2169 chain will allow adversaries to steal the token and gain unauthorized 2170 access to protected resources. 2172 7.4.3. Summary of Recommendations 2174 7.4.3.1. Safeguard bearer tokens 2176 Client implementations MUST ensure that bearer tokens are not leaked 2177 to unintended parties, as they will be able to use them to gain 2178 access to protected resources. This is the primary security 2179 consideration when using bearer tokens and underlies all the more 2180 specific recommendations that follow. 2182 7.4.3.2. Validate TLS certificate chains 2184 The client MUST validate the TLS certificate chain when making 2185 requests to protected resources. Failing to do so may enable DNS 2186 hijacking attacks to steal the token and gain unintended access. 2188 7.4.3.3. Always use TLS (https) 2190 Clients MUST always use TLS (https) or equivalent transport security 2191 when making requests with bearer tokens. Failing to do so exposes 2192 the token to numerous attacks that could give attackers unintended 2193 access. 2195 7.4.3.4. Don't store bearer tokens in HTTP cookies 2197 Implementations MUST NOT store bearer tokens within cookies that can 2198 be sent in the clear (which is the default transmission mode for 2199 cookies). Implementations that do store bearer tokens in cookies 2200 MUST take precautions against cross-site request forgery. 2202 7.4.3.5. Issue short-lived bearer tokens 2204 Token servers SHOULD issue short-lived (one hour or less) bearer 2205 tokens, particularly when issuing tokens to clients that run within a 2206 web browser or other environments where information leakage may 2207 occur. Using short-lived bearer tokens can reduce the impact of them 2208 being leaked. 2210 7.4.3.6. Issue scoped bearer tokens 2212 Token servers SHOULD issue bearer tokens that contain an audience 2213 restriction, scoping their use to the intended relying party or set 2214 of relying parties. 2216 7.4.3.7. Don't pass bearer tokens in page URLs 2218 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2219 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2220 message headers or message bodies for which confidentiality measures 2221 are taken. Browsers, web servers, and other software may not 2222 adequately secure URLs in the browser history, web server logs, and 2223 other data structures. If bearer tokens are passed in page URLs, 2224 attackers might be able to steal them from the history data, logs, or 2225 other unsecured locations. 2227 7.4.4. Token Replay Prevention 2229 A sender-constrained access token scopes the applicability of an 2230 access token to a certain sender. This sender is obliged to 2231 demonstrate knowledge of a certain secret as prerequisite for the 2232 acceptance of that token at the recipient (e.g., a resource server). 2234 Authorization and resource servers SHOULD use mechanisms for sender- 2235 constrained access tokens to prevent token replay as described in 2236 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2237 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2239 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2240 terminated at an intermediary, refer to Section 4.11 of 2241 [I-D.ietf-oauth-security-topics] for further security advice. 2243 7.4.5. Access Token Privilege Restriction 2245 The privileges associated with an access token SHOULD be restricted 2246 to the minimum required for the particular application or use case. 2247 This prevents clients from exceeding the privileges authorized by the 2248 resource owner. It also prevents users from exceeding their 2249 privileges authorized by the respective security policy. Privilege 2250 restrictions also help to reduce the impact of access token leakage. 2252 In particular, access tokens SHOULD be restricted to certain resource 2253 servers (audience restriction), preferably to a single resource 2254 server. To put this into effect, the authorization server associates 2255 the access token with certain resource servers and every resource 2256 server is obliged to verify, for every request, whether the access 2257 token sent with that request was meant to be used for that particular 2258 resource server. If not, the resource server MUST refuse to serve 2259 the respective request. Clients and authorization servers MAY 2260 utilize the parameters "scope" or "resource" as specified in this 2261 document and [RFC8707], respectively, to determine the resource 2262 server they want to access. 2264 Additionally, access tokens SHOULD be restricted to certain resources 2265 and actions on resource servers or resources. To put this into 2266 effect, the authorization server associates the access token with the 2267 respective resource and actions and every resource server is obliged 2268 to verify, for every request, whether the access token sent with that 2269 request was meant to be used for that particular action on the 2270 particular resource. If not, the resource server must refuse to 2271 serve the respective request. Clients and authorization servers MAY 2272 utilize the parameter "scope" and "authorization_details" as 2273 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2274 actions. 2276 8. Extensibility 2278 8.1. Defining Access Token Types 2280 Access token types can be defined in one of two ways: registered in 2281 the Access Token Types registry (following the procedures in 2282 Section 13.1), or by using a unique absolute URI as its name. 2284 Types utilizing a URI name SHOULD be limited to vendor-specific 2285 implementations that are not commonly applicable, and are specific to 2286 the implementation details of the resource server where they are 2287 used. 2289 All other types MUST be registered. Type names MUST conform to the 2290 type-name ABNF. If the type definition includes a new HTTP 2291 authentication scheme, the type name SHOULD be identical to the HTTP 2292 authentication scheme name (as defined by [RFC2617]). The token type 2293 "example" is reserved for use in examples. 2295 type-name = 1*name-char 2296 name-char = "-" / "." / "_" / DIGIT / ALPHA 2298 8.2. Defining New Endpoint Parameters 2300 New request or response parameters for use with the authorization 2301 endpoint or the token endpoint are defined and registered in the 2302 OAuth Parameters registry following the procedure in Section 13.2. 2304 Parameter names MUST conform to the param-name ABNF, and parameter 2305 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2306 to the syntax of an existing parameter). 2308 param-name = 1*name-char 2309 name-char = "-" / "." / "_" / DIGIT / ALPHA 2311 Unregistered vendor-specific parameter extensions that are not 2312 commonly applicable and that are specific to the implementation 2313 details of the authorization server where they are used SHOULD 2314 utilize a vendor-specific prefix that is not likely to conflict with 2315 other registered values (e.g., begin with 'companyname_'). 2317 8.3. Defining New Authorization Grant Types 2319 New authorization grant types can be defined by assigning them a 2320 unique absolute URI for use with the "grant_type" parameter. If the 2321 extension grant type requires additional token endpoint parameters, 2322 they MUST be registered in the OAuth Parameters registry as described 2323 by Section 13.2. 2325 8.4. Defining New Authorization Endpoint Response Types 2327 New response types for use with the authorization endpoint are 2328 defined and registered in the Authorization Endpoint Response Types 2329 registry following the procedure in Section 13.3. Response type 2330 names MUST conform to the response-type ABNF. 2332 response-type = response-name *( SP response-name ) 2333 response-name = 1*response-char 2334 response-char = "_" / DIGIT / ALPHA 2336 If a response type contains one or more space characters (%x20), it 2337 is compared as a space-delimited list of values in which the order of 2338 values does not matter. Only one order of values can be registered, 2339 which covers all other arrangements of the same set of values. 2341 For example, an extension can define and register the "code 2342 other_token" response type. Once registered, the same combination 2343 cannot be registered as "other_token code", but both values can be 2344 used to denote the same response type. 2346 8.5. Defining Additional Error Codes 2348 In cases where protocol extensions (i.e., access token types, 2349 extension parameters, or extension grant types) require additional 2350 error codes to be used with the authorization code grant error 2351 response (Section 4.1.2.1), the token error response (Section 5.2), 2352 or the resource access error response (Section 7.3), such error codes 2353 MAY be defined. 2355 Extension error codes MUST be registered (following the procedures in 2356 Section 13.4) if the extension they are used in conjunction with is a 2357 registered access token type, a registered endpoint parameter, or an 2358 extension grant type. Error codes used with unregistered extensions 2359 MAY be registered. 2361 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2362 an identifying name when possible. For example, an error identifying 2363 an invalid value set to the extension parameter "example" SHOULD be 2364 named "example_invalid". 2366 error = 1*error-char 2367 error-char = %x20-21 / %x23-5B / %x5D-7E 2369 9. Security Considerations 2371 As a flexible and extensible framework, OAuth's security 2372 considerations depend on many factors. The following sections 2373 provide implementers with security guidelines focused on the three 2374 client profiles described in Section 2.1: web application, browser- 2375 based application, and native application. 2377 A comprehensive OAuth security model and analysis, as well as 2378 background for the protocol design, is provided by [RFC6819] and 2379 [I-D.ietf-oauth-security-topics]. 2381 9.1. Client Authentication 2383 Authorization servers SHOULD use client authentication if possible. 2385 It is RECOMMENDED to use asymmetric (public-key based) methods for 2386 client authentication such as mTLS [RFC8705] or "private_key_jwt" 2387 [OpenID]. When asymmetric methods for client authentication are 2388 used, authorization servers do not need to store sensitive symmetric 2389 keys, making these methods more robust against a number of attacks. 2391 Authorization server MUST only rely on client authentication if the 2392 process of issuance/registration and distribution of the underlying 2393 credentials ensures their confidentiality. 2395 When client authentication is not possible, the authorization server 2396 SHOULD employ other means to validate the client's identity - for 2397 example, by requiring the registration of the client redirection URI 2398 or enlisting the resource owner to confirm identity. A valid 2399 redirection URI is not sufficient to verify the client's identity 2400 when asking for resource owner authorization but can be used to 2401 prevent delivering credentials to a counterfeit client after 2402 obtaining resource owner authorization. 2404 The authorization server must consider the security implications of 2405 interacting with unauthenticated clients and take measures to limit 2406 the potential exposure of other credentials (e.g., refresh tokens) 2407 issued to such clients. 2409 The privileges an authorization server associates with a certain 2410 client identity MUST depend on the assessment of the overall process 2411 for client identification and client credential lifecycle management. 2412 For example, authentication of a dynamically registered client just 2413 ensures the authorization server it is talking to the same client 2414 again. In contrast, if there is a web application whose developer's 2415 identity was verified, who signed a contract and is issued a client 2416 secret that is only used in a secure backend service, the 2417 authorization server might allow this client to access more sensible 2418 services or to use the client credential grant type. 2420 9.1.1. Client Authentication of Native Apps 2422 Secrets that are statically included as part of an app distributed to 2423 multiple users should not be treated as confidential secrets, as one 2424 user may inspect their copy and learn the shared secret. For this 2425 reason, it is NOT RECOMMENDED for authorization servers to require 2426 client authentication of public native apps clients using a shared 2427 secret, as this serves little value beyond client identification 2428 which is already provided by the "client_id" request parameter. 2430 Authorization servers that still require a statically included shared 2431 secret for native app clients MUST treat the client as a public 2432 client (as defined in Section 2.1), and not accept the secret as 2433 proof of the client's identity. Without additional measures, such 2434 clients are subject to client impersonation (see Section 9.3.1). 2436 9.2. Registration of Native App Clients 2438 Except when using a mechanism like Dynamic Client Registration 2439 [RFC7591] to provision per-instance secrets, native apps are 2440 classified as public clients, as defined in Section 2.1; they MUST be 2441 registered with the authorization server as such. Authorization 2442 servers MUST record the client type in the client registration 2443 details in order to identify and process requests accordingly. 2445 Authorization servers MUST require clients to register their complete 2446 redirect URI (including the path component) and reject authorization 2447 requests that specify a redirect URI that doesn't exactly match the 2448 one that was registered; the exception is loopback redirects, where 2449 an exact match is required except for the port URI component. 2451 For private-use URI scheme-based redirects, authorization servers 2452 SHOULD enforce the requirement in Section 10.3.1 that clients use 2453 schemes that are reverse domain name based. At a minimum, any 2454 private-use URI scheme that doesn't contain a period character (".") 2455 SHOULD be rejected. 2457 In addition to the collision-resistant properties, requiring a URI 2458 scheme based on a domain name that is under the control of the app 2459 can help to prove ownership in the event of a dispute where two apps 2460 claim the same private-use URI scheme (where one app is acting 2461 maliciously). For example, if two apps claimed "com.example.app", 2462 the owner of "example.com" could petition the app store operator to 2463 remove the counterfeit app. Such a petition is harder to prove if a 2464 generic URI scheme was used. 2466 Authorization servers MAY request the inclusion of other platform- 2467 specific information, such as the app package or bundle name, or 2468 other information that may be useful for verifying the calling app's 2469 identity on operating systems that support such functions. 2471 9.3. Client Impersonation 2473 A malicious client can impersonate another client and obtain access 2474 to protected resources if the impersonated client fails to, or is 2475 unable to, keep its client credentials confidential. 2477 The authorization server MUST authenticate the client whenever 2478 possible. If the authorization server cannot authenticate the client 2479 due to the client's nature, the authorization server MUST require the 2480 registration of any redirection URI used for receiving authorization 2481 responses and SHOULD utilize other means to protect resource owners 2482 from such potentially malicious clients. For example, the 2483 authorization server can engage the resource owner to assist in 2484 identifying the client and its origin. 2486 The authorization server SHOULD enforce explicit resource owner 2487 authentication and provide the resource owner with information about 2488 the client and the requested authorization scope and lifetime. It is 2489 up to the resource owner to review the information in the context of 2490 the current client and to authorize or deny the request. 2492 The authorization server SHOULD NOT process repeated authorization 2493 requests automatically (without active resource owner interaction) 2494 without authenticating the client or relying on other measures to 2495 ensure that the repeated request comes from the original client and 2496 not an impersonator. 2498 9.3.1. Impersonation of Native Apps 2500 As stated above, the authorization server SHOULD NOT process 2501 authorization requests automatically without user consent or 2502 interaction, except when the identity of the client can be assured. 2503 This includes the case where the user has previously approved an 2504 authorization request for a given client id - unless the identity of 2505 the client can be proven, the request SHOULD be processed as if no 2506 previous request had been approved. 2508 Measures such as claimed "https" scheme redirects MAY be accepted by 2509 authorization servers as identity proof. Some operating systems may 2510 offer alternative platform-specific identity features that MAY be 2511 accepted, as appropriate. 2513 9.4. Access Tokens 2515 Access token credentials (as well as any confidential access token 2516 attributes) MUST be kept confidential in transit and storage, and 2517 only shared among the authorization server, the resource servers the 2518 access token is valid for, and the client to whom the access token is 2519 issued. Access token credentials MUST only be transmitted using TLS 2520 as described in Section 1.6 with server authentication as defined by 2521 [RFC2818]. 2523 The authorization server MUST ensure that access tokens cannot be 2524 generated, modified, or guessed to produce valid access tokens by 2525 unauthorized parties. 2527 9.4.1. Access Token Privilege Restriction 2529 The client SHOULD request access tokens with the minimal scope 2530 necessary. The authorization server SHOULD take the client identity 2531 into account when choosing how to honor the requested scope and MAY 2532 issue an access token with less rights than requested. 2534 The privileges associated with an access token SHOULD be restricted 2535 to the minimum required for the particular application or use case. 2536 This prevents clients from exceeding the privileges authorized by the 2537 resource owner. It also prevents users from exceeding their 2538 privileges authorized by the respective security policy. Privilege 2539 restrictions also help to reduce the impact of access token leakage. 2541 In particular, access tokens SHOULD be restricted to certain resource 2542 servers (audience restriction), preferably to a single resource 2543 server. To put this into effect, the authorization server associates 2544 the access token with certain resource servers and every resource 2545 server is obliged to verify, for every request, whether the access 2546 token sent with that request was meant to be used for that particular 2547 resource server. If not, the resource server MUST refuse to serve 2548 the respective request. Clients and authorization servers MAY 2549 utilize the parameters "scope" or "resource" as specified in 2550 [RFC8707], respectively, to determine the resource server they want 2551 to access. 2553 9.4.2. Access Token Replay Prevention 2555 Additionally, access tokens SHOULD be restricted to certain resources 2556 and actions on resource servers or resources. To put this into 2557 effect, the authorization server associates the access token with the 2558 respective resource and actions and every resource server is obliged 2559 to verify, for every request, whether the access token sent with that 2560 request was meant to be used for that particular action on the 2561 particular resource. If not, the resource server must refuse to 2562 serve the respective request. Clients and authorization servers MAY 2563 utilize the parameter "scope" and "authorization_details" as 2564 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2565 actions. 2567 Authorization and resource servers SHOULD use mechanisms for sender- 2568 constrained access tokens to prevent token replay as described in 2569 (#pop_tokens). A sender-constrained access token scopes the 2570 applicability of an access token to a certain sender. This sender is 2571 obliged to demonstrate knowledge of a certain secret as prerequisite 2572 for the acceptance of that token at the recipient (e.g., a resource 2573 server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2574 RECOMMENDED. 2576 9.5. Refresh Tokens 2578 Authorization servers MAY issue refresh tokens to clients. 2580 Refresh tokens MUST be kept confidential in transit and storage, and 2581 shared only among the authorization server and the client to whom the 2582 refresh tokens were issued. The authorization server MUST maintain 2583 the binding between a refresh token and the client to whom it was 2584 issued. Refresh tokens MUST only be transmitted using TLS as 2585 described in Section 1.6 with server authentication as defined by 2586 [RFC2818]. 2588 The authorization server MUST verify the binding between the refresh 2589 token and client identity whenever the client identity can be 2590 authenticated. When client authentication is not possible, the 2591 authorization server MUST issue sender-constrained refresh tokens or 2592 use refresh token rotation as described in 2593 (#refresh_token_protection). 2595 The authorization server MUST ensure that refresh tokens cannot be 2596 generated, modified, or guessed to produce valid refresh tokens by 2597 unauthorized parties. 2599 9.6. Protecting Redirect-Based Flows 2601 When comparing client redirect URIs against pre-registered URIs, 2602 authorization servers MUST utilize exact string matching. This 2603 measure contributes to the prevention of leakage of authorization 2604 codes and access tokens (see (#insufficient_uri_validation)). It can 2605 also help to detect mix-up attacks (see (#mix_up)). 2607 Clients MUST NOT expose URLs that forward the user's browser to 2608 arbitrary URIs obtained from a query parameter ("open redirector"). 2609 Open redirectors can enable exfiltration of authorization codes and 2610 access tokens, see (#open_redirector_on_client). 2612 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2613 context, CSRF refers to requests to the redirection endpoint that do 2614 not originate at the authorization server, but a malicious third 2615 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2616 have ensured that the authorization server supports PKCE MAY rely the 2617 CSRF protection provided by PKCE. In OpenID Connect flows, the 2618 "nonce" parameter provides CSRF protection. Otherwise, one-time use 2619 CSRF tokens carried in the "state" parameter that are securely bound 2620 to the user agent MUST be used for CSRF protection (see 2621 (#csrf_countermeasures)). 2623 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2624 process redirect responses of the authorization server they sent the 2625 respective request to and from the same user agent this authorization 2626 request was initiated with. Clients MUST store the authorization 2627 server they sent an authorization request to and bind this 2628 information to the user agent and check that the authorization 2629 request was received from the correct authorization server. Clients 2630 MUST ensure that the subsequent token request, if applicable, is sent 2631 to the same authorization server. Clients SHOULD use distinct 2632 redirect URIs for each authorization server as a means to identify 2633 the authorization server a particular response came from. 2635 An AS that redirects a request potentially containing user 2636 credentials MUST avoid forwarding these user credentials accidentally 2637 (see Section 9.6.2 for details). 2639 9.6.1. Loopback Redirect Considerations in Native Apps 2641 Loopback interface redirect URIs use the "http" scheme (i.e., without 2642 Transport Layer Security (TLS)). This is acceptable for loopback 2643 interface redirect URIs as the HTTP request never leaves the device. 2645 Clients should open the network port only when starting the 2646 authorization request and close it once the response is returned. 2648 Clients should listen on the loopback network interface only, in 2649 order to avoid interference by other network actors. 2651 While redirect URIs using localhost (i.e., 2652 "http://localhost:{port}/{path}") function similarly to loopback IP 2653 redirects described in Section 10.3.3, the use of "localhost" is NOT 2654 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2655 rather than "localhost" avoids inadvertently listening on network 2656 interfaces other than the loopback interface. It is also less 2657 susceptible to client-side firewalls and misconfigured host name 2658 resolution on the user's device. 2660 9.6.2. HTTP 307 Redirect 2662 An AS which redirects a request that potentially contains user 2663 credentials MUST NOT use the HTTP 307 status code for redirection. 2664 If an HTTP redirection (and not, for example, JavaScript) is used for 2665 such a request, AS SHOULD use HTTP status code 303 "See Other". 2667 At the authorization endpoint, a typical protocol flow is that the AS 2668 prompts the user to enter her credentials in a form that is then 2669 submitted (using the HTTP POST method) back to the authorization 2670 server. The AS checks the credentials and, if successful, redirects 2671 the user agent to the client's redirection endpoint. 2673 If the status code 307 were used for redirection, the user agent 2674 would send the user credentials via HTTP POST to the client. 2676 This discloses the sensitive credentials to the client. If the 2677 relying party is malicious, it can use the credentials to impersonate 2678 the user at the AS. 2680 The behavior might be unexpected for developers, but is defined in 2681 [RFC7231], Section 6.4.7. This status code does not require the user 2682 agent to rewrite the POST request to a GET request and thereby drop 2683 the form data in the POST request body. 2685 In the HTTP standard [RFC7231], only the status code 303 2686 unambigiously enforces rewriting the HTTP POST request to an HTTP GET 2687 request. For all other status codes, including the popular 302, user 2688 agents can opt not to rewrite POST to GET requests and therefore to 2689 reveal the user credentials to the client. (In practice, however, 2690 most user agents will only show this behaviour for 307 redirects.) 2692 Therefore, the RECOMMENDED status code for HTTP redirects is 303. 2694 9.7. Authorization Codes 2696 The transmission of authorization codes MUST be made over a secure 2697 channel, and the client MUST require the use of TLS with its 2698 redirection URI if the URI identifies a network resource. Since 2699 authorization codes are transmitted via user-agent redirections, they 2700 could potentially be disclosed through user-agent history and HTTP 2701 referrer headers. 2703 Authorization codes MUST be short lived and single-use. If the 2704 authorization server observes multiple attempts to exchange an 2705 authorization code for an access token, the authorization server 2706 SHOULD attempt to revoke all refresh and access tokens already 2707 granted based on the compromised authorization code. 2709 If the client can be authenticated, the authorization servers MUST 2710 authenticate the client and ensure that the authorization code was 2711 issued to the same client. 2713 Clients MUST prevent injection (replay) of authorization codes into 2714 the authorization response by attackers. The use of PKCE is 2715 RECOMMENDED to this end. The OpenID Connect "nonce" parameter and ID 2716 Token Claim [OpenID] MAY be used as well. The PKCE challenge or 2717 OpenID Connect "nonce" MUST be transaction-specific and securely 2718 bound to the client and the user agent in which the transaction was 2719 started. 2721 Note: although PKCE so far was designed as a mechanism to protect 2722 native apps, this advice applies to all kinds of OAuth clients, 2723 including web applications. 2725 When using PKCE, clients SHOULD use PKCE code challenge methods that 2726 do not expose the PKCE verifier in the authorization request. 2727 Otherwise, attackers that can read the authorization request (cf. 2728 Attacker A4 in (#secmodel)) can break the security provided by PKCE. 2729 Currently, "S256" is the only such method. 2731 Authorization servers MUST support PKCE. 2733 Authorization servers MUST provide a way to detect their support for 2734 PKCE. To this end, they MUST either (a) publish the element 2735 "code_challenge_methods_supported" in their AS metadata ([RFC8414]) 2736 containing the supported PKCE challenge methods (which can be used by 2737 the client to detect PKCE support) or (b) provide a deployment- 2738 specific way to ensure or determine PKCE support by the AS. 2740 9.8. Request Confidentiality 2742 Access tokens, refresh tokens, authorization codes, and client 2743 credentials MUST NOT be transmitted in the clear. 2745 The "state" and "scope" parameters SHOULD NOT include sensitive 2746 client or resource owner information in plain text, as they can be 2747 transmitted over insecure channels or stored insecurely. 2749 9.9. Ensuring Endpoint Authenticity 2751 In order to prevent man-in-the-middle attacks, the authorization 2752 server MUST require the use of TLS with server authentication as 2753 defined by [RFC2818] for any request sent to the authorization and 2754 token endpoints. The client MUST validate the authorization server's 2755 TLS certificate as defined by [RFC6125] and in accordance with its 2756 requirements for server identity authentication. 2758 9.10. Credentials-Guessing Attacks 2760 The authorization server MUST prevent attackers from guessing access 2761 tokens, authorization codes, refresh tokens, resource owner 2762 passwords, and client credentials. 2764 The probability of an attacker guessing generated tokens (and other 2765 credentials not intended for handling by end-users) MUST be less than 2766 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2768 The authorization server MUST utilize other means to protect 2769 credentials intended for end-user usage. 2771 9.11. Phishing Attacks 2773 Wide deployment of this and similar protocols may cause end-users to 2774 become inured to the practice of being redirected to websites where 2775 they are asked to enter their passwords. If end-users are not 2776 careful to verify the authenticity of these websites before entering 2777 their credentials, it will be possible for attackers to exploit this 2778 practice to steal resource owners' passwords. 2780 Service providers should attempt to educate end-users about the risks 2781 phishing attacks pose and should provide mechanisms that make it easy 2782 for end-users to confirm the authenticity of their sites. Client 2783 developers should consider the security implications of how they 2784 interact with the user-agent (e.g., external, embedded), and the 2785 ability of the end-user to verify the authenticity of the 2786 authorization server. 2788 To reduce the risk of phishing attacks, the authorization servers 2789 MUST require the use of TLS on every endpoint used for end-user 2790 interaction. 2792 9.12. Fake External User-Agents in Native Apps 2794 The native app that is initiating the authorization request has a 2795 large degree of control over the user interface and can potentially 2796 present a fake external user-agent, that is, an embedded user-agent 2797 made to appear as an external user-agent. 2799 When all good actors are using external user-agents, the advantage is 2800 that it is possible for security experts to detect bad actors, as 2801 anyone faking an external user-agent is provably bad. On the other 2802 hand, if good and bad actors alike are using embedded user-agents, 2803 bad actors don't need to fake anything, making them harder to detect. 2804 Once a malicious app is detected, it may be possible to use this 2805 knowledge to blacklist the app's signature in malware scanning 2806 software, take removal action (in the case of apps distributed by app 2807 stores) and other steps to reduce the impact and spread of the 2808 malicious app. 2810 Authorization servers can also directly protect against fake external 2811 user-agents by requiring an authentication factor only available to 2812 true external user-agents. 2814 Users who are particularly concerned about their security when using 2815 in-app browser tabs may also take the additional step of opening the 2816 request in the full browser from the in-app browser tab and complete 2817 the authorization there, as most implementations of the in-app 2818 browser tab pattern offer such functionality. 2820 9.13. Malicious External User-Agents in Native Apps 2822 If a malicious app is able to configure itself as the default handler 2823 for "https" scheme URIs in the operating system, it will be able to 2824 intercept authorization requests that use the default browser and 2825 abuse this position of trust for malicious ends such as phishing the 2826 user. 2828 This attack is not confined to OAuth; a malicious app configured in 2829 this way would present a general and ongoing risk to the user beyond 2830 OAuth usage by native apps. Many operating systems mitigate this 2831 issue by requiring an explicit user action to change the default 2832 handler for "http" and "https" scheme URIs. 2834 9.14. Cross-Site Request Forgery 2836 An attacker might attempt to inject a request to the redirect URI of 2837 the legitimate client on the victim's device, e.g., to cause the 2838 client to access resources under the attacker's control. This is a 2839 variant of an attack known as Cross-Site Request Forgery (CSRF). 2841 The traditional countermeasure are CSRF tokens that are bound to the 2842 user agent and passed in the "state" parameter to the authorization 2843 server as described in [RFC6819]. The same protection is provided by 2844 PKCE or the OpenID Connect "nonce" value. 2846 When using PKCE instead of "state" or "nonce" for CSRF protection, it 2847 is important to note that: 2849 * Clients MUST ensure that the AS supports PKCE before using PKCE 2850 for CSRF protection. If an authorization server does not support 2851 PKCE, "state" or "nonce" MUST be used for CSRF protection. 2853 * If "state" is used for carrying application state, and integrity 2854 of its contents is a concern, clients MUST protect "state" against 2855 tampering and swapping. This can be achieved by binding the 2856 contents of state to the browser session and/or signed/encrypted 2857 state values [I-D.bradley-oauth-jwt-encoded-state]. 2859 AS therefore MUST provide a way to detect their support for PKCE 2860 either via AS metadata according to [RFC8414] or provide a 2861 deployment-specific way to ensure or determine PKCE support. 2863 9.15. Clickjacking 2865 As described in Section 4.4.1.9 of [RFC6819], the authorization 2866 request is susceptible to clickjacking. An attacker can use this 2867 vector to obtain the user's authentication credentials, change the 2868 scope of access granted to the client, and potentially access the 2869 user's resources. 2871 Authorization servers MUST prevent clickjacking attacks. Multiple 2872 countermeasures are described in [RFC6819], including the use of the 2873 X-Frame-Options HTTP response header field and frame-busting 2874 JavaScript. In addition to those, authorization servers SHOULD also 2875 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2877 To be effective, CSP must be used on the authorization endpoint and, 2878 if applicable, other endpoints used to authenticate the user and 2879 authorize the client (e.g., the device authorization endpoint, login 2880 pages, error pages, etc.). This prevents framing by unauthorized 2881 origins in user agents that support CSP. The client MAY permit being 2882 framed by some other origin than the one used in its redirection 2883 endpoint. For this reason, authorization servers SHOULD allow 2884 administrators to configure allowed origins for particular clients 2885 and/or for clients to register these dynamically. 2887 Using CSP allows authorization servers to specify multiple origins in 2888 a single response header field and to constrain these using flexible 2889 patterns (see [CSP-2] for details). Level 2 of this standard 2890 provides a robust mechanism for protecting against clickjacking by 2891 using policies that restrict the origin of frames (using "frame- 2892 ancestors") together with those that restrict the sources of scripts 2893 allowed to execute on an HTML page (by using "script-src"). A non- 2894 normative example of such a policy is shown in the following listing: 2896 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 2897 https://ext.example.org:8000 Content-Security-Policy: script-src 2898 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 2900 Because some user agents do not support [CSP-2], this technique 2901 SHOULD be combined with others, including those described in 2902 [RFC6819], unless such legacy user agents are explicitly unsupported 2903 by the authorization server. Even in such cases, additional 2904 countermeasures SHOULD still be employed. 2906 9.16. Code Injection and Input Validation 2908 A code injection attack occurs when an input or otherwise external 2909 variable is used by an application unsanitized and causes 2910 modification to the application logic. This may allow an attacker to 2911 gain access to the application device or its data, cause denial of 2912 service, or introduce a wide range of malicious side-effects. 2914 The authorization server and client MUST sanitize (and validate when 2915 possible) any value received - in particular, the value of the 2916 "state" and "redirect_uri" parameters. 2918 9.17. Open Redirectors 2920 The following attacks can occur when an AS or client has an open 2921 redirector. An open redirector is an endpoint that forwards a user's 2922 browser to an arbitrary URI obtained from a query parameter. 2924 9.17.1. Client as Open Redirector 2926 Clients MUST NOT expose open redirectors. Attackers may use open 2927 redirectors to produce URLs pointing to the client and utilize them 2928 to exfiltrate authorization codes and access tokens, as described in 2929 (#redir_uri_open_redir). Another abuse case is to produce URLs that 2930 appear to point to the client. This might trick users into trusting 2931 the URL and follow it in their browser. This can be abused for 2932 phishing. 2934 In order to prevent open redirection, clients should only redirect if 2935 the target URLs are whitelisted or if the origin and integrity of a 2936 request can be authenticated. Countermeasures against open 2937 redirection are described by OWASP [owasp_redir]. 2939 9.17.2. Authorization Server as Open Redirector 2941 Just as with clients, attackers could try to utilize a user's trust 2942 in the authorization server (and its URL in particular) for 2943 performing phishing attacks. OAuth authorization servers regularly 2944 redirect users to other web sites (the clients), but must do so in a 2945 safe way. 2947 Section 4.1.2.1 already prevents open redirects by stating that the 2948 AS MUST NOT automatically redirect the user agent in case of an 2949 invalid combination of "client_id" and "redirect_uri". 2951 However, an attacker could also utilize a correctly registered 2952 redirect URI to perform phishing attacks. The attacker could, for 2953 example, register a client via dynamic client registration [RFC7591] 2954 and intentionally send an erroneous authorization request, e.g., by 2955 using an invalid scope value, thus instructing the AS to redirect the 2956 user agent to its phishing site. 2958 The AS MUST take precautions to prevent this threat. Based on its 2959 risk assessment, the AS needs to decide whether it can trust the 2960 redirect URI and SHOULD only automatically redirect the user agent if 2961 it trusts the redirect URI. If the URI is not trusted, the AS MAY 2962 inform the user and rely on the user to make the correct decision. 2964 9.18. Authorization Server Mix-Up Mitigation in Native Apps 2966 (TODO: merge this with the regular mix-up section when it is brought 2967 in) 2969 To protect against a compromised or malicious authorization server 2970 attacking another authorization server used by the same app, it is 2971 REQUIRED that a unique redirect URI is used for each authorization 2972 server used by the app (for example, by varying the path component), 2973 and that authorization responses are rejected if the redirect URI 2974 they were received on doesn't match the redirect URI in an outgoing 2975 authorization request. 2977 The native app MUST store the redirect URI used in the authorization 2978 request with the authorization session data (i.e., along with "state" 2979 and other related data) and MUST verify that the URI on which the 2980 authorization response was received exactly matches it. 2982 The requirement of Section 9.2, specifically that authorization 2983 servers reject requests with URIs that don't match what was 2984 registered, is also required to prevent such attacks. 2986 9.19. Embedded User Agents in Native Apps 2988 Embedded user-agents are a technically possible method for 2989 authorizing native apps. These embedded user-agents are unsafe for 2990 use by third parties to the authorization server by definition, as 2991 the app that hosts the embedded user-agent can access the user's full 2992 authentication credential, not just the OAuth authorization grant 2993 that was intended for the app. 2995 In typical web-view-based implementations of embedded user-agents, 2996 the host application can record every keystroke entered in the login 2997 form to capture usernames and passwords, automatically submit forms 2998 to bypass user consent, and copy session cookies and use them to 2999 perform authenticated actions as the user. 3001 Even when used by trusted apps belonging to the same party as the 3002 authorization server, embedded user-agents violate the principle of 3003 least privilege by having access to more powerful credentials than 3004 they need, potentially increasing the attack surface. 3006 Encouraging users to enter credentials in an embedded user-agent 3007 without the usual address bar and visible certificate validation 3008 features that browsers have makes it impossible for the user to know 3009 if they are signing in to the legitimate site; even when they are, it 3010 trains them that it's OK to enter credentials without validating the 3011 site first. 3013 Aside from the security concerns, embedded user-agents do not share 3014 the authentication state with other apps or the browser, requiring 3015 the user to log in for every authorization request, which is often 3016 considered an inferior user experience. 3018 9.20. Other Recommendations 3020 Authorization servers SHOULD NOT allow clients to influence their 3021 "client_id" or "sub" value or any other claim if that can cause 3022 confusion with a genuine resource owner (see 3023 (#client_impersonating)). 3025 10. Native Applications 3027 Native applications are clients installed and executed on the device 3028 used by the resource owner (i.e., desktop application, native mobile 3029 application). Native applications require special consideration 3030 related to security, platform capabilities, and overall end-user 3031 experience. 3033 The authorization endpoint requires interaction between the client 3034 and the resource owner's user-agent. The best current practice is to 3035 perform the OAuth authorization request in an external user-agent 3036 (typically the browser) rather than an embedded user-agent (such as 3037 one implemented with web-views). 3039 The native application can capture the response from the 3040 authorization server using a redirection URI with a scheme registered 3041 with the operating system to invoke the client as the handler, manual 3042 copy-and-paste of the credentials, running a local web server, 3043 installing a user-agent extension, or by providing a redirection URI 3044 identifying a server-hosted resource under the client's control, 3045 which in turn makes the response available to the native application. 3047 Previously, it was common for native apps to use embedded user-agents 3048 (commonly implemented with web-views) for OAuth authorization 3049 requests. That approach has many drawbacks, including the host app 3050 being able to copy user credentials and cookies as well as the user 3051 needing to authenticate from scratch in each app. See Section 9.19 3052 for a deeper analysis of the drawbacks of using embedded user-agents 3053 for OAuth. 3055 Native app authorization requests that use the browser are more 3056 secure and can take advantage of the user's authentication state. 3057 Being able to use the existing authentication session in the browser 3058 enables single sign-on, as users don't need to authenticate to the 3059 authorization server each time they use a new app (unless required by 3060 the authorization server policy). 3062 Supporting authorization flows between a native app and the browser 3063 is possible without changing the OAuth protocol itself, as the OAuth 3064 authorization request and response are already defined in terms of 3065 URIs. This encompasses URIs that can be used for inter-app 3066 communication. Some OAuth server implementations that assume all 3067 clients are confidential web clients will need to add an 3068 understanding of public native app clients and the types of redirect 3069 URIs they use to support this best practice. 3071 10.1. Using Inter-App URI Communication for OAuth in Native Apps 3073 Just as URIs are used for OAuth on the web to initiate the 3074 authorization request and return the authorization response to the 3075 requesting website, URIs can be used by native apps to initiate the 3076 authorization request in the device's browser and return the response 3077 to the requesting native app. 3079 By adopting the same methods used on the web for OAuth, benefits seen 3080 in the web context like the usability of a single sign-on session and 3081 the security of a separate authentication context are likewise gained 3082 in the native app context. Reusing the same approach also reduces 3083 the implementation complexity and increases interoperability by 3084 relying on standards-based web flows that are not specific to a 3085 particular platform. 3087 Native apps MUST use an external user-agent to perform OAuth 3088 authorization requests. This is achieved by opening the 3089 authorization request in the browser (detailed in Section 10.2) and 3090 using a redirect URI that will return the authorization response back 3091 to the native app (defined in Section 10.3). 3093 10.2. Initiating the Authorization Request from a Native App 3095 Native apps needing user authorization create an authorization 3096 request URI with the authorization code grant type per Section 4.1 3097 using a redirect URI capable of being received by the native app. 3099 The function of the redirect URI for a native app authorization 3100 request is similar to that of a web-based authorization request. 3101 Rather than returning the authorization response to the OAuth 3102 client's server, the redirect URI used by a native app returns the 3103 response to the app. Several options for a redirect URI that will 3104 return the authorization response to the native app in different 3105 platforms are documented in Section 10.3. Any redirect URI that 3106 allows the app to receive the URI and inspect its parameters is 3107 viable. 3109 After constructing the authorization request URI, the app uses 3110 platform-specific APIs to open the URI in an external user-agent. 3111 Typically, the external user-agent used is the default browser, that 3112 is, the application configured for handling "http" and "https" scheme 3113 URIs on the system; however, different browser selection criteria and 3114 other categories of external user-agents MAY be used. 3116 This best practice focuses on the browser as the RECOMMENDED external 3117 user-agent for native apps. An external user-agent designed 3118 specifically for user authorization and capable of processing 3119 authorization requests and responses like a browser MAY also be used. 3120 Other external user-agents, such as a native app provided by the 3121 authorization server may meet the criteria set out in this best 3122 practice, including using the same redirection URI properties, but 3123 their use is out of scope for this specification. 3125 Some platforms support a browser feature known as "in-app browser 3126 tabs", where an app can present a tab of the browser within the app 3127 context without switching apps, but still retain key benefits of the 3128 browser such as a shared authentication state and security context. 3129 On platforms where they are supported, it is RECOMMENDED, for 3130 usability reasons, that apps use in-app browser tabs for the 3131 authorization request. 3133 10.3. Receiving the Authorization Response in a Native App 3135 There are several redirect URI options available to native apps for 3136 receiving the authorization response from the browser, the 3137 availability and user experience of which varies by platform. 3139 To fully support native apps, authorization servers MUST offer at 3140 least the three redirect URI options described in the following 3141 subsections to native apps. Native apps MAY use whichever redirect 3142 option suits their needs best, taking into account platform-specific 3143 implementation details. 3145 10.3.1. Private-Use URI Scheme Redirection 3147 Many mobile and desktop computing platforms support inter-app 3148 communication via URIs by allowing apps to register private-use URI 3149 schemes (sometimes colloquially referred to as "custom URL schemes") 3150 like "com.example.app". When the browser or another app attempts to 3151 load a URI with a private-use URI scheme, the app that registered it 3152 is launched to handle the request. 3154 To perform an authorization request with a private-use URI scheme 3155 redirect, the native app launches the browser with a standard 3156 authorization request, but one where the redirection URI utilizes a 3157 private-use URI scheme it registered with the operating system. 3159 When choosing a URI scheme to associate with the app, apps MUST use a 3160 URI scheme based on a domain name under their control, expressed in 3161 reverse order, as recommended by Section 3.8 of [RFC7595] for 3162 private-use URI schemes. 3164 For example, an app that controls the domain name "app.example.com" 3165 can use "com.example.app" as their scheme. Some authorization 3166 servers assign client identifiers based on domain names, for example, 3167 "client1234.usercontent.example.net", which can also be used as the 3168 domain name for the scheme when reversed in the same manner. A 3169 scheme such as "myapp", however, would not meet this requirement, as 3170 it is not based on a domain name. 3172 When there are multiple apps by the same publisher, care must be 3173 taken so that each scheme is unique within that group. On platforms 3174 that use app identifiers based on reverse-order domain names, those 3175 identifiers can be reused as the private-use URI scheme for the OAuth 3176 redirect to help avoid this problem. 3178 Following the requirements of Section 3.2 of [RFC3986], as there is 3179 no naming authority for private-use URI scheme redirects, only a 3180 single slash ("/") appears after the scheme component. A complete 3181 example of a redirect URI utilizing a private-use URI scheme is: 3183 com.example.app:/oauth2redirect/example-provider 3185 When the authorization server completes the request, it redirects to 3186 the client's redirection URI as it would normally. As the 3187 redirection URI uses a private-use URI scheme, it results in the 3188 operating system launching the native app, passing in the URI as a 3189 launch parameter. Then, the native app uses normal processing for 3190 the authorization response. 3192 10.3.2. Claimed "https" Scheme URI Redirection 3194 Some operating systems allow apps to claim "https" scheme [RFC7230] 3195 URIs in the domains they control. When the browser encounters a 3196 claimed URI, instead of the page being loaded in the browser, the 3197 native app is launched with the URI supplied as a launch parameter. 3199 Such URIs can be used as redirect URIs by native apps. They are 3200 indistinguishable to the authorization server from a regular web- 3201 based client redirect URI. An example is: 3203 https://app.example.com/oauth2redirect/example-provider 3205 As the redirect URI alone is not enough to distinguish public native 3206 app clients from confidential web clients, it is REQUIRED in 3207 Section 9.2 that the client type be recorded during client 3208 registration to enable the server to determine the client type and 3209 act accordingly. 3211 App-claimed "https" scheme redirect URIs have some advantages 3212 compared to other native app redirect options in that the identity of 3213 the destination app is guaranteed to the authorization server by the 3214 operating system. For this reason, native apps SHOULD use them over 3215 the other options where possible. 3217 10.3.3. Loopback Interface Redirection 3219 Native apps that are able to open a port on the loopback network 3220 interface without needing special permissions (typically, those on 3221 desktop operating systems) can use the loopback interface to receive 3222 the OAuth redirect. 3224 Loopback redirect URIs use the "http" scheme and are constructed with 3225 the loopback IP literal and whatever port the client is listening on. 3227 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3228 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3229 IPv4 loopback interface with a randomly assigned port: 3231 http://127.0.0.1:51004/oauth2redirect/example-provider 3233 An example redirect using the IPv6 loopback interface with a randomly 3234 assigned port: 3236 http://[::1]:61023/oauth2redirect/example-provider 3238 The authorization server MUST allow any port to be specified at the 3239 time of the request for loopback IP redirect URIs, to accommodate 3240 clients that obtain an available ephemeral port from the operating 3241 system at the time of the request. 3243 Clients SHOULD NOT assume that the device supports a particular 3244 version of the Internet Protocol. It is RECOMMENDED that clients 3245 attempt to bind to the loopback interface using both IPv4 and IPv6 3246 and use whichever is available. 3248 11. Browser-Based Apps 3250 Browser-based apps are are clients that run in a web browser, 3251 typically written in JavaScript, also known as "single-page apps". 3252 These types of apps have particular security considerations similar 3253 to native apps. 3255 TODO: Bring in the normative text of the browser-based apps BCP when 3256 it is finalized. 3258 12. Differences from OAuth 2.0 3260 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3261 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3262 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3263 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3264 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3265 ([RFC6750]). 3267 Where a later draft updates or obsoletes functionality found in the 3268 original [RFC6749], that functionality in this draft is updated with 3269 the normative changes described in a later draft, or removed 3270 entirely. 3272 A non-normative list of changes from OAuth 2.0 is listed below: 3274 * The authorization code grant is extended with the functionality 3275 from PKCE ([RFC7636]) such that the only method of using the 3276 authorization code grant according to this specification requires 3277 the addition of the PKCE mechanism 3279 * Redirect URIs must be compared using exact string matching as per 3280 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3282 * The Implicit grant ("response_type=token") is omitted from this 3283 specification as per Section 2.1.2 of 3284 [I-D.ietf-oauth-security-topics] 3286 * The Resource Owner Password Credentials grant is omitted from this 3287 specification as per Section 2.4 of 3288 [I-D.ietf-oauth-security-topics] 3290 * Bearer token usage omits the use of bearer tokens in the query 3291 string of URIs as per Section 4.3.2 of 3292 [I-D.ietf-oauth-security-topics] 3294 * Refresh tokens must either be sender-constrained or one-time use 3295 as per Section 4.12.2 of [I-D.ietf-oauth-security-topics] 3297 13. IANA Considerations 3299 13.1. OAuth Access Token Types Registry 3301 This specification establishes the OAuth Access Token Types registry. 3303 Access token types are registered with a Specification Required 3304 ([RFC8126]) after a two-week review period on the oauth-ext- 3305 review@ietf.org mailing list, on the advice of one or more Designated 3306 Experts. However, to allow for the allocation of values prior to 3307 publication, the Designated Expert(s) may approve registration once 3308 they are satisfied that such a specification will be published. 3310 Registration requests must be sent to the oauth-ext-review@ietf.org 3311 mailing list for review and comment, with an appropriate subject 3312 (e.g., "Request for access token type: example"). 3314 Within the review period, the Designated Expert(s) will either 3315 approve or deny the registration request, communicating this decision 3316 to the review list and IANA. Denials should include an explanation 3317 and, if applicable, suggestions as to how to make the request 3318 successful. 3320 IANA must only accept registry updates from the Designated Expert(s) 3321 and should direct all requests for registration to the review mailing 3322 list. 3324 13.1.1. Registration Template 3326 Type name: The name requested (e.g., "example"). 3328 Additional Token Endpoint Response Parameters: Additional response 3329 parameters returned together with the "access_token" parameter. 3330 New parameters MUST be separately registered in the OAuth 3331 Parameters registry as described by Section 13.2. 3333 HTTP Authentication Scheme(s): The HTTP authentication scheme 3334 name(s), if any, used to authenticate protected resource requests 3335 using access tokens of this type. 3337 Change controller: For Standards Track RFCs, state "IETF". For 3338 others, give the name of the responsible party. Other details 3339 (e.g., postal address, email address, home page URI) may also be 3340 included. 3342 Specification document(s): Reference to the document(s) that specify 3343 the parameter, preferably including a URI that can be used to 3344 retrieve a copy of the document(s). An indication of the relevant 3345 sections may also be included but is not required. 3347 13.1.2. Initial Registry Contents 3349 The OAuth Access Token Types registry's initial contents are: 3351 * Type name: Bearer 3353 * Additional Token Endpoint Response Parameters: (none) 3355 * HTTP Authentication Scheme(s): Bearer 3357 * Change controller: IETF 3359 * Specification document(s): OAuth 2.1 3361 13.2. OAuth Parameters Registry 3363 This specification establishes the OAuth Parameters registry. 3365 Additional parameters for inclusion in the authorization endpoint 3366 request, the authorization endpoint response, the token endpoint 3367 request, or the token endpoint response are registered with a 3368 Specification Required ([RFC8126]) after a two-week review period on 3369 the oauth-ext-review@ietf.org mailing list, on the advice of one or 3370 more Designated Experts. However, to allow for the allocation of 3371 values prior to publication, the Designated Expert(s) may approve 3372 registration once they are satisfied that such a specification will 3373 be published. 3375 Registration requests must be sent to the oauth-ext-review@ietf.org 3376 mailing list for review and comment, with an appropriate subject 3377 (e.g., "Request for parameter: example"). 3379 Within the review period, the Designated Expert(s) will either 3380 approve or deny the registration request, communicating this decision 3381 to the review list and IANA. Denials should include an explanation 3382 and, if applicable, suggestions as to how to make the request 3383 successful. 3385 IANA must only accept registry updates from the Designated Expert(s) 3386 and should direct all requests for registration to the review mailing 3387 list. 3389 13.2.1. Registration Template 3391 Parameter name: The name requested (e.g., "example"). 3393 Parameter usage location: The location(s) where parameter can be 3394 used. The possible locations are authorization request, 3395 authorization response, token request, or token response. 3397 Change controller: For Standards Track RFCs, state "IETF". For 3398 others, give the name of the responsible party. Other details 3399 (e.g., postal address, email address, home page URI) may also be 3400 included. 3402 Specification document(s): Reference to the document(s) that specify 3403 the parameter, preferably including a URI that can be used to 3404 retrieve a copy of the document(s). An indication of the relevant 3405 sections may also be included but is not required. 3407 13.2.2. Initial Registry Contents 3409 The OAuth Parameters registry's initial contents are: 3411 * Parameter name: client_id 3413 * Parameter usage location: authorization request, token request 3415 * Change controller: IETF 3417 * Specification document(s): RFC 6749 3419 * Parameter name: client_secret 3421 * Parameter usage location: token request 3423 * Change controller: IETF 3425 * Specification document(s): RFC 6749 3427 * Parameter name: response_type 3429 * Parameter usage location: authorization request 3431 * Change controller: IETF 3433 * Specification document(s): RFC 6749 3435 * Parameter name: redirect_uri 3436 * Parameter usage location: authorization request, token request 3438 * Change controller: IETF 3440 * Specification document(s): RFC 6749 3442 * Parameter name: scope 3444 * Parameter usage location: authorization request, authorization 3445 response, token request, token response 3447 * Change controller: IETF 3449 * Specification document(s): RFC 6749 3451 * Parameter name: state 3453 * Parameter usage location: authorization request, authorization 3454 response 3456 * Change controller: IETF 3458 * Specification document(s): RFC 6749 3460 * Parameter name: code 3462 * Parameter usage location: authorization response, token request 3464 * Change controller: IETF 3466 * Specification document(s): RFC 6749 3468 * Parameter name: error_description 3470 * Parameter usage location: authorization response, token response 3472 * Change controller: IETF 3474 * Specification document(s): RFC 6749 3476 * Parameter name: error_uri 3478 * Parameter usage location: authorization response, token response 3480 * Change controller: IETF 3482 * Specification document(s): RFC 6749 3483 * Parameter name: grant_type 3485 * Parameter usage location: token request 3487 * Change controller: IETF 3489 * Specification document(s): RFC 6749 3491 * Parameter name: access_token 3493 * Parameter usage location: authorization response, token response 3495 * Change controller: IETF 3497 * Specification document(s): RFC 6749 3499 * Parameter name: token_type 3501 * Parameter usage location: authorization response, token response 3503 * Change controller: IETF 3505 * Specification document(s): RFC 6749 3507 * Parameter name: expires_in 3509 * Parameter usage location: authorization response, token response 3511 * Change controller: IETF 3513 * Specification document(s): RFC 6749 3515 * Parameter name: username 3517 * Parameter usage location: token request 3519 * Change controller: IETF 3521 * Specification document(s): RFC 6749 3523 * Parameter name: password 3525 * Parameter usage location: token request 3527 * Change controller: IETF 3529 * Specification document(s): RFC 6749 3530 * Parameter name: refresh_token 3532 * Parameter usage location: token request, token response 3534 * Change controller: IETF 3536 * Specification document(s): RFC 6749 3538 13.3. OAuth Authorization Endpoint Response Types Registry 3540 This specification establishes the OAuth Authorization Endpoint 3541 Response Types registry. 3543 Additional response types for use with the authorization endpoint are 3544 registered with a Specification Required ([RFC8126]) after a two-week 3545 review period on the oauth-ext-review@ietf.org mailing list, on the 3546 advice of one or more Designated Experts. However, to allow for the 3547 allocation of values prior to publication, the Designated Expert(s) 3548 may approve registration once they are satisfied that such a 3549 specification will be published. 3551 Registration requests must be sent to the oauth-ext-review@ietf.org 3552 mailing list for review and comment, with an appropriate subject 3553 (e.g., "Request for response type: example"). 3555 Within the review period, the Designated Expert(s) will either 3556 approve or deny the registration request, communicating this decision 3557 to the review list and IANA. Denials should include an explanation 3558 and, if applicable, suggestions as to how to make the request 3559 successful. 3561 IANA must only accept registry updates from the Designated Expert(s) 3562 and should direct all requests for registration to the review mailing 3563 list. 3565 13.3.1. Registration Template 3567 Response type name: The name requested (e.g., "example"). 3569 Change controller: For Standards Track RFCs, state "IETF". For 3570 others, give the name of the responsible party. Other details 3571 (e.g., postal address, email address, home page URI) may also be 3572 included. 3574 Specification document(s): Reference to the document(s) that specify 3575 the type, preferably including a URI that can be used to retrieve 3576 a copy of the document(s). An indication of the relevant sections 3577 may also be included but is not required. 3579 13.3.2. Initial Registry Contents 3581 The OAuth Authorization Endpoint Response Types registry's initial 3582 contents are: 3584 * Response type name: code 3586 * Change controller: IETF 3588 * Specification document(s): RFC 6749 3590 13.4. OAuth Extensions Error Registry 3592 This specification establishes the OAuth Extensions Error registry. 3594 Additional error codes used together with other protocol extensions 3595 (i.e., extension grant types, access token types, or extension 3596 parameters) are registered with a Specification Required ([RFC8126]) 3597 after a two-week review period on the oauth-ext-review@ietf.org 3598 mailing list, on the advice of one or more Designated Experts. 3599 However, to allow for the allocation of values prior to publication, 3600 the Designated Expert(s) may approve registration once they are 3601 satisfied that such a specification will be published. 3603 Registration requests must be sent to the oauth-ext-review@ietf.org 3604 mailing list for review and comment, with an appropriate subject 3605 (e.g., "Request for error code: example"). 3607 Within the review period, the Designated Expert(s) will either 3608 approve or deny the registration request, communicating this decision 3609 to the review list and IANA. Denials should include an explanation 3610 and, if applicable, suggestions as to how to make the request 3611 successful. 3613 IANA must only accept registry updates from the Designated Expert(s) 3614 and should direct all requests for registration to the review mailing 3615 list. 3617 13.4.1. Registration Template 3619 Error name: The name requested (e.g., "example"). Values for the 3620 error name MUST NOT include characters outside the set %x20-21 / 3621 %x23-5B / %x5D-7E. 3623 Error usage location: The location(s) where the error can be used. 3624 The possible locations are authorization code grant error response 3625 (Section 4.1.2.1), token error response (Section 5.2), or resource 3626 access error response (Section 7.3). 3628 Related protocol extension: The name of the extension grant type, 3629 access token type, or extension parameter that the error code is 3630 used in conjunction with. 3632 Change controller: For Standards Track RFCs, state "IETF". For 3633 others, give the name of the responsible party. Other details 3634 (e.g., postal address, email address, home page URI) may also be 3635 included. 3637 Specification document(s): Reference to the document(s) that specify 3638 the error code, preferably including a URI that can be used to 3639 retrieve a copy of the document(s). An indication of the relevant 3640 sections may also be included but is not required. 3642 13.4.2. Initial Registry Contents 3644 The OAuth Error registry's initial contents are: 3646 * Error name: invalid_request 3648 * Error usage location: Resource access error response 3650 * Change controller: IETF 3652 * Specification document(s): OAuth 2.1 3654 * Error name: invalid_token 3656 * Error usage location: Resource access error response 3658 * Change controller: IETF 3660 * Specification document(s): OAuth 2.1 3662 * Error name: insufficient_scope 3664 * Error usage location: Resource access error response 3666 * Change controller: IETF 3668 * Specification document(s): OAuth 2.1 3670 14. References 3672 14.1. Normative References 3674 [I-D.ietf-oauth-security-topics] 3675 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3676 "OAuth 2.0 Security Best Current Practice", Work in 3677 Progress, Internet-Draft, draft-ietf-oauth-security- 3678 topics-15, 5 April 2020, . 3681 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3682 Requirement Levels", BCP 14, RFC 2119, 3683 DOI 10.17487/RFC2119, March 1997, 3684 . 3686 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3687 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3688 Authentication: Basic and Digest Access Authentication", 3689 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3690 . 3692 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3693 DOI 10.17487/RFC2818, May 2000, 3694 . 3696 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3697 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3698 2003, . 3700 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3701 Resource Identifier (URI): Generic Syntax", STD 66, 3702 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3703 . 3705 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3706 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3707 . 3709 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3710 Specifications: ABNF", STD 68, RFC 5234, 3711 DOI 10.17487/RFC5234, January 2008, 3712 . 3714 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3715 Housley, R., and W. Polk, "Internet X.509 Public Key 3716 Infrastructure Certificate and Certificate Revocation List 3717 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3718 . 3720 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3721 Verification of Domain-Based Application Service Identity 3722 within Internet Public Key Infrastructure Using X.509 3723 (PKIX) Certificates in the Context of Transport Layer 3724 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3725 2011, . 3727 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3728 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3729 . 3731 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3732 Framework: Bearer Token Usage", RFC 6750, 3733 DOI 10.17487/RFC6750, October 2012, 3734 . 3736 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3737 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3738 2014, . 3740 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3741 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3742 DOI 10.17487/RFC7231, June 2014, 3743 . 3745 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3746 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3747 RFC 7234, DOI 10.17487/RFC7234, June 2014, 3748 . 3750 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3751 and Registration Procedures for URI Schemes", BCP 35, 3752 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3753 . 3755 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3756 Writing an IANA Considerations Section in RFCs", BCP 26, 3757 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3758 . 3760 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3761 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3762 May 2017, . 3764 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3765 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3766 . 3768 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3769 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3770 . 3772 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3773 Standard Code for Information Interchange, ANSI X3.4", 3774 1986. 3776 [W3C.REC-html401-19991224] 3777 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3778 Specification", World Wide Web Consortium Recommendation 3779 REC-html401-19991224, 24 December 1999, 3780 . 3782 [W3C.REC-xml-20081126] 3783 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3784 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3785 Edition)", World Wide Web Consortium Recommendation REC- 3786 xml-20081126, 26 November 2008, 3787 . 3789 14.2. Informative References 3791 [CSP-2] "Content Security Policy Level 2", December 2016, 3792 . 3794 [I-D.bradley-oauth-jwt-encoded-state] 3795 Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding 3796 claims in the OAuth 2 state parameter using a JWT", Work 3797 in Progress, Internet-Draft, draft-bradley-oauth-jwt- 3798 encoded-state-09, 4 November 2018, . 3802 [I-D.ietf-oauth-browser-based-apps] 3803 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3804 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3805 browser-based-apps-06, 5 April 2020, . 3809 [I-D.ietf-oauth-rar] 3810 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3811 Rich Authorization Requests", Work in Progress, Internet- 3812 Draft, draft-ietf-oauth-rar-01, 19 February 2020, 3813 . 3816 [I-D.ietf-oauth-token-binding] 3817 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 3818 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3819 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3820 . 3823 [NIST800-63] 3824 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3825 Gupta, S., and E. Nabbus, "NIST Special Publication 3826 800-63-1, INFORMATION SECURITY", December 2011, 3827 . 3829 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3830 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3831 and B. Boyer, "Online Multimedia Authorization Protocol: 3832 An Industry Standard for Authorized Access to Internet 3833 Multimedia Resources", April 2012, 3834 . 3836 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3837 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3838 . 3840 [OpenID.Messages] 3841 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3842 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3843 June 2012, . 3846 [owasp_redir] 3847 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3848 Forwards", 2020, 3849 . 3852 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3853 DOI 10.17487/RFC6265, April 2011, 3854 . 3856 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3857 Threat Model and Security Considerations", RFC 6819, 3858 DOI 10.17487/RFC6819, January 2013, 3859 . 3861 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3862 Protocol (HTTP/1.1): Message Syntax and Routing", 3863 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3864 . 3866 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3867 Protocol (HTTP/1.1): Authentication", RFC 7235, 3868 DOI 10.17487/RFC7235, June 2014, 3869 . 3871 [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security 3872 Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 3873 Client Authentication and Authorization Grants", RFC 7522, 3874 DOI 10.17487/RFC7522, May 2015, 3875 . 3877 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3878 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3879 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3880 . 3882 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3883 for Code Exchange by OAuth Public Clients", RFC 7636, 3884 DOI 10.17487/RFC7636, September 2015, 3885 . 3887 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3888 Authorization Server Metadata", RFC 8414, 3889 DOI 10.17487/RFC8414, June 2018, 3890 . 3892 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3893 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3894 and Certificate-Bound Access Tokens", RFC 8705, 3895 DOI 10.17487/RFC8705, February 2020, 3896 . 3898 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3899 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3900 February 2020, . 3902 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3904 This section provides Augmented Backus-Naur Form (ABNF) syntax 3905 descriptions for the elements defined in this specification using the 3906 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3907 code points [W3C.REC-xml-20081126]; these characters are typically 3908 encoded in UTF-8. Elements are presented in the order first defined. 3910 Some of the definitions that follow use the "URI-reference" 3911 definition from [RFC3986]. 3913 Some of the definitions that follow use these common definitions: 3915 VSCHAR = %x20-7E 3916 NQCHAR = %x21 / %x23-5B / %x5D-7E 3917 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3918 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3919 %xE000-FFFD / %x10000-10FFFF 3921 (The UNICODECHARNOCRLF definition is based upon the Char definition 3922 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3923 Return and Linefeed characters.) 3925 A.1. "client_id" Syntax 3927 The "client_id" element is defined in Section 2.3.1: 3929 client-id = *VSCHAR 3931 A.2. "client_secret" Syntax 3933 The "client_secret" element is defined in Section 2.3.1: 3935 client-secret = *VSCHAR 3937 A.3. "response_type" Syntax 3939 The "response_type" element is defined in Section 3.1.1 and 3940 Section 8.4: 3942 response-type = response-name *( SP response-name ) 3943 response-name = 1*response-char 3944 response-char = "_" / DIGIT / ALPHA 3946 A.4. "scope" Syntax 3948 The "scope" element is defined in Section 3.3: 3950 scope = scope-token *( SP scope-token ) 3951 scope-token = 1*NQCHAR 3953 A.5. "state" Syntax 3955 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3956 Section 4.1.2.1: 3958 state = 1*VSCHAR 3960 A.6. "redirect_uri" Syntax 3962 The "redirect_uri" element is defined in Section 4.1.1, and 3963 Section 4.1.3: 3965 redirect-uri = URI-reference 3967 A.7. "error" Syntax 3969 The "error" element is defined in Sections Section 4.1.2.1, 3970 Section 5.2, 7.2, and 8.5: 3972 error = 1*NQSCHAR 3974 A.8. "error_description" Syntax 3976 The "error_description" element is defined in Sections 3977 Section 4.1.2.1, Section 5.2, and Section 7.3: 3979 error-description = 1*NQSCHAR 3981 A.9. "error_uri" Syntax 3983 The "error_uri" element is defined in Sections Section 4.1.2.1, 3984 Section 5.2, and 7.2: 3986 error-uri = URI-reference 3988 A.10. "grant_type" Syntax 3990 The "grant_type" element is defined in Sections Section 4.1.3, 3991 Section 4.2.3, Section 4.2.2, Section 4.3, and Section 6: 3993 grant-type = grant-name / URI-reference 3994 grant-name = 1*name-char 3995 name-char = "-" / "." / "_" / DIGIT / ALPHA 3997 A.11. "code" Syntax 3999 The "code" element is defined in Section 4.1.3: 4001 code = 1*VSCHAR 4003 A.12. "access_token" Syntax 4005 The "access_token" element is defined in Section 4.2.3 and 4006 Section 5.1: 4008 access-token = 1*VSCHAR 4010 A.13. "token_type" Syntax 4012 The "token_type" element is defined in Section 5.1, and Section 8.1: 4014 token-type = type-name / URI-reference 4015 type-name = 1*name-char 4016 name-char = "-" / "." / "_" / DIGIT / ALPHA 4018 A.14. "expires_in" Syntax 4020 The "expires_in" element is defined in Section 5.1: 4022 expires-in = 1*DIGIT 4024 A.15. "refresh_token" Syntax 4026 The "refresh_token" element is defined in Section 5.1 and Section 6: 4028 refresh-token = 1*VSCHAR 4030 A.16. Endpoint Parameter Syntax 4032 The syntax for new endpoint parameters is defined in Section 8.2: 4034 param-name = 1*name-char 4035 name-char = "-" / "." / "_" / DIGIT / ALPHA 4037 A.17. "code_verifier" Syntax 4039 ABNF for "code_verifier" is as follows. 4041 code-verifier = 43*128unreserved 4042 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 4043 ALPHA = %x41-5A / %x61-7A 4044 DIGIT = %x30-39 4046 A.18. "code_challenge" Syntax 4048 ABNF for "code_challenge" is as follows. 4050 code-challenge = 43*128unreserved 4051 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 4052 ALPHA = %x41-5A / %x61-7A 4053 DIGIT = %x30-39 4055 Appendix B. Use of application/x-www-form-urlencoded Media Type 4057 At the time of publication of this specification, the "application/x- 4058 www-form-urlencoded" media type was defined in Section 17.13.4 of 4059 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 4060 Types registry (http://www.iana.org/assignments/media-types 4061 (http://www.iana.org/assignments/media-types)). Furthermore, that 4062 definition is incomplete, as it does not consider non-US-ASCII 4063 characters. 4065 To address this shortcoming when generating payloads using this media 4066 type, names and values MUST be encoded using the UTF-8 character 4067 encoding scheme [RFC3629] first; the resulting octet sequence then 4068 needs to be further encoded using the escaping rules defined in 4069 [W3C.REC-html401-19991224]. 4071 When parsing data from a payload using this media type, the names and 4072 values resulting from reversing the name/value encoding consequently 4073 need to be treated as octet sequences, to be decoded using the UTF-8 4074 character encoding scheme. 4076 For example, the value consisting of the six Unicode code points (1) 4077 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 4078 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 4079 SIGN) would be encoded into the octet sequence below (using 4080 hexadecimal notation): 4082 20 25 26 2B C2 A3 E2 82 AC 4084 and then represented in the payload as: 4086 +%25%26%2B%C2%A3%E2%82%AC 4088 Appendix C. Acknowledgements 4090 TBD 4092 Authors' Addresses 4094 Dick Hardt 4095 SignIn.Org 4097 Email: dick.hardt@gmail.com 4098 Aaron Parecki 4099 Okta 4101 Email: aaron@parecki.com 4102 URI: https://aaronparecki.com 4104 Torsten Lodderstedt 4105 yes.com 4107 Email: torsten@lodderstedt.net