idnits 2.17.1 draft-ietf-oauth-v2-1-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 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 (15 March 2021) is 1138 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 1163, but not defined == Missing Reference: '0-9' is mentioned on line 1163, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-16 ** 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-11 == Outdated reference: A later version (-17) exists of draft-ietf-oauth-browser-based-apps-07 == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-02 == Outdated reference: A later version (-10) exists of draft-ietf-oauth-par-05 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-03 -- 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: 7 errors (**), 0 flaws (~~), 10 warnings (==), 5 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: 16 September 2021 Okta 6 T. Lodderstedt 7 yes.com 8 15 March 2021 10 The OAuth 2.1 Authorization Framework 11 draft-ietf-oauth-v2-1-02 13 Abstract 15 The OAuth 2.1 authorization framework enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and an authorization service, or by 19 allowing the third-party application to obtain access on its own 20 behalf. This specification replaces and obsoletes the OAuth 2.0 21 Authorization 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 16 September 2021. 40 Copyright Notice 42 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . 9 62 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 63 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10 64 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 65 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 66 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12 67 1.9. Compatibility with OAuth 2.0 . . . . . . . . . . . . . . 13 68 1.10. Notational Conventions . . . . . . . . . . . . . . . . . 13 69 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 14 70 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14 71 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 16 72 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 16 73 2.3.1. Client Secret . . . . . . . . . . . . . . . . . . . . 17 74 2.3.2. Other Authentication Methods . . . . . . . . . . . . 18 75 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 18 76 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 18 77 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 19 78 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 19 79 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 20 80 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 22 81 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 22 82 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 23 83 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 23 84 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23 85 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 25 86 4.1.2. Authorization Response . . . . . . . . . . . . . . . 28 87 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 31 88 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 32 89 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 32 90 4.2.1. Authorization Request and Response . . . . . . . . . 33 91 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 33 92 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 34 93 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 34 94 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 35 95 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 35 96 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 36 98 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 38 99 6.1. Refresh Token Request . . . . . . . . . . . . . . . . . . 38 100 6.2. Refresh Token Response . . . . . . . . . . . . . . . . . 40 101 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 102 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 103 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42 104 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 42 105 7.2.2. The WWW-Authenticate Response Header Field . . . . . 44 106 7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 45 107 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 46 108 7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 46 109 7.4. Access Token Security Considerations . . . . . . . . . . 46 110 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 47 111 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 47 112 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 49 113 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 50 114 7.4.5. Access Token Privilege Restriction . . . . . . . . . 51 115 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 51 116 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 51 117 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 52 118 8.3. Defining New Authorization Grant Types . . . . . . . . . 52 119 8.4. Defining New Authorization Endpoint Response Types . . . 52 120 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 53 121 9. Security Considerations . . . . . . . . . . . . . . . . . . . 53 122 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 54 123 9.1.1. Client Authentication of Native Apps . . . . . . . . 54 124 9.2. Registration of Native App Clients . . . . . . . . . . . 55 125 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 55 126 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 56 127 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 56 128 9.4.1. Access Token Privilege Restriction . . . . . . . . . 57 129 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 57 130 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 58 131 9.6. Client Impersonating Resource Owner . . . . . . . . . . . 58 132 9.7. Protecting Redirect-Based Flows . . . . . . . . . . . . . 59 133 9.7.1. Loopback Redirect Considerations in Native Apps . . . 59 134 9.7.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 60 135 9.8. Authorization Codes . . . . . . . . . . . . . . . . . . . 61 136 9.9. Request Confidentiality . . . . . . . . . . . . . . . . . 62 137 9.10. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 62 138 9.11. Credentials-Guessing Attacks . . . . . . . . . . . . . . 63 139 9.12. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 63 140 9.13. Fake External User-Agents in Native Apps . . . . . . . . 63 141 9.14. Malicious External User-Agents in Native Apps . . . . . . 64 142 9.15. Cross-Site Request Forgery . . . . . . . . . . . . . . . 64 143 9.16. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 65 144 9.17. Code Injection and Input Validation . . . . . . . . . . . 66 145 9.18. Open Redirectors . . . . . . . . . . . . . . . . . . . . 66 146 9.18.1. Client as Open Redirector . . . . . . . . . . . . . 66 147 9.18.2. Authorization Server as Open Redirector . . . . . . 66 148 9.19. Authorization Server Mix-Up Mitigation in Native Apps . . 67 149 9.20. Embedded User Agents in Native Apps . . . . . . . . . . . 67 150 9.21. Other Recommendations . . . . . . . . . . . . . . . . . . 68 151 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 68 152 10.1. Using Inter-App URI Communication for OAuth in Native 153 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 69 154 10.2. Initiating the Authorization Request from a Native 155 App . . . . . . . . . . . . . . . . . . . . . . . . . . 70 156 10.3. Receiving the Authorization Response in a Native App . . 71 157 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 71 158 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 72 159 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 72 160 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 73 161 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 73 162 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 163 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 164 14.1. Normative References . . . . . . . . . . . . . . . . . . 74 165 14.2. Informative References . . . . . . . . . . . . . . . . . 77 166 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 80 167 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 81 168 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 81 169 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 81 170 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 81 171 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 81 172 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 81 173 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 81 174 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 82 175 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 82 176 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 82 177 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 82 178 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 82 179 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 82 180 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 82 181 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 83 182 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 83 183 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 83 184 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 83 185 Appendix B. Use of application/x-www-form-urlencoded Media 186 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 83 187 Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 84 188 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 86 189 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 191 1. Introduction 193 In the traditional client-server authentication model, the client 194 requests an access-restricted resource (protected resource) on the 195 server by authenticating with the server using the resource owner's 196 credentials. In order to provide third-party applications access to 197 restricted resources, the resource owner shares its credentials with 198 the third party. This creates several problems and limitations: 200 * Third-party applications are required to store the resource 201 owner's credentials for future use, typically a password in clear- 202 text. 204 * Servers are required to support password authentication, despite 205 the security weaknesses inherent in passwords. 207 * Third-party applications gain overly broad access to the resource 208 owner's protected resources, leaving resource owners without any 209 ability to restrict duration or access to a limited subset of 210 resources. 212 * Resource owners often reuse passwords with other unrelated 213 services, despite best security practices. This password reuse 214 means a vulnerability or exposure in one service may have security 215 implications in completely unrelated services. 217 * Resource owners cannot revoke access to an individual third party 218 without revoking access to all third parties, and must do so by 219 changing the third party's password. 221 * Compromise of any third-party application results in compromise of 222 the end-user's password and all of the data protected by that 223 password. 225 OAuth addresses these issues by introducing an authorization layer 226 and separating the role of the client from that of the resource 227 owner. In OAuth, the client requests access to resources controlled 228 by the resource owner and hosted by the resource server. Instead of 229 using the resource owner's credentials to access protected resources, 230 the client obtains an access token - a credential representing a 231 specific set of access attributes such as scope and lifetime. Access 232 tokens are issued to clients by an authorization server with the 233 approval of the resource owner. The client uses the access token to 234 access the protected resources hosted by the resource server. 236 For example, an end-user (resource owner) can grant a printing 237 service (client) access to their protected photos stored at a photo- 238 sharing service (resource server), without sharing their username and 239 password with the printing service. Instead, they authenticates 240 directly with a server trusted by the photo-sharing service 241 (authorization server), which issues the printing service delegation- 242 specific credentials (access token). 244 This specification is designed for use with HTTP ([RFC7230]). The 245 use of OAuth over any protocol other than HTTP is out of scope. 247 Since the publication of the OAuth 2.0 Authorization Framework 248 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 249 Native Apps ([RFC8252]), OAuth Security Best Current Practice 250 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 251 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 252 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 253 updated with ([I-D.ietf-oauth-security-topics]). This Standards 254 Track specification consolidates the information in all of these 255 documents and removes features that have been found to be insecure in 256 [I-D.ietf-oauth-security-topics]. 258 1.1. Roles 260 OAuth defines four roles: 262 "resource owner": An entity capable of granting access to a 263 protected resource. When the resource owner is a person, it is 264 referred to as an end-user. This is sometimes abbreviated as 265 "RO". 267 "resource server": The server hosting the protected resources, 268 capable of accepting and responding to protected resource requests 269 using access tokens. The resource server is often accessible via 270 an API. This is sometimes abbreviated as "RS". 272 "client": An application making protected resource requests on 273 behalf of the resource owner and with its authorization. The term 274 "client" does not imply any particular implementation 275 characteristics (e.g., whether the application executes on a 276 server, a desktop, or other devices). 278 "authorization server": The server issuing access tokens to the 279 client after successfully authenticating the resource owner and 280 obtaining authorization. This is sometimes abbreviated as "AS". 282 The interaction between the authorization server and resource server 283 is beyond the scope of this specification, however several extension 284 have been defined to provide an option for interoperability between 285 resource servers and authorization servers. The authorization server 286 may be the same server as the resource server or a separate entity. 287 A single authorization server may issue access tokens accepted by 288 multiple resource servers. 290 1.2. Protocol Flow 292 +--------+ +---------------+ 293 | |--(1)- Authorization Request ->| Resource | 294 | | | Owner | 295 | |<-(2)-- Authorization Grant ---| | 296 | | +---------------+ 297 | | 298 | | +---------------+ 299 | |--(3)-- Authorization Grant -->| Authorization | 300 | Client | | Server | 301 | |<-(4)----- Access Token -------| | 302 | | +---------------+ 303 | | 304 | | +---------------+ 305 | |--(5)----- Access Token ------>| Resource | 306 | | | Server | 307 | |<-(6)--- Protected Resource ---| | 308 +--------+ +---------------+ 310 Figure 1: Abstract Protocol Flow 312 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 313 interaction between the four roles and includes the following steps: 315 1. The client requests authorization from the resource owner. The 316 authorization request can be made directly to the resource owner 317 (as shown), or preferably indirectly via the authorization server 318 as an intermediary. 320 2. The client receives an authorization grant, which is a credential 321 representing the resource owner's authorization, expressed using 322 one of two authorization grant types defined in this 323 specification or using an extension grant type. The 324 authorization grant type depends on the method used by the client 325 to request authorization and the types supported by the 326 authorization server. 328 3. The client requests an access token by authenticating with the 329 authorization server and presenting the authorization grant. 331 4. The authorization server authenticates the client and validates 332 the authorization grant, and if valid, issues an access token. 334 5. The client requests the protected resource from the resource 335 server and authenticates by presenting the access token. 337 6. The resource server validates the access token, and if valid, 338 serves the request. 340 The preferred method for the client to obtain an authorization grant 341 from the resource owner (depicted in steps (1) and (2)) is to use the 342 authorization server as an intermediary, which is illustrated in 343 Figure 3 in Section 4.1. 345 1.3. Authorization Grant 347 An authorization grant is a credential representing the resource 348 owner's authorization (to access its protected resources) used by the 349 client to obtain an access token. This specification defines two 350 grant types - authorization code and client credentials - as well as 351 an extensibility mechanism for defining additional types. 353 1.3.1. Authorization Code 355 An authorization code is a temporary credential used to obtain an 356 access token. Instead of the client requesting authorization 357 directly from the resource owner, the client directs the resource 358 owner to an authorization server (via its user-agent as defined in 359 [RFC7231]), which in turn directs the resource owner back to the 360 client with the authorization code. The client can then exchange the 361 authorization code for an access token. 363 Before directing the resource owner back to the client with the 364 authorization code, the authorization server authenticates the 365 resource owner, and may request the resource owner's consent or 366 otherwise inform them of the client's request. Because the resource 367 owner only authenticates with the authorization server, the resource 368 owner's credentials are never shared with the client, and the client 369 does not need to have knowledge of any additional authentication 370 steps such as multi-factor authentication or delegated accounts. 372 The authorization code provides a few important security benefits, 373 such as the ability to authenticate the client, as well as the 374 transmission of the access token directly to the client without 375 passing it through the resource owner's user-agent and potentially 376 exposing it to others, including the resource owner. 378 1.3.2. Client Credentials 380 The client credentials or other forms of client authentication (e.g. 381 a "client_secret" or a private key used to sign a JWT) can be used as 382 an authorization grant when the authorization scope is limited to the 383 protected resources under the control of the client, or to protected 384 resources previously arranged with the authorization server. Client 385 credentials are used as an authorization grant typically when the 386 client is acting on its own behalf (the client is also the resource 387 owner) or is requesting access to protected resources based on an 388 authorization previously arranged with the authorization server. 390 1.4. Access Token 392 Access tokens are credentials used to access protected resources. An 393 access token is a string representing an authorization issued to the 394 client. The string is considered opaque to the client, even if it 395 has a structure. Depending on the authorization server, the access 396 token string may be parseable by the resource server. 398 Access tokens represent specific scopes and durations of access, 399 granted by the resource owner, and enforced by the resource server 400 and authorization server. 402 The token may be used by the RS to retrieve the authorization 403 information, or the token may self-contain the authorization 404 information in a verifiable manner (i.e., a token string consisting 405 of a signed data payload). One example of a token retrieval 406 mechanism is Token Introspection [RFC7662], in which the RS calls an 407 endpoint on the AS to validate the token presented by the client. 408 One example of a structured token format is 409 [I-D.ietf-oauth-access-token-jwt], a method of encoding access token 410 data as a JSON Web Token [RFC7519]. 412 Additional authentication credentials, which are beyond the scope of 413 this specification, may be required in order for the client to use an 414 access token. This is typically referred to as a sender-constrained 415 access token, such as Mutual TLS Access Tokens [RFC8705]. 417 The access token provides an abstraction layer, replacing different 418 authorization constructs (e.g., username and password) with a single 419 token understood by the resource server. This abstraction enables 420 issuing access tokens more restrictive than the authorization grant 421 used to obtain them, as well as removing the resource server's need 422 to understand a wide range of authentication methods. 424 Access tokens can have different formats, structures, and methods of 425 utilization (e.g., cryptographic properties) based on the resource 426 server security requirements. Access token attributes and the 427 methods used to access protected resources may be extended beyond 428 what is described in this specification. 430 1.5. Refresh Token 432 Refresh tokens are credentials used to obtain access tokens. Refresh 433 tokens are issued to the client by the authorization server and are 434 used to obtain a new access token when the current access token 435 becomes invalid or expires, or to obtain additional access tokens 436 with identical or narrower scope (access tokens may have a shorter 437 lifetime and fewer permissions than authorized by the resource 438 owner). Issuing a refresh token is optional at the discretion of the 439 authorization server, and may be issued based on properties of the 440 client, properties of the request, policies within the authorization 441 server, or any other criteria. If the authorization server issues a 442 refresh token, it is included when issuing an access token (i.e., 443 step (2) in Figure 2). 445 A refresh token is a string representing the authorization granted to 446 the client by the resource owner. The string is considered opaque to 447 the client. The refresh token may be an identifier used to retrieve 448 the authorization information or may encode this information into the 449 string itself. Unlike access tokens, refresh tokens are intended for 450 use only with authorization servers and are never sent to resource 451 servers. 453 +--------+ +---------------+ 454 | |--(1)------- Authorization Grant --------->| | 455 | | | | 456 | |<-(2)----------- Access Token -------------| | 457 | | & Refresh Token | | 458 | | | | 459 | | +----------+ | | 460 | |--(3)---- Access Token ---->| | | | 461 | | | | | | 462 | |<-(4)- Protected Resource --| Resource | | Authorization | 463 | Client | | Server | | Server | 464 | |--(5)---- Access Token ---->| | | | 465 | | | | | | 466 | |<-(6)- Invalid Token Error -| | | | 467 | | +----------+ | | 468 | | | | 469 | |--(7)----------- Refresh Token ----------->| | 470 | | | | 471 | |<-(8)----------- Access Token -------------| | 472 +--------+ & Optional Refresh Token +---------------+ 474 Figure 2: Refreshing an Expired Access Token 476 The flow illustrated in Figure 2 includes the following steps: 478 1. The client requests an access token by authenticating with the 479 authorization server and presenting an authorization grant. 481 2. The authorization server authenticates the client and validates 482 the authorization grant, and if valid, issues an access token and 483 optionally a refresh token. 485 3. The client makes a protected resource request to the resource 486 server by presenting the access token. 488 4. The resource server validates the access token, and if valid, 489 serves the request. 491 5. Steps (3) and (4) repeat until the access token expires. If the 492 client knows the access token expired, it skips to step (7); 493 otherwise, it makes another protected resource request. 495 6. Since the access token is invalid, the resource server returns an 496 invalid token error. 498 7. The client requests a new access token by presenting the refresh 499 token and providing client authentication if it has been issued 500 credentials. The client authentication requirements are based on 501 the client type and on the authorization server policies. 503 8. The authorization server authenticates the client and validates 504 the refresh token, and if valid, issues a new access token (and, 505 optionally, a new refresh token). 507 1.6. TLS Version 509 Whenever Transport Layer Security (TLS) is used by this 510 specification, the appropriate version (or versions) of TLS will vary 511 over time, based on the widespread deployment and known security 512 vulnerabilities. Refer to [BCP195] for up to date recommendations on 513 transport layer security. 515 Implementations MAY also support additional transport-layer security 516 mechanisms that meet their security requirements. 518 1.7. HTTP Redirections 520 This specification makes extensive use of HTTP redirections, in which 521 the client or the authorization server directs the resource owner's 522 user-agent to another destination. While the examples in this 523 specification show the use of the HTTP 302 status code, any other 524 method available via the user-agent to accomplish this redirection, 525 with the exception of HTTP 307, is allowed and is considered to be an 526 implementation detail. See Section 9.7.2 for details. 528 1.8. Interoperability 530 OAuth 2.1 provides a rich authorization framework with well-defined 531 security properties. 533 This specification leaves a few required components partially or 534 fully undefined (e.g., client registration, authorization server 535 capabilities, endpoint discovery). Some of these behaviors are 536 defined in optional extensions which implementations can choose to 537 use, such as: 539 * [RFC8414]: Authorization Server Metadata, defining an endpoint 540 clients can use to look up the information needed to interact with 541 a particular OAuth server 543 * [RFC7591]: Dynamic Client Registration, providing a mechanism for 544 programmatically registering clients with an authorization server 546 * [RFC7592]: Dynamic Client Management, providing a mechanism for 547 updating dynamically registered client information 549 * [RFC7662]: Token Introspection, defining a mechanism for resource 550 servers to obtain information about access tokens 552 Please refer to Appendix C for a list of current known extensions at 553 the time of this publication. 555 1.9. Compatibility with OAuth 2.0 557 OAuth 2.1 is compatible with OAuth 2.0 with the extensions and 558 restrictions from known best current practices applied. 559 Specifically, features not specified in OAuth 2.0 core, such as PKCE, 560 are required in OAuth 2.1. Additionally, some features available in 561 OAuth 2.0, such as the Implicit or Resource Owner Credentials grant 562 types, are not specified in OAuth 2.1. Furthermore, some behaviors 563 allowed in OAuth 2.0 are restricted in OAuth 2.1, such as the strict 564 string matching of redirect URIs required by OAuth 2.1. 566 See Section 12 for more details on the differences from OAuth 2.0. 568 1.10. Notational Conventions 570 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 571 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 572 "OPTIONAL" in this document are to be interpreted as described in BCP 573 14 [RFC2119] [RFC8174] when, and only when, they appear in all 574 capitals, as shown here. 576 This specification uses the Augmented Backus-Naur Form (ABNF) 577 notation of [RFC5234]. Additionally, the rule URI-reference is 578 included from "Uniform Resource Identifier (URI): Generic Syntax" 579 [RFC3986]. 581 Certain security-related terms are to be understood in the sense 582 defined in [RFC4949]. These terms include, but are not limited to, 583 "attack", "authentication", "authorization", "certificate", 584 "confidentiality", "credential", "encryption", "identity", "sign", 585 "signature", "trust", "validate", and "verify". 587 The term "payload" is to be interpreted as described in Section 3.3 588 of [RFC7231]. 590 Unless otherwise noted, all the protocol parameter names and values 591 are case sensitive. 593 2. Client Registration 595 Before initiating the protocol, the client must establish its 596 registration with the authorization server. The means through which 597 the client registers with the authorization server are beyond the 598 scope of this specification but typically involve the client 599 developer manually registering the client at the authorization 600 server's website after creating an account and agreeing to the 601 service's Terms of Service, or by using Dynamic Client Registration 602 ([RFC7591]). 604 Client registration does not require a direct interaction between the 605 client and the authorization server. When supported by the 606 authorization server, registration can rely on other means for 607 establishing trust and obtaining the required client properties 608 (e.g., redirect URI, client type). For example, registration can be 609 accomplished using a self-issued or third-party-issued assertion, or 610 by the authorization server performing client discovery using a 611 trusted channel. 613 When registering a client, the client developer SHALL: 615 * specify the client type as described in Section 2.1, 617 * provide client details needed by the grant type in use, such as 618 redirect URIs as described in Section 3.1.2, and 620 * include any other information required by the authorization server 621 (e.g., application name, website, description, logo image, the 622 acceptance of legal terms). 624 Dynamic Client Registration ([RFC7591]) defines a common general data 625 model for clients that may be used even with manual client 626 registration. 628 2.1. Client Types 630 OAuth 2.1 defines three client types based on their ability to 631 authenticate securely with the authorization server as well as the 632 authorization server's assurance of the client's identity. 634 "confidential": Clients that have credentials and their identity has 635 been confirmed by the AS are designated as "confidential clients" 637 "credentialed": Clients that have credentials and their identity has 638 been not been confirmed by the AS are designated as "credentialed 639 clients" 641 "public": Clients without credentials are called "public clients" 643 Any clients with credentials MUST take precautions to prevent leakage 644 and abuse of their credentials. 646 Authorization servers SHOULD consider the level of confidence in a 647 client's identity when deciding whether they allow such a client 648 access to more critical functions, such as the Client Credentials 649 grant type. 651 A single "client_id" MUST NOT be treated as more than one type of 652 client. 654 This specification has been designed around the following client 655 profiles: 657 "web application": A web application is a confidential client 658 running on a web server. Resource owners access the client via an 659 HTML user interface rendered in a user-agent on the device used by 660 the resource owner. The client credentials as well as any access 661 token issued to the client are stored on the web server and are 662 not exposed to or accessible by the resource owner. 664 "browser-based application": A browser-based application is a public 665 client in which the client code is downloaded from a web server 666 and executes within a user-agent (e.g., web browser) on the device 667 used by the resource owner. Protocol data and credentials are 668 easily accessible (and often visible) to the resource owner. 669 Since such applications reside within the user-agent, they can 670 make seamless use of the user-agent capabilities when requesting 671 authorization. 673 "native application": A native application is a public client 674 installed and executed on the device used by the resource owner. 675 Protocol data and credentials are accessible to the resource 676 owner. It is assumed that any client authentication credentials 677 included in the application can be extracted. On the other hand, 678 dynamically issued credentials such as access tokens or refresh 679 tokens can receive an acceptable level of protection. At a 680 minimum, these credentials are protected from hostile servers with 681 which the application may interact. On some platforms, these 682 credentials might be protected from other applications residing on 683 the same device. 685 2.2. Client Identifier 687 The authorization server issues the registered client a client 688 identifier - a unique string representing the registration 689 information provided by the client. The client identifier is not a 690 secret; it is exposed to the resource owner and MUST NOT be used 691 alone for client authentication. The client identifier is unique to 692 the authorization server. 694 The client identifier string size is left undefined by this 695 specification. The client should avoid making assumptions about the 696 identifier size. The authorization server SHOULD document the size 697 of any identifier it issues. 699 Authorization servers SHOULD NOT allow clients to choose or influence 700 their "client_id" value. See Section 9.6 for details. 702 2.3. Client Authentication 704 Confidential and credentialed clients establish a client 705 authentication method with the authorization server suitable for the 706 security requirements of the authorization server. The authorization 707 server MAY accept any form of client authentication meeting its 708 security requirements. 710 Confidential and credentialed clients are typically issued (or 711 establish) a set of client credentials used for authenticating with 712 the authorization server (e.g., password, public/private key pair). 714 Authorization servers SHOULD use client authentication if possible. 716 It is RECOMMENDED to use asymmetric (public-key based) methods for 717 client authentication such as mTLS [RFC8705] or "private_key_jwt" 718 [OpenID]. When asymmetric methods for client authentication are 719 used, authorization servers do not need to store sensitive symmetric 720 keys, making these methods more robust against a number of attacks. 722 The authorization server MAY establish a client authentication method 723 with public clients, which converts them to credentialed clients. 724 However, the authorization server MUST NOT rely on credentialed 725 client authentication for the purpose of identifying the client. 727 The client MUST NOT use more than one authentication method in each 728 request. 730 2.3.1. Client Secret 732 Clients in possession of a client secret, sometimes known as a client 733 password, MAY use the HTTP Basic authentication scheme as defined in 734 [RFC2617] to authenticate with the authorization server. The client 735 identifier is encoded using the "application/x-www-form-urlencoded" 736 encoding algorithm per Appendix B, and the encoded value is used as 737 the username; the client secret is encoded using the same algorithm 738 and used as the password. The authorization server MUST support the 739 HTTP Basic authentication scheme for authenticating clients that were 740 issued a client secret. 742 For example (with extra line breaks for display purposes only): 744 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 746 Alternatively, the authorization server MAY support including the 747 client credentials in the request-body using the following 748 parameters: 750 "client_id": REQUIRED. The client identifier issued to the client 751 during the registration process described by Section 2.2. 753 "client_secret": REQUIRED. The client secret. 755 Including the client credentials in the request-body using the two 756 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 757 to directly utilize the HTTP Basic authentication scheme (or other 758 password-based HTTP authentication schemes). The parameters can only 759 be transmitted in the request-body and MUST NOT be included in the 760 request URI. 762 For example, a request to refresh an access token (Section 6) using 763 the body parameters (with extra line breaks for display purposes 764 only): 766 POST /token HTTP/1.1 767 Host: server.example.com 768 Content-Type: application/x-www-form-urlencoded 770 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 771 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 773 The authorization server MUST require the use of TLS as described in 774 Section 1.6 when sending requests using password authentication. 776 Since this client authentication method involves a password, the 777 authorization server MUST protect any endpoint utilizing it against 778 brute force attacks. 780 2.3.2. Other Authentication Methods 782 The authorization server MAY support any suitable authentication 783 scheme matching its security requirements. When using other 784 authentication methods, the authorization server MUST define a 785 mapping between the client identifier (registration record) and 786 authentication scheme. 788 Some additional authentication methods such as mTLS [RFC8705] and 789 "private_key_jwt" [OpenID] are defined in the "OAuth Token Endpoint 790 Authentication Methods (https://www.iana.org/assignments/oauth- 791 parameters/oauth-parameters.xhtml#token-endpoint-auth-method)" 792 registry, and may be useful as generic client authentication methods 793 beyond the specific use of protecting the token endpoint. 795 2.4. Unregistered Clients 797 This specification does not exclude the use of unregistered clients. 798 However, the use of such clients is beyond the scope of this 799 specification and requires additional security analysis and review of 800 its interoperability impact. 802 3. Protocol Endpoints 804 The authorization process utilizes two authorization server endpoints 805 (HTTP resources): 807 * Authorization endpoint - used by the client to obtain 808 authorization from the resource owner via user-agent redirection. 810 * Token endpoint - used by the client to exchange an authorization 811 grant for an access token, typically with client authentication. 813 As well as one client endpoint: 815 * Redirection endpoint - used by the authorization server to return 816 responses containing authorization credentials to the client via 817 the resource owner user-agent. 819 Not every authorization grant type utilizes both endpoints. 820 Extension grant types MAY define additional endpoints as needed. 822 3.1. Authorization Endpoint 824 The authorization endpoint is used to interact with the resource 825 owner and obtain an authorization grant. The authorization server 826 MUST first verify the identity of the resource owner. The way in 827 which the authorization server authenticates the resource owner 828 (e.g., username and password login, session cookies) is beyond the 829 scope of this specification. 831 The means through which the client obtains the location of the 832 authorization endpoint are beyond the scope of this specification, 833 but the location is typically provided in the service documentation, 834 or in the authorization server's metadata document ([RFC8414]). 836 The endpoint URI MAY include an "application/x-www-form-urlencoded" 837 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 838 which MUST be retained when adding additional query parameters. The 839 endpoint URI MUST NOT include a fragment component. 841 Since requests to the authorization endpoint result in user 842 authentication and the transmission of clear-text credentials (in the 843 HTTP response), the authorization server MUST require the use of TLS 844 as described in Section 1.6 when sending requests to the 845 authorization endpoint. 847 The authorization server MUST support the use of the HTTP "GET" 848 method [RFC7231] for the authorization endpoint and MAY support the 849 use of the "POST" method as well. 851 The authorization server MUST ignore unrecognized request parameters. 853 Request and response parameters defined by this specification MUST 854 NOT be included more than once. Parameters sent without a value MUST 855 be treated as if they were omitted from the request. 857 3.1.1. Response Type 859 The authorization endpoint is used by the authorization code flow. 860 The client informs the authorization server of the desired response 861 type using the following parameter: 863 "response_type": REQUIRED. The value MUST be "code" for requesting 864 an authorization code as described by Section 4.1.1, or a 865 registered extension value as described by Section 8.4. 867 Extension response types MAY contain a space-delimited (%x20) list of 868 values, where the order of values does not matter (e.g., response 869 type "a b" is the same as "b a"). The meaning of such composite 870 response types is defined by their respective specifications. 872 Some extension response types are defined by ([OpenID]). 874 If an authorization request is missing the "response_type" parameter, 875 or if the response type is not understood, the authorization server 876 MUST return an error response as described in Section 4.1.2.1. 878 3.1.2. Redirection Endpoint 880 After completing its interaction with the resource owner, the 881 authorization server directs the resource owner's user-agent back to 882 the client. The authorization server redirects the user-agent to one 883 of the client's redirection endpoints previously established with the 884 authorization server during the client registration process. 886 The redirect URI MUST be an absolute URI as defined by [RFC3986] 887 Section 4.3. The endpoint URI MAY include an "application/x-www- 888 form-urlencoded" formatted (per Appendix B) query component 889 ([RFC3986] Section 3.4), which MUST be retained when adding 890 additional query parameters. The endpoint URI MUST NOT include a 891 fragment component. 893 3.1.2.1. Endpoint Request Confidentiality 895 The redirection endpoint SHOULD require the use of TLS as described 896 in Section 1.6 when the requested response type is "code", or when 897 the redirection request will result in the transmission of sensitive 898 credentials over an open network. If TLS is not available, the 899 authorization server SHOULD warn the resource owner about the 900 insecure endpoint prior to redirection (e.g., display a message 901 during the authorization request). 903 Lack of transport-layer security can have a severe impact on the 904 security of the client and the protected resources it is authorized 905 to access. The use of transport-layer security is particularly 906 critical when the authorization process is used as a form of 907 delegated end-user authentication by the client (e.g., third-party 908 sign-in service). 910 3.1.2.2. Registration Requirements 912 The authorization server MUST require all clients to register one or 913 more complete redirect URIs prior to utilizing the authorization 914 endpoint. The client MAY use the "state" request parameter to 915 achieve per-request customization if needed. 917 The authorization server MAY allow the client to register multiple 918 redirect URIs. 920 Without requiring registration of redirect URIs, attackers can use 921 the authorization endpoint as an open redirector as described in 922 Section 9.18. 924 3.1.2.3. Dynamic Configuration 926 If multiple redirect URIs have been registered the client MUST 927 include a redirect URI with the authorization request using the 928 "redirect_uri" request parameter. 930 3.1.2.4. Invalid Endpoint 932 If an authorization request fails validation due to a missing, 933 invalid, or mismatching redirect URI, the authorization server SHOULD 934 inform the resource owner of the error and MUST NOT automatically 935 redirect the user-agent to the invalid redirect URI. 937 3.1.2.5. Endpoint Content 939 The redirection request to the client's endpoint typically results in 940 an HTML document response, processed by the user-agent. If the HTML 941 response is served directly as the result of the redirection request, 942 any script included in the HTML document will execute with full 943 access to the redirect URI and the credentials (e.g. authorization 944 code) it contains. Additionally, the request URL containing the 945 authorization code may be sent in the HTTP Referer header to any 946 embedded images, stylesheets and other elements loaded in the page. 948 The client SHOULD NOT include any third-party scripts (e.g., third- 949 party analytics, social plug-ins, ad networks) in the redirection 950 endpoint response. Instead, it SHOULD extract the credentials from 951 the URI and redirect the user-agent again to another endpoint without 952 exposing the credentials (in the URI or elsewhere). If third-party 953 scripts are included, the client MUST ensure that its own scripts 954 (used to extract and remove the credentials from the URI) will 955 execute first. 957 3.2. Token Endpoint 959 The token endpoint is used by the client to obtain an access token 960 using a grant such as those described in Section 4 and Section 6. 962 The means through which the client obtains the location of the token 963 endpoint are beyond the scope of this specification, but the location 964 is typically provided in the service documentation and configured 965 during development of the client, or provided in the authorization 966 server's metadata document ([RFC8414]) and fetched programmatically 967 at runtime. 969 The endpoint URI MAY include an "application/x-www-form-urlencoded" 970 formatted (per Appendix B) query component ([RFC3986] Section 3.4) 971 and MUST NOT include a fragment component. 973 Since requests to the token endpoint result in the transmission of 974 clear-text credentials (in the HTTP request and response), the 975 authorization server MUST require the use of TLS as described in 976 Section 1.6 when sending requests to the token endpoint. 978 The client MUST use the HTTP "POST" method when making access token 979 requests. 981 The authorization server MUST ignore unrecognized request parameters. 983 Parameters sent without a value MUST be treated as if they were 984 omitted from the request. Request and response parameters defined by 985 this specification MUST NOT be included more than once. 987 3.2.1. Client Authentication 989 Confidential clients or other clients issued client credentials MUST 990 authenticate with the authorization server as described in 991 Section 2.3 when making requests to the token endpoint. Client 992 authentication is used for: 994 * Enforcing the binding of refresh tokens and authorization codes to 995 the client they were issued to. Client authentication is critical 996 when an authorization code is transmitted to the redirection 997 endpoint over an insecure channel. 999 * Recovering from a compromised client by disabling the client or 1000 changing its credentials, thus preventing an attacker from abusing 1001 stolen refresh tokens. Changing a single set of client 1002 credentials is significantly faster than revoking an entire set of 1003 refresh tokens. 1005 * Implementing authentication management best practices, which 1006 require periodic credential rotation. Rotation of an entire set 1007 of refresh tokens can be challenging, while rotation of a single 1008 set of client credentials is significantly easier. 1010 3.3. Access Token Scope 1012 The authorization and token endpoints allow the client to specify the 1013 scope of the access request using the "scope" request parameter. In 1014 turn, the authorization server uses the "scope" response parameter to 1015 inform the client of the scope of the access token issued. 1017 The value of the scope parameter is expressed as a list of space- 1018 delimited, case-sensitive strings. The strings are defined by the 1019 authorization server. If the value contains multiple space-delimited 1020 strings, their order does not matter, and each string adds an 1021 additional access range to the requested scope. 1023 scope = scope-token *( SP scope-token ) 1024 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 1026 The authorization server MAY fully or partially ignore the scope 1027 requested by the client, based on the authorization server policy or 1028 the resource owner's instructions. If the issued access token scope 1029 is different from the one requested by the client, the authorization 1030 server MUST include the "scope" response parameter to inform the 1031 client of the actual scope granted. 1033 If the client omits the scope parameter when requesting 1034 authorization, the authorization server MUST either process the 1035 request using a pre-defined default value or fail the request 1036 indicating an invalid scope. The authorization server SHOULD 1037 document its scope requirements and default value (if defined). 1039 4. Obtaining Authorization 1041 To request an access token, the client obtains authorization from the 1042 resource owner. OAuth defines two authorization grant types: 1043 authorization code and client credentials. It also provides an 1044 extension mechanism for defining additional grant types. 1046 4.1. Authorization Code Grant 1048 The authorization code grant type is used to obtain both access 1049 tokens and refresh tokens. 1051 Since this is a redirect-based flow, the client must be capable of 1052 initiating the flow with the resource owner's user-agent (typically a 1053 web browser) and capable of being redirected back to from the 1054 authorization server. 1056 +----------+ 1057 | Resource | 1058 | Owner | 1059 | | 1060 +----------+ 1061 ^ 1062 | 1063 (2) 1064 +----|-----+ Client Identifier +---------------+ 1065 | -+----(1)-- & Redirect URI ---->| | 1066 | User- | | Authorization | 1067 | Agent -+----(2)-- User authenticates --->| Server | 1068 | | | | 1069 | -+----(3)-- Authorization Code ---<| | 1070 +-|----|---+ +---------------+ 1071 | | ^ v 1072 (1) (3) | | 1073 | | | | 1074 ^ v | | 1075 +---------+ | | 1076 | |>---(4)-- Authorization Code ---------' | 1077 | Client | & Redirect URI | 1078 | | | 1079 | |<---(5)----- Access Token -------------------' 1080 +---------+ (w/ Optional Refresh Token) 1082 Note: The lines illustrating steps (1), (2), and (3) are broken into 1083 two parts as they pass through the user-agent. 1085 Figure 3: Authorization Code Flow 1087 The flow illustrated in Figure 3 includes the following steps: 1089 (1) The client initiates the flow by directing the resource owner's 1090 user-agent to the authorization endpoint. The client includes its 1091 client identifier, code challenge (derived from a generated code 1092 verifier), optional requested scope, optional local state, and a 1093 redirect URI to which the authorization server will send the user- 1094 agent back once access is granted (or denied). 1096 (2) The authorization server authenticates the resource owner (via 1097 the user-agent) and establishes whether the resource owner grants or 1098 denies the client's access request. 1100 (3) Assuming the resource owner grants access, the authorization 1101 server redirects the user-agent back to the client using the redirect 1102 URI provided earlier (in the request or during client registration). 1103 The redirect URI includes an authorization code and any local state 1104 provided by the client earlier. 1106 (4) The client requests an access token from the authorization 1107 server's token endpoint by including the authorization code received 1108 in the previous step, and including its code verifier. When making 1109 the request, the client authenticates with the authorization server 1110 if it can. The client includes the redirect URI used to obtain the 1111 authorization code for verification. 1113 (5) The authorization server authenticates the client when possible, 1114 validates the authorization code, validates the code verifier, and 1115 ensures that the redirect URI received matches the URI used to 1116 redirect the client in step (3). If valid, the authorization server 1117 responds back with an access token and, optionally, a refresh token. 1119 4.1.1. Authorization Request 1121 To begin the authorization request, the client builds the 1122 authorization request URI by adding parameters to the authorization 1123 server's authorization endpoint URI. The client will eventually 1124 redirect the user-agent to this URI to initiate the request, as 1125 described in Section 4.1.1.1. 1127 Clients use a unique secret per authorization request to protect 1128 against authorization code injection and CSRF attacks. The client 1129 first generates this secret, which it can use at the time of 1130 redeeming the authorization code to prove that the client using the 1131 authorization code is the same client that requested it. 1133 4.1.1.1. Client Initiates the Authorization Request 1135 The client constructs the request URI by adding the following 1136 parameters to the query component of the authorization endpoint URI 1137 using the "application/x-www-form-urlencoded" format, per Appendix B: 1139 "response_type": REQUIRED. Value MUST be set to "code". 1141 "client_id": REQUIRED. The client identifier as described in 1142 Section 2.2. 1144 "code_challenge": REQUIRED or RECOMMENDED (see Section 9.8). Code 1145 challenge. 1147 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1148 present in the request. Code verifier transformation method is 1149 "S256" or "plain". 1151 "redirect_uri": OPTIONAL. As described in Section 3.1.2. 1153 "scope": OPTIONAL. The scope of the access request as described by 1154 Section 3.3. 1156 "state": OPTIONAL. An opaque value used by the client to maintain 1157 state between the request and callback. The authorization server 1158 includes this value when redirecting the user-agent back to the 1159 client. 1161 The "code_verifier" is a unique high-entropy cryptographically random 1162 string generated for each authorization request, using the unreserved 1163 characters "[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"", with a 1164 minimum length of 43 characters and a maximum length of 128 1165 characters. 1167 The client stores the "code_verifier" temporarily, and calculates the 1168 "code_challenge" which it uses in the authorization request. 1170 ABNF for "code_verifier" is as follows. 1172 code-verifier = 43*128unreserved 1173 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1174 ALPHA = %x41-5A / %x61-7A 1175 DIGIT = %x30-39 1177 NOTE: The code verifier SHOULD have enough entropy to make it 1178 impractical to guess the value. It is RECOMMENDED that the output of 1179 a suitable random number generator be used to create a 32-octet 1180 sequence. The octet sequence is then base64url-encoded to produce a 1181 43-octet URL-safe string to use as the code verifier. 1183 The client then creates a "code_challenge" derived from the code 1184 verifier by using one of the following transformations on the code 1185 verifier: 1187 S256 1188 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1190 plain 1191 code_challenge = code_verifier 1193 If the client is capable of using "S256", it MUST use "S256", as 1194 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1195 permitted to use "plain" only if they cannot support "S256" for some 1196 technical reason, for example constrained environments that do not 1197 have a hashing function available, and know via out-of-band 1198 configuration or via Authorization Server Metadata ([RFC8414]) that 1199 the server supports "plain". 1201 ABNF for "code_challenge" is as follows. 1203 code-challenge = 43*128unreserved 1204 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1205 ALPHA = %x41-5A / %x61-7A 1206 DIGIT = %x30-39 1208 The properties "code_challenge" and "code_verifier" are adopted from 1209 the OAuth 2.0 extension known as "Proof-Key for Code Exchange", or 1210 PKCE ([RFC7636]) where this technique was originally developed. 1212 Clients MUST use "code_challenge" and "code_verifier" and 1213 authorization servers MUST enforce their use except under the 1214 conditions described in Section 9.8. In this case, using and 1215 enforcing "code_challenge" and "code_verifier" as described in the 1216 following is still RECOMMENDED. 1218 The client directs the resource owner to the constructed URI using an 1219 HTTP redirection, or by other means available to it via the user- 1220 agent. 1222 For example, the client directs the user-agent to make the following 1223 HTTP request using TLS (with extra line breaks for display purposes 1224 only): 1226 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1227 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1228 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1229 &code_challenge_method=S256 HTTP/1.1 1230 Host: server.example.com 1232 The authorization server validates the request to ensure that all 1233 required parameters are present and valid. 1235 In particular, the authorization server MUST validate the 1236 "redirect_uri" in the request if present, ensuring that it matches 1237 one of the registered redirect URIs previously established during 1238 client registration (Section 2). When comparing the two URIs the 1239 authorization server MUST using simple character-by-character string 1240 comparison as defined in [RFC3986], Section 6.2.1. 1242 If the request is valid, the authorization server authenticates the 1243 resource owner and obtains an authorization decision (by asking the 1244 resource owner or by establishing approval via other means). 1246 When a decision is established, the authorization server directs the 1247 user-agent to the provided client redirect URI using an HTTP 1248 redirection response, or by other means available to it via the user- 1249 agent. 1251 4.1.2. Authorization Response 1253 If the resource owner grants the access request, the authorization 1254 server issues an authorization code and delivers it to the client by 1255 adding the following parameters to the query component of the 1256 redirect URI using the "application/x-www-form-urlencoded" format, 1257 per Appendix B: 1259 "code": REQUIRED. The authorization code generated by the 1260 authorization server. The authorization code MUST expire shortly 1261 after it is issued to mitigate the risk of leaks. A maximum 1262 authorization code lifetime of 10 minutes is RECOMMENDED. The 1263 client MUST NOT use the authorization code more than once. If an 1264 authorization code is used more than once, the authorization 1265 server MUST deny the request and SHOULD revoke (when possible) all 1266 access tokens and refresh tokens previously issued based on that 1267 authorization code. The authorization code is bound to the client 1268 identifier and redirect URI. 1270 "state": REQUIRED if the "state" parameter was present in the client 1271 authorization request. The exact value received from the client. 1273 For example, the authorization server redirects the user-agent by 1274 sending the following HTTP response: 1276 HTTP/1.1 302 Found 1277 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1278 &state=xyz 1280 The client MUST ignore unrecognized response parameters. The 1281 authorization code string size is left undefined by this 1282 specification. The client should avoid making assumptions about code 1283 value sizes. The authorization server SHOULD document the size of 1284 any value it issues. 1286 The authorization server MUST associate the "code_challenge" and 1287 "code_challenge_method" values with the issued authorization code so 1288 the code challenge can be verified later. 1290 The exact method that the server uses to associate the 1291 "code_challenge" with the issued code is out of scope for this 1292 specification. The code challenge could be stored on the server and 1293 associated with the code there. The "code_challenge" and 1294 "code_challenge_method" values may be stored in encrypted form in the 1295 code itself, but the server MUST NOT include the "code_challenge" 1296 value in a response parameter in a form that entities other than the 1297 AS can extract. 1299 4.1.2.1. Error Response 1301 If the request fails due to a missing, invalid, or mismatching 1302 redirect URI, or if the client identifier is missing or invalid, the 1303 authorization server SHOULD inform the resource owner of the error 1304 and MUST NOT automatically redirect the user-agent to the invalid 1305 redirect URI. 1307 An AS MUST reject requests without a "code_challenge" from public 1308 clients, and MUST reject such requests from other clients unless 1309 there is reasonable assurance that the client mitigates authorization 1310 code injection in other ways. See Section 9.8 for details. 1312 If the server does not support the requested "code_challenge_method" 1313 transformation, the authorization endpoint MUST return the 1314 authorization error response with "error" value set to 1315 "invalid_request". The "error_description" or the response of 1316 "error_uri" SHOULD explain the nature of error, e.g., transform 1317 algorithm not supported. 1319 If the resource owner denies the access request or if the request 1320 fails for reasons other than a missing or invalid redirect URI, the 1321 authorization server informs the client by adding the following 1322 parameters to the query component of the redirect URI using the 1323 "application/x-www-form-urlencoded" format, per Appendix B: 1325 "error": REQUIRED. A single ASCII [USASCII] error code from the 1326 following: 1328 "invalid_request": The request is missing a required parameter, 1329 includes an invalid parameter value, includes a parameter more 1330 than once, or is otherwise malformed. 1332 "unauthorized_client": The client is not authorized to request an 1333 authorization code using this method. 1335 "access_denied": The resource owner or authorization server 1336 denied the request. 1338 "unsupported_response_type": The authorization server does not 1339 support obtaining an authorization code using this method. 1341 "invalid_scope": The requested scope is invalid, unknown, or 1342 malformed. 1344 "server_error": The authorization server encountered an 1345 unexpected condition that prevented it from fulfilling the 1346 request. (This error code is needed because a 500 Internal 1347 Server Error HTTP status code cannot be returned to the client 1348 via an HTTP redirect.) 1350 "temporarily_unavailable": The authorization server is currently 1351 unable to handle the request due to a temporary overloading or 1352 maintenance of the server. (This error code is needed because 1353 a 503 Service Unavailable HTTP status code cannot be returned 1354 to the client via an HTTP redirect.) 1356 Values for the "error" parameter MUST NOT include characters 1357 outside the set %x20-21 / %x23-5B / %x5D-7E. 1359 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1360 providing additional information, used to assist the client 1361 developer in understanding the error that occurred. Values for 1362 the "error_description" parameter MUST NOT include characters 1363 outside the set %x20-21 / %x23-5B / %x5D-7E. 1365 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1366 with information about the error, used to provide the client 1367 developer with additional information about the error. Values for 1368 the "error_uri" parameter MUST conform to the URI-reference syntax 1369 and thus MUST NOT include characters outside the set %x21 / 1370 %x23-5B / %x5D-7E. 1372 "state": REQUIRED if a "state" parameter was present in the client 1373 authorization request. The exact value received from the client. 1375 For example, the authorization server redirects the user-agent by 1376 sending the following HTTP response: 1378 HTTP/1.1 302 Found 1379 Location: https://client.example.com/cb?error=access_denied&state=xyz 1381 4.1.3. Access Token Request 1383 The client makes a request to the token endpoint by sending the 1384 following parameters using the "application/x-www-form-urlencoded" 1385 format per Appendix B with a character encoding of UTF-8 in the HTTP 1386 request payload: 1388 "grant_type": REQUIRED. Value MUST be set to "authorization_code". 1390 "code": REQUIRED. The authorization code received from the 1391 authorization server. 1393 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1394 included in the authorization request as described in 1395 Section 4.1.1, and their values MUST be identical. 1397 "client_id": REQUIRED, if the client is not authenticating with the 1398 authorization server as described in Section 3.2.1. 1400 "code_verifier": REQUIRED, if the "code_challenge" parameter was 1401 included in the authorization request. MUST NOT be used 1402 otherwise. The original code verifier string. 1404 Confidential or credentialed clients MUST authenticate with the 1405 authorization server as described in Section 3.2.1. 1407 For example, the client makes the following HTTP request using TLS 1408 (with extra line breaks for display purposes only): 1410 POST /token HTTP/1.1 1411 Host: server.example.com 1412 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1413 Content-Type: application/x-www-form-urlencoded 1415 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1416 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1417 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1419 The authorization server MUST: 1421 * require client authentication for confidential and credentialed 1422 clients (or clients with other authentication requirements), 1424 * authenticate the client if client authentication is included, 1426 * ensure that the authorization code was issued to the authenticated 1427 confidential or credentialed client, or if the client is public, 1428 ensure that the code was issued to "client_id" in the request, 1430 * verify that the authorization code is valid, 1432 * verify that the "code_verifier" parameter is present if and only 1433 if a "code_challenge" parameter was present in the authorization 1434 request, 1436 * if a "code_verifier" is present, verify the "code_verifier" by 1437 calculating the code challenge from the received "code_verifier" 1438 and comparing it with the previously associated "code_challenge", 1439 after first transforming it according to the 1440 "code_challenge_method" method specified by the client, and 1442 * ensure that the "redirect_uri" parameter is present if the 1443 "redirect_uri" parameter was included in the initial authorization 1444 request as described in Section 4.1.1.1, and if included ensure 1445 that their values are identical. 1447 4.1.4. Access Token Response 1449 If the access token request is valid and authorized, the 1450 authorization server issues an access token and optional refresh 1451 token as described in Section 5.1. If the request client 1452 authentication failed or is invalid, the authorization server returns 1453 an error response as described in Section 5.2. 1455 An example successful response: 1457 HTTP/1.1 200 OK 1458 Content-Type: application/json 1459 Cache-Control: no-store 1460 Pragma: no-cache 1462 { 1463 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1464 "token_type": "Bearer", 1465 "expires_in": 3600, 1466 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 1467 "example_parameter": "example_value" 1468 } 1470 4.2. Client Credentials Grant 1472 The client can request an access token using only its client 1473 credentials (or other supported means of authentication) when the 1474 client is requesting access to the protected resources under its 1475 control, or those of another resource owner that have been previously 1476 arranged with the authorization server (the method of which is beyond 1477 the scope of this specification). 1479 The client credentials grant type MUST only be used by confidential 1480 or credentialed clients. 1482 +---------+ +---------------+ 1483 | | | | 1484 | |>--(1)- Client Authentication --->| Authorization | 1485 | Client | | Server | 1486 | |<--(2)---- Access Token ---------<| | 1487 | | | | 1488 +---------+ +---------------+ 1490 Figure 4: Client Credentials Flow 1492 The flow illustrated in Figure 4 includes the following steps: 1494 (1) The client authenticates with the authorization server and 1495 requests an access token from the token endpoint. 1497 (2) The authorization server authenticates the client, and if valid, 1498 issues an access token. 1500 4.2.1. Authorization Request and Response 1502 Since the client authentication is used as the authorization grant, 1503 no additional authorization request is needed. 1505 4.2.2. Access Token Request 1507 The client makes a request to the token endpoint by adding the 1508 following parameters using the "application/x-www-form-urlencoded" 1509 format per Appendix B with a character encoding of UTF-8 in the HTTP 1510 request payload: 1512 "grant_type": REQUIRED. Value MUST be set to "client_credentials". 1514 "scope": OPTIONAL. The scope of the access request as described by 1515 Section 3.3. 1517 The client MUST authenticate with the authorization server as 1518 described in Section 3.2.1. 1520 For example, the client makes the following HTTP request using 1521 transport-layer security (with extra line breaks for display purposes 1522 only): 1524 POST /token HTTP/1.1 1525 Host: server.example.com 1526 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1527 Content-Type: application/x-www-form-urlencoded 1529 grant_type=client_credentials 1531 The authorization server MUST authenticate the client. 1533 4.2.3. Access Token Response 1535 If the access token request is valid and authorized, the 1536 authorization server issues an access token as described in 1537 Section 5.1. A refresh token SHOULD NOT be included. If the request 1538 failed client authentication or is invalid, the authorization server 1539 returns an error response as described in Section 5.2. 1541 An example successful response: 1543 HTTP/1.1 200 OK 1544 Content-Type: application/json 1545 Cache-Control: no-store 1546 Pragma: no-cache 1548 { 1549 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1550 "token_type": "Bearer", 1551 "expires_in": 3600, 1552 "example_parameter": "example_value" 1553 } 1555 4.3. Extension Grants 1557 The client uses an extension grant type by specifying the grant type 1558 using an absolute URI (defined by the authorization server) as the 1559 value of the "grant_type" parameter of the token endpoint, and by 1560 adding any additional parameters necessary. 1562 For example, to request an access token using the Device 1563 Authorization Grant as defined by [RFC8628] after the user has 1564 authorized the client on a separate device, the client makes the 1565 following HTTP request using TLS (with extra line breaks for display 1566 purposes only): 1568 POST /token HTTP/1.1 1569 Host: server.example.com 1570 Content-Type: application/x-www-form-urlencoded 1572 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 1573 &device_code=GmRhmhcxhwEzkoEqiMEg_DnyEysNkuNhszIySk9eS 1574 &client_id=C409020731 1576 If the access token request is valid and authorized, the 1577 authorization server issues an access token and optional refresh 1578 token as described in Section 5.1. If the request failed client 1579 authentication or is invalid, the authorization server returns an 1580 error response as described in Section 5.2. 1582 5. Issuing an Access Token 1584 If the access token request is valid and authorized, the 1585 authorization server issues an access token and optional refresh 1586 token as described in Section 5.1. If the request failed client 1587 authentication or is invalid, the authorization server returns an 1588 error response as described in Section 5.2. 1590 5.1. Successful Response 1592 The authorization server issues an access token and optional refresh 1593 token by creating an HTTP response body using the "application/json" 1594 media type as defined by [RFC8259] with the following parameters and 1595 an HTTP 200 (OK) status code: 1597 "access_token": REQUIRED. The access token issued by the 1598 authorization server. 1600 "token_type": REQUIRED. The type of the access token issued as 1601 described in Section 7.1. Value is case insensitive. 1603 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1604 token. For example, the value "3600" denotes that the access 1605 token will expire in one hour from the time the response was 1606 generated. If omitted, the authorization server SHOULD provide 1607 the expiration time via other means or document the default value. 1609 "refresh_token": OPTIONAL. The refresh token, which can be used to 1610 obtain new access tokens using the same authorization grant as 1611 described in Section 6. 1613 "scope": OPTIONAL, if identical to the scope requested by the 1614 client; otherwise, REQUIRED. The scope of the access token as 1615 described by Section 3.3. 1617 The parameters are serialized into a JavaScript Object Notation 1618 (JSON) structure by adding each parameter at the highest structure 1619 level. Parameter names and string values are included as JSON 1620 strings. Numerical values are included as JSON numbers. The order 1621 of parameters does not matter and can vary. 1623 The authorization server MUST include the HTTP "Cache-Control" 1624 response header field [RFC7234] with a value of "no-store" in any 1625 response containing tokens, credentials, or other sensitive 1626 information, as well as the "Pragma" response header field [RFC7234] 1627 with a value of "no-cache". 1629 For example: 1631 HTTP/1.1 200 OK 1632 Content-Type: application/json 1633 Cache-Control: no-store 1634 Pragma: no-cache 1636 { 1637 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1638 "token_type":"Bearer", 1639 "expires_in":3600, 1640 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1641 "example_parameter":"example_value" 1642 } 1644 The client MUST ignore unrecognized value names in the response. The 1645 sizes of tokens and other values received from the authorization 1646 server are left undefined. The client should avoid making 1647 assumptions about value sizes. The authorization server SHOULD 1648 document the size of any value it issues. 1650 5.2. Error Response 1652 The authorization server responds with an HTTP 400 (Bad Request) 1653 status code (unless specified otherwise) and includes the following 1654 parameters with the response: 1656 "error": REQUIRED. A single ASCII [USASCII] error code from the 1657 following: 1659 "invalid_request": The request is missing a required parameter, 1660 includes an unsupported parameter value (other than grant 1661 type), repeats a parameter, includes multiple credentials, 1662 utilizes more than one mechanism for authenticating the client, 1663 contains a "code_verifier" although no "code_challenge" was 1664 sent in the authorization request, or is otherwise malformed. 1666 "invalid_client": Client authentication failed (e.g., unknown 1667 client, no client authentication included, or unsupported 1668 authentication method). The authorization server MAY return an 1669 HTTP 401 (Unauthorized) status code to indicate which HTTP 1670 authentication schemes are supported. If the client attempted 1671 to authenticate via the "Authorization" request header field, 1672 the authorization server MUST respond with an HTTP 401 1673 (Unauthorized) status code and include the "WWW-Authenticate" 1674 response header field matching the authentication scheme used 1675 by the client. 1677 "invalid_grant": The provided authorization grant (e.g., 1678 authorization code, resource owner credentials) or refresh 1679 token is invalid, expired, revoked, does not match the redirect 1680 URI used in the authorization request, or was issued to another 1681 client. 1683 "unauthorized_client": The authenticated client is not authorized 1684 to use this authorization grant type. 1686 "unsupported_grant_type": The authorization grant type is not 1687 supported by the authorization server. 1689 "invalid_scope": The requested scope is invalid, unknown, 1690 malformed, or exceeds the scope granted by the resource owner. 1692 Values for the "error" parameter MUST NOT include characters 1693 outside the set %x20-21 / %x23-5B / %x5D-7E. 1695 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1696 providing additional information, used to assist the client 1697 developer in understanding the error that occurred. Values for 1698 the "error_description" parameter MUST NOT include characters 1699 outside the set %x20-21 / %x23-5B / %x5D-7E. 1701 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1702 with information about the error, used to provide the client 1703 developer with additional information about the error. Values for 1704 the "error_uri" parameter MUST conform to the URI-reference syntax 1705 and thus MUST NOT include characters outside the set %x21 / 1706 %x23-5B / %x5D-7E. 1708 The parameters are included in the payload of the HTTP response using 1709 the "application/json" media type as defined by [RFC7159]. The 1710 parameters are serialized into a JSON structure by adding each 1711 parameter at the highest structure level. Parameter names and string 1712 values are included as JSON strings. Numerical values are included 1713 as JSON numbers. The order of parameters does not matter and can 1714 vary. 1716 For example: 1718 HTTP/1.1 400 Bad Request 1719 Content-Type: application/json 1720 Cache-Control: no-store 1721 Pragma: no-cache 1723 { 1724 "error":"invalid_request" 1725 } 1727 6. Refreshing an Access Token 1729 Authorization servers SHOULD determine, based on a risk assessment 1730 and their own policies, whether to issue refresh tokens to a certain 1731 client. If the authorization server decides not to issue refresh 1732 tokens, the client MAY obtain new access tokens by starting the OAuth 1733 flow over, for example initiating a new authorization code request. 1734 In such a case, the authorization server may utilize cookies and 1735 persistent grants to optimize the user experience. 1737 If refresh tokens are issued, those refresh tokens MUST be bound to 1738 the scope and resource servers as consented by the resource owner. 1739 This is to prevent privilege escalation by the legitimate client and 1740 reduce the impact of refresh token leakage. 1742 6.1. Refresh Token Request 1744 To use a refresh token to obtain a new access token, the client makes 1745 a request to the token endpoint by adding the following parameters 1746 using the "application/x-www-form-urlencoded" format (per Appendix B) 1747 with a character encoding of UTF-8 in the HTTP request payload: 1749 "grant_type": REQUIRED. Value MUST be set to "refresh_token". 1751 "refresh_token": REQUIRED. The refresh token issued to the client. 1753 "scope": OPTIONAL. The scope of the access request as described by 1754 Section 3.3. The requested scope MUST NOT include any scope not 1755 originally granted by the resource owner, and if omitted is 1756 treated as equal to the scope originally granted by the resource 1757 owner. 1759 Because refresh tokens are typically long-lasting credentials used to 1760 request additional access tokens, the refresh token is bound to the 1761 client to which it was issued. Confidential or credentialed clients 1762 MUST authenticate with the authorization server as described in 1763 Section 3.2.1. 1765 For example, the client makes the following HTTP request using 1766 transport-layer security (with extra line breaks for display purposes 1767 only): 1769 POST /token HTTP/1.1 1770 Host: server.example.com 1771 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1772 Content-Type: application/x-www-form-urlencoded 1774 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1776 The authorization server MUST: 1778 * require client authentication for confidential or credentialed 1779 clients 1781 * authenticate the client if client authentication is included and 1782 ensure that the refresh token was issued to the authenticated 1783 client, and 1785 * validate the refresh token. 1787 Authorization servers SHOULD utilize one of these methods to detect 1788 refresh token replay by malicious actors for public clients: 1790 * _Sender-constrained refresh tokens:_ the authorization server 1791 cryptographically binds the refresh token to a certain client 1792 instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705], 1793 [I-D.ietf-oauth-dpop], or another suitable method. 1795 * _Refresh token rotation:_ the authorization server issues a new 1796 refresh token with every access token refresh response. The 1797 previous refresh token is invalidated but information about the 1798 relationship is retained by the authorization server. If a 1799 refresh token is compromised and subsequently used by both the 1800 attacker and the legitimate client, one of them will present an 1801 invalidated refresh token, which will inform the authorization 1802 server of the breach. The authorization server cannot determine 1803 which party submitted the invalid refresh token, but it will 1804 revoke the active refresh token. This stops the attack at the 1805 cost of forcing the legitimate client to obtain a fresh 1806 authorization grant. 1808 Implementation note: the grant to which a refresh token belongs may 1809 be encoded into the refresh token itself. This can enable an 1810 authorization server to efficiently determine the grant to which a 1811 refresh token belongs, and by extension, all refresh tokens that need 1812 to be revoked. Authorization servers MUST ensure the integrity of 1813 the refresh token value in this case, for example, using signatures. 1815 6.2. Refresh Token Response 1817 If valid and authorized, the authorization server issues an access 1818 token as described in Section 5.1. If the request failed 1819 verification or is invalid, the authorization server returns an error 1820 response as described in Section 5.2. 1822 The authorization server MAY issue a new refresh token, in which case 1823 the client MUST discard the old refresh token and replace it with the 1824 new refresh token. The authorization server MAY revoke the old 1825 refresh token after issuing a new refresh token to the client. If a 1826 new refresh token is issued, the refresh token scope MUST be 1827 identical to that of the refresh token included by the client in the 1828 request. 1830 Authorization servers MAY revoke refresh tokens automatically in case 1831 of a security event, such as: 1833 * password change 1835 * logout at the authorization server 1837 Refresh tokens SHOULD expire if the client has been inactive for some 1838 time, i.e., the refresh token has not been used to obtain new access 1839 tokens for some time. The expiration time is at the discretion of 1840 the authorization server. It might be a global value or determined 1841 based on the client policy or the grant associated with the refresh 1842 token (and its sensitivity). 1844 7. Accessing Protected Resources 1846 The client accesses protected resources by presenting the access 1847 token to the resource server. The resource server MUST validate the 1848 access token and ensure that it has not expired and that its scope 1849 covers the requested resource. The methods used by the resource 1850 server to validate the access token (as well as any error responses) 1851 are beyond the scope of this specification, but generally involve an 1852 interaction or coordination between the resource server and the 1853 authorization server, such as using Token Introspection [RFC7662] or 1854 a structured access token format such as a JWT 1855 [I-D.ietf-oauth-access-token-jwt]. 1857 The method in which the client utilizes the access token to 1858 authenticate with the resource server depends on the type of access 1859 token issued by the authorization server. Typically, it involves 1860 using the HTTP "Authorization" request header field [RFC2617] with an 1861 authentication scheme defined by the specification of the access 1862 token type used, such as "Bearer", defined below. 1864 7.1. Access Token Types 1866 The access token type provides the client with the information 1867 required to successfully utilize the access token to make a protected 1868 resource request (along with type-specific attributes). The client 1869 MUST NOT use an access token if it does not understand the token 1870 type. 1872 For example, the "Bearer" token type defined in this specification is 1873 utilized by simply including the access token string in the request: 1875 GET /resource/1 HTTP/1.1 1876 Host: example.com 1877 Authorization: Bearer mF_9.B5f-4.1JqM 1879 The above example is provided for illustration purposes only. 1881 Each access token type definition specifies the additional attributes 1882 (if any) sent to the client together with the "access_token" response 1883 parameter. It also defines the HTTP authentication method used to 1884 include the access token when making a protected resource request. 1886 7.2. Bearer Tokens 1888 A Bearer Token is a security token with the property that any party 1889 in possession of the token (a "bearer") can use the token in any way 1890 that any other party in possession of it can. Using a bearer token 1891 does not require a bearer to prove possession of cryptographic key 1892 material (proof-of-possession). 1894 Bearer tokens may be extended to include proof-of-possession 1895 techniques by other specifications. 1897 7.2.1. Authenticated Requests 1899 This section defines two methods of sending Bearer tokens in resource 1900 requests to resource servers. Clients MUST NOT use more than one 1901 method to transmit the token in each request. 1903 7.2.1.1. Authorization Request Header Field 1905 When sending the access token in the "Authorization" request header 1906 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 1907 authentication scheme to transmit the access token. 1909 For example: 1911 GET /resource HTTP/1.1 1912 Host: server.example.com 1913 Authorization: Bearer mF_9.B5f-4.1JqM 1915 The syntax of the "Authorization" header field for this scheme 1916 follows the usage of the Basic scheme defined in Section 2 of 1917 [RFC2617]. Note that, as with Basic, it does not conform to the 1918 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1919 with the general authentication framework in HTTP 1.1 Authentication 1920 [RFC7235], although it does not follow the preferred practice 1921 outlined therein in order to reflect existing deployments. The 1922 syntax for Bearer credentials is as follows: 1924 b64token = 1*( ALPHA / DIGIT / 1925 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1926 credentials = "Bearer" 1*SP b64token 1928 Clients SHOULD make authenticated requests with a bearer token using 1929 the "Authorization" request header field with the "Bearer" HTTP 1930 authorization scheme. Resource servers MUST support this method. 1932 7.2.1.2. Form-Encoded Body Parameter 1934 When sending the access token in the HTTP request payload, the client 1935 adds the access token to the request-body using the "access_token" 1936 parameter. The client MUST NOT use this method unless all of the 1937 following conditions are met: 1939 * The HTTP request entity-header includes the "Content-Type" header 1940 field set to "application/x-www-form-urlencoded". 1942 * The payload follows the encoding requirements of the "application/ 1943 x-www-form-urlencoded" content-type as defined by HTML 4.01 1944 [W3C.REC-html401-19991224]. 1946 * The HTTP request payload is single-part. 1948 * The content to be encoded in the payload MUST consist entirely of 1949 ASCII [USASCII] characters. 1951 * The HTTP request method is one for which the request-body has 1952 defined semantics. In particular, this means that the "GET" 1953 method MUST NOT be used. 1955 The payload MAY include other request-specific parameters, in which 1956 case the "access_token" parameter MUST be properly separated from the 1957 request-specific parameters using "&" character(s) (ASCII code 38). 1959 For example, the client makes the following HTTP request using 1960 transport-layer security: 1962 POST /resource HTTP/1.1 1963 Host: server.example.com 1964 Content-Type: application/x-www-form-urlencoded 1966 access_token=mF_9.B5f-4.1JqM 1968 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1969 except in application contexts where participating clients do not 1970 have access to the "Authorization" request header field. Resource 1971 servers MAY support this method. 1973 7.2.2. The WWW-Authenticate Response Header Field 1975 If the protected resource request does not include authentication 1976 credentials or does not contain an access token that enables access 1977 to the protected resource, the resource server MUST include the HTTP 1978 "WWW-Authenticate" response header field; it MAY include it in 1979 response to other conditions as well. The "WWW-Authenticate" header 1980 field uses the framework defined by HTTP/1.1 [RFC2617]. 1982 All challenges defined by this specification MUST use the auth-scheme 1983 value "Bearer". This scheme MUST be followed by one or more auth- 1984 param values. The auth-param attributes used or defined by this 1985 specification are as follows. Other auth-param attributes MAY be 1986 used as well. 1988 A "realm" attribute MAY be included to indicate the scope of 1989 protection in the manner described in HTTP/1.1 [RFC2617]. The 1990 "realm" attribute MUST NOT appear more than once. 1992 The "scope" attribute is defined in Section 3.3. The "scope" 1993 attribute is a space-delimited list of case-sensitive scope values 1994 indicating the required scope of the access token for accessing the 1995 requested resource. "scope" values are implementation defined; there 1996 is no centralized registry for them; allowed values are defined by 1997 the authorization server. The order of "scope" values is not 1998 significant. In some cases, the "scope" value will be used when 1999 requesting a new access token with sufficient scope of access to 2000 utilize the protected resource. Use of the "scope" attribute is 2001 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 2002 "scope" value is intended for programmatic use and is not meant to be 2003 displayed to end-users. 2005 Two example scope values follow; these are taken from the OpenID 2006 Connect [OpenID.Messages] and the Open Authentication Technology 2007 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 2008 OAuth 2.0 use cases, respectively: 2010 scope="openid profile email" 2011 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 2013 If the protected resource request included an access token and failed 2014 authentication, the resource server SHOULD include the "error" 2015 attribute to provide the client with the reason why the access 2016 request was declined. The parameter value is described in 2017 Section 7.2.3. In addition, the resource server MAY include the 2018 "error_description" attribute to provide developers a human-readable 2019 explanation that is not meant to be displayed to end-users. It also 2020 MAY include the "error_uri" attribute with an absolute URI 2021 identifying a human-readable web page explaining the error. The 2022 "error", "error_description", and "error_uri" attributes MUST NOT 2023 appear more than once. 2025 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 2026 include characters outside the set %x21 / %x23-5B / %x5D-7E for 2027 representing scope values and %x20 for delimiters between scope 2028 values. Values for the "error" and "error_description" attributes 2029 (specified in Appendixes A.7 and A.8) MUST NOT include characters 2030 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 2031 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 2032 the URI-reference syntax and thus MUST NOT include characters outside 2033 the set %x21 / %x23-5B / %x5D-7E. 2035 For example, in response to a protected resource request without 2036 authentication: 2038 HTTP/1.1 401 Unauthorized 2039 WWW-Authenticate: Bearer realm="example" 2041 And in response to a protected resource request with an 2042 authentication attempt using an expired access token: 2044 HTTP/1.1 401 Unauthorized 2045 WWW-Authenticate: Bearer realm="example", 2046 error="invalid_token", 2047 error_description="The access token expired" 2049 7.2.3. Error Codes 2051 When a request fails, the resource server responds using the 2052 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2053 includes one of the following error codes in the response: 2055 "invalid_request": The request is missing a required parameter, 2056 includes an unsupported parameter or parameter value, repeats the 2057 same parameter, uses more than one method for including an access 2058 token, or is otherwise malformed. The resource server SHOULD 2059 respond with the HTTP 400 (Bad Request) status code. 2061 "invalid_token": The access token provided is expired, revoked, 2062 malformed, or invalid for other reasons. The resource SHOULD 2063 respond with the HTTP 401 (Unauthorized) status code. The client 2064 MAY request a new access token and retry the protected resource 2065 request. 2067 "insufficient_scope": The request requires higher privileges than 2068 provided by the access token. The resource server SHOULD respond 2069 with the HTTP 403 (Forbidden) status code and MAY include the 2070 "scope" attribute with the scope necessary to access the protected 2071 resource. 2073 If the request lacks any authentication information (e.g., the client 2074 was unaware that authentication is necessary or attempted using an 2075 unsupported authentication method), the resource server SHOULD NOT 2076 include an error code or other error information. 2078 For example: 2080 HTTP/1.1 401 Unauthorized 2081 WWW-Authenticate: Bearer realm="example" 2083 7.3. Error Response 2085 If a resource access request fails, the resource server SHOULD inform 2086 the client of the error. The method by which the resource server 2087 does this is determined by the particular token type, such as the 2088 description of Bearer tokens in Section 7.2.3. 2090 7.3.1. Extension Token Types 2092 [RFC6750] establishes a common registry in Section 11.4 2093 (https://tools.ietf.org/html/rfc6749#section-11.4) for error values 2094 to be shared among OAuth token authentication schemes. 2096 New authentication schemes designed primarily for OAuth token 2097 authentication SHOULD define a mechanism for providing an error 2098 status code to the client, in which the error values allowed are 2099 registered in the error registry established by this specification. 2101 Such schemes MAY limit the set of valid error codes to a subset of 2102 the registered values. If the error code is returned using a named 2103 parameter, the parameter name SHOULD be "error". 2105 Other schemes capable of being used for OAuth token authentication, 2106 but not primarily designed for that purpose, MAY bind their error 2107 values to the registry in the same manner. 2109 New authentication schemes MAY choose to also specify the use of the 2110 "error_description" and "error_uri" parameters to return error 2111 information in a manner parallel to their usage in this 2112 specification. 2114 7.4. Access Token Security Considerations 2115 7.4.1. Security Threats 2117 The following list presents several common threats against protocols 2118 utilizing some form of tokens. This list of threats is based on NIST 2119 Special Publication 800-63 [NIST800-63]. 2121 7.4.1.1. Token manufacture/modification 2123 An attacker may generate a bogus token or modify the token contents 2124 (such as the authentication or attribute statements) of an existing 2125 token, causing the resource server to grant inappropriate access to 2126 the client. For example, an attacker may modify the token to extend 2127 the validity period; a malicious client may modify the assertion to 2128 gain access to information that they should not be able to view. 2130 7.4.1.2. Token disclosure 2132 Tokens may contain authentication and attribute statements that 2133 include sensitive information. 2135 7.4.1.3. Token redirect 2137 An attacker uses a token generated for consumption by one resource 2138 server to gain access to a different resource server that mistakenly 2139 believes the token to be for it. 2141 7.4.1.4. Token replay 2143 An attacker attempts to use a token that has already been used with 2144 that resource server in the past. 2146 7.4.2. Threat Mitigation 2148 A large range of threats can be mitigated by protecting the contents 2149 of the token by using a digital signature. Alternatively, a bearer 2150 token can contain a reference to authorization information, rather 2151 than encoding the information directly. Such references MUST be 2152 infeasible for an attacker to guess; using a reference may require an 2153 extra interaction between a server and the token issuer to resolve 2154 the reference to the authorization information. The mechanics of 2155 such an interaction are not defined by this specification. 2157 This document does not specify the encoding or the contents of the 2158 token; hence, detailed recommendations about the means of 2159 guaranteeing token integrity protection are outside the scope of this 2160 document. The token integrity protection MUST be sufficient to 2161 prevent the token from being modified. 2163 To deal with token redirect, it is important for the authorization 2164 server to include the identity of the intended recipients (the 2165 audience), typically a single resource server (or a list of resource 2166 servers), in the token. Restricting the use of the token to a 2167 specific scope is also RECOMMENDED. 2169 The authorization server MUST implement TLS. Which version(s) ought 2170 to be implemented will vary over time and will depend on the 2171 widespread deployment and known security vulnerabilities at the time 2172 of implementation. 2174 To protect against token disclosure, confidentiality protection MUST 2175 be applied using TLS with a ciphersuite that provides confidentiality 2176 and integrity protection. This requires that the communication 2177 interaction between the client and the authorization server, as well 2178 as the interaction between the client and the resource server, 2179 utilize confidentiality and integrity protection. Since TLS is 2180 mandatory to implement and to use with this specification, it is the 2181 preferred approach for preventing token disclosure via the 2182 communication channel. For those cases where the client is prevented 2183 from observing the contents of the token, token encryption MUST be 2184 applied in addition to the usage of TLS protection. As a further 2185 defense against token disclosure, the client MUST validate the TLS 2186 certificate chain when making requests to protected resources, 2187 including checking the Certificate Revocation List (CRL) [RFC5280]. 2189 Cookies are typically transmitted in the clear. Thus, any 2190 information contained in them is at risk of disclosure. Therefore, 2191 Bearer tokens MUST NOT be stored in cookies that can be sent in the 2192 clear, as any information in them is at risk of disclosure. See 2193 "HTTP State Management Mechanism" [RFC6265] for security 2194 considerations about cookies. 2196 In some deployments, including those utilizing load balancers, the 2197 TLS connection to the resource server terminates prior to the actual 2198 server that provides the resource. This could leave the token 2199 unprotected between the front-end server where the TLS connection 2200 terminates and the back-end server that provides the resource. In 2201 such deployments, sufficient measures MUST be employed to ensure 2202 confidentiality of the token between the front-end and back-end 2203 servers; encryption of the token is one such possible measure. 2205 To deal with token capture and replay, the following recommendations 2206 are made: First, the lifetime of the token MUST be limited; one means 2207 of achieving this is by putting a validity time field inside the 2208 protected part of the token. Note that using short-lived (one hour 2209 or less) tokens reduces the impact of them being leaked. Second, 2210 confidentiality protection of the exchanges between the client and 2211 the authorization server and between the client and the resource 2212 server MUST be applied. As a consequence, no eavesdropper along the 2213 communication path is able to observe the token exchange. 2214 Consequently, such an on-path adversary cannot replay the token. 2215 Furthermore, when presenting the token to a resource server, the 2216 client MUST verify the identity of that resource server, as per 2217 Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST 2218 validate the TLS certificate chain when making these requests to 2219 protected resources. Presenting the token to an unauthenticated and 2220 unauthorized resource server or failing to validate the certificate 2221 chain will allow adversaries to steal the token and gain unauthorized 2222 access to protected resources. 2224 7.4.3. Summary of Recommendations 2226 7.4.3.1. Safeguard bearer tokens 2228 Client implementations MUST ensure that bearer tokens are not leaked 2229 to unintended parties, as they will be able to use them to gain 2230 access to protected resources. This is the primary security 2231 consideration when using bearer tokens and underlies all the more 2232 specific recommendations that follow. 2234 7.4.3.2. Validate TLS certificate chains 2236 The client MUST validate the TLS certificate chain when making 2237 requests to protected resources. Failing to do so may enable DNS 2238 hijacking attacks to steal the token and gain unintended access. 2240 7.4.3.3. Always use TLS (https) 2242 Clients MUST always use TLS (https) or equivalent transport security 2243 when making requests with bearer tokens. Failing to do so exposes 2244 the token to numerous attacks that could give attackers unintended 2245 access. 2247 7.4.3.4. Don't store bearer tokens in HTTP cookies 2249 Implementations MUST NOT store bearer tokens within cookies that can 2250 be sent in the clear (which is the default transmission mode for 2251 cookies). Implementations that do store bearer tokens in cookies 2252 MUST take precautions against cross-site request forgery. 2254 7.4.3.5. Issue short-lived bearer tokens 2256 Authorization servers SHOULD issue short-lived (one hour or less) 2257 bearer tokens, particularly when issuing tokens to clients that run 2258 within a web browser or other environments where information leakage 2259 may occur. Using short-lived bearer tokens can reduce the impact of 2260 them being leaked. 2262 7.4.3.6. Issue scoped bearer tokens 2264 Authorization servers SHOULD issue bearer tokens that contain an 2265 audience restriction, scoping their use to the intended relying party 2266 or set of relying parties. 2268 7.4.3.7. Don't pass bearer tokens in page URLs 2270 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2271 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2272 message headers or message bodies for which confidentiality measures 2273 are taken. Browsers, web servers, and other software may not 2274 adequately secure URLs in the browser history, web server logs, and 2275 other data structures. If bearer tokens are passed in page URLs, 2276 attackers might be able to steal them from the history data, logs, or 2277 other unsecured locations. 2279 7.4.4. Token Replay Prevention 2281 A sender-constrained access token scopes the applicability of an 2282 access token to a certain sender. This sender is obliged to 2283 demonstrate knowledge of a certain secret as prerequisite for the 2284 acceptance of that access token at the recipient (e.g., a resource 2285 server). 2287 Authorization and resource servers SHOULD use mechanisms for sender- 2288 constrained access tokens to prevent token replay as described in 2289 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2290 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2292 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2293 terminated at an intermediary, refer to Section 4.11 of 2294 [I-D.ietf-oauth-security-topics] for further security advice. 2296 7.4.5. Access Token Privilege Restriction 2298 The privileges associated with an access token SHOULD be restricted 2299 to the minimum required for the particular application or use case. 2300 This prevents clients from exceeding the privileges authorized by the 2301 resource owner. It also prevents users from exceeding their 2302 privileges authorized by the respective security policy. Privilege 2303 restrictions also help to reduce the impact of access token leakage. 2305 In particular, access tokens SHOULD be restricted to certain resource 2306 servers (audience restriction), preferably to a single resource 2307 server. To put this into effect, the authorization server associates 2308 the access token with certain resource servers and every resource 2309 server is obliged to verify, for every request, whether the access 2310 token sent with that request was meant to be used for that particular 2311 resource server. If not, the resource server MUST refuse to serve 2312 the respective request. Clients and authorization servers MAY 2313 utilize the parameters "scope" or "resource" as specified in this 2314 document and [RFC8707], respectively, to determine the resource 2315 server they want to access. 2317 Additionally, access tokens SHOULD be restricted to certain resources 2318 and actions on resource servers or resources. To put this into 2319 effect, the authorization server associates the access token with the 2320 respective resource and actions and every resource server is obliged 2321 to verify, for every request, whether the access token sent with that 2322 request was meant to be used for that particular action on the 2323 particular resource. If not, the resource server must refuse to 2324 serve the respective request. Clients and authorization servers MAY 2325 utilize the parameter "scope" and "authorization_details" as 2326 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2327 actions. 2329 8. Extensibility 2331 8.1. Defining Access Token Types 2333 Access token types can be defined in one of two ways: registered in 2334 the Access Token Types registry (following the procedures in 2335 Section 11.1 of [RFC6749]), or by using a unique absolute URI as its 2336 name. 2338 Types utilizing a URI name SHOULD be limited to vendor-specific 2339 implementations that are not commonly applicable, and are specific to 2340 the implementation details of the resource server where they are 2341 used. 2343 All other types MUST be registered. Type names MUST conform to the 2344 type-name ABNF. If the type definition includes a new HTTP 2345 authentication scheme, the type name SHOULD be identical to the HTTP 2346 authentication scheme name (as defined by [RFC2617]). The token type 2347 "example" is reserved for use in examples. 2349 type-name = 1*name-char 2350 name-char = "-" / "." / "_" / DIGIT / ALPHA 2352 8.2. Defining New Endpoint Parameters 2354 New request or response parameters for use with the authorization 2355 endpoint or the token endpoint are defined and registered in the 2356 OAuth Parameters registry following the procedure in Section 11.2 of 2357 [RFC6749]. 2359 Parameter names MUST conform to the param-name ABNF, and parameter 2360 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2361 to the syntax of an existing parameter). 2363 param-name = 1*name-char 2364 name-char = "-" / "." / "_" / DIGIT / ALPHA 2366 Unregistered vendor-specific parameter extensions that are not 2367 commonly applicable and that are specific to the implementation 2368 details of the authorization server where they are used SHOULD 2369 utilize a vendor-specific prefix that is not likely to conflict with 2370 other registered values (e.g., begin with 'companyname_'). 2372 8.3. Defining New Authorization Grant Types 2374 New authorization grant types can be defined by assigning them a 2375 unique absolute URI for use with the "grant_type" parameter. If the 2376 extension grant type requires additional token endpoint parameters, 2377 they MUST be registered in the OAuth Parameters registry as described 2378 by Section 11.2 of [RFC6749]. 2380 8.4. Defining New Authorization Endpoint Response Types 2382 New response types for use with the authorization endpoint are 2383 defined and registered in the Authorization Endpoint Response Types 2384 registry following the procedure in Section 11.3 of [RFC6749]. 2385 Response type names MUST conform to the response-type ABNF. 2387 response-type = response-name *( SP response-name ) 2388 response-name = 1*response-char 2389 response-char = "_" / DIGIT / ALPHA 2390 If a response type contains one or more space characters (%x20), it 2391 is compared as a space-delimited list of values in which the order of 2392 values does not matter. Only one order of values can be registered, 2393 which covers all other arrangements of the same set of values. 2395 For example, an extension can define and register the "code 2396 other_token" response type. Once registered, the same combination 2397 cannot be registered as "other_token code", but both values can be 2398 used to denote the same response type. 2400 8.5. Defining Additional Error Codes 2402 In cases where protocol extensions (i.e., access token types, 2403 extension parameters, or extension grant types) require additional 2404 error codes to be used with the authorization code grant error 2405 response (Section 4.1.2.1), the token error response (Section 5.2), 2406 or the resource access error response (Section 7.3), such error codes 2407 MAY be defined. 2409 Extension error codes MUST be registered (following the procedures in 2410 Section 11.4 of [RFC6749]) if the extension they are used in 2411 conjunction with is a registered access token type, a registered 2412 endpoint parameter, or an extension grant type. Error codes used 2413 with unregistered extensions MAY be registered. 2415 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2416 an identifying name when possible. For example, an error identifying 2417 an invalid value set to the extension parameter "example" SHOULD be 2418 named "example_invalid". 2420 error = 1*error-char 2421 error-char = %x20-21 / %x23-5B / %x5D-7E 2423 9. Security Considerations 2425 As a flexible and extensible framework, OAuth's security 2426 considerations depend on many factors. The following sections 2427 provide implementers with security guidelines focused on the three 2428 client profiles described in Section 2.1: web application, browser- 2429 based application, and native application. 2431 A comprehensive OAuth security model and analysis, as well as 2432 background for the protocol design, is provided by [RFC6819] and 2433 [I-D.ietf-oauth-security-topics]. 2435 9.1. Client Authentication 2437 Authorization servers SHOULD use client authentication if possible. 2439 It is RECOMMENDED to use asymmetric (public-key based) methods for 2440 client authentication such as mTLS [RFC8705] or "private_key_jwt" 2441 [OpenID]. When asymmetric methods for client authentication are 2442 used, authorization servers do not need to store sensitive symmetric 2443 keys, making these methods more robust against a number of attacks. 2445 Authorization server MUST only rely on client authentication if the 2446 process of issuance/registration and distribution of the underlying 2447 credentials ensures their confidentiality. 2449 When client authentication is not possible, the authorization server 2450 SHOULD employ other means to validate the client's identity - for 2451 example, by requiring the registration of the client redirect URI or 2452 enlisting the resource owner to confirm identity. A valid redirect 2453 URI is not sufficient to verify the client's identity when asking for 2454 resource owner authorization but can be used to prevent delivering 2455 credentials to a counterfeit client after obtaining resource owner 2456 authorization. 2458 The authorization server must consider the security implications of 2459 interacting with unauthenticated clients and take measures to limit 2460 the potential exposure of other credentials (e.g., refresh tokens) 2461 issued to such clients. 2463 The privileges an authorization server associates with a certain 2464 client identity MUST depend on the assessment of the overall process 2465 for client identification and client credential lifecycle management. 2466 For example, authentication of a dynamically registered client just 2467 ensures the authorization server it is talking to the same client 2468 again. In contrast, if there is a web application whose developer's 2469 identity was verified, who signed a contract and is issued a client 2470 secret that is only used in a secure backend service, the 2471 authorization server might allow this client to access more sensible 2472 services or to use the client credential grant type. 2474 9.1.1. Client Authentication of Native Apps 2476 Secrets that are statically included as part of an app distributed to 2477 multiple users should not be treated as confidential secrets, as one 2478 user may inspect their copy and learn the shared secret. For this 2479 reason, it is NOT RECOMMENDED for authorization servers to require 2480 client authentication of public native apps clients using a shared 2481 secret, as this serves little value beyond client identification 2482 which is already provided by the "client_id" request parameter. 2484 Authorization servers that still require a statically included shared 2485 secret for native app clients MUST treat the client as a public 2486 client (as defined in Section 2.1), and not accept the secret as 2487 proof of the client's identity. Without additional measures, such 2488 clients are subject to client impersonation (see Section 9.3.1). 2490 9.2. Registration of Native App Clients 2492 Except when using a mechanism like Dynamic Client Registration 2493 [RFC7591] to provision per-instance secrets, native apps are 2494 classified as public clients, as defined in Section 2.1; they MUST be 2495 registered with the authorization server as such. Authorization 2496 servers MUST record the client type in the client registration 2497 details in order to identify and process requests accordingly. 2499 Authorization servers MUST require clients to register their complete 2500 redirect URI (including the path component) and reject authorization 2501 requests that specify a redirect URI that doesn't exactly match the 2502 one that was registered; the exception is loopback redirects, where 2503 an exact match is required except for the port URI component. 2505 For private-use URI scheme-based redirects, authorization servers 2506 SHOULD enforce the requirement in Section 10.3.1 that clients use 2507 schemes that are reverse domain name based. At a minimum, any 2508 private-use URI scheme that doesn't contain a period character (".") 2509 SHOULD be rejected. 2511 In addition to the collision-resistant properties, requiring a URI 2512 scheme based on a domain name that is under the control of the app 2513 can help to prove ownership in the event of a dispute where two apps 2514 claim the same private-use URI scheme (where one app is acting 2515 maliciously). For example, if two apps claimed "com.example.app", 2516 the owner of "example.com" could petition the app store operator to 2517 remove the counterfeit app. Such a petition is harder to prove if a 2518 generic URI scheme was used. 2520 Authorization servers MAY request the inclusion of other platform- 2521 specific information, such as the app package or bundle name, or 2522 other information that may be useful for verifying the calling app's 2523 identity on operating systems that support such functions. 2525 9.3. Client Impersonation 2527 A malicious client can impersonate another client and obtain access 2528 to protected resources if the impersonated client fails to, or is 2529 unable to, keep its client credentials confidential. 2531 The authorization server MUST authenticate the client whenever 2532 possible. If the authorization server cannot authenticate the client 2533 due to the client's nature, the authorization server MUST require the 2534 registration of any redirect URI used for receiving authorization 2535 responses and SHOULD utilize other means to protect resource owners 2536 from such potentially malicious clients. For example, the 2537 authorization server can engage the resource owner to assist in 2538 identifying the client and its origin. 2540 The authorization server SHOULD enforce explicit resource owner 2541 authentication and provide the resource owner with information about 2542 the client and the requested authorization scope and lifetime. It is 2543 up to the resource owner to review the information in the context of 2544 the current client and to authorize or deny the request. 2546 The authorization server SHOULD NOT process repeated authorization 2547 requests automatically (without active resource owner interaction) 2548 without authenticating the client or relying on other measures to 2549 ensure that the repeated request comes from the original client and 2550 not an impersonator. 2552 9.3.1. Impersonation of Native Apps 2554 As stated above, the authorization server SHOULD NOT process 2555 authorization requests automatically without user consent or 2556 interaction, except when the identity of the client can be assured. 2557 This includes the case where the user has previously approved an 2558 authorization request for a given client id - unless the identity of 2559 the client can be proven, the request SHOULD be processed as if no 2560 previous request had been approved. 2562 Measures such as claimed "https" scheme redirects MAY be accepted by 2563 authorization servers as identity proof. Some operating systems may 2564 offer alternative platform-specific identity features that MAY be 2565 accepted, as appropriate. 2567 9.4. Access Tokens 2569 Access token credentials (as well as any confidential access token 2570 attributes) MUST be kept confidential in transit and storage, and 2571 only shared among the authorization server, the resource servers the 2572 access token is valid for, and the client to whom the access token is 2573 issued. Access token credentials MUST only be transmitted using TLS 2574 as described in Section 1.6 with server authentication as defined by 2575 [RFC2818]. 2577 The authorization server MUST ensure that access tokens cannot be 2578 generated, modified, or guessed to produce valid access tokens by 2579 unauthorized parties. 2581 9.4.1. Access Token Privilege Restriction 2583 The client SHOULD request access tokens with the minimal scope 2584 necessary. The authorization server SHOULD take the client identity 2585 into account when choosing how to honor the requested scope and MAY 2586 issue an access token with less rights than requested. 2588 The privileges associated with an access token SHOULD be restricted 2589 to the minimum required for the particular application or use case. 2590 This prevents clients from exceeding the privileges authorized by the 2591 resource owner. It also prevents users from exceeding their 2592 privileges authorized by the respective security policy. Privilege 2593 restrictions also help to reduce the impact of access token leakage. 2595 In particular, access tokens SHOULD be restricted to certain resource 2596 servers (audience restriction), preferably to a single resource 2597 server. To put this into effect, the authorization server associates 2598 the access token with certain resource servers and every resource 2599 server is obliged to verify, for every request, whether the access 2600 token sent with that request was meant to be used for that particular 2601 resource server. If not, the resource server MUST refuse to serve 2602 the respective request. Clients and authorization servers MAY 2603 utilize the parameters "scope" or "resource" as specified in 2604 [RFC8707], respectively, to determine the resource server they want 2605 to access. 2607 9.4.2. Access Token Replay Prevention 2609 Additionally, access tokens SHOULD be restricted to certain resources 2610 and actions on resource servers or resources. To put this into 2611 effect, the authorization server associates the access token with the 2612 respective resource and actions and every resource server is obliged 2613 to verify, for every request, whether the access token sent with that 2614 request was meant to be used for that particular action on the 2615 particular resource. If not, the resource server must refuse to 2616 serve the respective request. Clients and authorization servers MAY 2617 utilize the parameter "scope" and "authorization_details" as 2618 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2619 actions. 2621 Authorization and resource servers SHOULD use mechanisms for sender- 2622 constrained access tokens to prevent token replay as described in 2623 (#pop_tokens). A sender-constrained access token scopes the 2624 applicability of an access token to a certain sender. This sender is 2625 obliged to demonstrate knowledge of a certain secret as prerequisite 2626 for the acceptance of that access token at the recipient (e.g., a 2627 resource server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2628 RECOMMENDED. 2630 9.5. Refresh Tokens 2632 Authorization servers MAY issue refresh tokens to clients. 2634 Refresh tokens MUST be kept confidential in transit and storage, and 2635 shared only among the authorization server and the client to whom the 2636 refresh tokens were issued. The authorization server MUST maintain 2637 the binding between a refresh token and the client to whom it was 2638 issued. Refresh tokens MUST only be transmitted using TLS as 2639 described in Section 1.6 with server authentication as defined by 2640 [RFC2818]. 2642 The authorization server MUST verify the binding between the refresh 2643 token and client identity whenever the client identity can be 2644 authenticated. When client authentication is not possible, the 2645 authorization server SHOULD issue sender-constrained refresh tokens 2646 or use refresh token rotation as described in (#refreshing-an-access- 2647 token). 2649 The authorization server MUST ensure that refresh tokens cannot be 2650 generated, modified, or guessed to produce valid refresh tokens by 2651 unauthorized parties. 2653 9.6. Client Impersonating Resource Owner 2655 Resource servers may make access control decisions based on the 2656 identity of the resource owner as communicated in the "sub" claim 2657 returned by the authorization server in a token introspection 2658 response [RFC7662] or other mechanisms. If a client is able to 2659 choose its own "client_id" during registration with the authorization 2660 server, then there is a risk that it can register with the same "sub" 2661 value as a privileged user. A subsequent access token obtained under 2662 the client credentials grant may be mistaken for an access token 2663 authorized by the privileged user if the resource server does not 2664 perform additional checks. 2666 Authorization servers SHOULD NOT allow clients to influence their 2667 "client_id" or "sub" value or any other claim if that can cause 2668 confusion with a genuine resource owner. Where this cannot be 2669 avoided, authorization servers MUST provide other means for the 2670 resource server to distinguish between access tokens authorized by a 2671 resource owner from access tokens authorized by the client itself. 2673 9.7. Protecting Redirect-Based Flows 2675 When comparing client redirect URIs against pre-registered URIs, 2676 authorization servers MUST utilize exact string matching. This 2677 measure contributes to the prevention of leakage of authorization 2678 codes and access tokens (see (#insufficient_uri_validation)). It can 2679 also help to detect mix-up attacks (see (#mix_up)). 2681 Clients MUST NOT expose URLs that forward the user's browser to 2682 arbitrary URIs obtained from a query parameter ("open redirector"). 2683 Open redirectors can enable exfiltration of authorization codes and 2684 access tokens, see (#open_redirector_on_client). 2686 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2687 context, CSRF refers to requests to the redirection endpoint that do 2688 not originate at the authorization server, but a malicious third 2689 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2690 have ensured that the authorization server supports the 2691 "code_challenge" parameter MAY rely the CSRF protection provided by 2692 that mechanism. In OpenID Connect flows, the "nonce" parameter 2693 provides CSRF protection. Otherwise, one-time use CSRF tokens 2694 carried in the "state" parameter that are securely bound to the user 2695 agent MUST be used for CSRF protection (see (#csrf_countermeasures)). 2697 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2698 process redirect responses of the authorization server they sent the 2699 respective request to and from the same user agent this authorization 2700 request was initiated with. Clients MUST store the authorization 2701 server they sent an authorization request to and bind this 2702 information to the user agent and check that the authorization 2703 request was received from the correct authorization server. Clients 2704 MUST ensure that the subsequent access token request, if applicable, 2705 is sent to the same authorization server. Clients SHOULD use 2706 distinct redirect URIs for each authorization server as a means to 2707 identify the authorization server a particular response came from. 2709 An AS that redirects a request potentially containing user 2710 credentials MUST avoid forwarding these user credentials accidentally 2711 (see Section 9.7.2 for details). 2713 9.7.1. Loopback Redirect Considerations in Native Apps 2715 Loopback interface redirect URIs use the "http" scheme (i.e., without 2716 Transport Layer Security (TLS)). This is acceptable for loopback 2717 interface redirect URIs as the HTTP request never leaves the device. 2719 Clients should open the network port only when starting the 2720 authorization request and close it once the response is returned. 2722 Clients should listen on the loopback network interface only, in 2723 order to avoid interference by other network actors. 2725 While redirect URIs using localhost (i.e., 2726 "http://localhost:{port}/{path}") function similarly to loopback IP 2727 redirects described in Section 10.3.3, the use of "localhost" is NOT 2728 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2729 rather than "localhost" avoids inadvertently listening on network 2730 interfaces other than the loopback interface. It is also less 2731 susceptible to client-side firewalls and misconfigured host name 2732 resolution on the user's device. 2734 9.7.2. HTTP 307 Redirect 2736 An AS which redirects a request that potentially contains user 2737 credentials MUST NOT use the HTTP 307 status code for redirection. 2738 If an HTTP redirection (and not, for example, JavaScript) is used for 2739 such a request, AS SHOULD use HTTP status code 303 "See Other". 2741 At the authorization endpoint, a typical protocol flow is that the AS 2742 prompts the user to enter their credentials in a form that is then 2743 submitted (using the HTTP POST method) back to the authorization 2744 server. The AS checks the credentials and, if successful, redirects 2745 the user agent to the client's redirect URI. 2747 If the status code 307 were used for redirection, the user agent 2748 would send the user credentials via HTTP POST to the client. 2750 This discloses the sensitive credentials to the client. If the 2751 relying party is malicious, it can use the credentials to impersonate 2752 the user at the AS. 2754 The behavior might be unexpected for developers, but is defined in 2755 [RFC7231], Section 6.4.7. This status code does not require the user 2756 agent to rewrite the POST request to a GET request and thereby drop 2757 the form data in the POST request body. 2759 In the HTTP standard [RFC7231], only the status code 303 2760 unambigiously enforces rewriting the HTTP POST request to an HTTP GET 2761 request. For all other status codes, including the popular 302, user 2762 agents can opt not to rewrite POST to GET requests and therefore to 2763 reveal the user credentials to the client. (In practice, however, 2764 most user agents will only show this behaviour for 307 redirects.) 2766 Therefore, the RECOMMENDED status code for HTTP redirects is 303. 2768 9.8. Authorization Codes 2770 The transmission of authorization codes MUST be made over a secure 2771 channel, and the client MUST require the use of TLS with its redirect 2772 URI if the URI identifies a network resource. Since authorization 2773 codes are transmitted via user-agent redirections, they could 2774 potentially be disclosed through user-agent history and HTTP referrer 2775 headers. 2777 Authorization codes MUST be short lived and single-use. If the 2778 authorization server observes multiple attempts to exchange an 2779 authorization code for an access token, the authorization server 2780 SHOULD attempt to revoke all refresh and access tokens already 2781 granted based on the compromised authorization code. 2783 If the client can be authenticated, the authorization servers MUST 2784 authenticate the client and ensure that the authorization code was 2785 issued to the same client. 2787 Clients MUST prevent injection (replay) of authorization codes into 2788 the authorization response by attackers. To this end, using 2789 "code_challenge" and "code_verifier" is REQUIRED for clients and 2790 authorization servers MUST enforce their use, unless both of the 2791 following criteria are met: 2793 * The client is a confidential client. 2795 * In the specific deployment and the specific request, there is 2796 reasonable assurance for authorization server that the client 2797 implements the OpenID Connect "nonce" mechanism properly. 2799 In this case, using and enforcing "code_challenge" and 2800 "code_verifier" is still RECOMMENDED. 2802 The "code_challenge" or OpenID Connect "nonce" value MUST be 2803 transaction-specific and securely bound to the client and the user 2804 agent in which the transaction was started. If a transaction leads 2805 to an error, fresh values for "code_challenge" or "nonce" MUST be 2806 chosen. 2808 Historic note: Although PKCE [RFC7636] was originally designed as a 2809 mechanism to protect native apps, this advice applies to all kinds of 2810 OAuth clients, including web applications and other confidential 2811 clients. 2813 Clients SHOULD use code challenge methods that do not expose the 2814 "code_verifier" in the authorization request. Otherwise, attackers 2815 that can read the authorization request (cf. Attacker A4 in 2816 (#secmodel)) can break the security provided by this mechanism. 2817 Currently, "S256" is the only such method. 2819 When an authorization code arrives at the token endpoint, the 2820 authorization server MUST do the following check: 2822 1. If there was a "code_challenge" in the authorization request for 2823 which this code was issued, there must be a "code_verifier" in 2824 the token request, and it MUST be verified according to the steps 2825 in Section 4.1.3. (This is no change from the current behavior 2826 in [RFC7636].) 2828 2. If there was no "code_challenge" in the authorization request, 2829 any request to the token endpoint containing a "code_verifier" 2830 MUST be rejected. 2832 Authorization servers MUST support the "code_challenge" and 2833 "code_verifier" parameters. 2835 Authorization servers MUST provide a way to detect their support for 2836 the "code_challenge" mechanism. To this end, they MUST either (a) 2837 publish the element "code_challenge_methods_supported" in their AS 2838 metadata ([RFC8414]) containing the supported 2839 "code_challenge_method"s (which can be used by the client to detect 2840 support) or (b) provide a deployment-specific way to ensure or 2841 determine support by the AS. 2843 9.9. Request Confidentiality 2845 Access tokens, refresh tokens, authorization codes, and client 2846 credentials MUST NOT be transmitted in the clear. 2848 The "state" and "scope" parameters SHOULD NOT include sensitive 2849 client or resource owner information in plain text, as they can be 2850 transmitted over insecure channels or stored insecurely. 2852 9.10. Ensuring Endpoint Authenticity 2854 In order to prevent man-in-the-middle attacks, the authorization 2855 server MUST require the use of TLS with server authentication as 2856 defined by [RFC2818] for any request sent to the authorization and 2857 token endpoints. The client MUST validate the authorization server's 2858 TLS certificate as defined by [RFC6125] and in accordance with its 2859 requirements for server identity authentication. 2861 9.11. Credentials-Guessing Attacks 2863 The authorization server MUST prevent attackers from guessing access 2864 tokens, authorization codes, refresh tokens, resource owner 2865 passwords, and client credentials. 2867 The probability of an attacker guessing generated tokens (and other 2868 credentials not intended for handling by end-users) MUST be less than 2869 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2871 The authorization server MUST utilize other means to protect 2872 credentials intended for end-user usage. 2874 9.12. Phishing Attacks 2876 Wide deployment of this and similar protocols may cause end-users to 2877 become inured to the practice of being redirected to websites where 2878 they are asked to enter their passwords. If end-users are not 2879 careful to verify the authenticity of these websites before entering 2880 their credentials, it will be possible for attackers to exploit this 2881 practice to steal resource owners' passwords. 2883 Service providers should attempt to educate end-users about the risks 2884 phishing attacks pose and should provide mechanisms that make it easy 2885 for end-users to confirm the authenticity of their sites. Client 2886 developers should consider the security implications of how they 2887 interact with the user-agent (e.g., external, embedded), and the 2888 ability of the end-user to verify the authenticity of the 2889 authorization server. 2891 To reduce the risk of phishing attacks, the authorization servers 2892 MUST require the use of TLS on every endpoint used for end-user 2893 interaction. 2895 9.13. Fake External User-Agents in Native Apps 2897 The native app that is initiating the authorization request has a 2898 large degree of control over the user interface and can potentially 2899 present a fake external user-agent, that is, an embedded user-agent 2900 made to appear as an external user-agent. 2902 When all good actors are using external user-agents, the advantage is 2903 that it is possible for security experts to detect bad actors, as 2904 anyone faking an external user-agent is provably bad. On the other 2905 hand, if good and bad actors alike are using embedded user-agents, 2906 bad actors don't need to fake anything, making them harder to detect. 2907 Once a malicious app is detected, it may be possible to use this 2908 knowledge to blacklist the app's signature in malware scanning 2909 software, take removal action (in the case of apps distributed by app 2910 stores) and other steps to reduce the impact and spread of the 2911 malicious app. 2913 Authorization servers can also directly protect against fake external 2914 user-agents by requiring an authentication factor only available to 2915 true external user-agents. 2917 Users who are particularly concerned about their security when using 2918 in-app browser tabs may also take the additional step of opening the 2919 request in the full browser from the in-app browser tab and complete 2920 the authorization there, as most implementations of the in-app 2921 browser tab pattern offer such functionality. 2923 9.14. Malicious External User-Agents in Native Apps 2925 If a malicious app is able to configure itself as the default handler 2926 for "https" scheme URIs in the operating system, it will be able to 2927 intercept authorization requests that use the default browser and 2928 abuse this position of trust for malicious ends such as phishing the 2929 user. 2931 This attack is not confined to OAuth; a malicious app configured in 2932 this way would present a general and ongoing risk to the user beyond 2933 OAuth usage by native apps. Many operating systems mitigate this 2934 issue by requiring an explicit user action to change the default 2935 handler for "http" and "https" scheme URIs. 2937 9.15. Cross-Site Request Forgery 2939 An attacker might attempt to inject a request to the redirect URI of 2940 the legitimate client on the victim's device, e.g., to cause the 2941 client to access resources under the attacker's control. This is a 2942 variant of an attack known as Cross-Site Request Forgery (CSRF). 2944 The traditional countermeasure are CSRF tokens that are bound to the 2945 user agent and passed in the "state" parameter to the authorization 2946 server as described in [RFC6819]. The same protection is provided by 2947 the "code_verifier" parameter or the OpenID Connect "nonce" value. 2949 When using "code_verifier" instead of "state" or "nonce" for CSRF 2950 protection, it is important to note that: 2952 * Clients MUST ensure that the AS supports the 2953 "code_challenge_method" intended to be used by the client. If an 2954 authorization server does not support the requested method, 2955 "state" or "nonce" MUST be used for CSRF protection instead. 2957 * If "state" is used for carrying application state, and integrity 2958 of its contents is a concern, clients MUST protect "state" against 2959 tampering and swapping. This can be achieved by binding the 2960 contents of state to the browser session and/or signed/encrypted 2961 state values [I-D.bradley-oauth-jwt-encoded-state]. 2963 AS therefore MUST provide a way to detect their supported code 2964 challenge methods either via AS metadata according to [RFC8414] or 2965 provide a deployment-specific way to ensure or determine support. 2967 9.16. Clickjacking 2969 As described in Section 4.4.1.9 of [RFC6819], the authorization 2970 request is susceptible to clickjacking. An attacker can use this 2971 vector to obtain the user's authentication credentials, change the 2972 scope of access granted to the client, and potentially access the 2973 user's resources. 2975 Authorization servers MUST prevent clickjacking attacks. Multiple 2976 countermeasures are described in [RFC6819], including the use of the 2977 X-Frame-Options HTTP response header field and frame-busting 2978 JavaScript. In addition to those, authorization servers SHOULD also 2979 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2981 To be effective, CSP must be used on the authorization endpoint and, 2982 if applicable, other endpoints used to authenticate the user and 2983 authorize the client (e.g., the device authorization endpoint, login 2984 pages, error pages, etc.). This prevents framing by unauthorized 2985 origins in user agents that support CSP. The client MAY permit being 2986 framed by some other origin than the one used in its redirection 2987 endpoint. For this reason, authorization servers SHOULD allow 2988 administrators to configure allowed origins for particular clients 2989 and/or for clients to register these dynamically. 2991 Using CSP allows authorization servers to specify multiple origins in 2992 a single response header field and to constrain these using flexible 2993 patterns (see [CSP-2] for details). Level 2 of this standard 2994 provides a robust mechanism for protecting against clickjacking by 2995 using policies that restrict the origin of frames (using "frame- 2996 ancestors") together with those that restrict the sources of scripts 2997 allowed to execute on an HTML page (by using "script-src"). A non- 2998 normative example of such a policy is shown in the following listing: 3000 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 3001 https://ext.example.org:8000 Content-Security-Policy: script-src 3002 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 3003 Because some user agents do not support [CSP-2], this technique 3004 SHOULD be combined with others, including those described in 3005 [RFC6819], unless such legacy user agents are explicitly unsupported 3006 by the authorization server. Even in such cases, additional 3007 countermeasures SHOULD still be employed. 3009 9.17. Code Injection and Input Validation 3011 A code injection attack occurs when an input or otherwise external 3012 variable is used by an application unsanitized and causes 3013 modification to the application logic. This may allow an attacker to 3014 gain access to the application device or its data, cause denial of 3015 service, or introduce a wide range of malicious side-effects. 3017 The authorization server and client MUST sanitize (and validate when 3018 possible) any value received - in particular, the value of the 3019 "state" and "redirect_uri" parameters. 3021 9.18. Open Redirectors 3023 The following attacks can occur when an AS or client has an open 3024 redirector. An open redirector is an endpoint that forwards a user's 3025 browser to an arbitrary URI obtained from a query parameter. 3027 9.18.1. Client as Open Redirector 3029 Clients MUST NOT expose open redirectors. Attackers may use open 3030 redirectors to produce URLs pointing to the client and utilize them 3031 to exfiltrate authorization codes and access tokens, as described in 3032 (#redir_uri_open_redir). Another abuse case is to produce URLs that 3033 appear to point to the client. This might trick users into trusting 3034 the URL and follow it in their browser. This can be abused for 3035 phishing. 3037 In order to prevent open redirection, clients should only redirect if 3038 the target URLs are whitelisted or if the origin and integrity of a 3039 request can be authenticated. Countermeasures against open 3040 redirection are described by OWASP [owasp_redir]. 3042 9.18.2. Authorization Server as Open Redirector 3044 Just as with clients, attackers could try to utilize a user's trust 3045 in the authorization server (and its URL in particular) for 3046 performing phishing attacks. OAuth authorization servers regularly 3047 redirect users to other web sites (the clients), but must do so in a 3048 safe way. 3050 Section 4.1.2.1 already prevents open redirects by stating that the 3051 AS MUST NOT automatically redirect the user agent in case of an 3052 invalid combination of "client_id" and "redirect_uri". 3054 However, an attacker could also utilize a correctly registered 3055 redirect URI to perform phishing attacks. The attacker could, for 3056 example, register a client via dynamic client registration [RFC7591] 3057 and intentionally send an erroneous authorization request, e.g., by 3058 using an invalid scope value, thus instructing the AS to redirect the 3059 user agent to its phishing site. 3061 The AS MUST take precautions to prevent this threat. Based on its 3062 risk assessment, the AS needs to decide whether it can trust the 3063 redirect URI and SHOULD only automatically redirect the user agent if 3064 it trusts the redirect URI. If the URI is not trusted, the AS MAY 3065 inform the user and rely on the user to make the correct decision. 3067 9.19. Authorization Server Mix-Up Mitigation in Native Apps 3069 (TODO: merge this with the regular mix-up section when it is brought 3070 in) 3072 To protect against a compromised or malicious authorization server 3073 attacking another authorization server used by the same app, it is 3074 REQUIRED that a unique redirect URI is used for each authorization 3075 server used by the app (for example, by varying the path component), 3076 and that authorization responses are rejected if the redirect URI 3077 they were received on doesn't match the redirect URI in an outgoing 3078 authorization request. 3080 The native app MUST store the redirect URI used in the authorization 3081 request with the authorization session data (i.e., along with "state" 3082 and other related data) and MUST verify that the URI on which the 3083 authorization response was received exactly matches it. 3085 The requirement of Section 9.2, specifically that authorization 3086 servers reject requests with URIs that don't match what was 3087 registered, is also required to prevent such attacks. 3089 9.20. Embedded User Agents in Native Apps 3091 Embedded user-agents are a technically possible method for 3092 authorizing native apps. These embedded user-agents are unsafe for 3093 use by third parties to the authorization server by definition, as 3094 the app that hosts the embedded user-agent can access the user's full 3095 authentication credential, not just the OAuth authorization grant 3096 that was intended for the app. 3098 In typical web-view-based implementations of embedded user-agents, 3099 the host application can record every keystroke entered in the login 3100 form to capture usernames and passwords, automatically submit forms 3101 to bypass user consent, and copy session cookies and use them to 3102 perform authenticated actions as the user. 3104 Even when used by trusted apps belonging to the same party as the 3105 authorization server, embedded user-agents violate the principle of 3106 least privilege by having access to more powerful credentials than 3107 they need, potentially increasing the attack surface. 3109 Encouraging users to enter credentials in an embedded user-agent 3110 without the usual address bar and visible certificate validation 3111 features that browsers have makes it impossible for the user to know 3112 if they are signing in to the legitimate site; even when they are, it 3113 trains them that it's OK to enter credentials without validating the 3114 site first. 3116 Aside from the security concerns, embedded user-agents do not share 3117 the authentication state with other apps or the browser, requiring 3118 the user to log in for every authorization request, which is often 3119 considered an inferior user experience. 3121 9.21. Other Recommendations 3123 Authorization servers SHOULD NOT allow clients to influence their 3124 "client_id" or "sub" value or any other claim if that can cause 3125 confusion with a genuine resource owner (see 3126 (#client_impersonating)). 3128 10. Native Applications 3130 Native applications are clients installed and executed on the device 3131 used by the resource owner (i.e., desktop application, native mobile 3132 application). Native applications require special consideration 3133 related to security, platform capabilities, and overall end-user 3134 experience. 3136 The authorization endpoint requires interaction between the client 3137 and the resource owner's user-agent. The best current practice is to 3138 perform the OAuth authorization request in an external user-agent 3139 (typically the browser) rather than an embedded user-agent (such as 3140 one implemented with web-views). 3142 The native application can capture the response from the 3143 authorization server using a redirect URI with a scheme registered 3144 with the operating system to invoke the client as the handler, manual 3145 copy-and-paste of the credentials, running a local web server, 3146 installing a user-agent extension, or by providing a redirect URI 3147 identifying a server-hosted resource under the client's control, 3148 which in turn makes the response available to the native application. 3150 Previously, it was common for native apps to use embedded user-agents 3151 (commonly implemented with web-views) for OAuth authorization 3152 requests. That approach has many drawbacks, including the host app 3153 being able to copy user credentials and cookies as well as the user 3154 needing to authenticate from scratch in each app. See Section 9.20 3155 for a deeper analysis of the drawbacks of using embedded user-agents 3156 for OAuth. 3158 Native app authorization requests that use the browser are more 3159 secure and can take advantage of the user's authentication state. 3160 Being able to use the existing authentication session in the browser 3161 enables single sign-on, as users don't need to authenticate to the 3162 authorization server each time they use a new app (unless required by 3163 the authorization server policy). 3165 Supporting authorization flows between a native app and the browser 3166 is possible without changing the OAuth protocol itself, as the OAuth 3167 authorization request and response are already defined in terms of 3168 URIs. This encompasses URIs that can be used for inter-app 3169 communication. Some OAuth server implementations that assume all 3170 clients are confidential web clients will need to add an 3171 understanding of public native app clients and the types of redirect 3172 URIs they use to support this best practice. 3174 10.1. Using Inter-App URI Communication for OAuth in Native Apps 3176 Just as URIs are used for OAuth on the web to initiate the 3177 authorization request and return the authorization response to the 3178 requesting website, URIs can be used by native apps to initiate the 3179 authorization request in the device's browser and return the response 3180 to the requesting native app. 3182 By adopting the same methods used on the web for OAuth, benefits seen 3183 in the web context like the usability of a single sign-on session and 3184 the security of a separate authentication context are likewise gained 3185 in the native app context. Reusing the same approach also reduces 3186 the implementation complexity and increases interoperability by 3187 relying on standards-based web flows that are not specific to a 3188 particular platform. 3190 Native apps MUST use an external user-agent to perform OAuth 3191 authorization requests. This is achieved by opening the 3192 authorization request in the browser (detailed in Section 10.2) and 3193 using a redirect URI that will return the authorization response back 3194 to the native app (defined in Section 10.3). 3196 10.2. Initiating the Authorization Request from a Native App 3198 Native apps needing user authorization create an authorization 3199 request URI with the authorization code grant type per Section 4.1 3200 using a redirect URI capable of being received by the native app. 3202 The function of the redirect URI for a native app authorization 3203 request is similar to that of a web-based authorization request. 3204 Rather than returning the authorization response to the OAuth 3205 client's server, the redirect URI used by a native app returns the 3206 response to the app. Several options for a redirect URI that will 3207 return the authorization response to the native app in different 3208 platforms are documented in Section 10.3. Any redirect URI that 3209 allows the app to receive the URI and inspect its parameters is 3210 viable. 3212 After constructing the authorization request URI, the app uses 3213 platform-specific APIs to open the URI in an external user-agent. 3214 Typically, the external user-agent used is the default browser, that 3215 is, the application configured for handling "http" and "https" scheme 3216 URIs on the system; however, different browser selection criteria and 3217 other categories of external user-agents MAY be used. 3219 This best practice focuses on the browser as the RECOMMENDED external 3220 user-agent for native apps. An external user-agent designed 3221 specifically for user authorization and capable of processing 3222 authorization requests and responses like a browser MAY also be used. 3223 Other external user-agents, such as a native app provided by the 3224 authorization server may meet the criteria set out in this best 3225 practice, including using the same redirect URI properties, but their 3226 use is out of scope for this specification. 3228 Some platforms support a browser feature known as "in-app browser 3229 tabs", where an app can present a tab of the browser within the app 3230 context without switching apps, but still retain key benefits of the 3231 browser such as a shared authentication state and security context. 3232 On platforms where they are supported, it is RECOMMENDED, for 3233 usability reasons, that apps use in-app browser tabs for the 3234 authorization request. 3236 10.3. Receiving the Authorization Response in a Native App 3238 There are several redirect URI options available to native apps for 3239 receiving the authorization response from the browser, the 3240 availability and user experience of which varies by platform. 3242 To fully support native apps, authorization servers MUST offer at 3243 least the three redirect URI options described in the following 3244 subsections to native apps. Native apps MAY use whichever redirect 3245 option suits their needs best, taking into account platform-specific 3246 implementation details. 3248 10.3.1. Private-Use URI Scheme Redirection 3250 Many mobile and desktop computing platforms support inter-app 3251 communication via URIs by allowing apps to register private-use URI 3252 schemes (sometimes colloquially referred to as "custom URL schemes") 3253 like "com.example.app". When the browser or another app attempts to 3254 load a URI with a private-use URI scheme, the app that registered it 3255 is launched to handle the request. 3257 To perform an authorization request with a private-use URI scheme 3258 redirect, the native app launches the browser with a standard 3259 authorization request, but one where the redirect URI utilizes a 3260 private-use URI scheme it registered with the operating system. 3262 When choosing a URI scheme to associate with the app, apps MUST use a 3263 URI scheme based on a domain name under their control, expressed in 3264 reverse order, as recommended by Section 3.8 of [RFC7595] for 3265 private-use URI schemes. 3267 For example, an app that controls the domain name "app.example.com" 3268 can use "com.example.app" as their scheme. Some authorization 3269 servers assign client identifiers based on domain names, for example, 3270 "client1234.usercontent.example.net", which can also be used as the 3271 domain name for the scheme when reversed in the same manner. A 3272 scheme such as "myapp", however, would not meet this requirement, as 3273 it is not based on a domain name. 3275 When there are multiple apps by the same publisher, care must be 3276 taken so that each scheme is unique within that group. On platforms 3277 that use app identifiers based on reverse-order domain names, those 3278 identifiers can be reused as the private-use URI scheme for the OAuth 3279 redirect to help avoid this problem. 3281 Following the requirements of Section 3.2 of [RFC3986], as there is 3282 no naming authority for private-use URI scheme redirects, only a 3283 single slash ("/") appears after the scheme component. A complete 3284 example of a redirect URI utilizing a private-use URI scheme is: 3286 com.example.app:/oauth2redirect/example-provider 3288 When the authorization server completes the request, it redirects to 3289 the client's redirect URI as it would normally. As the redirect URI 3290 uses a private-use URI scheme, it results in the operating system 3291 launching the native app, passing in the URI as a launch parameter. 3292 Then, the native app uses normal processing for the authorization 3293 response. 3295 10.3.2. Claimed "https" Scheme URI Redirection 3297 Some operating systems allow apps to claim "https" scheme [RFC7230] 3298 URIs in the domains they control. When the browser encounters a 3299 claimed URI, instead of the page being loaded in the browser, the 3300 native app is launched with the URI supplied as a launch parameter. 3302 Such URIs can be used as redirect URIs by native apps. They are 3303 indistinguishable to the authorization server from a regular web- 3304 based client redirect URI. An example is: 3306 https://app.example.com/oauth2redirect/example-provider 3308 As the redirect URI alone is not enough to distinguish public native 3309 app clients from confidential web clients, it is REQUIRED in 3310 Section 9.2 that the client type be recorded during client 3311 registration to enable the server to determine the client type and 3312 act accordingly. 3314 App-claimed "https" scheme redirect URIs have some advantages 3315 compared to other native app redirect options in that the identity of 3316 the destination app is guaranteed to the authorization server by the 3317 operating system. For this reason, native apps SHOULD use them over 3318 the other options where possible. 3320 10.3.3. Loopback Interface Redirection 3322 Native apps that are able to open a port on the loopback network 3323 interface without needing special permissions (typically, those on 3324 desktop operating systems) can use the loopback interface to receive 3325 the OAuth redirect. 3327 Loopback redirect URIs use the "http" scheme and are constructed with 3328 the loopback IP literal and whatever port the client is listening on. 3330 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3331 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3332 IPv4 loopback interface with a randomly assigned port: 3334 http://127.0.0.1:51004/oauth2redirect/example-provider 3336 An example redirect using the IPv6 loopback interface with a randomly 3337 assigned port: 3339 http://[::1]:61023/oauth2redirect/example-provider 3341 The authorization server MUST allow any port to be specified at the 3342 time of the request for loopback IP redirect URIs, to accommodate 3343 clients that obtain an available ephemeral port from the operating 3344 system at the time of the request. 3346 Clients SHOULD NOT assume that the device supports a particular 3347 version of the Internet Protocol. It is RECOMMENDED that clients 3348 attempt to bind to the loopback interface using both IPv4 and IPv6 3349 and use whichever is available. 3351 11. Browser-Based Apps 3353 Browser-based apps are are clients that run in a web browser, 3354 typically written in JavaScript, also known as "single-page apps". 3355 These types of apps have particular security considerations similar 3356 to native apps. 3358 TODO: Bring in the normative text of the browser-based apps BCP when 3359 it is finalized. 3361 12. Differences from OAuth 2.0 3363 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3364 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3365 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3366 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3367 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3368 ([RFC6750]). 3370 Where a later draft updates or obsoletes functionality found in the 3371 original [RFC6749], that functionality in this draft is updated with 3372 the normative changes described in a later draft, or removed 3373 entirely. 3375 A non-normative list of changes from OAuth 2.0 is listed below: 3377 * The authorization code grant is extended with the functionality 3378 from PKCE ([RFC7636]) such that the default method of using the 3379 authorization code grant according to this specification requires 3380 the addition of the PKCE parameters 3382 * Redirect URIs must be compared using exact string matching as per 3383 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3385 * The Implicit grant ("response_type=token") is omitted from this 3386 specification as per Section 2.1.2 of 3387 [I-D.ietf-oauth-security-topics] 3389 * The Resource Owner Password Credentials grant is omitted from this 3390 specification as per Section 2.4 of 3391 [I-D.ietf-oauth-security-topics] 3393 * Bearer token usage omits the use of bearer tokens in the query 3394 string of URIs as per Section 4.3.2 of 3395 [I-D.ietf-oauth-security-topics] 3397 * Refresh tokens should either be sender-constrained or one-time use 3398 as per Section 4.12.2 of [I-D.ietf-oauth-security-topics] 3400 13. IANA Considerations 3402 This document does not require any IANA actions. 3404 All referenced registries are defined by RFC6749 and related 3405 documents that this work is based upon. No changes to those 3406 registries are required by this specification. 3408 14. References 3410 14.1. Normative References 3412 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 3413 "Recommendations for Secure Use of Transport Layer 3414 Security (TLS)", n.d.. 3416 [I-D.ietf-oauth-security-topics] 3417 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3418 "OAuth 2.0 Security Best Current Practice", Work in 3419 Progress, Internet-Draft, draft-ietf-oauth-security- 3420 topics-16, 5 October 2020, . 3423 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3424 Requirement Levels", BCP 14, RFC 2119, 3425 DOI 10.17487/RFC2119, March 1997, 3426 . 3428 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3429 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3430 Authentication: Basic and Digest Access Authentication", 3431 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3432 . 3434 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3435 DOI 10.17487/RFC2818, May 2000, 3436 . 3438 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3439 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3440 2003, . 3442 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3443 Resource Identifier (URI): Generic Syntax", STD 66, 3444 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3445 . 3447 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3448 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3449 . 3451 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3452 Specifications: ABNF", STD 68, RFC 5234, 3453 DOI 10.17487/RFC5234, January 2008, 3454 . 3456 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3457 Housley, R., and W. Polk, "Internet X.509 Public Key 3458 Infrastructure Certificate and Certificate Revocation List 3459 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3460 . 3462 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3463 Verification of Domain-Based Application Service Identity 3464 within Internet Public Key Infrastructure Using X.509 3465 (PKIX) Certificates in the Context of Transport Layer 3466 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3467 2011, . 3469 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3470 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3471 . 3473 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3474 Framework: Bearer Token Usage", RFC 6750, 3475 DOI 10.17487/RFC6750, October 2012, 3476 . 3478 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3479 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3480 2014, . 3482 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3483 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3484 DOI 10.17487/RFC7231, June 2014, 3485 . 3487 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3488 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3489 RFC 7234, DOI 10.17487/RFC7234, June 2014, 3490 . 3492 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3493 and Registration Procedures for URI Schemes", BCP 35, 3494 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3495 . 3497 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3498 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3499 May 2017, . 3501 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3502 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3503 . 3505 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3506 Interchange Format", STD 90, RFC 8259, 3507 DOI 10.17487/RFC8259, December 2017, 3508 . 3510 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3511 Standard Code for Information Interchange, ANSI X3.4", 3512 1986. 3514 [W3C.REC-html401-19991224] 3515 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3516 Specification", World Wide Web Consortium Recommendation 3517 REC-html401-19991224, 24 December 1999, 3518 . 3520 [W3C.REC-xml-20081126] 3521 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3522 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3523 Edition)", World Wide Web Consortium Recommendation REC- 3524 xml-20081126, 26 November 2008, 3525 . 3527 14.2. Informative References 3529 [CSP-2] "Content Security Policy Level 2", December 2016, 3530 . 3532 [I-D.bradley-oauth-jwt-encoded-state] 3533 Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding 3534 claims in the OAuth 2 state parameter using a JWT", Work 3535 in Progress, Internet-Draft, draft-bradley-oauth-jwt- 3536 encoded-state-09, 4 November 2018, . 3540 [I-D.ietf-oauth-access-token-jwt] 3541 Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 3542 Access Tokens", Work in Progress, Internet-Draft, draft- 3543 ietf-oauth-access-token-jwt-11, 22 January 2021, 3544 . 3547 [I-D.ietf-oauth-browser-based-apps] 3548 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3549 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3550 browser-based-apps-07, 2 October 2020, 3551 . 3554 [I-D.ietf-oauth-dpop] 3555 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 3556 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 3557 of-Possession at the Application Layer (DPoP)", Work in 3558 Progress, Internet-Draft, draft-ietf-oauth-dpop-02, 18 3559 November 2020, . 3562 [I-D.ietf-oauth-par] 3563 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 3564 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 3565 Work in Progress, Internet-Draft, draft-ietf-oauth-par-05, 3566 14 December 2020, . 3569 [I-D.ietf-oauth-rar] 3570 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3571 Rich Authorization Requests", Work in Progress, Internet- 3572 Draft, draft-ietf-oauth-rar-03, 18 October 2020, 3573 . 3576 [I-D.ietf-oauth-token-binding] 3577 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 3578 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3579 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3580 . 3583 [NIST800-63] 3584 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3585 Gupta, S., and E. Nabbus, "NIST Special Publication 3586 800-63-1, INFORMATION SECURITY", December 2011, 3587 . 3589 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3590 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3591 and B. Boyer, "Online Multimedia Authorization Protocol: 3592 An Industry Standard for Authorized Access to Internet 3593 Multimedia Resources", April 2012, 3594 . 3596 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3597 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3598 . 3600 [OpenID.Messages] 3601 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3602 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3603 June 2012, . 3606 [owasp_redir] 3607 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3608 Forwards", 2020, 3609 . 3612 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3613 DOI 10.17487/RFC6265, April 2011, 3614 . 3616 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3617 Threat Model and Security Considerations", RFC 6819, 3618 DOI 10.17487/RFC6819, January 2013, 3619 . 3621 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 3622 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 3623 August 2013, . 3625 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3626 Protocol (HTTP/1.1): Message Syntax and Routing", 3627 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3628 . 3630 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3631 Protocol (HTTP/1.1): Authentication", RFC 7235, 3632 DOI 10.17487/RFC7235, June 2014, 3633 . 3635 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3636 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3637 . 3639 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3640 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3641 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3642 . 3644 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 3645 "OAuth 2.0 Dynamic Client Registration Management 3646 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 3647 . 3649 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3650 for Code Exchange by OAuth Public Clients", RFC 7636, 3651 DOI 10.17487/RFC7636, September 2015, 3652 . 3654 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 3655 RFC 7662, DOI 10.17487/RFC7662, October 2015, 3656 . 3658 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3659 Authorization Server Metadata", RFC 8414, 3660 DOI 10.17487/RFC8414, June 2018, 3661 . 3663 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 3664 "OAuth 2.0 Device Authorization Grant", RFC 8628, 3665 DOI 10.17487/RFC8628, August 2019, 3666 . 3668 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3669 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3670 and Certificate-Bound Access Tokens", RFC 8705, 3671 DOI 10.17487/RFC8705, February 2020, 3672 . 3674 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3675 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3676 February 2020, . 3678 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3680 This section provides Augmented Backus-Naur Form (ABNF) syntax 3681 descriptions for the elements defined in this specification using the 3682 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3683 code points [W3C.REC-xml-20081126]; these characters are typically 3684 encoded in UTF-8. Elements are presented in the order first defined. 3686 Some of the definitions that follow use the "URI-reference" 3687 definition from [RFC3986]. 3689 Some of the definitions that follow use these common definitions: 3691 VSCHAR = %x20-7E 3692 NQCHAR = %x21 / %x23-5B / %x5D-7E 3693 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3694 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3695 %xE000-FFFD / %x10000-10FFFF 3697 (The UNICODECHARNOCRLF definition is based upon the Char definition 3698 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3699 Return and Linefeed characters.) 3701 A.1. "client_id" Syntax 3703 The "client_id" element is defined in Section 2.3.1: 3705 client-id = *VSCHAR 3707 A.2. "client_secret" Syntax 3709 The "client_secret" element is defined in Section 2.3.1: 3711 client-secret = *VSCHAR 3713 A.3. "response_type" Syntax 3715 The "response_type" element is defined in Section 3.1.1 and 3716 Section 8.4: 3718 response-type = response-name *( SP response-name ) 3719 response-name = 1*response-char 3720 response-char = "_" / DIGIT / ALPHA 3722 A.4. "scope" Syntax 3724 The "scope" element is defined in Section 3.3: 3726 scope = scope-token *( SP scope-token ) 3727 scope-token = 1*NQCHAR 3729 A.5. "state" Syntax 3731 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3732 Section 4.1.2.1: 3734 state = 1*VSCHAR 3736 A.6. "redirect_uri" Syntax 3738 The "redirect_uri" element is defined in Section 4.1.1, and 3739 Section 4.1.3: 3741 redirect-uri = URI-reference 3743 A.7. "error" Syntax 3745 The "error" element is defined in Sections Section 4.1.2.1, 3746 Section 5.2, 7.2, and 8.5: 3748 error = 1*NQSCHAR 3750 A.8. "error_description" Syntax 3752 The "error_description" element is defined in Sections 3753 Section 4.1.2.1, Section 5.2, and Section 7.3: 3755 error-description = 1*NQSCHAR 3757 A.9. "error_uri" Syntax 3759 The "error_uri" element is defined in Sections Section 4.1.2.1, 3760 Section 5.2, and 7.2: 3762 error-uri = URI-reference 3764 A.10. "grant_type" Syntax 3766 The "grant_type" element is defined in Sections Section 4.1.3, 3767 Section 4.2.3, Section 4.2.2, Section 4.3, and Section 6: 3769 grant-type = grant-name / URI-reference 3770 grant-name = 1*name-char 3771 name-char = "-" / "." / "_" / DIGIT / ALPHA 3773 A.11. "code" Syntax 3775 The "code" element is defined in Section 4.1.3: 3777 code = 1*VSCHAR 3779 A.12. "access_token" Syntax 3781 The "access_token" element is defined in Section 4.2.3 and 3782 Section 5.1: 3784 access-token = 1*VSCHAR 3786 A.13. "token_type" Syntax 3788 The "token_type" element is defined in Section 5.1, and Section 8.1: 3790 token-type = type-name / URI-reference 3791 type-name = 1*name-char 3792 name-char = "-" / "." / "_" / DIGIT / ALPHA 3794 A.14. "expires_in" Syntax 3796 The "expires_in" element is defined in Section 5.1: 3798 expires-in = 1*DIGIT 3800 A.15. "refresh_token" Syntax 3802 The "refresh_token" element is defined in Section 5.1 and Section 6: 3804 refresh-token = 1*VSCHAR 3806 A.16. Endpoint Parameter Syntax 3808 The syntax for new endpoint parameters is defined in Section 8.2: 3810 param-name = 1*name-char 3811 name-char = "-" / "." / "_" / DIGIT / ALPHA 3813 A.17. "code_verifier" Syntax 3815 ABNF for "code_verifier" is as follows. 3817 code-verifier = 43*128unreserved 3818 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3819 ALPHA = %x41-5A / %x61-7A 3820 DIGIT = %x30-39 3822 A.18. "code_challenge" Syntax 3824 ABNF for "code_challenge" is as follows. 3826 code-challenge = 43*128unreserved 3827 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3828 ALPHA = %x41-5A / %x61-7A 3829 DIGIT = %x30-39 3831 Appendix B. Use of application/x-www-form-urlencoded Media Type 3833 At the time of publication of this specification, the "application/x- 3834 www-form-urlencoded" media type was defined in Section 17.13.4 of 3835 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 3836 Types registry (http://www.iana.org/assignments/media-types 3837 (http://www.iana.org/assignments/media-types)). Furthermore, that 3838 definition is incomplete, as it does not consider non-US-ASCII 3839 characters. 3841 To address this shortcoming when generating payloads using this media 3842 type, names and values MUST be encoded using the UTF-8 character 3843 encoding scheme [RFC3629] first; the resulting octet sequence then 3844 needs to be further encoded using the escaping rules defined in 3845 [W3C.REC-html401-19991224]. 3847 When parsing data from a payload using this media type, the names and 3848 values resulting from reversing the name/value encoding consequently 3849 need to be treated as octet sequences, to be decoded using the UTF-8 3850 character encoding scheme. 3852 For example, the value consisting of the six Unicode code points (1) 3853 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3854 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3855 SIGN) would be encoded into the octet sequence below (using 3856 hexadecimal notation): 3858 20 25 26 2B C2 A3 E2 82 AC 3860 and then represented in the payload as: 3862 +%25%26%2B%C2%A3%E2%82%AC 3864 Appendix C. Extensions 3866 Below is a list of well-established extensions at the time of 3867 publication: 3869 * [RFC8628]: OAuth 2.0 Device Authorization Grant 3871 - The Device Authorization Grant (formerly known as the Device 3872 Flow) is an extension that enables devices with no browser or 3873 limited input capability to obtain an access token. This is 3874 commonly used by smart TV apps, or devices like hardware video 3875 encoders that can stream video to a streaming video service. 3877 * [RFC8414]: Authorization Server Metadata 3879 - Authorization Server Metadata (also known as OAuth Discovery) 3880 defines an endpoint clients can use to look up the information 3881 needed to interact with a particular OAuth server, such as the 3882 location of the authorization and token endpoints and the 3883 supported grant types. 3885 * [RFC8707]: Resource Indicators 3887 - Provides a way for the client to explicitly signal to the 3888 authorization server where it intends to use the access token 3889 it is requesting. 3891 * [RFC7591]: Dynamic Client Registration 3892 - Dynamic Client Registration provides a mechanism for 3893 programmatically registering clients with an authorization 3894 server. 3896 * [RFC7592]: Dynamic Client Management 3898 - Dynamic Client Management provides a mechanism for updating 3899 dynamically registered client information. 3901 * [I-D.ietf-oauth-access-token-jwt]: JSON Web Token (JWT) Profile 3902 for OAuth 2.0 Access Tokens 3904 - This specification defines a profile for issuing OAuth access 3905 tokens in JSON Web Token (JWT) format. 3907 * [RFC8705]: Mutual TLS 3909 - Mutual TLS describes a mechanism of binding access tokens and 3910 refresh tokens to the clients they were issued to, as well as a 3911 client authentication mechanism, via TLS certificate 3912 authentication. 3914 * [RFC7662]: Token Introspection 3916 - The Token Introspection extension defines a mechanism for 3917 resource servers to obtain information about access tokens. 3919 * [RFC7009]: Token Revocation 3921 - The Token Revocation extension defines a mechanism for clients 3922 to indicate to the authorization server that an access token is 3923 no longer needed. 3925 * [I-D.ietf-oauth-par]: Pushed Authorization Requests 3927 - The Pushed Authorization Requsts extension describes a 3928 technique of initiating an OAuth flow from the back channel, 3929 providing better security and more flexibility for building 3930 complex authorization requests. 3932 * [I-D.ietf-oauth-rar]: Rich Authorization Requests 3934 - Rich Authorization Requests specifies a new parameter 3935 "authorization_details" that is used to carry fine-grained 3936 authorization data in the OAuth authorization request. 3938 Appendix D. Acknowledgements 3940 TBD 3942 Authors' Addresses 3944 Dick Hardt 3945 SignIn.Org 3947 Email: dick.hardt@gmail.com 3949 Aaron Parecki 3950 Okta 3952 Email: aaron@parecki.com 3953 URI: https://aaronparecki.com 3955 Torsten Lodderstedt 3956 yes.com 3958 Email: torsten@lodderstedt.net