idnits 2.17.1 draft-parecki-oauth-v2-1-03.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 20 instances of too long lines in the document, the longest one being 1 character 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 (5 July 2020) is 1381 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 1103, but not defined == Missing Reference: '0-9' is mentioned on line 1103, but not defined == Outdated reference: A later version (-25) 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 (-13) exists of draft-ietf-oauth-access-token-jwt-07 == Outdated reference: A later version (-17) exists of draft-ietf-oauth-browser-based-apps-06 == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-01 == Outdated reference: A later version (-10) exists of draft-ietf-oauth-par-01 == 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 (~~), 10 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: 6 January 2021 Okta 6 T. Lodderstedt 7 yes.com 8 5 July 2020 10 The OAuth 2.1 Authorization Framework 11 draft-parecki-oauth-v2-1-03 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 6 January 2021. 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 . . . . . . . . . . . . . . . . 30 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 6.1. Refresh Token Protection . . . . . . . . . . . . . . . . 38 98 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 40 99 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 40 100 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 41 101 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 41 102 7.2.2. The WWW-Authenticate Response Header Field . . . . . 43 103 7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 44 104 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 45 105 7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 45 106 7.4. Access Token Security Considerations . . . . . . . . . . 45 107 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 46 108 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 46 109 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 48 110 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 49 111 7.4.5. Access Token Privilege Restriction . . . . . . . . . 50 112 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 50 113 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 50 114 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 51 115 8.3. Defining New Authorization Grant Types . . . . . . . . . 51 116 8.4. Defining New Authorization Endpoint Response Types . . . 51 117 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 52 118 9. Security Considerations . . . . . . . . . . . . . . . . . . . 52 119 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 53 120 9.1.1. Client Authentication of Native Apps . . . . . . . . 53 121 9.2. Registration of Native App Clients . . . . . . . . . . . 54 122 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 54 123 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 55 124 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 55 125 9.4.1. Access Token Privilege Restriction . . . . . . . . . 56 126 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 56 127 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 57 128 9.6. Client Impersonating Resource Owner . . . . . . . . . . . 57 129 9.7. Protecting Redirect-Based Flows . . . . . . . . . . . . . 58 130 9.7.1. Loopback Redirect Considerations in Native Apps . . . 58 131 9.7.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 59 132 9.8. Authorization Codes . . . . . . . . . . . . . . . . . . . 60 133 9.9. Request Confidentiality . . . . . . . . . . . . . . . . . 61 134 9.10. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 61 135 9.11. Credentials-Guessing Attacks . . . . . . . . . . . . . . 62 136 9.12. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 62 137 9.13. Fake External User-Agents in Native Apps . . . . . . . . 62 138 9.14. Malicious External User-Agents in Native Apps . . . . . . 63 139 9.15. Cross-Site Request Forgery . . . . . . . . . . . . . . . 63 140 9.16. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 64 141 9.17. Code Injection and Input Validation . . . . . . . . . . . 65 142 9.18. Open Redirectors . . . . . . . . . . . . . . . . . . . . 65 143 9.18.1. Client as Open Redirector . . . . . . . . . . . . . 65 144 9.18.2. Authorization Server as Open Redirector . . . . . . 65 146 9.19. Authorization Server Mix-Up Mitigation in Native Apps . . 66 147 9.20. Embedded User Agents in Native Apps . . . . . . . . . . . 66 148 9.21. Other Recommendations . . . . . . . . . . . . . . . . . . 67 149 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 67 150 10.1. Using Inter-App URI Communication for OAuth in Native 151 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 68 152 10.2. Initiating the Authorization Request from a Native 153 App . . . . . . . . . . . . . . . . . . . . . . . . . . 69 154 10.3. Receiving the Authorization Response in a Native App . . 70 155 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 70 156 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 71 157 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 71 158 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 72 159 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 72 160 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 161 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 162 14.1. Normative References . . . . . . . . . . . . . . . . . . 73 163 14.2. Informative References . . . . . . . . . . . . . . . . . 76 164 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 79 165 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 79 166 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 79 167 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 80 168 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 80 169 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 80 170 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 80 171 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 80 172 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 80 173 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 81 174 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 81 175 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 81 176 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 81 177 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 81 178 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 81 179 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 81 180 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 82 181 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 82 182 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 82 183 Appendix B. Use of application/x-www-form-urlencoded Media 184 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 82 185 Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 83 186 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 84 187 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 189 1. Introduction 191 In the traditional client-server authentication model, the client 192 requests an access-restricted resource (protected resource) on the 193 server by authenticating with the server using the resource owner's 194 credentials. In order to provide third-party applications access to 195 restricted resources, the resource owner shares its credentials with 196 the third party. This creates several problems and limitations: 198 * Third-party applications are required to store the resource 199 owner's credentials for future use, typically a password in clear- 200 text. 202 * Servers are required to support password authentication, despite 203 the security weaknesses inherent in passwords. 205 * Third-party applications gain overly broad access to the resource 206 owner's protected resources, leaving resource owners without any 207 ability to restrict duration or access to a limited subset of 208 resources. 210 * Resource owners cannot revoke access to an individual third party 211 without revoking access to all third parties, and must do so by 212 changing the third party's password. 214 * Compromise of any third-party application results in compromise of 215 the end-user's password and all of the data protected by that 216 password. 218 OAuth addresses these issues by introducing an authorization layer 219 and separating the role of the client from that of the resource 220 owner. In OAuth, the client requests access to resources controlled 221 by the resource owner and hosted by the resource server, and is 222 issued a different set of credentials than those of the resource 223 owner. 225 Instead of using the resource owner's credentials to access protected 226 resources, the client obtains an access token - a string denoting a 227 specific scope, lifetime, and other access attributes. Access tokens 228 are issued to third-party clients by an authorization server with the 229 approval of the resource owner. The client uses the access token to 230 access the protected resources hosted by the resource server. 232 For example, an end-user (resource owner) can grant a printing 233 service (client) access to her protected photos stored at a photo- 234 sharing service (resource server), without sharing her username and 235 password with the printing service. Instead, she authenticates 236 directly with a server trusted by the photo-sharing service 237 (authorization server), which issues the printing service delegation- 238 specific credentials (access token). 240 This specification is designed for use with HTTP ([RFC7230]). The 241 use of OAuth over any protocol other than HTTP is out of scope. 243 Since the publication of the OAuth 2.0 Authorization Framework 244 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 245 Native Apps ([RFC8252]), OAuth Security Best Current Practice 246 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 247 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 248 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 249 updated with ([I-D.ietf-oauth-security-topics]). This Standards 250 Track specification consolidates the information in all of these 251 documents and removes features that have been found to be insecure in 252 [I-D.ietf-oauth-security-topics]. 254 1.1. Roles 256 OAuth defines four roles: 258 "resource owner": An entity capable of granting access to a 259 protected resource. When the resource owner is a person, it is 260 referred to as an end-user. This is sometimes abbreviated as 261 "RO". 263 "resource server": The server hosting the protected resources, 264 capable of accepting and responding to protected resource requests 265 using access tokens. This is sometimes abbreviated as "RS". 267 "client": An application making protected resource requests on 268 behalf of the resource owner and with its authorization. The term 269 "client" does not imply any particular implementation 270 characteristics (e.g., whether the application executes on a 271 server, a desktop, or other devices). 273 "authorization server": The server issuing access tokens to the 274 client after successfully authenticating the resource owner and 275 obtaining authorization. This is sometimes abbreviated as "AS". 277 The interaction between the authorization server and resource server 278 is beyond the scope of this specification, however several extension 279 have been defined to provide an option for interoperability between 280 resource servers and authorization servers. The authorization server 281 may be the same server as the resource server or a separate entity. 282 A single authorization server may issue access tokens accepted by 283 multiple resource servers. 285 1.2. Protocol Flow 287 +--------+ +---------------+ 288 | |--(1)- Authorization Request ->| Resource | 289 | | | Owner | 290 | |<-(2)-- Authorization Grant ---| | 291 | | +---------------+ 292 | | 293 | | +---------------+ 294 | |--(3)-- Authorization Grant -->| Authorization | 295 | Client | | Server | 296 | |<-(4)----- Access Token -------| | 297 | | +---------------+ 298 | | 299 | | +---------------+ 300 | |--(5)----- Access Token ------>| Resource | 301 | | | Server | 302 | |<-(6)--- Protected Resource ---| | 303 +--------+ +---------------+ 305 Figure 1: Abstract Protocol Flow 307 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 308 interaction between the four roles and includes the following steps: 310 1. The client requests authorization from the resource owner. The 311 authorization request can be made directly to the resource owner 312 (as shown), or preferably indirectly via the authorization server 313 as an intermediary. 315 2. The client receives an authorization grant, which is a credential 316 representing the resource owner's authorization, expressed using 317 one of two grant types defined in this specification or using an 318 extension grant type. The authorization grant type depends on 319 the method used by the client to request authorization and the 320 types supported by the authorization server. 322 3. The client requests an access token by authenticating with the 323 authorization server and presenting the authorization grant. 325 4. The authorization server authenticates the client and validates 326 the authorization grant, and if valid, issues an access token. 328 5. The client requests the protected resource from the resource 329 server and authenticates by presenting the access token. 331 6. The resource server validates the access token, and if valid, 332 serves the request. 334 The preferred method for the client to obtain an authorization grant 335 from the resource owner (depicted in steps (1) and (2)) is to use the 336 authorization server as an intermediary, which is illustrated in 337 Figure 3 in Section 4.1. 339 1.3. Authorization Grant 341 An authorization grant is a credential representing the resource 342 owner's authorization (to access its protected resources) used by the 343 client to obtain an access token. This specification defines two 344 grant types - authorization code and client credentials - as well as 345 an extensibility mechanism for defining additional types. 347 1.3.1. Authorization Code 349 The authorization code is obtained by using an authorization server 350 as an intermediary between the client and resource owner. Instead of 351 requesting authorization directly from the resource owner, the client 352 directs the resource owner to an authorization server (via its user- 353 agent as defined in [RFC7231]), which in turn directs the resource 354 owner back to the client with the authorization code. 356 Before directing the resource owner back to the client with the 357 authorization code, the authorization server authenticates the 358 resource owner and obtains authorization. Because the resource owner 359 only authenticates with the authorization server, the resource 360 owner's credentials are never shared with the client. 362 The authorization code provides a few important security benefits, 363 such as the ability to authenticate the client, as well as the 364 transmission of the access token directly to the client without 365 passing it through the resource owner's user-agent and potentially 366 exposing it to others, including the resource owner. 368 1.3.2. Client Credentials 370 The client credentials (or other forms of client authentication) can 371 be used as an authorization grant when the authorization scope is 372 limited to the protected resources under the control of the client, 373 or to protected resources previously arranged with the authorization 374 server. Client credentials are used as an authorization grant 375 typically when the client is acting on its own behalf (the client is 376 also the resource owner) or is requesting access to protected 377 resources based on an authorization previously arranged with the 378 authorization server. 380 1.4. Access Token 382 Access tokens are credentials used to access protected resources. An 383 access token is a string representing an authorization issued to the 384 client. The string is opaque to the client, but depending on the 385 authorization server, may be parseable by the resource server. 387 Tokens represent specific scopes and durations of access, granted by 388 the resource owner, and enforced by the resource server and 389 authorization server. 391 The token may denote an identifier used to retrieve the authorization 392 information or may self-contain the authorization information in a 393 verifiable manner (i.e., a token string consisting of some data and a 394 signature). One example of a structured token format is 395 [I-D.ietf-oauth-access-token-jwt], a method of encoding access token 396 data as a JSON Web Token [RFC7519]. 398 Additional authentication credentials, which are beyond the scope of 399 this specification, may be required in order for the client to use a 400 token. This is typically referred to as a sender-constrained access 401 token, such as Mutual TLS Access Tokens [RFC8705]. 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 optionally 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 presenting the refresh 482 token and providing client authentication if it has been issued 483 credentials. The client authentication requirements are based on 484 the client type 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.7.2 for details. 511 1.8. Interoperability 513 OAuth 2.1 provides a rich authorization framework with well-defined 514 security properties. 516 This specification leaves a few required components partially or 517 fully undefined (e.g., client registration, authorization server 518 capabilities, endpoint discovery). Some of these behaviors are 519 defined in optional extensions which implementations can choose to 520 use. 522 Please refer to Appendix C for a list of current known extensions at 523 the time of this publication. 525 1.9. Notational Conventions 527 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 528 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 529 "OPTIONAL" in this document are to be interpreted as described in BCP 530 14 [RFC2119] [RFC8174] when, and only when, they appear in all 531 capitals, as shown here. 533 This specification uses the Augmented Backus-Naur Form (ABNF) 534 notation of [RFC5234]. Additionally, the rule URI-reference is 535 included from "Uniform Resource Identifier (URI): Generic Syntax" 536 [RFC3986]. 538 Certain security-related terms are to be understood in the sense 539 defined in [RFC4949]. These terms include, but are not limited to, 540 "attack", "authentication", "authorization", "certificate", 541 "confidentiality", "credential", "encryption", "identity", "sign", 542 "signature", "trust", "validate", and "verify". 544 Unless otherwise noted, all the protocol parameter names and values 545 are case sensitive. 547 2. Client Registration 549 Before initiating the protocol, the client registers with the 550 authorization server. The means through which the client registers 551 with the authorization server are beyond the scope of this 552 specification but typically involve end-user interaction with an HTML 553 registration form, or by using Dynamic Client Registration 554 ([RFC7591]). 556 Client registration does not require a direct interaction between the 557 client and the authorization server. When supported by the 558 authorization server, registration can rely on other means for 559 establishing trust and obtaining the required client properties 560 (e.g., redirect URI, client type). For example, registration can be 561 accomplished using a self-issued or third-party-issued assertion, or 562 by the authorization server performing client discovery using a 563 trusted channel. 565 When registering a client, the client developer SHALL: 567 * specify the client type as described in Section 2.1, 569 * provide its client redirect URIs as described in Section 3.1.2, 570 and 572 * include any other information required by the authorization server 573 (e.g., application name, website, description, logo image, the 574 acceptance of legal terms). 576 Dynamic Client Registration ([RFC7591]) defines a common general data 577 model for clients that may be used even with manual client 578 registration. 580 2.1. Client Types 582 Clients are identified at the authorization server by a "client_id". 583 It is, for example, used by the authorization server to determine the 584 set of redirect URIs this client can use. 586 Clients requiring a higher level of confidence in their identity by 587 the authorization server use credentials to authenticate with the 588 authorization server. Such credentials are either issued by the 589 authorization server or registered by the developer of the client 590 with the authorization server. 592 OAuth 2.1 defines three client types: 594 "confidential": Clients that have credentials and their identity has 595 been confirmed by the AS are designated as "confidential clients" 597 "credentialed": Clients that have credentials and their identity has 598 been not been confirmed by the AS are designated as "credentialed 599 clients" 601 "public": Clients without credentials are called "public clients" 603 Any clients with credentials MUST take precautions to prevent leakage 604 and 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 single "client_id" MUST NOT be treated as more than one type of 612 client. 614 This specification has been designed around the following client 615 profiles: 617 "web application": A web application is a confidential client 618 running on a web server. Resource owners access the client via an 619 HTML user interface rendered in a user-agent on the device used by 620 the resource owner. The client credentials as well as any access 621 token issued to the client are stored on the web server and are 622 not exposed to or accessible by the resource owner. 624 "browser-based application": A browser-based application is a public 625 client in which the client code is downloaded from a web server 626 and executes within a user-agent (e.g., web browser) on the device 627 used by the resource owner. Protocol data and credentials are 628 easily accessible (and often visible) to the resource owner. 629 Since such applications reside within the user-agent, they can 630 make seamless use of the user-agent capabilities when requesting 631 authorization. 633 "native application": A native application is a public client 634 installed and executed on the device used by the resource owner. 635 Protocol data and credentials are accessible to the resource 636 owner. It is assumed that any client authentication credentials 637 included in the application can be extracted. On the other hand, 638 dynamically issued credentials such as access tokens or refresh 639 tokens can receive an acceptable level of protection. At a 640 minimum, these credentials are protected from hostile servers with 641 which the application may interact. On some platforms, these 642 credentials might be protected from other applications residing on 643 the same device. 645 2.2. Client Identifier 647 The authorization server issues the registered client a client 648 identifier - a unique string representing the registration 649 information provided by the client. The client identifier is not a 650 secret; it is exposed to the resource owner and MUST NOT be used 651 alone for client authentication. The client identifier is unique to 652 the authorization server. 654 The client identifier string size is left undefined by this 655 specification. The client should avoid making assumptions about the 656 identifier size. The authorization server SHOULD document the size 657 of any identifier it issues. 659 Authorization servers SHOULD NOT allow clients to choose or influence 660 their "client_id" value. See Section 9.6 for details. 662 2.3. Client Authentication 664 If the client has credentials, (is a confidential or credentialed 665 client), the client and authorization server establish a client 666 authentication method suitable for the security requirements of the 667 authorization server. The authorization server MAY accept any form 668 of client authentication meeting its security requirements. 670 Confidential and credentialed clients are typically issued (or 671 establish) a set of client credentials used for authenticating with 672 the authorization server (e.g., password, public/private key pair). 674 Authorization servers SHOULD use client authentication if possible. 676 It is RECOMMENDED to use asymmetric (public-key based) methods for 677 client authentication such as mTLS [RFC8705] or "private_key_jwt" 678 [OpenID]. When asymmetric methods for client authentication are 679 used, authorization servers do not need to store sensitive symmetric 680 keys, making these methods more robust against a number of attacks. 682 The authorization server MAY establish a client authentication method 683 with public clients, which converts them to credentialed clients. 684 However, the authorization server MUST NOT rely on credentialed 685 client authentication for the purpose of identifying the client. 687 The client MUST NOT use more than one authentication method in each 688 request. 690 2.3.1. Client Password 692 Clients in possession of a client password, also known as a client 693 secret, MAY use the HTTP Basic authentication scheme as defined in 694 [RFC2617] to authenticate with the authorization server. The client 695 identifier is encoded using the "application/x-www-form-urlencoded" 696 encoding algorithm per Appendix B, and the encoded value is used as 697 the username; the client secret is encoded using the same algorithm 698 and used as the password. The authorization server MUST support the 699 HTTP Basic authentication scheme for authenticating clients that were 700 issued a client secret. 702 For example (with extra line breaks for display purposes only): 704 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 706 Alternatively, the authorization server MAY support including the 707 client credentials in the request-body using the following 708 parameters: 710 "client_id": REQUIRED. The client identifier issued to the client 711 during the registration process described by Section 2.2. 713 "client_secret": REQUIRED. The client secret. 715 Including the client credentials in the request-body using the two 716 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 717 to directly utilize the HTTP Basic authentication scheme (or other 718 password-based HTTP authentication schemes). The parameters can only 719 be transmitted in the request-body and MUST NOT be included in the 720 request URI. 722 For example, a request to refresh an access token (Section 6) using 723 the body parameters (with extra line breaks for display purposes 724 only): 726 POST /token HTTP/1.1 727 Host: server.example.com 728 Content-Type: application/x-www-form-urlencoded 730 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 731 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 733 The authorization server MUST require the use of TLS as described in 734 Section 1.6 when sending requests using password authentication. 736 Since this client authentication method involves a password, the 737 authorization server MUST protect any endpoint utilizing it against 738 brute force attacks. 740 2.3.2. Other Authentication Methods 742 The authorization server MAY support any suitable authentication 743 scheme matching its security requirements. When using other 744 authentication methods, the authorization server MUST define a 745 mapping between the client identifier (registration record) and 746 authentication scheme. 748 Some additional authentication methods are defined in the "OAuth 749 Token Endpoint Authentication Methods 750 (https://www.iana.org/assignments/oauth-parameters/oauth- 751 parameters.xhtml#token-endpoint-auth-method)" registry, and may be 752 useful as generic client authentication methods beyond the specific 753 use of protecting the token endpoint. 755 2.4. Unregistered Clients 757 This specification does not exclude the use of unregistered clients. 758 However, the use of such clients is beyond the scope of this 759 specification and requires additional security analysis and review of 760 its interoperability impact. 762 3. Protocol Endpoints 764 The authorization process utilizes two authorization server endpoints 765 (HTTP resources): 767 * Authorization endpoint - used by the client to obtain 768 authorization from the resource owner via user-agent redirection. 770 * Token endpoint - used by the client to exchange an authorization 771 grant for an access token, typically with client authentication. 773 As well as one client endpoint: 775 * Redirection endpoint - used by the authorization server to return 776 responses containing authorization credentials to the client via 777 the resource owner user-agent. 779 Not every authorization grant type utilizes both endpoints. 780 Extension grant types MAY define additional endpoints as needed. 782 3.1. Authorization Endpoint 784 The authorization endpoint is used to interact with the resource 785 owner and obtain an authorization grant. The authorization server 786 MUST first verify the identity of the resource owner. The way in 787 which the authorization server authenticates the resource owner 788 (e.g., username and password login, session cookies) is beyond the 789 scope of this specification. 791 The means through which the client obtains the location of the 792 authorization endpoint are beyond the scope of this specification, 793 but the location is typically provided in the service documentation, 794 or in the authorization server's metadata document ([RFC8414]). 796 The endpoint URI MAY include an "application/x-www-form-urlencoded" 797 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 798 which MUST be retained when adding additional query parameters. The 799 endpoint URI MUST NOT include a fragment component. 801 Since requests to the authorization endpoint result in user 802 authentication and the transmission of clear-text credentials (in the 803 HTTP response), the authorization server MUST require the use of TLS 804 as described in Section 1.6 when sending requests to the 805 authorization endpoint. 807 The authorization server MUST support the use of the HTTP "GET" 808 method [RFC7231] for the authorization endpoint and MAY support the 809 use of the "POST" method as well. 811 Parameters sent without a value MUST be treated as if they were 812 omitted from the request. The authorization server MUST ignore 813 unrecognized request parameters. Request and response parameters 814 defined by this specification MUST NOT be included more than once. 816 3.1.1. Response Type 818 The authorization endpoint is used by the authorization code flow. 819 The client informs the authorization server of the desired response 820 type using the following parameter: 822 "response_type": REQUIRED. The value MUST be "code" for requesting 823 an authorization code as described by Section 4.1.1, or a 824 registered extension value as described by Section 8.4. 826 Extension response types MAY contain a space-delimited (%x20) list of 827 values, where the order of values does not matter (e.g., response 828 type "a b" is the same as "b a"). The meaning of such composite 829 response types is defined by their respective specifications. 831 If an authorization request is missing the "response_type" parameter, 832 or if the response type is not understood, the authorization server 833 MUST return an error response as described in Section 4.1.2.1. 835 3.1.2. Redirection Endpoint 837 After completing its interaction with the resource owner, the 838 authorization server directs the resource owner's user-agent back to 839 the client. The authorization server redirects the user-agent to the 840 client's redirection endpoint previously established with the 841 authorization server during the client registration process. 843 The authorization server MUST compare the two URIs using simple 844 string comparison as defined in [RFC3986], Section 6.2.1. 846 The redirect URI MUST be an absolute URI as defined by [RFC3986] 847 Section 4.3. The endpoint URI MAY include an "application/x-www- 848 form-urlencoded" formatted (per Appendix B) query component 849 ([RFC3986] Section 3.4), which MUST be retained when adding 850 additional query parameters. The endpoint URI MUST NOT include a 851 fragment component. 853 3.1.2.1. Endpoint Request Confidentiality 855 The redirection endpoint SHOULD require the use of TLS as described 856 in Section 1.6 when the requested response type is "code", or when 857 the redirection request will result in the transmission of sensitive 858 credentials over an open network. If TLS is not available, the 859 authorization server SHOULD warn the resource owner about the 860 insecure endpoint prior to redirection (e.g., display a message 861 during the authorization request). 863 Lack of transport-layer security can have a severe impact on the 864 security of the client and the protected resources it is authorized 865 to access. The use of transport-layer security is particularly 866 critical when the authorization process is used as a form of 867 delegated end-user authentication by the client (e.g., third-party 868 sign-in service). 870 3.1.2.2. Registration Requirements 872 The authorization server MUST require all clients to register one or 873 more complete redirect URIs prior to utilizing the authorization 874 endpoint. The client MAY use the "state" request parameter to 875 achieve per-request customization if needed. 877 The authorization server MAY allow the client to register multiple 878 redirect URIs. 880 Lack of requiring registration of redirect URIs enables an attacker 881 to use the authorization endpoint as an open redirector as described 882 in Section 9.18. 884 3.1.2.3. Dynamic Configuration 886 If multiple redirect URIs have been registered the client MUST 887 include a redirect URI with the authorization request using the 888 "redirect_uri" request parameter. 890 3.1.2.4. Invalid Endpoint 892 If an authorization request fails validation due to a missing, 893 invalid, or mismatching redirect URI, the authorization server SHOULD 894 inform the resource owner of the error and MUST NOT automatically 895 redirect the user-agent to the invalid redirect URI. 897 3.1.2.5. Endpoint Content 899 The redirection request to the client's endpoint typically results in 900 an HTML document response, processed by the user-agent. If the HTML 901 response is served directly as the result of the redirection request, 902 any script included in the HTML document will execute with full 903 access to the redirect URI and the credentials (e.g. authorization 904 code) it contains. 906 The client SHOULD NOT include any third-party scripts (e.g., third- 907 party analytics, social plug-ins, ad networks) in the redirection 908 endpoint response. Instead, it SHOULD extract the credentials from 909 the URI and redirect the user-agent again to another endpoint without 910 exposing the credentials (in the URI or elsewhere). If third-party 911 scripts are included, the client MUST ensure that its own scripts 912 (used to extract and remove the credentials from the URI) will 913 execute first. 915 3.2. Token Endpoint 917 The token endpoint is used by the client to obtain an access token by 918 presenting its authorization grant or refresh token. 920 The means through which the client obtains the location of the token 921 endpoint are beyond the scope of this specification, but the location 922 is typically provided in the service documentation, or in the 923 authorization server's metadata document ([RFC8414]). 925 The endpoint URI MAY include an "application/x-www-form-urlencoded" 926 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 927 which MUST be retained when adding additional query parameters. The 928 endpoint URI MUST NOT include a fragment component. 930 Since requests to the token endpoint result in the transmission of 931 clear-text credentials (in the HTTP request and response), the 932 authorization server MUST require the use of TLS as described in 933 Section 1.6 when sending requests to the token endpoint. 935 The client MUST use the HTTP "POST" method when making access token 936 requests. 938 Parameters sent without a value MUST be treated as if they were 939 omitted from the request. The authorization server MUST ignore 940 unrecognized request parameters. Request and response parameters 941 defined by this specification MUST NOT be included more than once. 943 3.2.1. Client Authentication 945 Confidential or credentialed clients client MUST authenticate with 946 the authorization server as described in Section 2.3 when making 947 requests to the token endpoint. Client authentication is used for: 949 * Enforcing the binding of refresh tokens and authorization codes to 950 the client they were issued to. Client authentication is critical 951 when an authorization code is transmitted to the redirection 952 endpoint over an insecure channel. 954 * Recovering from a compromised client by disabling the client or 955 changing its credentials, thus preventing an attacker from abusing 956 stolen refresh tokens. Changing a single set of client 957 credentials is significantly faster than revoking an entire set of 958 refresh tokens. 960 * Implementing authentication management best practices, which 961 require periodic credential rotation. Rotation of an entire set 962 of refresh tokens can be challenging, while rotation of a single 963 set of client credentials is significantly easier. 965 3.3. Access Token Scope 967 The authorization and token endpoints allow the client to specify the 968 scope of the access request using the "scope" request parameter. In 969 turn, the authorization server uses the "scope" response parameter to 970 inform the client of the scope of the access token issued. 972 The value of the scope parameter is expressed as a list of space- 973 delimited, case-sensitive strings. The strings are defined by the 974 authorization server. If the value contains multiple space-delimited 975 strings, their order does not matter, and each string adds an 976 additional access range to the requested scope. 978 scope = scope-token *( SP scope-token ) 979 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 981 The authorization server MAY fully or partially ignore the scope 982 requested by the client, based on the authorization server policy or 983 the resource owner's instructions. If the issued access token scope 984 is different from the one requested by the client, the authorization 985 server MUST include the "scope" response parameter to inform the 986 client of the actual scope granted. 988 If the client omits the scope parameter when requesting 989 authorization, the authorization server MUST either process the 990 request using a pre-defined default value or fail the request 991 indicating an invalid scope. The authorization server SHOULD 992 document its scope requirements and default value (if defined). 994 4. Obtaining Authorization 996 To request an access token, the client obtains authorization from the 997 resource owner. The authorization is expressed in the form of an 998 authorization grant, which the client uses to request the access 999 token. OAuth defines two grant types: authorization code and client 1000 credentials. It also provides an extension mechanism for defining 1001 additional grant types. 1003 4.1. Authorization Code Grant 1005 The authorization code grant type is used to obtain both access 1006 tokens and refresh tokens. 1008 Since this is a redirect-based flow, the client must be capable of 1009 interacting with the resource owner's user-agent (typically a web 1010 browser) and capable of receiving incoming requests (via redirection) 1011 from the authorization server. 1013 +----------+ 1014 | Resource | 1015 | Owner | 1016 | | 1017 +----------+ 1018 ^ 1019 | 1020 (2) 1021 +----|-----+ Client Identifier +---------------+ 1022 | -+----(1)-- & Redirect URI ---->| | 1023 | User- | | Authorization | 1024 | Agent -+----(2)-- User authenticates --->| Server | 1025 | | | | 1026 | -+----(3)-- Authorization Code ---<| | 1027 +-|----|---+ +---------------+ 1028 | | ^ v 1029 (1) (3) | | 1030 | | | | 1031 ^ v | | 1032 +---------+ | | 1033 | |>---(4)-- Authorization Code ---------' | 1034 | Client | & Redirect URI | 1035 | | | 1036 | |<---(5)----- Access Token -------------------' 1037 +---------+ (w/ Optional Refresh Token) 1039 Note: The lines illustrating steps (1), (2), and (3) are broken into 1040 two parts as they pass through the user-agent. 1042 Figure 3: Authorization Code Flow 1044 The flow illustrated in Figure 3 includes the following steps: 1046 (1) The client initiates the flow by directing the resource owner's 1047 user-agent to the authorization endpoint. The client includes its 1048 client identifier, code challenge (derived from a generated code 1049 verifier), optional requested scope, optional local state, and a 1050 redirect URI to which the authorization server will send the user- 1051 agent back once access is granted (or denied). 1053 (2) The authorization server authenticates the resource owner (via 1054 the user-agent) and establishes whether the resource owner grants or 1055 denies the client's access request. 1057 (3) Assuming the resource owner grants access, the authorization 1058 server redirects the user-agent back to the client using the redirect 1059 URI provided earlier (in the request or during client registration). 1060 The redirect URI includes an authorization code and any local state 1061 provided by the client earlier. 1063 (4) The client requests an access token from the authorization 1064 server's token endpoint by including the authorization code received 1065 in the previous step, and including its code verifier. When making 1066 the request, the client authenticates with the authorization server 1067 if it can. The client includes the redirect URI used to obtain the 1068 authorization code for verification. 1070 (5) The authorization server authenticates the client when possible, 1071 validates the authorization code, validates the code verifier, and 1072 ensures that the redirect URI received matches the URI used to 1073 redirect the client in step (3). If valid, the authorization server 1074 responds back with an access token and, optionally, a refresh token. 1076 4.1.1. Authorization Request 1078 To begin the authorization request, the client builds the 1079 authorization request URI by adding parameters to the authorization 1080 server's authorization endpoint URI. 1082 Clients use a unique secret per authorization request to protect 1083 against code injection and CSRF attacks. The client first generates 1084 this secret, which it can later use along with the authorization code 1085 to prove that the application using the authorization code is the 1086 same application that requested it. The properties "code_challenge" 1087 and "code_verifier" are adopted from the OAuth 2.0 extension known as 1088 "Proof-Key for Code Exchange", or PKCE ([RFC7636]) where this 1089 technique was originally developed. 1091 Clients MUST use "code_challenge" and "code_verifier" and 1092 authorization servers MUST enforce their use except under the 1093 conditions described in Section 9.8. In this case, using and 1094 enforcing "code_challenge" and "code_verifier" as described in the 1095 following is still RECOMMENDED. 1097 4.1.1.1. Client Creates a Code Verifier 1099 The client first creates a code verifier, "code_verifier", for each 1100 Authorization Request, in the following manner: 1102 code_verifier = high-entropy cryptographic random STRING using the 1103 unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"` 1104 from Section 2.3 of {{RFC3986}}, with a minimum length of 43 characters 1105 and a maximum length of 128 characters. 1107 ABNF for "code_verifier" is as follows. 1109 code-verifier = 43*128unreserved 1110 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1111 ALPHA = %x41-5A / %x61-7A 1112 DIGIT = %x30-39 1114 NOTE: The code verifier SHOULD have enough entropy to make it 1115 impractical to guess the value. It is RECOMMENDED that the output of 1116 a suitable random number generator be used to create a 32-octet 1117 sequence. The octet sequence is then base64url-encoded to produce a 1118 43-octet URL-safe string to use as the code verifier. 1120 4.1.1.2. Client Creates the Code Challenge 1122 The client then creates a code challenge derived from the code 1123 verifier by using one of the following transformations on the code 1124 verifier: 1126 plain 1127 code_challenge = code_verifier 1129 S256 1130 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1132 If the client is capable of using "S256", it MUST use "S256", as 1133 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1134 permitted to use "plain" only if they cannot support "S256" for some 1135 technical reason and know via out-of-band configuration or via 1136 Authorization Server Metadata ([RFC8414]) that the server supports 1137 "plain". 1139 The plain transformation is for compatibility with existing 1140 deployments and for constrained environments that can't use the 1141 "S256" transformation. 1143 ABNF for "code_challenge" is as follows. 1145 code-challenge = 43*128unreserved 1146 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1147 ALPHA = %x41-5A / %x61-7A 1148 DIGIT = %x30-39 1150 4.1.1.3. Client Initiates the Authorization Request 1152 The client constructs the request URI by adding the following 1153 parameters to the query component of the authorization endpoint URI 1154 using the "application/x-www-form-urlencoded" format, per Appendix B: 1156 "response_type": REQUIRED. Value MUST be set to "code". 1158 "client_id": REQUIRED. The client identifier as described in 1159 Section 2.2. 1161 "code_challenge": REQUIRED or RECOMMENDED (see Section 9.8). Code 1162 challenge. 1164 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1165 present in the request. Code verifier transformation method is 1166 "S256" or "plain". 1168 "redirect_uri": OPTIONAL. As described in Section 3.1.2. 1170 "scope": OPTIONAL. The scope of the access request as described by 1171 Section 3.3. 1173 "state": OPTIONAL. An opaque value used by the client to maintain 1174 state between the request and callback. The authorization server 1175 includes this value when redirecting the user-agent back to the 1176 client. 1178 The client directs the resource owner to the constructed URI using an 1179 HTTP redirection response, or by other means available to it via the 1180 user-agent. 1182 For example, the client directs the user-agent to make the following 1183 HTTP request using TLS (with extra line breaks for display purposes 1184 only): 1186 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1187 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1188 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1189 &code_challenge_method=S256 HTTP/1.1 1190 Host: server.example.com 1192 The authorization server validates the request to ensure that all 1193 required parameters are present and valid. If the request is valid, 1194 the authorization server authenticates the resource owner and obtains 1195 an authorization decision (by asking the resource owner or by 1196 establishing approval via other means). 1198 When a decision is established, the authorization server directs the 1199 user-agent to the provided client redirect URI using an HTTP 1200 redirection response, or by other means available to it via the user- 1201 agent. 1203 4.1.2. Authorization Response 1205 If the resource owner grants the access request, the authorization 1206 server issues an authorization code and delivers it to the client by 1207 adding the following parameters to the query component of the 1208 redirect URI using the "application/x-www-form-urlencoded" format, 1209 per Appendix B: 1211 "code": REQUIRED. The authorization code generated by the 1212 authorization server. The authorization code MUST expire shortly 1213 after it is issued to mitigate the risk of leaks. A maximum 1214 authorization code lifetime of 10 minutes is RECOMMENDED. The 1215 client MUST NOT use the authorization code more than once. If an 1216 authorization code is used more than once, the authorization 1217 server MUST deny the request and SHOULD revoke (when possible) all 1218 tokens previously issued based on that authorization code. The 1219 authorization code is bound to the client identifier and redirect 1220 URI. 1222 "state": REQUIRED if the "state" parameter was present in the client 1223 authorization request. The exact value received from the client. 1225 For example, the authorization server redirects the user-agent by 1226 sending the following HTTP response: 1228 HTTP/1.1 302 Found 1229 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1230 &state=xyz 1232 The client MUST ignore unrecognized response parameters. The 1233 authorization code string size is left undefined by this 1234 specification. The client should avoid making assumptions about code 1235 value sizes. The authorization server SHOULD document the size of 1236 any value it issues. 1238 When the server issues the authorization code in the authorization 1239 response, it MUST associate the "code_challenge" and 1240 "code_challenge_method" values with the authorization code so it can 1241 be verified later. 1243 The "code_challenge" and "code_challenge_method" values may be stored 1244 in encrypted form in the "code" itself, but could alternatively be 1245 stored on the server associated with the code. The server MUST NOT 1246 include the "code_challenge" value in client requests in a form that 1247 other entities can extract. 1249 The exact method that the server uses to associate the 1250 "code_challenge" with the issued "code" is out of scope for this 1251 specification. 1253 4.1.2.1. Error Response 1255 If the request fails due to a missing, invalid, or mismatching 1256 redirect URI, or if the client identifier is missing or invalid, the 1257 authorization server SHOULD inform the resource owner of the error 1258 and MUST NOT automatically redirect the user-agent to the invalid 1259 redirect URI. 1261 An AS MUST reject requests without a "code_challenge" from public 1262 clients, and MUST reject such requests from other clients unless 1263 there is reasonable assurance that the client mitigates authorization 1264 code injection in other ways. See Section 9.8 for details. 1266 If the server does not support the requested "code_challenge_method" 1267 transformation, the authorization endpoint MUST return the 1268 authorization error response with "error" value set to 1269 "invalid_request". The "error_description" or the response of 1270 "error_uri" SHOULD explain the nature of error, e.g., transform 1271 algorithm not supported. 1273 If the resource owner denies the access request or if the request 1274 fails for reasons other than a missing or invalid redirect URI, the 1275 authorization server informs the client by adding the following 1276 parameters to the query component of the redirect URI using the 1277 "application/x-www-form-urlencoded" format, per Appendix B: 1279 "error": REQUIRED. A single ASCII [USASCII] error code from the 1280 following: 1282 "invalid_request": The request is missing a required parameter, 1283 includes an invalid parameter value, includes a parameter more 1284 than once, or is otherwise malformed. 1286 "unauthorized_client": The client is not authorized to request an 1287 authorization code using this method. 1289 "access_denied": The resource owner or authorization server 1290 denied the request. 1292 "unsupported_response_type": The authorization server does not 1293 support obtaining an authorization code using this method. 1295 "invalid_scope": The requested scope is invalid, unknown, or 1296 malformed. 1298 "server_error": The authorization server encountered an 1299 unexpected condition that prevented it from fulfilling the 1300 request. (This error code is needed because a 500 Internal 1301 Server Error HTTP status code cannot be returned to the client 1302 via an HTTP redirect.) 1304 "temporarily_unavailable": The authorization server is currently 1305 unable to handle the request due to a temporary overloading or 1306 maintenance of the server. (This error code is needed because 1307 a 503 Service Unavailable HTTP status code cannot be returned 1308 to the client via an HTTP redirect.) 1310 Values for the "error" parameter MUST NOT include characters 1311 outside the set %x20-21 / %x23-5B / %x5D-7E. 1313 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1314 providing additional information, used to assist the client 1315 developer in understanding the error that occurred. Values for 1316 the "error_description" parameter MUST NOT include characters 1317 outside the set %x20-21 / %x23-5B / %x5D-7E. 1319 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1320 with information about the error, used to provide the client 1321 developer with additional information about the error. Values for 1322 the "error_uri" parameter MUST conform to the URI-reference syntax 1323 and thus MUST NOT include characters outside the set %x21 / 1324 %x23-5B / %x5D-7E. 1326 "state": REQUIRED if a "state" parameter was present in the client 1327 authorization request. The exact value received from the client. 1329 For example, the authorization server redirects the user-agent by 1330 sending the following HTTP response: 1332 HTTP/1.1 302 Found 1333 Location: https://client.example.com/cb?error=access_denied&state=xyz 1335 4.1.3. Access Token Request 1337 The client makes a request to the token endpoint by sending the 1338 following parameters using the "application/x-www-form-urlencoded" 1339 format per Appendix B with a character encoding of UTF-8 in the HTTP 1340 request entity-body: 1342 "grant_type": REQUIRED. Value MUST be set to "authorization_code". 1344 "code": REQUIRED. The authorization code received from the 1345 authorization server. 1347 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1348 included in the authorization request as described in 1349 Section 4.1.1, and their values MUST be identical. 1351 "client_id": REQUIRED, if the client is not authenticating with the 1352 authorization server as described in Section 3.2.1. 1354 "code_verifier": REQUIRED, if the "code_challenge" parameter was 1355 included in the authorization request. MUST NOT be used 1356 otherwise. The original code verifier string. 1358 Confidential or credentialed clients MUST authenticate with the 1359 authorization server as described in Section 3.2.1. 1361 For example, the client makes the following HTTP request using TLS 1362 (with extra line breaks for display purposes only): 1364 POST /token HTTP/1.1 1365 Host: server.example.com 1366 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1367 Content-Type: application/x-www-form-urlencoded 1369 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1370 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1371 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1373 The authorization server MUST: 1375 * require client authentication for confidential and credentialed 1376 clients (or clients with other authentication requirements), 1378 * authenticate the client if client authentication is included, 1380 * ensure that the authorization code was issued to the authenticated 1381 confidential or credentialed client, or if the client is public, 1382 ensure that the code was issued to "client_id" in the request, 1384 * verify that the authorization code is valid, 1386 * verify that the "code_verifier" parameter is present if and only 1387 if a "code_challenge" parameter was present in the authorization 1388 request, 1390 * if a "code_verifier" is present, verify the "code_verifier" by 1391 calculating the code challenge from the received "code_verifier" 1392 and comparing it with the previously associated "code_challenge", 1393 after first transforming it according to the 1394 "code_challenge_method" method specified by the client, and 1396 * ensure that the "redirect_uri" parameter is present if the 1397 "redirect_uri" parameter was included in the initial authorization 1398 request as described in Section 4.1.1.3, and if included ensure 1399 that their values are identical. 1401 4.1.4. Access Token Response 1403 If the access token request is valid and authorized, the 1404 authorization server issues an access token and optional refresh 1405 token as described in Section 5.1. If the request client 1406 authentication failed or is invalid, the authorization server returns 1407 an error response as described in Section 5.2. 1409 An example successful response: 1411 HTTP/1.1 200 OK 1412 Content-Type: application/json 1413 Cache-Control: no-store 1414 Pragma: no-cache 1416 { 1417 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1418 "token_type": "Bearer", 1419 "expires_in": 3600, 1420 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 1421 "example_parameter": "example_value" 1422 } 1424 4.2. Client Credentials Grant 1426 The client can request an access token using only its client 1427 credentials (or other supported means of authentication) when the 1428 client is requesting access to the protected resources under its 1429 control, or those of another resource owner that have been previously 1430 arranged with the authorization server (the method of which is beyond 1431 the scope of this specification). 1433 The client credentials grant type MUST only be used by confidential 1434 or credentialed clients. 1436 +---------+ +---------------+ 1437 | | | | 1438 | |>--(1)- Client Authentication --->| Authorization | 1439 | Client | | Server | 1440 | |<--(2)---- Access Token ---------<| | 1441 | | | | 1442 +---------+ +---------------+ 1444 Figure 4: Client Credentials Flow 1446 The flow illustrated in Figure 4 includes the following steps: 1448 (1) The client authenticates with the authorization server and 1449 requests an access token from the token endpoint. 1451 (2) The authorization server authenticates the client, and if valid, 1452 issues an access token. 1454 4.2.1. Authorization Request and Response 1456 Since the client authentication is used as the authorization grant, 1457 no additional authorization request is needed. 1459 4.2.2. Access Token Request 1461 The client makes a request to the token endpoint by adding the 1462 following parameters using the "application/x-www-form-urlencoded" 1463 format per Appendix B with a character encoding of UTF-8 in the HTTP 1464 request entity-body: 1466 "grant_type": REQUIRED. Value MUST be set to "client_credentials". 1468 "scope": OPTIONAL. The scope of the access request as described by 1469 Section 3.3. 1471 The client MUST authenticate with the authorization server as 1472 described in Section 3.2.1. 1474 For example, the client makes the following HTTP request using 1475 transport-layer security (with extra line breaks for display purposes 1476 only): 1478 POST /token HTTP/1.1 1479 Host: server.example.com 1480 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1481 Content-Type: application/x-www-form-urlencoded 1483 grant_type=client_credentials 1485 The authorization server MUST authenticate the client. 1487 4.2.3. Access Token Response 1489 If the access token request is valid and authorized, the 1490 authorization server issues an access token as described in 1491 Section 5.1. A refresh token SHOULD NOT be included. If the request 1492 failed client authentication or is invalid, the authorization server 1493 returns an error response as described in Section 5.2. 1495 An example successful response: 1497 HTTP/1.1 200 OK 1498 Content-Type: application/json 1499 Cache-Control: no-store 1500 Pragma: no-cache 1502 { 1503 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1504 "token_type": "Bearer", 1505 "expires_in": 3600, 1506 "example_parameter": "example_value" 1507 } 1509 4.3. Extension Grants 1511 The client uses an extension grant type by specifying the grant type 1512 using an absolute URI (defined by the authorization server) as the 1513 value of the "grant_type" parameter of the token endpoint, and by 1514 adding any additional parameters necessary. 1516 For example, to request an access token using the Device 1517 Authorization Grant as defined by [RFC8628] after the user has 1518 authorized the client on a separate device, the client makes the 1519 following HTTP request using TLS (with extra line breaks for display 1520 purposes only): 1522 POST /token HTTP/1.1 1523 Host: server.example.com 1524 Content-Type: application/x-www-form-urlencoded 1526 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 1527 &device_code=GmRhmhcxhwEzkoEqiMEg_DnyEysNkuNhszIySk9eS 1528 &client_id=C409020731 1530 If the access token request is valid and authorized, the 1531 authorization server issues an access token and optional refresh 1532 token as described in Section 5.1. If the request failed client 1533 authentication or is invalid, the authorization server returns an 1534 error response as described in Section 5.2. 1536 5. Issuing an Access Token 1538 If the access token request is valid and authorized, the 1539 authorization server issues an access token and optional refresh 1540 token as described in Section 5.1. If the request failed client 1541 authentication or is invalid, the authorization server returns an 1542 error response as described in Section 5.2. 1544 5.1. Successful Response 1546 The authorization server issues an access token and optional refresh 1547 token, and constructs the response by adding the following parameters 1548 to the entity-body of the HTTP response with a 200 (OK) status code: 1550 "access_token": REQUIRED. The access token issued by the 1551 authorization server. 1553 "token_type": REQUIRED. The type of the token issued as described 1554 in Section 7.1. Value is case insensitive. 1556 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1557 token. For example, the value "3600" denotes that the access 1558 token will expire in one hour from the time the response was 1559 generated. If omitted, the authorization server SHOULD provide 1560 the expiration time via other means or document the default value. 1562 "refresh_token": OPTIONAL. The refresh token, which can be used to 1563 obtain new access tokens using the same authorization grant as 1564 described in Section 6. 1566 "scope": OPTIONAL, if identical to the scope requested by the 1567 client; otherwise, REQUIRED. The scope of the access token as 1568 described by Section 3.3. 1570 The parameters are included in the entity-body of the HTTP response 1571 using the "application/json" media type as defined by [RFC7159]. The 1572 parameters are serialized into a JavaScript Object Notation (JSON) 1573 structure by adding each parameter at the highest structure level. 1574 Parameter names and string values are included as JSON strings. 1575 Numerical values are included as JSON numbers. The order of 1576 parameters does not matter and can vary. 1578 The authorization server MUST include the HTTP "Cache-Control" 1579 response header field [RFC7234] with a value of "no-store" in any 1580 response containing tokens, credentials, or other sensitive 1581 information, as well as the "Pragma" response header field [RFC7234] 1582 with a value of "no-cache". 1584 For example: 1586 HTTP/1.1 200 OK 1587 Content-Type: application/json 1588 Cache-Control: no-store 1589 Pragma: no-cache 1591 { 1592 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1593 "token_type":"Bearer", 1594 "expires_in":3600, 1595 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1596 "example_parameter":"example_value" 1597 } 1599 The client MUST ignore unrecognized value names in the response. The 1600 sizes of tokens and other values received from the authorization 1601 server are left undefined. The client should avoid making 1602 assumptions about value sizes. The authorization server SHOULD 1603 document the size of any value it issues. 1605 5.2. Error Response 1607 The authorization server responds with an HTTP 400 (Bad Request) 1608 status code (unless specified otherwise) and includes the following 1609 parameters with the response: 1611 "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 contains a "code_verifier" although no "code_challenge" was 1619 sent in the authorization request, or is otherwise malformed. 1621 "invalid_client": Client authentication failed (e.g., unknown 1622 client, no client authentication included, or unsupported 1623 authentication method). The authorization server MAY return an 1624 HTTP 401 (Unauthorized) status code to indicate which HTTP 1625 authentication schemes are supported. If the client attempted 1626 to authenticate via the "Authorization" request header field, 1627 the authorization server MUST respond with an HTTP 401 1628 (Unauthorized) status code and include the "WWW-Authenticate" 1629 response header field matching the authentication scheme used 1630 by the client. 1632 "invalid_grant": The provided authorization grant (e.g., 1633 authorization code, resource owner credentials) or refresh 1634 token is invalid, expired, revoked, does not match the redirect 1635 URI used in the authorization request, or was issued to another 1636 client. 1638 "unauthorized_client": The authenticated client is not authorized 1639 to use this authorization grant type. 1641 "unsupported_grant_type": The authorization grant type is not 1642 supported by the authorization server. 1644 "invalid_scope": The requested scope is invalid, unknown, 1645 malformed, or exceeds the scope granted by the resource owner. 1647 Values for the "error" parameter MUST NOT include characters 1648 outside the set %x20-21 / %x23-5B / %x5D-7E. 1650 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1651 providing additional information, used to assist the client 1652 developer in understanding the error that occurred. Values for 1653 the "error_description" parameter MUST NOT include characters 1654 outside the set %x20-21 / %x23-5B / %x5D-7E. 1656 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1657 with information about the error, used to provide the client 1658 developer with additional information about the error. Values for 1659 the "error_uri" parameter MUST conform to the URI-reference syntax 1660 and thus MUST NOT include characters outside the set %x21 / 1661 %x23-5B / %x5D-7E. 1663 The parameters are included in the entity-body of the HTTP response 1664 using the "application/json" media type as defined by [RFC7159]. The 1665 parameters are serialized into a JSON structure by adding each 1666 parameter at the highest structure level. Parameter names and string 1667 values are included as JSON strings. Numerical values are included 1668 as JSON numbers. The order of parameters does not matter and can 1669 vary. 1671 For example: 1673 HTTP/1.1 400 Bad Request 1674 Content-Type: application/json 1675 Cache-Control: no-store 1676 Pragma: no-cache 1678 { 1679 "error":"invalid_request" 1680 } 1682 6. Refreshing an Access Token 1684 Authorization servers SHOULD determine, based on a risk assessment, 1685 whether to issue refresh tokens to a certain client. If the 1686 authorization server decides not to issue refresh tokens, the client 1687 MAY refresh access tokens by utilizing other grant types, such as the 1688 authorization code grant type. In such a case, the authorization 1689 server may utilize cookies and persistent grants to optimize the user 1690 experience. 1692 If refresh tokens are issued, those refresh tokens MUST be bound to 1693 the scope and resource servers as consented by the resource owner. 1694 This is to prevent privilege escalation by the legitimate client and 1695 reduce the impact of refresh token leakage. 1697 If the authorization server issued a refresh token to the client, the 1698 client makes a refresh request to the token endpoint by adding the 1699 following parameters using the "application/x-www-form-urlencoded" 1700 format per Appendix B with a character encoding of UTF-8 in the HTTP 1701 request entity-body: 1703 "grant_type": REQUIRED. Value MUST be set to "refresh_token". 1705 "refresh_token": REQUIRED. The refresh token issued to the client. 1707 "scope": OPTIONAL. The scope of the access request as described by 1708 Section 3.3. The requested scope MUST NOT include any scope not 1709 originally granted by the resource owner, and if omitted is 1710 treated as equal to the scope originally granted by the resource 1711 owner. 1713 Because refresh tokens are typically long-lasting credentials used to 1714 request additional access tokens, the refresh token is bound to the 1715 client to which it was issued. Confidential or credentialed clients 1716 MUST authenticate with the authorization server as described in 1717 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 or credentialed 1733 clients 1735 * authenticate the client if client authentication is included and 1736 ensure that the refresh token was issued to the authenticated 1737 client, and 1739 * validate the refresh token. 1741 6.1. Refresh Token Protection 1743 Authorization servers SHOULD utilize one of these methods to detect 1744 refresh token replay by malicious actors for public clients: 1746 * _Sender-constrained refresh tokens:_ the authorization server 1747 cryptographically binds the refresh token to a certain client 1748 instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705], 1749 [I-D.ietf-oauth-dpop], or another suitable method. 1751 * _Refresh token rotation:_ the authorization server issues a new 1752 refresh token with every access token refresh response. The 1753 previous refresh token is invalidated but information about the 1754 relationship is retained by the authorization server. If a 1755 refresh token is compromised and subsequently used by both the 1756 attacker and the legitimate client, one of them will present an 1757 invalidated refresh token, which will inform the authorization 1758 server of the breach. The authorization server cannot determine 1759 which party submitted the invalid refresh token, but it will 1760 revoke the active refresh token. This stops the attack at the 1761 cost of forcing the legitimate client to obtain a fresh 1762 authorization grant. 1764 Implementation note: the grant to which a refresh token belongs may 1765 be encoded into the refresh token itself. This can enable an 1766 authorization server to efficiently determine the grant to which a 1767 refresh token belongs, and by extension, all refresh tokens that need 1768 to be revoked. Authorization servers MUST ensure the integrity of 1769 the refresh token value in this case, for example, using signatures. 1771 If valid and authorized, the authorization server issues an access 1772 token as described in Section 5.1. If the request failed 1773 verification or is invalid, the authorization server returns an error 1774 response as described in Section 5.2. 1776 The authorization server MAY issue a new refresh token, in which case 1777 the client MUST discard the old refresh token and replace it with the 1778 new refresh token. The authorization server MAY revoke the old 1779 refresh token after issuing a new refresh token to the client. If a 1780 new refresh token is issued, the refresh token scope MUST be 1781 identical to that of the refresh token included by the client in the 1782 request. 1784 Authorization servers MAY revoke refresh tokens automatically in case 1785 of a security event, such as: 1787 * password change 1789 * logout at the authorization server 1791 Refresh tokens SHOULD expire if the client has been inactive for some 1792 time, i.e., the refresh token has not been used to obtain fresh 1793 access tokens for some time. The expiration time is at the 1794 discretion of the authorization server. It might be a global value 1795 or determined based on the client policy or the grant associated with 1796 the refresh token (and its sensitivity). 1798 7. Accessing Protected Resources 1800 The client accesses protected resources by presenting the access 1801 token to the resource server. The resource server MUST validate the 1802 access token and ensure that it has not expired and that its scope 1803 covers the requested resource. The methods used by the resource 1804 server to validate the access token (as well as any error responses) 1805 are beyond the scope of this specification, but generally involve an 1806 interaction or coordination between the resource server and the 1807 authorization server, such as using Token Introspection [RFC7662] or 1808 a structured access token format such as a JWT 1809 [I-D.ietf-oauth-access-token-jwt]. 1811 The method in which the client utilizes the access token to 1812 authenticate with the resource server depends on the type of access 1813 token issued by the authorization server. Typically, it involves 1814 using the HTTP "Authorization" request header field [RFC2617] with an 1815 authentication scheme defined by the specification of the access 1816 token type used, such as "Bearer", defined below. 1818 7.1. Access Token Types 1820 The access token type provides the client with the information 1821 required to successfully utilize the access token to make a protected 1822 resource request (along with type-specific attributes). The client 1823 MUST NOT use an access token if it does not understand the token 1824 type. 1826 For example, the "Bearer" token type defined in this specification is 1827 utilized by simply including the access token string in the request: 1829 GET /resource/1 HTTP/1.1 1830 Host: example.com 1831 Authorization: Bearer mF_9.B5f-4.1JqM 1833 The above example is provided for illustration purposes only. 1835 Each access token type definition specifies the additional attributes 1836 (if any) sent to the client together with the "access_token" response 1837 parameter. It also defines the HTTP authentication method used to 1838 include the access token when making a protected resource request. 1840 7.2. Bearer Tokens 1842 A Bearer Token is a security token with the property that any party 1843 in possession of the token (a "bearer") can use the token in any way 1844 that any other party in possession of it can. Using a bearer token 1845 does not require a bearer to prove possession of cryptographic key 1846 material (proof-of-possession). 1848 Bearer tokens may be extended to include proof-of-possession 1849 techniques by other specifications. 1851 7.2.1. Authenticated Requests 1853 This section defines two methods of sending Bearer tokens in resource 1854 requests to resource servers. Clients MUST NOT use more than one 1855 method to transmit the token in each request. 1857 7.2.1.1. Authorization Request Header Field 1859 When sending the access token in the "Authorization" request header 1860 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 1861 authentication scheme to transmit the access token. 1863 For example: 1865 GET /resource HTTP/1.1 1866 Host: server.example.com 1867 Authorization: Bearer mF_9.B5f-4.1JqM 1869 The syntax of the "Authorization" header field for this scheme 1870 follows the usage of the Basic scheme defined in Section 2 of 1871 [RFC2617]. Note that, as with Basic, it does not conform to the 1872 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1873 with the general authentication framework in HTTP 1.1 Authentication 1874 [RFC7235], although it does not follow the preferred practice 1875 outlined therein in order to reflect existing deployments. The 1876 syntax for Bearer credentials is as follows: 1878 b64token = 1*( ALPHA / DIGIT / 1879 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1880 credentials = "Bearer" 1*SP b64token 1882 Clients SHOULD make authenticated requests with a bearer token using 1883 the "Authorization" request header field with the "Bearer" HTTP 1884 authorization scheme. Resource servers MUST support this method. 1886 7.2.1.2. Form-Encoded Body Parameter 1888 When sending the access token in the HTTP request entity-body, the 1889 client adds the access token to the request-body using the 1890 "access_token" parameter. The client MUST NOT use this method unless 1891 all of the following conditions are met: 1893 * The HTTP request entity-header includes the "Content-Type" header 1894 field set to "application/x-www-form-urlencoded". 1896 * The entity-body follows the encoding requirements of the 1897 "application/x-www-form-urlencoded" content-type as defined by 1898 HTML 4.01 [W3C.REC-html401-19991224]. 1900 * The HTTP request entity-body is single-part. 1902 * The content to be encoded in the entity-body MUST consist entirely 1903 of ASCII [USASCII] characters. 1905 * The HTTP request method is one for which the request-body has 1906 defined semantics. In particular, this means that the "GET" 1907 method MUST NOT be used. 1909 The entity-body MAY include other request-specific parameters, in 1910 which case the "access_token" parameter MUST be properly separated 1911 from the request-specific parameters using "&" character(s) (ASCII 1912 code 38). 1914 For example, the client makes the following HTTP request using 1915 transport-layer security: 1917 POST /resource HTTP/1.1 1918 Host: server.example.com 1919 Content-Type: application/x-www-form-urlencoded 1921 access_token=mF_9.B5f-4.1JqM 1923 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1924 except in application contexts where participating clients do not 1925 have access to the "Authorization" request header field. Resource 1926 servers MAY support this method. 1928 7.2.2. The WWW-Authenticate Response Header Field 1930 If the protected resource request does not include authentication 1931 credentials or does not contain an access token that enables access 1932 to the protected resource, the resource server MUST include the HTTP 1933 "WWW-Authenticate" response header field; it MAY include it in 1934 response to other conditions as well. The "WWW-Authenticate" header 1935 field uses the framework defined by HTTP/1.1 [RFC2617]. 1937 All challenges defined by this specification MUST use the auth-scheme 1938 value "Bearer". This scheme MUST be followed by one or more auth- 1939 param values. The auth-param attributes used or defined by this 1940 specification are as follows. Other auth-param attributes MAY be 1941 used as well. 1943 A "realm" attribute MAY be included to indicate the scope of 1944 protection in the manner described in HTTP/1.1 [RFC2617]. The 1945 "realm" attribute MUST NOT appear more than once. 1947 The "scope" attribute is defined in Section 3.3. The "scope" 1948 attribute is a space-delimited list of case-sensitive scope values 1949 indicating the required scope of the access token for accessing the 1950 requested resource. "scope" values are implementation defined; there 1951 is no centralized registry for them; allowed values are defined by 1952 the authorization server. The order of "scope" values is not 1953 significant. In some cases, the "scope" value will be used when 1954 requesting a new access token with sufficient scope of access to 1955 utilize the protected resource. Use of the "scope" attribute is 1956 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 1957 "scope" value is intended for programmatic use and is not meant to be 1958 displayed to end-users. 1960 Two example scope values follow; these are taken from the OpenID 1961 Connect [OpenID.Messages] and the Open Authentication Technology 1962 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 1963 OAuth 2.0 use cases, respectively: 1965 scope="openid profile email" 1966 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 1968 If the protected resource request included an access token and failed 1969 authentication, the resource server SHOULD include the "error" 1970 attribute to provide the client with the reason why the access 1971 request was declined. The parameter value is described in 1972 Section 7.2.3. In addition, the resource server MAY include the 1973 "error_description" attribute to provide developers a human-readable 1974 explanation that is not meant to be displayed to end-users. It also 1975 MAY include the "error_uri" attribute with an absolute URI 1976 identifying a human-readable web page explaining the error. The 1977 "error", "error_description", and "error_uri" attributes MUST NOT 1978 appear more than once. 1980 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 1981 include characters outside the set %x21 / %x23-5B / %x5D-7E for 1982 representing scope values and %x20 for delimiters between scope 1983 values. Values for the "error" and "error_description" attributes 1984 (specified in Appendixes A.7 and A.8) MUST NOT include characters 1985 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 1986 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 1987 the URI-reference syntax and thus MUST NOT include characters outside 1988 the set %x21 / %x23-5B / %x5D-7E. 1990 For example, in response to a protected resource request without 1991 authentication: 1993 HTTP/1.1 401 Unauthorized 1994 WWW-Authenticate: Bearer realm="example" 1996 And in response to a protected resource request with an 1997 authentication attempt using an expired access token: 1999 HTTP/1.1 401 Unauthorized 2000 WWW-Authenticate: Bearer realm="example", 2001 error="invalid_token", 2002 error_description="The access token expired" 2004 7.2.3. Error Codes 2006 When a request fails, the resource server responds using the 2007 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2008 includes one of the following error codes in the response: 2010 "invalid_request": The request is missing a required parameter, 2011 includes an unsupported parameter or parameter value, repeats the 2012 same parameter, uses more than one method for including an access 2013 token, or is otherwise malformed. The resource server SHOULD 2014 respond with the HTTP 400 (Bad Request) status code. 2016 "invalid_token": The access token provided is expired, revoked, 2017 malformed, or invalid for other reasons. The resource SHOULD 2018 respond with the HTTP 401 (Unauthorized) status code. The client 2019 MAY request a new access token and retry the protected resource 2020 request. 2022 "insufficient_scope": The request requires higher privileges than 2023 provided by the access token. The resource server SHOULD respond 2024 with the HTTP 403 (Forbidden) status code and MAY include the 2025 "scope" attribute with the scope necessary to access the protected 2026 resource. 2028 If the request lacks any authentication information (e.g., the client 2029 was unaware that authentication is necessary or attempted using an 2030 unsupported authentication method), the resource server SHOULD NOT 2031 include an error code or other error information. 2033 For example: 2035 HTTP/1.1 401 Unauthorized 2036 WWW-Authenticate: Bearer realm="example" 2038 7.3. Error Response 2040 If a resource access request fails, the resource server SHOULD inform 2041 the client of the error. The method by which the resource server 2042 does this is determined by the particular token type, such as the 2043 description of Bearer tokens in Section 7.2.3. 2045 7.3.1. Extension Token Types 2047 [RFC6750] establishes a common registry in Section 11.4 2048 (https://tools.ietf.org/html/rfc6749#section-11.4) for error values 2049 to be shared among OAuth token authentication schemes. 2051 New authentication schemes designed primarily for OAuth token 2052 authentication SHOULD define a mechanism for providing an error 2053 status code to the client, in which the error values allowed are 2054 registered in the error registry established by this specification. 2056 Such schemes MAY limit the set of valid error codes to a subset of 2057 the registered values. If the error code is returned using a named 2058 parameter, the parameter name SHOULD be "error". 2060 Other schemes capable of being used for OAuth token authentication, 2061 but not primarily designed for that purpose, MAY bind their error 2062 values to the registry in the same manner. 2064 New authentication schemes MAY choose to also specify the use of the 2065 "error_description" and "error_uri" parameters to return error 2066 information in a manner parallel to their usage in this 2067 specification. 2069 7.4. Access Token Security Considerations 2070 7.4.1. Security Threats 2072 The following list presents several common threats against protocols 2073 utilizing some form of tokens. This list of threats is based on NIST 2074 Special Publication 800-63 [NIST800-63]. 2076 7.4.1.1. Token manufacture/modification 2078 An attacker may generate a bogus token or modify the token contents 2079 (such as the authentication or attribute statements) of an existing 2080 token, causing the resource server to grant inappropriate access to 2081 the client. For example, an attacker may modify the token to extend 2082 the validity period; a malicious client may modify the assertion to 2083 gain access to information that they should not be able to view. 2085 7.4.1.2. Token disclosure 2087 Tokens may contain authentication and attribute statements that 2088 include sensitive information. 2090 7.4.1.3. Token redirect 2092 An attacker uses a token generated for consumption by one resource 2093 server to gain access to a different resource server that mistakenly 2094 believes the token to be for it. 2096 7.4.1.4. Token replay 2098 An attacker attempts to use a token that has already been used with 2099 that resource server in the past. 2101 7.4.2. Threat Mitigation 2103 A large range of threats can be mitigated by protecting the contents 2104 of the token by using a digital signature. Alternatively, a bearer 2105 token can contain a reference to authorization information, rather 2106 than encoding the information directly. Such references MUST be 2107 infeasible for an attacker to guess; using a reference may require an 2108 extra interaction between a server and the token issuer to resolve 2109 the reference to the authorization information. The mechanics of 2110 such an interaction are not defined by this specification. 2112 This document does not specify the encoding or the contents of the 2113 token; hence, detailed recommendations about the means of 2114 guaranteeing token integrity protection are outside the scope of this 2115 document. The token integrity protection MUST be sufficient to 2116 prevent the token from being modified. 2118 To deal with token redirect, it is important for the authorization 2119 server to include the identity of the intended recipients (the 2120 audience), typically a single resource server (or a list of resource 2121 servers), in the token. Restricting the use of the token to a 2122 specific scope is also RECOMMENDED. 2124 The authorization server MUST implement TLS. Which version(s) ought 2125 to be implemented will vary over time and will depend on the 2126 widespread deployment and known security vulnerabilities at the time 2127 of implementation. 2129 To protect against token disclosure, confidentiality protection MUST 2130 be applied using TLS with a ciphersuite that provides confidentiality 2131 and integrity protection. This requires that the communication 2132 interaction between the client and the authorization server, as well 2133 as the interaction between the client and the resource server, 2134 utilize confidentiality and integrity protection. Since TLS is 2135 mandatory to implement and to use with this specification, it is the 2136 preferred approach for preventing token disclosure via the 2137 communication channel. For those cases where the client is prevented 2138 from observing the contents of the token, token encryption MUST be 2139 applied in addition to the usage of TLS protection. As a further 2140 defense against token disclosure, the client MUST validate the TLS 2141 certificate chain when making requests to protected resources, 2142 including checking the Certificate Revocation List (CRL) [RFC5280]. 2144 Cookies are typically transmitted in the clear. Thus, any 2145 information contained in them is at risk of disclosure. Therefore, 2146 Bearer tokens MUST NOT be stored in cookies that can be sent in the 2147 clear, as any information in them is at risk of disclosure. See 2148 "HTTP State Management Mechanism" [RFC6265] for security 2149 considerations about cookies. 2151 In some deployments, including those utilizing load balancers, the 2152 TLS connection to the resource server terminates prior to the actual 2153 server that provides the resource. This could leave the token 2154 unprotected between the front-end server where the TLS connection 2155 terminates and the back-end server that provides the resource. In 2156 such deployments, sufficient measures MUST be employed to ensure 2157 confidentiality of the token between the front-end and back-end 2158 servers; encryption of the token is one such possible measure. 2160 To deal with token capture and replay, the following recommendations 2161 are made: First, the lifetime of the token MUST be limited; one means 2162 of achieving this is by putting a validity time field inside the 2163 protected part of the token. Note that using short-lived (one hour 2164 or less) tokens reduces the impact of them being leaked. Second, 2165 confidentiality protection of the exchanges between the client and 2166 the authorization server and between the client and the resource 2167 server MUST be applied. As a consequence, no eavesdropper along the 2168 communication path is able to observe the token exchange. 2169 Consequently, such an on-path adversary cannot replay the token. 2170 Furthermore, when presenting the token to a resource server, the 2171 client MUST verify the identity of that resource server, as per 2172 Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST 2173 validate the TLS certificate chain when making these requests to 2174 protected resources. Presenting the token to an unauthenticated and 2175 unauthorized resource server or failing to validate the certificate 2176 chain will allow adversaries to steal the token and gain unauthorized 2177 access to protected resources. 2179 7.4.3. Summary of Recommendations 2181 7.4.3.1. Safeguard bearer tokens 2183 Client implementations MUST ensure that bearer tokens are not leaked 2184 to unintended parties, as they will be able to use them to gain 2185 access to protected resources. This is the primary security 2186 consideration when using bearer tokens and underlies all the more 2187 specific recommendations that follow. 2189 7.4.3.2. Validate TLS certificate chains 2191 The client MUST validate the TLS certificate chain when making 2192 requests to protected resources. Failing to do so may enable DNS 2193 hijacking attacks to steal the token and gain unintended access. 2195 7.4.3.3. Always use TLS (https) 2197 Clients MUST always use TLS (https) or equivalent transport security 2198 when making requests with bearer tokens. Failing to do so exposes 2199 the token to numerous attacks that could give attackers unintended 2200 access. 2202 7.4.3.4. Don't store bearer tokens in HTTP cookies 2204 Implementations MUST NOT store bearer tokens within cookies that can 2205 be sent in the clear (which is the default transmission mode for 2206 cookies). Implementations that do store bearer tokens in cookies 2207 MUST take precautions against cross-site request forgery. 2209 7.4.3.5. Issue short-lived bearer tokens 2211 Token servers SHOULD issue short-lived (one hour or less) bearer 2212 tokens, particularly when issuing tokens to clients that run within a 2213 web browser or other environments where information leakage may 2214 occur. Using short-lived bearer tokens can reduce the impact of them 2215 being leaked. 2217 7.4.3.6. Issue scoped bearer tokens 2219 Token servers SHOULD issue bearer tokens that contain an audience 2220 restriction, scoping their use to the intended relying party or set 2221 of relying parties. 2223 7.4.3.7. Don't pass bearer tokens in page URLs 2225 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2226 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2227 message headers or message bodies for which confidentiality measures 2228 are taken. Browsers, web servers, and other software may not 2229 adequately secure URLs in the browser history, web server logs, and 2230 other data structures. If bearer tokens are passed in page URLs, 2231 attackers might be able to steal them from the history data, logs, or 2232 other unsecured locations. 2234 7.4.4. Token Replay Prevention 2236 A sender-constrained access token scopes the applicability of an 2237 access token to a certain sender. This sender is obliged to 2238 demonstrate knowledge of a certain secret as prerequisite for the 2239 acceptance of that token at the recipient (e.g., a resource server). 2241 Authorization and resource servers SHOULD use mechanisms for sender- 2242 constrained access tokens to prevent token replay as described in 2243 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2244 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2246 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2247 terminated at an intermediary, refer to Section 4.11 of 2248 [I-D.ietf-oauth-security-topics] for further security advice. 2250 7.4.5. Access Token Privilege Restriction 2252 The privileges associated with an access token SHOULD be restricted 2253 to the minimum required for the particular application or use case. 2254 This prevents clients from exceeding the privileges authorized by the 2255 resource owner. It also prevents users from exceeding their 2256 privileges authorized by the respective security policy. Privilege 2257 restrictions also help to reduce the impact of access token leakage. 2259 In particular, access tokens SHOULD be restricted to certain resource 2260 servers (audience restriction), preferably to a single resource 2261 server. To put this into effect, the authorization server associates 2262 the access token with certain resource servers and every resource 2263 server is obliged to verify, for every request, whether the access 2264 token sent with that request was meant to be used for that particular 2265 resource server. If not, the resource server MUST refuse to serve 2266 the respective request. Clients and authorization servers MAY 2267 utilize the parameters "scope" or "resource" as specified in this 2268 document and [RFC8707], respectively, to determine the resource 2269 server they want to access. 2271 Additionally, access tokens SHOULD be restricted to certain resources 2272 and actions on resource servers or resources. To put this into 2273 effect, the authorization server associates the access token with the 2274 respective resource and actions and every resource server is obliged 2275 to verify, for every request, whether the access token sent with that 2276 request was meant to be used for that particular action on the 2277 particular resource. If not, the resource server must refuse to 2278 serve the respective request. Clients and authorization servers MAY 2279 utilize the parameter "scope" and "authorization_details" as 2280 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2281 actions. 2283 8. Extensibility 2285 8.1. Defining Access Token Types 2287 Access token types can be defined in one of two ways: registered in 2288 the Access Token Types registry (following the procedures in 2289 Section 11.1 of [RFC6749]), or by using a unique absolute URI as its 2290 name. 2292 Types utilizing a URI name SHOULD be limited to vendor-specific 2293 implementations that are not commonly applicable, and are specific to 2294 the implementation details of the resource server where they are 2295 used. 2297 All other types MUST be registered. Type names MUST conform to the 2298 type-name ABNF. If the type definition includes a new HTTP 2299 authentication scheme, the type name SHOULD be identical to the HTTP 2300 authentication scheme name (as defined by [RFC2617]). The token type 2301 "example" is reserved for use in examples. 2303 type-name = 1*name-char 2304 name-char = "-" / "." / "_" / DIGIT / ALPHA 2306 8.2. Defining New Endpoint Parameters 2308 New request or response parameters for use with the authorization 2309 endpoint or the token endpoint are defined and registered in the 2310 OAuth Parameters registry following the procedure in Section 11.2 of 2311 [RFC6749]. 2313 Parameter names MUST conform to the param-name ABNF, and parameter 2314 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2315 to the syntax of an existing parameter). 2317 param-name = 1*name-char 2318 name-char = "-" / "." / "_" / DIGIT / ALPHA 2320 Unregistered vendor-specific parameter extensions that are not 2321 commonly applicable and that are specific to the implementation 2322 details of the authorization server where they are used SHOULD 2323 utilize a vendor-specific prefix that is not likely to conflict with 2324 other registered values (e.g., begin with 'companyname_'). 2326 8.3. Defining New Authorization Grant Types 2328 New authorization grant types can be defined by assigning them a 2329 unique absolute URI for use with the "grant_type" parameter. If the 2330 extension grant type requires additional token endpoint parameters, 2331 they MUST be registered in the OAuth Parameters registry as described 2332 by Section 11.2 of [RFC6749]. 2334 8.4. Defining New Authorization Endpoint Response Types 2336 New response types for use with the authorization endpoint are 2337 defined and registered in the Authorization Endpoint Response Types 2338 registry following the procedure in Section 11.3 of [RFC6749]. 2339 Response type names MUST conform to the response-type ABNF. 2341 response-type = response-name *( SP response-name ) 2342 response-name = 1*response-char 2343 response-char = "_" / DIGIT / ALPHA 2344 If a response type contains one or more space characters (%x20), it 2345 is compared as a space-delimited list of values in which the order of 2346 values does not matter. Only one order of values can be registered, 2347 which covers all other arrangements of the same set of values. 2349 For example, an extension can define and register the "code 2350 other_token" response type. Once registered, the same combination 2351 cannot be registered as "other_token code", but both values can be 2352 used to denote the same response type. 2354 8.5. Defining Additional Error Codes 2356 In cases where protocol extensions (i.e., access token types, 2357 extension parameters, or extension grant types) require additional 2358 error codes to be used with the authorization code grant error 2359 response (Section 4.1.2.1), the token error response (Section 5.2), 2360 or the resource access error response (Section 7.3), such error codes 2361 MAY be defined. 2363 Extension error codes MUST be registered (following the procedures in 2364 Section 11.4 of [RFC6749]) if the extension they are used in 2365 conjunction with is a registered access token type, a registered 2366 endpoint parameter, or an extension grant type. Error codes used 2367 with unregistered extensions MAY be registered. 2369 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2370 an identifying name when possible. For example, an error identifying 2371 an invalid value set to the extension parameter "example" SHOULD be 2372 named "example_invalid". 2374 error = 1*error-char 2375 error-char = %x20-21 / %x23-5B / %x5D-7E 2377 9. Security Considerations 2379 As a flexible and extensible framework, OAuth's security 2380 considerations depend on many factors. The following sections 2381 provide implementers with security guidelines focused on the three 2382 client profiles described in Section 2.1: web application, browser- 2383 based application, and native application. 2385 A comprehensive OAuth security model and analysis, as well as 2386 background for the protocol design, is provided by [RFC6819] and 2387 [I-D.ietf-oauth-security-topics]. 2389 9.1. Client Authentication 2391 Authorization servers SHOULD use client authentication if possible. 2393 It is RECOMMENDED to use asymmetric (public-key based) methods for 2394 client authentication such as mTLS [RFC8705] or "private_key_jwt" 2395 [OpenID]. When asymmetric methods for client authentication are 2396 used, authorization servers do not need to store sensitive symmetric 2397 keys, making these methods more robust against a number of attacks. 2399 Authorization server MUST only rely on client authentication if the 2400 process of issuance/registration and distribution of the underlying 2401 credentials ensures their confidentiality. 2403 When client authentication is not possible, the authorization server 2404 SHOULD employ other means to validate the client's identity - for 2405 example, by requiring the registration of the client redirect URI or 2406 enlisting the resource owner to confirm identity. A valid redirect 2407 URI is not sufficient to verify the client's identity when asking for 2408 resource owner authorization but can be used to prevent delivering 2409 credentials to a counterfeit client after obtaining resource owner 2410 authorization. 2412 The authorization server must consider the security implications of 2413 interacting with unauthenticated clients and take measures to limit 2414 the potential exposure of other credentials (e.g., refresh tokens) 2415 issued to such clients. 2417 The privileges an authorization server associates with a certain 2418 client identity MUST depend on the assessment of the overall process 2419 for client identification and client credential lifecycle management. 2420 For example, authentication of a dynamically registered client just 2421 ensures the authorization server it is talking to the same client 2422 again. In contrast, if there is a web application whose developer's 2423 identity was verified, who signed a contract and is issued a client 2424 secret that is only used in a secure backend service, the 2425 authorization server might allow this client to access more sensible 2426 services or to use the client credential grant type. 2428 9.1.1. Client Authentication of Native Apps 2430 Secrets that are statically included as part of an app distributed to 2431 multiple users should not be treated as confidential secrets, as one 2432 user may inspect their copy and learn the shared secret. For this 2433 reason, it is NOT RECOMMENDED for authorization servers to require 2434 client authentication of public native apps clients using a shared 2435 secret, as this serves little value beyond client identification 2436 which is already provided by the "client_id" request parameter. 2438 Authorization servers that still require a statically included shared 2439 secret for native app clients MUST treat the client as a public 2440 client (as defined in Section 2.1), and not accept the secret as 2441 proof of the client's identity. Without additional measures, such 2442 clients are subject to client impersonation (see Section 9.3.1). 2444 9.2. Registration of Native App Clients 2446 Except when using a mechanism like Dynamic Client Registration 2447 [RFC7591] to provision per-instance secrets, native apps are 2448 classified as public clients, as defined in Section 2.1; they MUST be 2449 registered with the authorization server as such. Authorization 2450 servers MUST record the client type in the client registration 2451 details in order to identify and process requests accordingly. 2453 Authorization servers MUST require clients to register their complete 2454 redirect URI (including the path component) and reject authorization 2455 requests that specify a redirect URI that doesn't exactly match the 2456 one that was registered; the exception is loopback redirects, where 2457 an exact match is required except for the port URI component. 2459 For private-use URI scheme-based redirects, authorization servers 2460 SHOULD enforce the requirement in Section 10.3.1 that clients use 2461 schemes that are reverse domain name based. At a minimum, any 2462 private-use URI scheme that doesn't contain a period character (".") 2463 SHOULD be rejected. 2465 In addition to the collision-resistant properties, requiring a URI 2466 scheme based on a domain name that is under the control of the app 2467 can help to prove ownership in the event of a dispute where two apps 2468 claim the same private-use URI scheme (where one app is acting 2469 maliciously). For example, if two apps claimed "com.example.app", 2470 the owner of "example.com" could petition the app store operator to 2471 remove the counterfeit app. Such a petition is harder to prove if a 2472 generic URI scheme was used. 2474 Authorization servers MAY request the inclusion of other platform- 2475 specific information, such as the app package or bundle name, or 2476 other information that may be useful for verifying the calling app's 2477 identity on operating systems that support such functions. 2479 9.3. Client Impersonation 2481 A malicious client can impersonate another client and obtain access 2482 to protected resources if the impersonated client fails to, or is 2483 unable to, keep its client credentials confidential. 2485 The authorization server MUST authenticate the client whenever 2486 possible. If the authorization server cannot authenticate the client 2487 due to the client's nature, the authorization server MUST require the 2488 registration of any redirect URI used for receiving authorization 2489 responses and SHOULD utilize other means to protect resource owners 2490 from such potentially malicious clients. For example, the 2491 authorization server can engage the resource owner to assist in 2492 identifying the client and its origin. 2494 The authorization server SHOULD enforce explicit resource owner 2495 authentication and provide the resource owner with information about 2496 the client and the requested authorization scope and lifetime. It is 2497 up to the resource owner to review the information in the context of 2498 the current client and to authorize or deny the request. 2500 The authorization server SHOULD NOT process repeated authorization 2501 requests automatically (without active resource owner interaction) 2502 without authenticating the client or relying on other measures to 2503 ensure that the repeated request comes from the original client and 2504 not an impersonator. 2506 9.3.1. Impersonation of Native Apps 2508 As stated above, the authorization server SHOULD NOT process 2509 authorization requests automatically without user consent or 2510 interaction, except when the identity of the client can be assured. 2511 This includes the case where the user has previously approved an 2512 authorization request for a given client id - unless the identity of 2513 the client can be proven, the request SHOULD be processed as if no 2514 previous request had been approved. 2516 Measures such as claimed "https" scheme redirects MAY be accepted by 2517 authorization servers as identity proof. Some operating systems may 2518 offer alternative platform-specific identity features that MAY be 2519 accepted, as appropriate. 2521 9.4. Access Tokens 2523 Access token credentials (as well as any confidential access token 2524 attributes) MUST be kept confidential in transit and storage, and 2525 only shared among the authorization server, the resource servers the 2526 access token is valid for, and the client to whom the access token is 2527 issued. Access token credentials MUST only be transmitted using TLS 2528 as described in Section 1.6 with server authentication as defined by 2529 [RFC2818]. 2531 The authorization server MUST ensure that access tokens cannot be 2532 generated, modified, or guessed to produce valid access tokens by 2533 unauthorized parties. 2535 9.4.1. Access Token Privilege Restriction 2537 The client SHOULD request access tokens with the minimal scope 2538 necessary. The authorization server SHOULD take the client identity 2539 into account when choosing how to honor the requested scope and MAY 2540 issue an access token with less rights than requested. 2542 The privileges associated with an access token SHOULD be restricted 2543 to the minimum required for the particular application or use case. 2544 This prevents clients from exceeding the privileges authorized by the 2545 resource owner. It also prevents users from exceeding their 2546 privileges authorized by the respective security policy. Privilege 2547 restrictions also help to reduce the impact of access token leakage. 2549 In particular, access tokens SHOULD be restricted to certain resource 2550 servers (audience restriction), preferably to a single resource 2551 server. To put this into effect, the authorization server associates 2552 the access token with certain resource servers and every resource 2553 server is obliged to verify, for every request, whether the access 2554 token sent with that request was meant to be used for that particular 2555 resource server. If not, the resource server MUST refuse to serve 2556 the respective request. Clients and authorization servers MAY 2557 utilize the parameters "scope" or "resource" as specified in 2558 [RFC8707], respectively, to determine the resource server they want 2559 to access. 2561 9.4.2. Access Token Replay Prevention 2563 Additionally, access tokens SHOULD be restricted to certain resources 2564 and actions on resource servers or resources. To put this into 2565 effect, the authorization server associates the access token with the 2566 respective resource and actions and every resource server is obliged 2567 to verify, for every request, whether the access token sent with that 2568 request was meant to be used for that particular action on the 2569 particular resource. If not, the resource server must refuse to 2570 serve the respective request. Clients and authorization servers MAY 2571 utilize the parameter "scope" and "authorization_details" as 2572 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2573 actions. 2575 Authorization and resource servers SHOULD use mechanisms for sender- 2576 constrained access tokens to prevent token replay as described in 2577 (#pop_tokens). A sender-constrained access token scopes the 2578 applicability of an access token to a certain sender. This sender is 2579 obliged to demonstrate knowledge of a certain secret as prerequisite 2580 for the acceptance of that token at the recipient (e.g., a resource 2581 server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2582 RECOMMENDED. 2584 9.5. Refresh Tokens 2586 Authorization servers MAY issue refresh tokens to clients. 2588 Refresh tokens MUST be kept confidential in transit and storage, and 2589 shared only among the authorization server and the client to whom the 2590 refresh tokens were issued. The authorization server MUST maintain 2591 the binding between a refresh token and the client to whom it was 2592 issued. Refresh tokens MUST only be transmitted using TLS as 2593 described in Section 1.6 with server authentication as defined by 2594 [RFC2818]. 2596 The authorization server MUST verify the binding between the refresh 2597 token and client identity whenever the client identity can be 2598 authenticated. When client authentication is not possible, the 2599 authorization server SHOULD issue sender-constrained refresh tokens 2600 or use refresh token rotation as described in 2601 (#refresh_token_protection). 2603 The authorization server MUST ensure that refresh tokens cannot be 2604 generated, modified, or guessed to produce valid refresh tokens by 2605 unauthorized parties. 2607 9.6. Client Impersonating Resource Owner 2609 Resource servers may make access control decisions based on the 2610 identity of the resource owner as communicated in the "sub" claim 2611 returned by the authorization server in a token introspection 2612 response [RFC7662] or other mechanisms. If a client is able to 2613 choose its own "client_id" during registration with the authorization 2614 server, then there is a risk that it can register with the same "sub" 2615 value as a privileged user. A subsequent access token obtained under 2616 the client credentials grant may be mistaken for an access token 2617 authorized by the privileged user if the resource server does not 2618 perform additional checks. 2620 Authorization servers SHOULD NOT allow clients to influence their 2621 "client_id" or "sub" value or any other claim if that can cause 2622 confusion with a genuine resource owner. Where this cannot be 2623 avoided, authorization servers MUST provide other means for the 2624 resource server to distinguish between access tokens authorized by a 2625 resource owner from access tokens authorized by the client itself. 2627 9.7. Protecting Redirect-Based Flows 2629 When comparing client redirect URIs against pre-registered URIs, 2630 authorization servers MUST utilize exact string matching. This 2631 measure contributes to the prevention of leakage of authorization 2632 codes and access tokens (see (#insufficient_uri_validation)). It can 2633 also help to detect mix-up attacks (see (#mix_up)). 2635 Clients MUST NOT expose URLs that forward the user's browser to 2636 arbitrary URIs obtained from a query parameter ("open redirector"). 2637 Open redirectors can enable exfiltration of authorization codes and 2638 access tokens, see (#open_redirector_on_client). 2640 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2641 context, CSRF refers to requests to the redirection endpoint that do 2642 not originate at the authorization server, but a malicious third 2643 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2644 have ensured that the authorization server supports the 2645 "code_challenge" parameter MAY rely the CSRF protection provided by 2646 that mechanism. In OpenID Connect flows, the "nonce" parameter 2647 provides CSRF protection. Otherwise, one-time use CSRF tokens 2648 carried in the "state" parameter that are securely bound to the user 2649 agent MUST be used for CSRF protection (see (#csrf_countermeasures)). 2651 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2652 process redirect responses of the authorization server they sent the 2653 respective request to and from the same user agent this authorization 2654 request was initiated with. Clients MUST store the authorization 2655 server they sent an authorization request to and bind this 2656 information to the user agent and check that the authorization 2657 request was received from the correct authorization server. Clients 2658 MUST ensure that the subsequent token request, if applicable, is sent 2659 to the same authorization server. Clients SHOULD use distinct 2660 redirect URIs for each authorization server as a means to identify 2661 the authorization server a particular response came from. 2663 An AS that redirects a request potentially containing user 2664 credentials MUST avoid forwarding these user credentials accidentally 2665 (see Section 9.7.2 for details). 2667 9.7.1. Loopback Redirect Considerations in Native Apps 2669 Loopback interface redirect URIs use the "http" scheme (i.e., without 2670 Transport Layer Security (TLS)). This is acceptable for loopback 2671 interface redirect URIs as the HTTP request never leaves the device. 2673 Clients should open the network port only when starting the 2674 authorization request and close it once the response is returned. 2676 Clients should listen on the loopback network interface only, in 2677 order to avoid interference by other network actors. 2679 While redirect URIs using localhost (i.e., 2680 "http://localhost:{port}/{path}") function similarly to loopback IP 2681 redirects described in Section 10.3.3, the use of "localhost" is NOT 2682 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2683 rather than "localhost" avoids inadvertently listening on network 2684 interfaces other than the loopback interface. It is also less 2685 susceptible to client-side firewalls and misconfigured host name 2686 resolution on the user's device. 2688 9.7.2. HTTP 307 Redirect 2690 An AS which redirects a request that potentially contains user 2691 credentials MUST NOT use the HTTP 307 status code for redirection. 2692 If an HTTP redirection (and not, for example, JavaScript) is used for 2693 such a request, AS SHOULD use HTTP status code 303 "See Other". 2695 At the authorization endpoint, a typical protocol flow is that the AS 2696 prompts the user to enter her credentials in a form that is then 2697 submitted (using the HTTP POST method) back to the authorization 2698 server. The AS checks the credentials and, if successful, redirects 2699 the user agent to the client's redirect URI. 2701 If the status code 307 were used for redirection, the user agent 2702 would send the user credentials via HTTP POST to the client. 2704 This discloses the sensitive credentials to the client. If the 2705 relying party is malicious, it can use the credentials to impersonate 2706 the user at the AS. 2708 The behavior might be unexpected for developers, but is defined in 2709 [RFC7231], Section 6.4.7. This status code does not require the user 2710 agent to rewrite the POST request to a GET request and thereby drop 2711 the form data in the POST request body. 2713 In the HTTP standard [RFC7231], only the status code 303 2714 unambigiously enforces rewriting the HTTP POST request to an HTTP GET 2715 request. For all other status codes, including the popular 302, user 2716 agents can opt not to rewrite POST to GET requests and therefore to 2717 reveal the user credentials to the client. (In practice, however, 2718 most user agents will only show this behaviour for 307 redirects.) 2720 Therefore, the RECOMMENDED status code for HTTP redirects is 303. 2722 9.8. Authorization Codes 2724 The transmission of authorization codes MUST be made over a secure 2725 channel, and the client MUST require the use of TLS with its redirect 2726 URI if the URI identifies a network resource. Since authorization 2727 codes are transmitted via user-agent redirections, they could 2728 potentially be disclosed through user-agent history and HTTP referrer 2729 headers. 2731 Authorization codes MUST be short lived and single-use. If the 2732 authorization server observes multiple attempts to exchange an 2733 authorization code for an access token, the authorization server 2734 SHOULD attempt to revoke all refresh and access tokens already 2735 granted based on the compromised authorization code. 2737 If the client can be authenticated, the authorization servers MUST 2738 authenticate the client and ensure that the authorization code was 2739 issued to the same client. 2741 Clients MUST prevent injection (replay) of authorization codes into 2742 the authorization response by attackers. To this end, using 2743 "code_challenge" and "code_verifier" is REQUIRED for clients and 2744 authorization servers MUST enforce their use, unless both of the 2745 following criteria are met: 2747 * The client is a confidential or credentialed client. 2749 * In the specific deployment and the specific request, there is 2750 reasonable assurance for authorization server that the client 2751 implements the OpenID Connect "nonce" mechanism properly. 2753 In this case, using and enforcing "code_challenge" and 2754 "code_verifier" is still RECOMMENDED. 2756 The "code_challenge" or OpenID Connect "nonce" value MUST be 2757 transaction-specific and securely bound to the client and the user 2758 agent in which the transaction was started. If a transaction leads 2759 to an error, fresh values for "code_challenge" or "nonce" MUST be 2760 chosen. 2762 Historic note: Although PKCE [RFC7636] was originally designed as a 2763 mechanism to protect native apps, this advice applies to all kinds of 2764 OAuth clients, including web applications and other confidential 2765 clients. 2767 Clients SHOULD use code challenge methods that do not expose the 2768 "code_verifier" in the authorization request. Otherwise, attackers 2769 that can read the authorization request (cf. Attacker A4 in 2770 (#secmodel)) can break the security provided by this mechanism. 2771 Currently, "S256" is the only such method. 2773 When an authorization code arrives at the token endpoint, the 2774 authorization server MUST do the following check: 2776 1. If there was a "code_challenge" in the authorization request for 2777 which this code was issued, there must be a "code_verifier" in 2778 the token request, and it MUST be verified according to the steps 2779 in Section 4.1.3. (This is no change from the current behavior 2780 in [RFC7636].) 2782 2. If there was no "code_challenge" in the authorization request, 2783 any request to the token endpoint containing a "code_verifier" 2784 MUST be rejected. 2786 Authorization servers MUST support the "code_challenge" and 2787 "code_verifier" parameters. 2789 Authorization servers MUST provide a way to detect their support for 2790 the "code_challenge" mechanism. To this end, they MUST either (a) 2791 publish the element "code_challenge_methods_supported" in their AS 2792 metadata ([RFC8414]) containing the supported 2793 "code_challenge_method"s (which can be used by the client to detect 2794 support) or (b) provide a deployment-specific way to ensure or 2795 determine support by the AS. 2797 9.9. Request Confidentiality 2799 Access tokens, refresh tokens, authorization codes, and client 2800 credentials MUST NOT be transmitted in the clear. 2802 The "state" and "scope" parameters SHOULD NOT include sensitive 2803 client or resource owner information in plain text, as they can be 2804 transmitted over insecure channels or stored insecurely. 2806 9.10. Ensuring Endpoint Authenticity 2808 In order to prevent man-in-the-middle attacks, the authorization 2809 server MUST require the use of TLS with server authentication as 2810 defined by [RFC2818] for any request sent to the authorization and 2811 token endpoints. The client MUST validate the authorization server's 2812 TLS certificate as defined by [RFC6125] and in accordance with its 2813 requirements for server identity authentication. 2815 9.11. Credentials-Guessing Attacks 2817 The authorization server MUST prevent attackers from guessing access 2818 tokens, authorization codes, refresh tokens, resource owner 2819 passwords, and client credentials. 2821 The probability of an attacker guessing generated tokens (and other 2822 credentials not intended for handling by end-users) MUST be less than 2823 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2825 The authorization server MUST utilize other means to protect 2826 credentials intended for end-user usage. 2828 9.12. Phishing Attacks 2830 Wide deployment of this and similar protocols may cause end-users to 2831 become inured to the practice of being redirected to websites where 2832 they are asked to enter their passwords. If end-users are not 2833 careful to verify the authenticity of these websites before entering 2834 their credentials, it will be possible for attackers to exploit this 2835 practice to steal resource owners' passwords. 2837 Service providers should attempt to educate end-users about the risks 2838 phishing attacks pose and should provide mechanisms that make it easy 2839 for end-users to confirm the authenticity of their sites. Client 2840 developers should consider the security implications of how they 2841 interact with the user-agent (e.g., external, embedded), and the 2842 ability of the end-user to verify the authenticity of the 2843 authorization server. 2845 To reduce the risk of phishing attacks, the authorization servers 2846 MUST require the use of TLS on every endpoint used for end-user 2847 interaction. 2849 9.13. Fake External User-Agents in Native Apps 2851 The native app that is initiating the authorization request has a 2852 large degree of control over the user interface and can potentially 2853 present a fake external user-agent, that is, an embedded user-agent 2854 made to appear as an external user-agent. 2856 When all good actors are using external user-agents, the advantage is 2857 that it is possible for security experts to detect bad actors, as 2858 anyone faking an external user-agent is provably bad. On the other 2859 hand, if good and bad actors alike are using embedded user-agents, 2860 bad actors don't need to fake anything, making them harder to detect. 2861 Once a malicious app is detected, it may be possible to use this 2862 knowledge to blacklist the app's signature in malware scanning 2863 software, take removal action (in the case of apps distributed by app 2864 stores) and other steps to reduce the impact and spread of the 2865 malicious app. 2867 Authorization servers can also directly protect against fake external 2868 user-agents by requiring an authentication factor only available to 2869 true external user-agents. 2871 Users who are particularly concerned about their security when using 2872 in-app browser tabs may also take the additional step of opening the 2873 request in the full browser from the in-app browser tab and complete 2874 the authorization there, as most implementations of the in-app 2875 browser tab pattern offer such functionality. 2877 9.14. Malicious External User-Agents in Native Apps 2879 If a malicious app is able to configure itself as the default handler 2880 for "https" scheme URIs in the operating system, it will be able to 2881 intercept authorization requests that use the default browser and 2882 abuse this position of trust for malicious ends such as phishing the 2883 user. 2885 This attack is not confined to OAuth; a malicious app configured in 2886 this way would present a general and ongoing risk to the user beyond 2887 OAuth usage by native apps. Many operating systems mitigate this 2888 issue by requiring an explicit user action to change the default 2889 handler for "http" and "https" scheme URIs. 2891 9.15. Cross-Site Request Forgery 2893 An attacker might attempt to inject a request to the redirect URI of 2894 the legitimate client on the victim's device, e.g., to cause the 2895 client to access resources under the attacker's control. This is a 2896 variant of an attack known as Cross-Site Request Forgery (CSRF). 2898 The traditional countermeasure are CSRF tokens that are bound to the 2899 user agent and passed in the "state" parameter to the authorization 2900 server as described in [RFC6819]. The same protection is provided by 2901 the "code_verifier" parameter or the OpenID Connect "nonce" value. 2903 When using "code_verifier" instead of "state" or "nonce" for CSRF 2904 protection, it is important to note that: 2906 * Clients MUST ensure that the AS supports the 2907 "code_challenge_method" intended to be used by the client. If an 2908 authorization server does not support the requested method, 2909 "state" or "nonce" MUST be used for CSRF protection instead. 2911 * If "state" is used for carrying application state, and integrity 2912 of its contents is a concern, clients MUST protect "state" against 2913 tampering and swapping. This can be achieved by binding the 2914 contents of state to the browser session and/or signed/encrypted 2915 state values [I-D.bradley-oauth-jwt-encoded-state]. 2917 AS therefore MUST provide a way to detect their supported code 2918 challenge methods either via AS metadata according to [RFC8414] or 2919 provide a deployment-specific way to ensure or determine support. 2921 9.16. Clickjacking 2923 As described in Section 4.4.1.9 of [RFC6819], the authorization 2924 request is susceptible to clickjacking. An attacker can use this 2925 vector to obtain the user's authentication credentials, change the 2926 scope of access granted to the client, and potentially access the 2927 user's resources. 2929 Authorization servers MUST prevent clickjacking attacks. Multiple 2930 countermeasures are described in [RFC6819], including the use of the 2931 X-Frame-Options HTTP response header field and frame-busting 2932 JavaScript. In addition to those, authorization servers SHOULD also 2933 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2935 To be effective, CSP must be used on the authorization endpoint and, 2936 if applicable, other endpoints used to authenticate the user and 2937 authorize the client (e.g., the device authorization endpoint, login 2938 pages, error pages, etc.). This prevents framing by unauthorized 2939 origins in user agents that support CSP. The client MAY permit being 2940 framed by some other origin than the one used in its redirection 2941 endpoint. For this reason, authorization servers SHOULD allow 2942 administrators to configure allowed origins for particular clients 2943 and/or for clients to register these dynamically. 2945 Using CSP allows authorization servers to specify multiple origins in 2946 a single response header field and to constrain these using flexible 2947 patterns (see [CSP-2] for details). Level 2 of this standard 2948 provides a robust mechanism for protecting against clickjacking by 2949 using policies that restrict the origin of frames (using "frame- 2950 ancestors") together with those that restrict the sources of scripts 2951 allowed to execute on an HTML page (by using "script-src"). A non- 2952 normative example of such a policy is shown in the following listing: 2954 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 2955 https://ext.example.org:8000 Content-Security-Policy: script-src 2956 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 2957 Because some user agents do not support [CSP-2], this technique 2958 SHOULD be combined with others, including those described in 2959 [RFC6819], unless such legacy user agents are explicitly unsupported 2960 by the authorization server. Even in such cases, additional 2961 countermeasures SHOULD still be employed. 2963 9.17. Code Injection and Input Validation 2965 A code injection attack occurs when an input or otherwise external 2966 variable is used by an application unsanitized and causes 2967 modification to the application logic. This may allow an attacker to 2968 gain access to the application device or its data, cause denial of 2969 service, or introduce a wide range of malicious side-effects. 2971 The authorization server and client MUST sanitize (and validate when 2972 possible) any value received - in particular, the value of the 2973 "state" and "redirect_uri" parameters. 2975 9.18. Open Redirectors 2977 The following attacks can occur when an AS or client has an open 2978 redirector. An open redirector is an endpoint that forwards a user's 2979 browser to an arbitrary URI obtained from a query parameter. 2981 9.18.1. Client as Open Redirector 2983 Clients MUST NOT expose open redirectors. Attackers may use open 2984 redirectors to produce URLs pointing to the client and utilize them 2985 to exfiltrate authorization codes and access tokens, as described in 2986 (#redir_uri_open_redir). Another abuse case is to produce URLs that 2987 appear to point to the client. This might trick users into trusting 2988 the URL and follow it in their browser. This can be abused for 2989 phishing. 2991 In order to prevent open redirection, clients should only redirect if 2992 the target URLs are whitelisted or if the origin and integrity of a 2993 request can be authenticated. Countermeasures against open 2994 redirection are described by OWASP [owasp_redir]. 2996 9.18.2. Authorization Server as Open Redirector 2998 Just as with clients, attackers could try to utilize a user's trust 2999 in the authorization server (and its URL in particular) for 3000 performing phishing attacks. OAuth authorization servers regularly 3001 redirect users to other web sites (the clients), but must do so in a 3002 safe way. 3004 Section 4.1.2.1 already prevents open redirects by stating that the 3005 AS MUST NOT automatically redirect the user agent in case of an 3006 invalid combination of "client_id" and "redirect_uri". 3008 However, an attacker could also utilize a correctly registered 3009 redirect URI to perform phishing attacks. The attacker could, for 3010 example, register a client via dynamic client registration [RFC7591] 3011 and intentionally send an erroneous authorization request, e.g., by 3012 using an invalid scope value, thus instructing the AS to redirect the 3013 user agent to its phishing site. 3015 The AS MUST take precautions to prevent this threat. Based on its 3016 risk assessment, the AS needs to decide whether it can trust the 3017 redirect URI and SHOULD only automatically redirect the user agent if 3018 it trusts the redirect URI. If the URI is not trusted, the AS MAY 3019 inform the user and rely on the user to make the correct decision. 3021 9.19. Authorization Server Mix-Up Mitigation in Native Apps 3023 (TODO: merge this with the regular mix-up section when it is brought 3024 in) 3026 To protect against a compromised or malicious authorization server 3027 attacking another authorization server used by the same app, it is 3028 REQUIRED that a unique redirect URI is used for each authorization 3029 server used by the app (for example, by varying the path component), 3030 and that authorization responses are rejected if the redirect URI 3031 they were received on doesn't match the redirect URI in an outgoing 3032 authorization request. 3034 The native app MUST store the redirect URI used in the authorization 3035 request with the authorization session data (i.e., along with "state" 3036 and other related data) and MUST verify that the URI on which the 3037 authorization response was received exactly matches it. 3039 The requirement of Section 9.2, specifically that authorization 3040 servers reject requests with URIs that don't match what was 3041 registered, is also required to prevent such attacks. 3043 9.20. Embedded User Agents in Native Apps 3045 Embedded user-agents are a technically possible method for 3046 authorizing native apps. These embedded user-agents are unsafe for 3047 use by third parties to the authorization server by definition, as 3048 the app that hosts the embedded user-agent can access the user's full 3049 authentication credential, not just the OAuth authorization grant 3050 that was intended for the app. 3052 In typical web-view-based implementations of embedded user-agents, 3053 the host application can record every keystroke entered in the login 3054 form to capture usernames and passwords, automatically submit forms 3055 to bypass user consent, and copy session cookies and use them to 3056 perform authenticated actions as the user. 3058 Even when used by trusted apps belonging to the same party as the 3059 authorization server, embedded user-agents violate the principle of 3060 least privilege by having access to more powerful credentials than 3061 they need, potentially increasing the attack surface. 3063 Encouraging users to enter credentials in an embedded user-agent 3064 without the usual address bar and visible certificate validation 3065 features that browsers have makes it impossible for the user to know 3066 if they are signing in to the legitimate site; even when they are, it 3067 trains them that it's OK to enter credentials without validating the 3068 site first. 3070 Aside from the security concerns, embedded user-agents do not share 3071 the authentication state with other apps or the browser, requiring 3072 the user to log in for every authorization request, which is often 3073 considered an inferior user experience. 3075 9.21. Other Recommendations 3077 Authorization servers SHOULD NOT allow clients to influence their 3078 "client_id" or "sub" value or any other claim if that can cause 3079 confusion with a genuine resource owner (see 3080 (#client_impersonating)). 3082 10. Native Applications 3084 Native applications are clients installed and executed on the device 3085 used by the resource owner (i.e., desktop application, native mobile 3086 application). Native applications require special consideration 3087 related to security, platform capabilities, and overall end-user 3088 experience. 3090 The authorization endpoint requires interaction between the client 3091 and the resource owner's user-agent. The best current practice is to 3092 perform the OAuth authorization request in an external user-agent 3093 (typically the browser) rather than an embedded user-agent (such as 3094 one implemented with web-views). 3096 The native application can capture the response from the 3097 authorization server using a redirect URI with a scheme registered 3098 with the operating system to invoke the client as the handler, manual 3099 copy-and-paste of the credentials, running a local web server, 3100 installing a user-agent extension, or by providing a redirect URI 3101 identifying a server-hosted resource under the client's control, 3102 which in turn makes the response available to the native application. 3104 Previously, it was common for native apps to use embedded user-agents 3105 (commonly implemented with web-views) for OAuth authorization 3106 requests. That approach has many drawbacks, including the host app 3107 being able to copy user credentials and cookies as well as the user 3108 needing to authenticate from scratch in each app. See Section 9.20 3109 for a deeper analysis of the drawbacks of using embedded user-agents 3110 for OAuth. 3112 Native app authorization requests that use the browser are more 3113 secure and can take advantage of the user's authentication state. 3114 Being able to use the existing authentication session in the browser 3115 enables single sign-on, as users don't need to authenticate to the 3116 authorization server each time they use a new app (unless required by 3117 the authorization server policy). 3119 Supporting authorization flows between a native app and the browser 3120 is possible without changing the OAuth protocol itself, as the OAuth 3121 authorization request and response are already defined in terms of 3122 URIs. This encompasses URIs that can be used for inter-app 3123 communication. Some OAuth server implementations that assume all 3124 clients are confidential web clients will need to add an 3125 understanding of public native app clients and the types of redirect 3126 URIs they use to support this best practice. 3128 10.1. Using Inter-App URI Communication for OAuth in Native Apps 3130 Just as URIs are used for OAuth on the web to initiate the 3131 authorization request and return the authorization response to the 3132 requesting website, URIs can be used by native apps to initiate the 3133 authorization request in the device's browser and return the response 3134 to the requesting native app. 3136 By adopting the same methods used on the web for OAuth, benefits seen 3137 in the web context like the usability of a single sign-on session and 3138 the security of a separate authentication context are likewise gained 3139 in the native app context. Reusing the same approach also reduces 3140 the implementation complexity and increases interoperability by 3141 relying on standards-based web flows that are not specific to a 3142 particular platform. 3144 Native apps MUST use an external user-agent to perform OAuth 3145 authorization requests. This is achieved by opening the 3146 authorization request in the browser (detailed in Section 10.2) and 3147 using a redirect URI that will return the authorization response back 3148 to the native app (defined in Section 10.3). 3150 10.2. Initiating the Authorization Request from a Native App 3152 Native apps needing user authorization create an authorization 3153 request URI with the authorization code grant type per Section 4.1 3154 using a redirect URI capable of being received by the native app. 3156 The function of the redirect URI for a native app authorization 3157 request is similar to that of a web-based authorization request. 3158 Rather than returning the authorization response to the OAuth 3159 client's server, the redirect URI used by a native app returns the 3160 response to the app. Several options for a redirect URI that will 3161 return the authorization response to the native app in different 3162 platforms are documented in Section 10.3. Any redirect URI that 3163 allows the app to receive the URI and inspect its parameters is 3164 viable. 3166 After constructing the authorization request URI, the app uses 3167 platform-specific APIs to open the URI in an external user-agent. 3168 Typically, the external user-agent used is the default browser, that 3169 is, the application configured for handling "http" and "https" scheme 3170 URIs on the system; however, different browser selection criteria and 3171 other categories of external user-agents MAY be used. 3173 This best practice focuses on the browser as the RECOMMENDED external 3174 user-agent for native apps. An external user-agent designed 3175 specifically for user authorization and capable of processing 3176 authorization requests and responses like a browser MAY also be used. 3177 Other external user-agents, such as a native app provided by the 3178 authorization server may meet the criteria set out in this best 3179 practice, including using the same redirect URI properties, but their 3180 use is out of scope for this specification. 3182 Some platforms support a browser feature known as "in-app browser 3183 tabs", where an app can present a tab of the browser within the app 3184 context without switching apps, but still retain key benefits of the 3185 browser such as a shared authentication state and security context. 3186 On platforms where they are supported, it is RECOMMENDED, for 3187 usability reasons, that apps use in-app browser tabs for the 3188 authorization request. 3190 10.3. Receiving the Authorization Response in a Native App 3192 There are several redirect URI options available to native apps for 3193 receiving the authorization response from the browser, the 3194 availability and user experience of which varies by platform. 3196 To fully support native apps, authorization servers MUST offer at 3197 least the three redirect URI options described in the following 3198 subsections to native apps. Native apps MAY use whichever redirect 3199 option suits their needs best, taking into account platform-specific 3200 implementation details. 3202 10.3.1. Private-Use URI Scheme Redirection 3204 Many mobile and desktop computing platforms support inter-app 3205 communication via URIs by allowing apps to register private-use URI 3206 schemes (sometimes colloquially referred to as "custom URL schemes") 3207 like "com.example.app". When the browser or another app attempts to 3208 load a URI with a private-use URI scheme, the app that registered it 3209 is launched to handle the request. 3211 To perform an authorization request with a private-use URI scheme 3212 redirect, the native app launches the browser with a standard 3213 authorization request, but one where the redirect URI utilizes a 3214 private-use URI scheme it registered with the operating system. 3216 When choosing a URI scheme to associate with the app, apps MUST use a 3217 URI scheme based on a domain name under their control, expressed in 3218 reverse order, as recommended by Section 3.8 of [RFC7595] for 3219 private-use URI schemes. 3221 For example, an app that controls the domain name "app.example.com" 3222 can use "com.example.app" as their scheme. Some authorization 3223 servers assign client identifiers based on domain names, for example, 3224 "client1234.usercontent.example.net", which can also be used as the 3225 domain name for the scheme when reversed in the same manner. A 3226 scheme such as "myapp", however, would not meet this requirement, as 3227 it is not based on a domain name. 3229 When there are multiple apps by the same publisher, care must be 3230 taken so that each scheme is unique within that group. On platforms 3231 that use app identifiers based on reverse-order domain names, those 3232 identifiers can be reused as the private-use URI scheme for the OAuth 3233 redirect to help avoid this problem. 3235 Following the requirements of Section 3.2 of [RFC3986], as there is 3236 no naming authority for private-use URI scheme redirects, only a 3237 single slash ("/") appears after the scheme component. A complete 3238 example of a redirect URI utilizing a private-use URI scheme is: 3240 com.example.app:/oauth2redirect/example-provider 3242 When the authorization server completes the request, it redirects to 3243 the client's redirect URI as it would normally. As the redirect URI 3244 uses a private-use URI scheme, it results in the operating system 3245 launching the native app, passing in the URI as a launch parameter. 3246 Then, the native app uses normal processing for the authorization 3247 response. 3249 10.3.2. Claimed "https" Scheme URI Redirection 3251 Some operating systems allow apps to claim "https" scheme [RFC7230] 3252 URIs in the domains they control. When the browser encounters a 3253 claimed URI, instead of the page being loaded in the browser, the 3254 native app is launched with the URI supplied as a launch parameter. 3256 Such URIs can be used as redirect URIs by native apps. They are 3257 indistinguishable to the authorization server from a regular web- 3258 based client redirect URI. An example is: 3260 https://app.example.com/oauth2redirect/example-provider 3262 As the redirect URI alone is not enough to distinguish public native 3263 app clients from confidential web clients, it is REQUIRED in 3264 Section 9.2 that the client type be recorded during client 3265 registration to enable the server to determine the client type and 3266 act accordingly. 3268 App-claimed "https" scheme redirect URIs have some advantages 3269 compared to other native app redirect options in that the identity of 3270 the destination app is guaranteed to the authorization server by the 3271 operating system. For this reason, native apps SHOULD use them over 3272 the other options where possible. 3274 10.3.3. Loopback Interface Redirection 3276 Native apps that are able to open a port on the loopback network 3277 interface without needing special permissions (typically, those on 3278 desktop operating systems) can use the loopback interface to receive 3279 the OAuth redirect. 3281 Loopback redirect URIs use the "http" scheme and are constructed with 3282 the loopback IP literal and whatever port the client is listening on. 3284 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3285 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3286 IPv4 loopback interface with a randomly assigned port: 3288 http://127.0.0.1:51004/oauth2redirect/example-provider 3290 An example redirect using the IPv6 loopback interface with a randomly 3291 assigned port: 3293 http://[::1]:61023/oauth2redirect/example-provider 3295 The authorization server MUST allow any port to be specified at the 3296 time of the request for loopback IP redirect URIs, to accommodate 3297 clients that obtain an available ephemeral port from the operating 3298 system at the time of the request. 3300 Clients SHOULD NOT assume that the device supports a particular 3301 version of the Internet Protocol. It is RECOMMENDED that clients 3302 attempt to bind to the loopback interface using both IPv4 and IPv6 3303 and use whichever is available. 3305 11. Browser-Based Apps 3307 Browser-based apps are are clients that run in a web browser, 3308 typically written in JavaScript, also known as "single-page apps". 3309 These types of apps have particular security considerations similar 3310 to native apps. 3312 TODO: Bring in the normative text of the browser-based apps BCP when 3313 it is finalized. 3315 12. Differences from OAuth 2.0 3317 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3318 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3319 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3320 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3321 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3322 ([RFC6750]). 3324 Where a later draft updates or obsoletes functionality found in the 3325 original [RFC6749], that functionality in this draft is updated with 3326 the normative changes described in a later draft, or removed 3327 entirely. 3329 A non-normative list of changes from OAuth 2.0 is listed below: 3331 * The authorization code grant is extended with the functionality 3332 from PKCE ([RFC7636]) such that the default method of using the 3333 authorization code grant according to this specification requires 3334 the addition of the PKCE parameters 3336 * Redirect URIs must be compared using exact string matching as per 3337 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3339 * The Implicit grant ("response_type=token") is omitted from this 3340 specification as per Section 2.1.2 of 3341 [I-D.ietf-oauth-security-topics] 3343 * The Resource Owner Password Credentials grant is omitted from this 3344 specification as per Section 2.4 of 3345 [I-D.ietf-oauth-security-topics] 3347 * Bearer token usage omits the use of bearer tokens in the query 3348 string of URIs as per Section 4.3.2 of 3349 [I-D.ietf-oauth-security-topics] 3351 * Refresh tokens should either be sender-constrained or one-time use 3352 as per Section 4.12.2 of [I-D.ietf-oauth-security-topics] 3354 13. IANA Considerations 3356 This document does not require any IANA actions. 3358 All referenced registries are defined by RFC6749 and related 3359 documents that this work is based upon. No changes to those 3360 registries are required by this specification. 3362 14. References 3364 14.1. Normative References 3366 [I-D.ietf-oauth-security-topics] 3367 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3368 "OAuth 2.0 Security Best Current Practice", Work in 3369 Progress, Internet-Draft, draft-ietf-oauth-security- 3370 topics-15, 5 April 2020, . 3373 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3374 Requirement Levels", BCP 14, RFC 2119, 3375 DOI 10.17487/RFC2119, March 1997, 3376 . 3378 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3379 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3380 Authentication: Basic and Digest Access Authentication", 3381 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3382 . 3384 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3385 DOI 10.17487/RFC2818, May 2000, 3386 . 3388 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3389 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3390 2003, . 3392 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3393 Resource Identifier (URI): Generic Syntax", STD 66, 3394 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3395 . 3397 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3398 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3399 . 3401 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3402 Specifications: ABNF", STD 68, RFC 5234, 3403 DOI 10.17487/RFC5234, January 2008, 3404 . 3406 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3407 Housley, R., and W. Polk, "Internet X.509 Public Key 3408 Infrastructure Certificate and Certificate Revocation List 3409 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3410 . 3412 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3413 Verification of Domain-Based Application Service Identity 3414 within Internet Public Key Infrastructure Using X.509 3415 (PKIX) Certificates in the Context of Transport Layer 3416 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3417 2011, . 3419 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3420 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3421 . 3423 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3424 Framework: Bearer Token Usage", RFC 6750, 3425 DOI 10.17487/RFC6750, October 2012, 3426 . 3428 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3429 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3430 2014, . 3432 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3433 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3434 DOI 10.17487/RFC7231, June 2014, 3435 . 3437 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3438 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3439 RFC 7234, DOI 10.17487/RFC7234, June 2014, 3440 . 3442 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3443 and Registration Procedures for URI Schemes", BCP 35, 3444 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3445 . 3447 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3448 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3449 May 2017, . 3451 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3452 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3453 . 3455 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3456 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3457 . 3459 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3460 Standard Code for Information Interchange, ANSI X3.4", 3461 1986. 3463 [W3C.REC-html401-19991224] 3464 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3465 Specification", World Wide Web Consortium Recommendation 3466 REC-html401-19991224, 24 December 1999, 3467 . 3469 [W3C.REC-xml-20081126] 3470 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3471 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3472 Edition)", World Wide Web Consortium Recommendation REC- 3473 xml-20081126, 26 November 2008, 3474 . 3476 14.2. Informative References 3478 [CSP-2] "Content Security Policy Level 2", December 2016, 3479 . 3481 [I-D.bradley-oauth-jwt-encoded-state] 3482 Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding 3483 claims in the OAuth 2 state parameter using a JWT", Work 3484 in Progress, Internet-Draft, draft-bradley-oauth-jwt- 3485 encoded-state-09, 4 November 2018, . 3489 [I-D.ietf-oauth-access-token-jwt] 3490 Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 3491 Access Tokens", Work in Progress, Internet-Draft, draft- 3492 ietf-oauth-access-token-jwt-07, 27 April 2020, 3493 . 3496 [I-D.ietf-oauth-browser-based-apps] 3497 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3498 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3499 browser-based-apps-06, 5 April 2020, . 3503 [I-D.ietf-oauth-dpop] 3504 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 3505 Jones, M., and D. Waite, "OAuth 2.0 Demonstration of 3506 Proof-of-Possession at the Application Layer (DPoP)", Work 3507 in Progress, Internet-Draft, draft-ietf-oauth-dpop-01, 1 3508 May 2020, . 3511 [I-D.ietf-oauth-par] 3512 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 3513 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 3514 Work in Progress, Internet-Draft, draft-ietf-oauth-par-01, 3515 18 February 2020, . 3518 [I-D.ietf-oauth-rar] 3519 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3520 Rich Authorization Requests", Work in Progress, Internet- 3521 Draft, draft-ietf-oauth-rar-01, 19 February 2020, 3522 . 3525 [I-D.ietf-oauth-token-binding] 3526 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 3527 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3528 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3529 . 3532 [NIST800-63] 3533 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3534 Gupta, S., and E. Nabbus, "NIST Special Publication 3535 800-63-1, INFORMATION SECURITY", December 2011, 3536 . 3538 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3539 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3540 and B. Boyer, "Online Multimedia Authorization Protocol: 3541 An Industry Standard for Authorized Access to Internet 3542 Multimedia Resources", April 2012, 3543 . 3545 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3546 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3547 . 3549 [OpenID.Messages] 3550 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3551 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3552 June 2012, . 3555 [owasp_redir] 3556 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3557 Forwards", 2020, 3558 . 3561 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3562 DOI 10.17487/RFC6265, April 2011, 3563 . 3565 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3566 Threat Model and Security Considerations", RFC 6819, 3567 DOI 10.17487/RFC6819, January 2013, 3568 . 3570 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 3571 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 3572 August 2013, . 3574 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3575 Protocol (HTTP/1.1): Message Syntax and Routing", 3576 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3577 . 3579 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3580 Protocol (HTTP/1.1): Authentication", RFC 7235, 3581 DOI 10.17487/RFC7235, June 2014, 3582 . 3584 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3585 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3586 . 3588 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3589 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3590 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3591 . 3593 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 3594 "OAuth 2.0 Dynamic Client Registration Management 3595 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 3596 . 3598 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3599 for Code Exchange by OAuth Public Clients", RFC 7636, 3600 DOI 10.17487/RFC7636, September 2015, 3601 . 3603 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 3604 RFC 7662, DOI 10.17487/RFC7662, October 2015, 3605 . 3607 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3608 Authorization Server Metadata", RFC 8414, 3609 DOI 10.17487/RFC8414, June 2018, 3610 . 3612 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 3613 "OAuth 2.0 Device Authorization Grant", RFC 8628, 3614 DOI 10.17487/RFC8628, August 2019, 3615 . 3617 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3618 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3619 and Certificate-Bound Access Tokens", RFC 8705, 3620 DOI 10.17487/RFC8705, February 2020, 3621 . 3623 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3624 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3625 February 2020, . 3627 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3629 This section provides Augmented Backus-Naur Form (ABNF) syntax 3630 descriptions for the elements defined in this specification using the 3631 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3632 code points [W3C.REC-xml-20081126]; these characters are typically 3633 encoded in UTF-8. Elements are presented in the order first defined. 3635 Some of the definitions that follow use the "URI-reference" 3636 definition from [RFC3986]. 3638 Some of the definitions that follow use these common definitions: 3640 VSCHAR = %x20-7E 3641 NQCHAR = %x21 / %x23-5B / %x5D-7E 3642 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3643 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3644 %xE000-FFFD / %x10000-10FFFF 3646 (The UNICODECHARNOCRLF definition is based upon the Char definition 3647 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3648 Return and Linefeed characters.) 3650 A.1. "client_id" Syntax 3652 The "client_id" element is defined in Section 2.3.1: 3654 client-id = *VSCHAR 3656 A.2. "client_secret" Syntax 3658 The "client_secret" element is defined in Section 2.3.1: 3660 client-secret = *VSCHAR 3662 A.3. "response_type" Syntax 3664 The "response_type" element is defined in Section 3.1.1 and 3665 Section 8.4: 3667 response-type = response-name *( SP response-name ) 3668 response-name = 1*response-char 3669 response-char = "_" / DIGIT / ALPHA 3671 A.4. "scope" Syntax 3673 The "scope" element is defined in Section 3.3: 3675 scope = scope-token *( SP scope-token ) 3676 scope-token = 1*NQCHAR 3678 A.5. "state" Syntax 3680 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3681 Section 4.1.2.1: 3683 state = 1*VSCHAR 3685 A.6. "redirect_uri" Syntax 3687 The "redirect_uri" element is defined in Section 4.1.1, and 3688 Section 4.1.3: 3690 redirect-uri = URI-reference 3692 A.7. "error" Syntax 3694 The "error" element is defined in Sections Section 4.1.2.1, 3695 Section 5.2, 7.2, and 8.5: 3697 error = 1*NQSCHAR 3699 A.8. "error_description" Syntax 3701 The "error_description" element is defined in Sections 3702 Section 4.1.2.1, Section 5.2, and Section 7.3: 3704 error-description = 1*NQSCHAR 3706 A.9. "error_uri" Syntax 3708 The "error_uri" element is defined in Sections Section 4.1.2.1, 3709 Section 5.2, and 7.2: 3711 error-uri = URI-reference 3713 A.10. "grant_type" Syntax 3715 The "grant_type" element is defined in Sections Section 4.1.3, 3716 Section 4.2.3, Section 4.2.2, Section 4.3, and Section 6: 3718 grant-type = grant-name / URI-reference 3719 grant-name = 1*name-char 3720 name-char = "-" / "." / "_" / DIGIT / ALPHA 3722 A.11. "code" Syntax 3724 The "code" element is defined in Section 4.1.3: 3726 code = 1*VSCHAR 3728 A.12. "access_token" Syntax 3730 The "access_token" element is defined in Section 4.2.3 and 3731 Section 5.1: 3733 access-token = 1*VSCHAR 3735 A.13. "token_type" Syntax 3737 The "token_type" element is defined in Section 5.1, and Section 8.1: 3739 token-type = type-name / URI-reference 3740 type-name = 1*name-char 3741 name-char = "-" / "." / "_" / DIGIT / ALPHA 3743 A.14. "expires_in" Syntax 3745 The "expires_in" element is defined in Section 5.1: 3747 expires-in = 1*DIGIT 3749 A.15. "refresh_token" Syntax 3751 The "refresh_token" element is defined in Section 5.1 and Section 6: 3753 refresh-token = 1*VSCHAR 3755 A.16. Endpoint Parameter Syntax 3757 The syntax for new endpoint parameters is defined in Section 8.2: 3759 param-name = 1*name-char 3760 name-char = "-" / "." / "_" / DIGIT / ALPHA 3762 A.17. "code_verifier" Syntax 3764 ABNF for "code_verifier" is as follows. 3766 code-verifier = 43*128unreserved 3767 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3768 ALPHA = %x41-5A / %x61-7A 3769 DIGIT = %x30-39 3771 A.18. "code_challenge" Syntax 3773 ABNF for "code_challenge" is as follows. 3775 code-challenge = 43*128unreserved 3776 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3777 ALPHA = %x41-5A / %x61-7A 3778 DIGIT = %x30-39 3780 Appendix B. Use of application/x-www-form-urlencoded Media Type 3782 At the time of publication of this specification, the "application/x- 3783 www-form-urlencoded" media type was defined in Section 17.13.4 of 3784 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 3785 Types registry (http://www.iana.org/assignments/media-types 3786 (http://www.iana.org/assignments/media-types)). Furthermore, that 3787 definition is incomplete, as it does not consider non-US-ASCII 3788 characters. 3790 To address this shortcoming when generating payloads using this media 3791 type, names and values MUST be encoded using the UTF-8 character 3792 encoding scheme [RFC3629] first; the resulting octet sequence then 3793 needs to be further encoded using the escaping rules defined in 3794 [W3C.REC-html401-19991224]. 3796 When parsing data from a payload using this media type, the names and 3797 values resulting from reversing the name/value encoding consequently 3798 need to be treated as octet sequences, to be decoded using the UTF-8 3799 character encoding scheme. 3801 For example, the value consisting of the six Unicode code points (1) 3802 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3803 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3804 SIGN) would be encoded into the octet sequence below (using 3805 hexadecimal notation): 3807 20 25 26 2B C2 A3 E2 82 AC 3809 and then represented in the payload as: 3811 +%25%26%2B%C2%A3%E2%82%AC 3813 Appendix C. Extensions 3815 Below is a list of well-established extensions at the time of 3816 publication: 3818 * [RFC8628]: OAuth 2.0 Device Authorization Grant 3820 - The Device Authorization Grant (formerly known as the Device 3821 Flow) is an extension that enables devices with no browser or 3822 limited input capability to obtain an access token. This is 3823 commonly used by smart TV apps, or devices like hardware video 3824 encoders that can stream video to a streaming video service. 3826 * [RFC8414]: Authorization Server Metadata 3828 - Authorization Server Metadata (also known as OAuth Discovery) 3829 defines an endpoint clients can use to look up the information 3830 needed to interact with a particular OAuth server, such as the 3831 location of the authorization and token endpoints and the 3832 supported grant types. 3834 * [RFC8707]: Resource Indicators 3836 - Provides a way for the client to explicitly signal to the 3837 authorization server where it intends to use the access token 3838 it is requesting. 3840 * [RFC7591]: Dynamic Client Registration 3842 - Dynamic Client Registration provides a mechanism for 3843 programmatically registering clients with an authorization 3844 server. 3846 * [RFC7592]: Dynamic Client Management 3847 - Dynamic Client Management provides a mechanism for updating 3848 dynamically registered client information. 3850 * [I-D.ietf-oauth-access-token-jwt]: JSON Web Token (JWT) Profile 3851 for OAuth 2.0 Access Tokens 3853 - This specification defines a profile for issuing OAuth access 3854 tokens in JSON web token (JWT) format. 3856 * [RFC8705]: Mutual TLS 3858 - Mutual TLS describes a mechanism of binding access tokens and 3859 refresh tokens to the clients they were issued to, as well as a 3860 client authentication mechanism, via TLS certificate 3861 authentication. 3863 * [RFC7662]: Token Introspection 3865 - The Token Introspection extension defines a mechanism for 3866 resource servers to obtain information about access tokens. 3868 * [RFC7009]: Token Revocation 3870 - The Token Revocation extension defines a mechanism for clients 3871 to indicate to the authorization server that an access token is 3872 no longer needed. 3874 * [I-D.ietf-oauth-par]: Pushed Authorization Requests 3876 - The Pushed Authorization Requsts extension describes a 3877 technique of initiating an OAuth flow from the back channel, 3878 providing better security and more flexibility for building 3879 complex authorization requests. 3881 * [I-D.ietf-oauth-rar]: Rich Authorization Requests 3883 - Rich Authorization Requests specifies a new parameter 3884 "authorization_details" that is used to carry fine-grained 3885 authorization data in the OAuth authorization request. 3887 Appendix D. Acknowledgements 3889 TBD 3891 Authors' Addresses 3892 Dick Hardt 3893 SignIn.Org 3895 Email: dick.hardt@gmail.com 3897 Aaron Parecki 3898 Okta 3900 Email: aaron@parecki.com 3901 URI: https://aaronparecki.com 3903 Torsten Lodderstedt 3904 yes.com 3906 Email: torsten@lodderstedt.net