idnits 2.17.00 (12 Aug 2021) /tmp/idnits20159/draft-ietf-oauth-v2-1-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 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 (1 February 2021) is 474 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 1151, but not defined == Missing Reference: '0-9' is mentioned on line 1151, but not defined == Unused Reference: 'RFC8446' is defined on line 3511, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-19) exists of draft-ietf-oauth-security-topics-16 ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Downref: Normative reference to an Informational RFC: RFC 2818 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: draft-ietf-oauth-access-token-jwt has been published as RFC 9068 == Outdated reference: A later version (-09) exists of draft-ietf-oauth-browser-based-apps-07 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-dpop-02 == Outdated reference: draft-ietf-oauth-par has been published as RFC 9126 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-rar-03 Summary: 4 errors (**), 0 flaws (~~), 11 warnings (==), 3 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: 5 August 2021 Okta 6 T. Lodderstedt 7 yes.com 8 1 February 2021 10 The OAuth 2.1 Authorization Framework 11 draft-ietf-oauth-v2-1-01 13 Abstract 15 The OAuth 2.1 authorization framework enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and 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 5 August 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 Password . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . 33 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 Protection . . . . . . . . . . . . . . . . 39 100 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 101 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 102 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42 103 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 42 104 7.2.2. The WWW-Authenticate Response Header Field . . . . . 44 105 7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 45 106 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 46 107 7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 46 108 7.4. Access Token Security Considerations . . . . . . . . . . 46 109 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 47 110 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 47 111 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 49 112 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 50 113 7.4.5. Access Token Privilege Restriction . . . . . . . . . 51 114 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 51 115 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 51 116 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 52 117 8.3. Defining New Authorization Grant Types . . . . . . . . . 52 118 8.4. Defining New Authorization Endpoint Response Types . . . 52 119 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 53 120 9. Security Considerations . . . . . . . . . . . . . . . . . . . 53 121 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 54 122 9.1.1. Client Authentication of Native Apps . . . . . . . . 54 123 9.2. Registration of Native App Clients . . . . . . . . . . . 55 124 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 55 125 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 56 126 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 56 127 9.4.1. Access Token Privilege Restriction . . . . . . . . . 57 128 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 57 129 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 58 130 9.6. Client Impersonating Resource Owner . . . . . . . . . . . 58 131 9.7. Protecting Redirect-Based Flows . . . . . . . . . . . . . 59 132 9.7.1. Loopback Redirect Considerations in Native Apps . . . 59 133 9.7.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 60 134 9.8. Authorization Codes . . . . . . . . . . . . . . . . . . . 61 135 9.9. Request Confidentiality . . . . . . . . . . . . . . . . . 62 136 9.10. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 62 137 9.11. Credentials-Guessing Attacks . . . . . . . . . . . . . . 63 138 9.12. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 63 139 9.13. Fake External User-Agents in Native Apps . . . . . . . . 63 140 9.14. Malicious External User-Agents in Native Apps . . . . . . 64 141 9.15. Cross-Site Request Forgery . . . . . . . . . . . . . . . 64 142 9.16. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 65 143 9.17. Code Injection and Input Validation . . . . . . . . . . . 66 144 9.18. Open Redirectors . . . . . . . . . . . . . . . . . . . . 66 145 9.18.1. Client as Open Redirector . . . . . . . . . . . . . 66 146 9.18.2. Authorization Server as Open Redirector . . . . . . 66 147 9.19. Authorization Server Mix-Up Mitigation in Native Apps . . 67 148 9.20. Embedded User Agents in Native Apps . . . . . . . . . . . 67 149 9.21. Other Recommendations . . . . . . . . . . . . . . . . . . 68 150 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 68 151 10.1. Using Inter-App URI Communication for OAuth in Native 152 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 69 153 10.2. Initiating the Authorization Request from a Native 154 App . . . . . . . . . . . . . . . . . . . . . . . . . . 70 155 10.3. Receiving the Authorization Response in a Native App . . 71 156 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 71 157 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 72 158 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 72 159 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 73 160 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 73 161 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 162 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 163 14.1. Normative References . . . . . . . . . . . . . . . . . . 74 164 14.2. Informative References . . . . . . . . . . . . . . . . . 77 165 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 80 166 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 81 167 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 81 168 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 81 169 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 81 170 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 81 171 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 81 172 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 81 173 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 82 174 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 82 175 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 82 176 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 82 177 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 82 178 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 82 179 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 82 180 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 83 181 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 83 182 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 83 183 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 83 184 Appendix B. Use of application/x-www-form-urlencoded Media 185 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 83 186 Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 84 187 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 86 188 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 190 1. Introduction 192 In the traditional client-server authentication model, the client 193 requests an access-restricted resource (protected resource) on the 194 server by authenticating with the server using the resource owner's 195 credentials. In order to provide third-party applications access to 196 restricted resources, the resource owner shares its credentials with 197 the third party. This creates several problems and limitations: 199 * Third-party applications are required to store the resource 200 owner's credentials for future use, typically a password in clear- 201 text. 203 * Servers are required to support password authentication, despite 204 the security weaknesses inherent in passwords. 206 * Third-party applications gain overly broad access to the resource 207 owner's protected resources, leaving resource owners without any 208 ability to restrict duration or access to a limited subset of 209 resources. 211 * Resource owners often reuse passwords with other unrelated 212 services, despite best security practices. This password reuse 213 means a vulnerability or exposure in one service may have security 214 implications in completely unrelated services. 216 * Resource owners cannot revoke access to an individual third party 217 without revoking access to all third parties, and must do so by 218 changing the third party's password. 220 * Compromise of any third-party application results in compromise of 221 the end-user's password and all of the data protected by that 222 password. 224 OAuth addresses these issues by introducing an authorization layer 225 and separating the role of the client from that of the resource 226 owner. In OAuth, the client requests access to resources controlled 227 by the resource owner and hosted by the resource server. Instead of 228 using the resource owner's credentials to access protected resources, 229 the client obtains an access token - a credential representing a 230 specific set of access attributes such as scope and lifetime. Access 231 tokens are issued to clients by an authorization server with the 232 approval of the resource owner. The client uses the access token to 233 access the protected resources hosted by the resource server. 235 For example, an end-user (resource owner) can grant a printing 236 service (client) access to their protected photos stored at a photo- 237 sharing service (resource server), without sharing their username and 238 password with the printing service. Instead, they authenticates 239 directly with a server trusted by the photo-sharing service 240 (authorization server), which issues the printing service delegation- 241 specific credentials (access token). 243 This specification is designed for use with HTTP ([RFC7230]). The 244 use of OAuth over any protocol other than HTTP is out of scope. 246 Since the publication of the OAuth 2.0 Authorization Framework 247 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 248 Native Apps ([RFC8252]), OAuth Security Best Current Practice 249 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 250 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 251 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 252 updated with ([I-D.ietf-oauth-security-topics]). This Standards 253 Track specification consolidates the information in all of these 254 documents and removes features that have been found to be insecure in 255 [I-D.ietf-oauth-security-topics]. 257 1.1. Roles 259 OAuth defines four roles: 261 "resource owner": An entity capable of granting access to a 262 protected resource. When the resource owner is a person, it is 263 referred to as an end-user. This is sometimes abbreviated as 264 "RO". 266 "resource server": The server hosting the protected resources, 267 capable of accepting and responding to protected resource requests 268 using access tokens. The resource server is often accessible via 269 an API. This is sometimes abbreviated as "RS". 271 "client": An application making protected resource requests on 272 behalf of the resource owner and with its authorization. The term 273 "client" does not imply any particular implementation 274 characteristics (e.g., whether the application executes on a 275 server, a desktop, or other devices). 277 "authorization server": The server issuing access tokens to the 278 client after successfully authenticating the resource owner and 279 obtaining authorization. This is sometimes abbreviated as "AS". 281 The interaction between the authorization server and resource server 282 is beyond the scope of this specification, however several extension 283 have been defined to provide an option for interoperability between 284 resource servers and authorization servers. The authorization server 285 may be the same server as the resource server or a separate entity. 286 A single authorization server may issue access tokens accepted by 287 multiple resource servers. 289 1.2. Protocol Flow 291 +--------+ +---------------+ 292 | |--(1)- Authorization Request ->| Resource | 293 | | | Owner | 294 | |<-(2)-- Authorization Grant ---| | 295 | | +---------------+ 296 | | 297 | | +---------------+ 298 | |--(3)-- Authorization Grant -->| Authorization | 299 | Client | | Server | 300 | |<-(4)----- Access Token -------| | 301 | | +---------------+ 302 | | 303 | | +---------------+ 304 | |--(5)----- Access Token ------>| Resource | 305 | | | Server | 306 | |<-(6)--- Protected Resource ---| | 307 +--------+ +---------------+ 309 Figure 1: Abstract Protocol Flow 311 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 312 interaction between the four roles and includes the following steps: 314 1. The client requests authorization from the resource owner. The 315 authorization request can be made directly to the resource owner 316 (as shown), or preferably indirectly via the authorization server 317 as an intermediary. 319 2. The client receives an authorization grant, which is a credential 320 representing the resource owner's authorization, expressed using 321 one of two authorization grant types defined in this 322 specification or using an extension grant type. The 323 authorization grant type depends on the method used by the client 324 to request authorization and the types supported by the 325 authorization server. 327 3. The client requests an access token by authenticating with the 328 authorization server and presenting the authorization grant. 330 4. The authorization server authenticates the client and validates 331 the authorization grant, and if valid, issues an access token. 333 5. The client requests the protected resource from the resource 334 server and authenticates by presenting the access token. 336 6. The resource server validates the access token, and if valid, 337 serves the request. 339 The preferred method for the client to obtain an authorization grant 340 from the resource owner (depicted in steps (1) and (2)) is to use the 341 authorization server as an intermediary, which is illustrated in 342 Figure 3 in Section 4.1. 344 1.3. Authorization Grant 346 An authorization grant is a credential representing the resource 347 owner's authorization (to access its protected resources) used by the 348 client to obtain an access token. This specification defines two 349 grant types - authorization code and client credentials - as well as 350 an extensibility mechanism for defining additional types. 352 1.3.1. Authorization Code 354 An authorization code is a temporary credential used to obtain an 355 access token. Instead of the client requesting authorization 356 directly from the resource owner, the client directs the resource 357 owner to an authorization server (via its user-agent as defined in 358 [RFC7231]), which in turn directs the resource owner back to the 359 client with the authorization code. The client can then exchange the 360 authorization code for an access token. 362 Before directing the resource owner back to the client with the 363 authorization code, the authorization server authenticates the 364 resource owner, and may request the resource owner's consent or 365 otherwise inform them of the client's request. Because the resource 366 owner only authenticates with the authorization server, the resource 367 owner's credentials are never shared with the client, and the client 368 does not need to have knowledge of any additional authentication 369 steps such as multi-factor authentication or delegated accounts. 371 The authorization code provides a few important security benefits, 372 such as the ability to authenticate the client, as well as the 373 transmission of the access token directly to the client without 374 passing it through the resource owner's user-agent and potentially 375 exposing it to others, including the resource owner. 377 1.3.2. Client Credentials 379 The client credentials or other forms of client authentication (e.g. 380 a "client_secret" or a private key used to sign a JWT) can be used as 381 an authorization grant when the authorization scope is limited to the 382 protected resources under the control of the client, or to protected 383 resources previously arranged with the authorization server. Client 384 credentials are used as an authorization grant typically when the 385 client is acting on its own behalf (the client is also the resource 386 owner) or is requesting access to protected resources based on an 387 authorization previously arranged with the authorization server. 389 1.4. Access Token 391 Access tokens are credentials used to access protected resources. An 392 access token is a string representing an authorization issued to the 393 client. The string is considered opaque to the client, even if it 394 has a structure. Depending on the authorization server, the access 395 token string may be parseable by the resource server. 397 Access tokens represent specific scopes and durations of access, 398 granted by the resource owner, and enforced by the resource server 399 and authorization server. 401 The token may be used by the RS to retrieve the authorization 402 information, or the token may self-contain the authorization 403 information in a verifiable manner (i.e., a token string consisting 404 of a signed data payload). One example of a token retrieval 405 mechanism is Token Introspection [RFC7662], in which the RS calls an 406 endpoint on the AS to validate the token presented by the client. 407 One example of a structured token format is 408 [I-D.ietf-oauth-access-token-jwt], a method of encoding access token 409 data as a JSON Web Token [RFC7519]. 411 Additional authentication credentials, which are beyond the scope of 412 this specification, may be required in order for the client to use an 413 access token. This is typically referred to as a sender-constrained 414 access token, such as Mutual TLS Access Tokens [RFC8705]. 416 The access token provides an abstraction layer, replacing different 417 authorization constructs (e.g., username and password) with a single 418 token understood by the resource server. This abstraction enables 419 issuing access tokens more restrictive than the authorization grant 420 used to obtain them, as well as removing the resource server's need 421 to understand a wide range of authentication methods. 423 Access tokens can have different formats, structures, and methods of 424 utilization (e.g., cryptographic properties) based on the resource 425 server security requirements. Access token attributes and the 426 methods used to access protected resources may be extended beyond 427 what is described in this specification. 429 1.5. Refresh Token 431 Refresh tokens are credentials used to obtain access tokens. Refresh 432 tokens are issued to the client by the authorization server and are 433 used to obtain a new access token when the current access token 434 becomes invalid or expires, or to obtain additional access tokens 435 with identical or narrower scope (access tokens may have a shorter 436 lifetime and fewer permissions than authorized by the resource 437 owner). Issuing a refresh token is optional at the discretion of the 438 authorization server, and may be issued based on properties of the 439 client, properties of the request, policies within the authorization 440 server, or any other criteria. If the authorization server issues a 441 refresh token, it is included when issuing an access token (i.e., 442 step (2) in Figure 2). 444 A refresh token is a string representing the authorization granted to 445 the client by the resource owner. The string is considered opaque to 446 the client. The refresh token may be an identifier used to retrieve 447 the authorization information or may encode this information into the 448 string itself. Unlike access tokens, refresh tokens are intended for 449 use only with authorization servers and are never sent to resource 450 servers. 452 +--------+ +---------------+ 453 | |--(1)------- Authorization Grant --------->| | 454 | | | | 455 | |<-(2)----------- Access Token -------------| | 456 | | & Refresh Token | | 457 | | | | 458 | | +----------+ | | 459 | |--(3)---- Access Token ---->| | | | 460 | | | | | | 461 | |<-(4)- Protected Resource --| Resource | | Authorization | 462 | Client | | Server | | Server | 463 | |--(5)---- Access Token ---->| | | | 464 | | | | | | 465 | |<-(6)- Invalid Token Error -| | | | 466 | | +----------+ | | 467 | | | | 468 | |--(7)----------- Refresh Token ----------->| | 469 | | | | 470 | |<-(8)----------- Access Token -------------| | 471 +--------+ & Optional Refresh Token +---------------+ 473 Figure 2: Refreshing an Expired Access Token 475 The flow illustrated in Figure 2 includes the following steps: 477 1. The client requests an access token by authenticating with the 478 authorization server and presenting an authorization grant. 480 2. The authorization server authenticates the client and validates 481 the authorization grant, and if valid, issues an access token and 482 optionally a refresh token. 484 3. The client makes a protected resource request to the resource 485 server by presenting the access token. 487 4. The resource server validates the access token, and if valid, 488 serves the request. 490 5. Steps (3) and (4) repeat until the access token expires. If the 491 client knows the access token expired, it skips to step (7); 492 otherwise, it makes another protected resource request. 494 6. Since the access token is invalid, the resource server returns an 495 invalid token error. 497 7. The client requests a new access token by presenting the refresh 498 token and providing client authentication if it has been issued 499 credentials. The client authentication requirements are based on 500 the client type and on the authorization server policies. 502 8. The authorization server authenticates the client and validates 503 the refresh token, and if valid, issues a new access token (and, 504 optionally, a new refresh token). 506 1.6. TLS Version 508 Whenever Transport Layer Security (TLS) is used by this 509 specification, the appropriate version (or versions) of TLS will vary 510 over time, based on the widespread deployment and known security 511 vulnerabilities. Refer to [BCP195] for up to date recommendations on 512 transport layer security. 514 Implementations MAY also support additional transport-layer security 515 mechanisms that meet their security requirements. 517 1.7. HTTP Redirections 519 This specification makes extensive use of HTTP redirections, in which 520 the client or the authorization server directs the resource owner's 521 user-agent to another destination. While the examples in this 522 specification show the use of the HTTP 302 status code, any other 523 method available via the user-agent to accomplish this redirection, 524 with the exception of HTTP 307, is allowed and is considered to be an 525 implementation detail. See Section 9.7.2 for details. 527 1.8. Interoperability 529 OAuth 2.1 provides a rich authorization framework with well-defined 530 security properties. 532 This specification leaves a few required components partially or 533 fully undefined (e.g., client registration, authorization server 534 capabilities, endpoint discovery). Some of these behaviors are 535 defined in optional extensions which implementations can choose to 536 use, such as: 538 * [RFC8414]: Authorization Server Metadata, defining an endpoint 539 clients can use to look up the information needed to interact with 540 a particular OAuth server 542 * [RFC7591]: Dynamic Client Registration, providing a mechanism for 543 programmatically registering clients with an authorization server 545 * [RFC7592]: Dynamic Client Management, providing a mechanism for 546 updating dynamically registered client information 548 * [RFC7662]: Token Introspection, defining a mechanism for resource 549 servers to obtain information about access tokens 551 Please refer to Appendix C for a list of current known extensions at 552 the time of this publication. 554 1.9. Compatibility with OAuth 2.0 556 OAuth 2.1 is compatible with OAuth 2.0 with the extensions and 557 restrictions from known best current practices applied. 558 Specifically, features not specified in OAuth 2.0 core, such as PKCE, 559 are required in OAuth 2.1. Additionally, some features available in 560 OAuth 2.0, such as the Implicit or Resource Owner Credentials grant 561 types, are not specified in OAuth 2.1. Furthermore, some behaviors 562 allowed in OAuth 2.0 are restricted in OAuth 2.1, such as the strict 563 string matching of redirect URIs required by OAuth 2.1. 565 See Section 12 for more details on the differences from OAuth 2.0. 567 1.10. Notational Conventions 569 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 570 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 571 "OPTIONAL" in this document are to be interpreted as described in BCP 572 14 [RFC2119] [RFC8174] when, and only when, they appear in all 573 capitals, as shown here. 575 This specification uses the Augmented Backus-Naur Form (ABNF) 576 notation of [RFC5234]. Additionally, the rule URI-reference is 577 included from "Uniform Resource Identifier (URI): Generic Syntax" 578 [RFC3986]. 580 Certain security-related terms are to be understood in the sense 581 defined in [RFC4949]. These terms include, but are not limited to, 582 "attack", "authentication", "authorization", "certificate", 583 "confidentiality", "credential", "encryption", "identity", "sign", 584 "signature", "trust", "validate", and "verify". 586 The term "payload" is to be interpreted as described in Section 3.3 587 of [RFC7231]. 589 Unless otherwise noted, all the protocol parameter names and values 590 are case sensitive. 592 2. Client Registration 594 Before initiating the protocol, the client must establish its 595 registration with the authorization server. The means through which 596 the client registers with the authorization server are beyond the 597 scope of this specification but typically involve the client 598 developer manually registering the client at the authorization 599 server's website after creating an account and agreeing to the 600 service's Terms of Service, or by using Dynamic Client Registration 601 ([RFC7591]). 603 Client registration does not require a direct interaction between the 604 client and the authorization server. When supported by the 605 authorization server, registration can rely on other means for 606 establishing trust and obtaining the required client properties 607 (e.g., redirect URI, client type). For example, registration can be 608 accomplished using a self-issued or third-party-issued assertion, or 609 by the authorization server performing client discovery using a 610 trusted channel. 612 When registering a client, the client developer SHALL: 614 * specify the client type as described in Section 2.1, 616 * provide its client redirect URIs as described in Section 3.1.2, 617 and 619 * include any other information required by the authorization server 620 (e.g., application name, website, description, logo image, the 621 acceptance of legal terms). 623 Dynamic Client Registration ([RFC7591]) defines a common general data 624 model for clients that may be used even with manual client 625 registration. 627 2.1. Client Types 629 Clients are identified at the authorization server by a "client_id". 630 It is, for example, used by the authorization server to determine the 631 set of redirect URIs this client can use. 633 Clients requiring a higher level of confidence in their identity by 634 the authorization server use credentials to authenticate with the 635 authorization server. Such credentials are either issued by the 636 authorization server or registered by the developer of the client 637 with the authorization server. 639 OAuth 2.1 defines three client types: 641 "confidential": Clients that have credentials and their identity has 642 been confirmed by the AS are designated as "confidential clients" 644 "credentialed": Clients that have credentials and their identity has 645 been not been confirmed by the AS are designated as "credentialed 646 clients" 648 "public": Clients without credentials are called "public clients" 650 Any clients with credentials MUST take precautions to prevent leakage 651 and abuse of their credentials. 653 Authorization servers SHOULD consider the level of confidence in a 654 client's identity when deciding whether they allow such a client 655 access to more critical functions, such as the Client Credentials 656 grant type. 658 A single "client_id" MUST NOT be treated as more than one type of 659 client. 661 This specification has been designed around the following client 662 profiles: 664 "web application": A web application is a confidential client 665 running on a web server. Resource owners access the client via an 666 HTML user interface rendered in a user-agent on the device used by 667 the resource owner. The client credentials as well as any access 668 token issued to the client are stored on the web server and are 669 not exposed to or accessible by the resource owner. 671 "browser-based application": A browser-based application is a public 672 client in which the client code is downloaded from a web server 673 and executes within a user-agent (e.g., web browser) on the device 674 used by the resource owner. Protocol data and credentials are 675 easily accessible (and often visible) to the resource owner. 676 Since such applications reside within the user-agent, they can 677 make seamless use of the user-agent capabilities when requesting 678 authorization. 680 "native application": A native application is a public client 681 installed and executed on the device used by the resource owner. 682 Protocol data and credentials are accessible to the resource 683 owner. It is assumed that any client authentication credentials 684 included in the application can be extracted. On the other hand, 685 dynamically issued credentials such as access tokens or refresh 686 tokens can receive an acceptable level of protection. At a 687 minimum, these credentials are protected from hostile servers with 688 which the application may interact. On some platforms, these 689 credentials might be protected from other applications residing on 690 the same device. 692 2.2. Client Identifier 694 The authorization server issues the registered client a client 695 identifier - a unique string representing the registration 696 information provided by the client. The client identifier is not a 697 secret; it is exposed to the resource owner and MUST NOT be used 698 alone for client authentication. The client identifier is unique to 699 the authorization server. 701 The client identifier string size is left undefined by this 702 specification. The client should avoid making assumptions about the 703 identifier size. The authorization server SHOULD document the size 704 of any identifier it issues. 706 Authorization servers SHOULD NOT allow clients to choose or influence 707 their "client_id" value. See Section 9.6 for details. 709 2.3. Client Authentication 711 If the client type is confidential, the client and authorization 712 server establish a client authentication method suitable for the 713 security requirements of the authorization server. The authorization 714 server MAY accept any form of client authentication meeting its 715 security requirements. 717 Confidential clients are typically issued (or establish) a set of 718 client credentials used for authenticating with the authorization 719 server (e.g., password, public/private key pair). 721 Authorization servers SHOULD use client authentication if possible. 723 It is RECOMMENDED to use asymmetric (public-key based) methods for 724 client authentication such as mTLS [RFC8705] or "private_key_jwt" 725 [OpenID]. When asymmetric methods for client authentication are 726 used, authorization servers do not need to store sensitive symmetric 727 keys, making these methods more robust against a number of attacks. 729 The authorization server MAY establish a client authentication method 730 with public clients, which converts them to credentialed clients. 731 However, the authorization server MUST NOT rely on credentialed 732 client authentication for the purpose of identifying the client. 734 The client MUST NOT use more than one authentication method in each 735 request. 737 2.3.1. Client Password 739 Clients in possession of a client password, also known as a client 740 secret, MAY use the HTTP Basic authentication scheme as defined in 741 [RFC2617] to authenticate with the authorization server. The client 742 identifier is encoded using the "application/x-www-form-urlencoded" 743 encoding algorithm per Appendix B, and the encoded value is used as 744 the username; the client secret is encoded using the same algorithm 745 and used as the password. The authorization server MUST support the 746 HTTP Basic authentication scheme for authenticating clients that were 747 issued a client secret. 749 For example (with extra line breaks for display purposes only): 751 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 753 Alternatively, the authorization server MAY support including the 754 client credentials in the request-body using the following 755 parameters: 757 "client_id": REQUIRED. The client identifier issued to the client 758 during the registration process described by Section 2.2. 760 "client_secret": REQUIRED. The client secret. 762 Including the client credentials in the request-body using the two 763 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 764 to directly utilize the HTTP Basic authentication scheme (or other 765 password-based HTTP authentication schemes). The parameters can only 766 be transmitted in the request-body and MUST NOT be included in the 767 request URI. 769 For example, a request to refresh an access token (Section 6) using 770 the body parameters (with extra line breaks for display purposes 771 only): 773 POST /token HTTP/1.1 774 Host: server.example.com 775 Content-Type: application/x-www-form-urlencoded 777 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 778 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 780 The authorization server MUST require the use of TLS as described in 781 Section 1.6 when sending requests using password authentication. 783 Since this client authentication method involves a password, the 784 authorization server MUST protect any endpoint utilizing it against 785 brute force attacks. 787 2.3.2. Other Authentication Methods 789 The authorization server MAY support any suitable authentication 790 scheme matching its security requirements. When using other 791 authentication methods, the authorization server MUST define a 792 mapping between the client identifier (registration record) and 793 authentication scheme. 795 Some additional authentication methods are defined in the "OAuth 796 Token Endpoint Authentication Methods 797 (https://www.iana.org/assignments/oauth-parameters/oauth- 798 parameters.xhtml#token-endpoint-auth-method)" registry, and may be 799 useful as generic client authentication methods beyond the specific 800 use of protecting the token endpoint. 802 2.4. Unregistered Clients 804 This specification does not exclude the use of unregistered clients. 805 However, the use of such clients is beyond the scope of this 806 specification and requires additional security analysis and review of 807 its interoperability impact. 809 3. Protocol Endpoints 811 The authorization process utilizes two authorization server endpoints 812 (HTTP resources): 814 * Authorization endpoint - used by the client to obtain 815 authorization from the resource owner via user-agent redirection. 817 * Token endpoint - used by the client to exchange an authorization 818 grant for an access token, typically with client authentication. 820 As well as one client endpoint: 822 * Redirection endpoint - used by the authorization server to return 823 responses containing authorization credentials to the client via 824 the resource owner user-agent. 826 Not every authorization grant type utilizes both endpoints. 827 Extension grant types MAY define additional endpoints as needed. 829 3.1. Authorization Endpoint 831 The authorization endpoint is used to interact with the resource 832 owner and obtain an authorization grant. The authorization server 833 MUST first verify the identity of the resource owner. The way in 834 which the authorization server authenticates the resource owner 835 (e.g., username and password login, session cookies) is beyond the 836 scope of this specification. 838 The means through which the client obtains the location of the 839 authorization endpoint are beyond the scope of this specification, 840 but the location is typically provided in the service documentation, 841 or in the authorization server's metadata document ([RFC8414]). 843 The endpoint URI MAY include an "application/x-www-form-urlencoded" 844 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 845 which MUST be retained when adding additional query parameters. The 846 endpoint URI MUST NOT include a fragment component. 848 Since requests to the authorization endpoint result in user 849 authentication and the transmission of clear-text credentials (in the 850 HTTP response), the authorization server MUST require the use of TLS 851 as described in Section 1.6 when sending requests to the 852 authorization endpoint. 854 The authorization server MUST support the use of the HTTP "GET" 855 method [RFC7231] for the authorization endpoint and MAY support the 856 use of the "POST" method as well. 858 Parameters sent without a value MUST be treated as if they were 859 omitted from the request. The authorization server MUST ignore 860 unrecognized request parameters. Request and response parameters 861 defined by this specification MUST NOT be included more than once. 863 3.1.1. Response Type 865 The authorization endpoint is used by the authorization code flow. 866 The client informs the authorization server of the desired response 867 type using the following parameter: 869 "response_type": REQUIRED. The value MUST be "code" for requesting 870 an authorization code as described by Section 4.1.1, or a 871 registered extension value as described by Section 8.4. 873 Extension response types MAY contain a space-delimited (%x20) list of 874 values, where the order of values does not matter (e.g., response 875 type "a b" is the same as "b a"). The meaning of such composite 876 response types is defined by their respective specifications. 878 If an authorization request is missing the "response_type" parameter, 879 or if the response type is not understood, the authorization server 880 MUST return an error response as described in Section 4.1.2.1. 882 3.1.2. Redirection Endpoint 884 After completing its interaction with the resource owner, the 885 authorization server directs the resource owner's user-agent back to 886 the client. The authorization server redirects the user-agent to the 887 client's redirection endpoint previously established with the 888 authorization server during the client registration process. 890 The authorization server MUST compare the two URIs using simple 891 string comparison as defined in [RFC3986], Section 6.2.1. 893 The redirect URI MUST be an absolute URI as defined by [RFC3986] 894 Section 4.3. The endpoint URI MAY include an "application/x-www- 895 form-urlencoded" formatted (per Appendix B) query component 896 ([RFC3986] Section 3.4), which MUST be retained when adding 897 additional query parameters. The endpoint URI MUST NOT include a 898 fragment component. 900 3.1.2.1. Endpoint Request Confidentiality 902 The redirection endpoint SHOULD require the use of TLS as described 903 in Section 1.6 when the requested response type is "code", or when 904 the redirection request will result in the transmission of sensitive 905 credentials over an open network. If TLS is not available, the 906 authorization server SHOULD warn the resource owner about the 907 insecure endpoint prior to redirection (e.g., display a message 908 during the authorization request). 910 Lack of transport-layer security can have a severe impact on the 911 security of the client and the protected resources it is authorized 912 to access. The use of transport-layer security is particularly 913 critical when the authorization process is used as a form of 914 delegated end-user authentication by the client (e.g., third-party 915 sign-in service). 917 3.1.2.2. Registration Requirements 919 The authorization server MUST require all clients to register one or 920 more complete redirect URIs prior to utilizing the authorization 921 endpoint. The client MAY use the "state" request parameter to 922 achieve per-request customization if needed. 924 The authorization server MAY allow the client to register multiple 925 redirect URIs. 927 Lack of requiring registration of redirect URIs enables an attacker 928 to use the authorization endpoint as an open redirector as described 929 in Section 9.18. 931 3.1.2.3. Dynamic Configuration 933 If multiple redirect URIs have been registered the client MUST 934 include a redirect URI with the authorization request using the 935 "redirect_uri" request parameter. 937 3.1.2.4. Invalid Endpoint 939 If an authorization request fails validation due to a missing, 940 invalid, or mismatching redirect URI, the authorization server SHOULD 941 inform the resource owner of the error and MUST NOT automatically 942 redirect the user-agent to the invalid redirect URI. 944 3.1.2.5. Endpoint Content 946 The redirection request to the client's endpoint typically results in 947 an HTML document response, processed by the user-agent. If the HTML 948 response is served directly as the result of the redirection request, 949 any script included in the HTML document will execute with full 950 access to the redirect URI and the credentials (e.g. authorization 951 code) it contains. 953 The client SHOULD NOT include any third-party scripts (e.g., third- 954 party analytics, social plug-ins, ad networks) in the redirection 955 endpoint response. Instead, it SHOULD extract the credentials from 956 the URI and redirect the user-agent again to another endpoint without 957 exposing the credentials (in the URI or elsewhere). If third-party 958 scripts are included, the client MUST ensure that its own scripts 959 (used to extract and remove the credentials from the URI) will 960 execute first. 962 3.2. Token Endpoint 964 The token endpoint is used by the client to obtain an access token by 965 presenting its authorization grant or refresh token. 967 The means through which the client obtains the location of the token 968 endpoint are beyond the scope of this specification, but the location 969 is typically provided in the service documentation, or in the 970 authorization server's metadata document ([RFC8414]). 972 The endpoint URI MAY include an "application/x-www-form-urlencoded" 973 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 974 which MUST be retained when adding additional query parameters. The 975 endpoint URI MUST NOT include a fragment component. 977 Since requests to the token endpoint result in the transmission of 978 clear-text credentials (in the HTTP request and response), the 979 authorization server MUST require the use of TLS as described in 980 Section 1.6 when sending requests to the token endpoint. 982 The client MUST use the HTTP "POST" method when making access token 983 requests. 985 Parameters sent without a value MUST be treated as if they were 986 omitted from the request. The authorization server MUST ignore 987 unrecognized request parameters. Request and response parameters 988 defined by this specification MUST NOT be included more than once. 990 3.2.1. Client Authentication 992 Confidential clients or other clients issued client credentials MUST 993 authenticate with the authorization server as described in 994 Section 2.3 when making requests to the token endpoint. Client 995 authentication is used for: 997 * Enforcing the binding of refresh tokens and authorization codes to 998 the client they were issued to. Client authentication is critical 999 when an authorization code is transmitted to the redirection 1000 endpoint over an insecure channel. 1002 * Recovering from a compromised client by disabling the client or 1003 changing its credentials, thus preventing an attacker from abusing 1004 stolen refresh tokens. Changing a single set of client 1005 credentials is significantly faster than revoking an entire set of 1006 refresh tokens. 1008 * Implementing authentication management best practices, which 1009 require periodic credential rotation. Rotation of an entire set 1010 of refresh tokens can be challenging, while rotation of a single 1011 set of client credentials is significantly easier. 1013 3.3. Access Token Scope 1015 The authorization and token endpoints allow the client to specify the 1016 scope of the access request using the "scope" request parameter. In 1017 turn, the authorization server uses the "scope" response parameter to 1018 inform the client of the scope of the access token issued. 1020 The value of the scope parameter is expressed as a list of space- 1021 delimited, case-sensitive strings. The strings are defined by the 1022 authorization server. If the value contains multiple space-delimited 1023 strings, their order does not matter, and each string adds an 1024 additional access range to the requested scope. 1026 scope = scope-token *( SP scope-token ) 1027 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 1029 The authorization server MAY fully or partially ignore the scope 1030 requested by the client, based on the authorization server policy or 1031 the resource owner's instructions. If the issued access token scope 1032 is different from the one requested by the client, the authorization 1033 server MUST include the "scope" response parameter to inform the 1034 client of the actual scope granted. 1036 If the client omits the scope parameter when requesting 1037 authorization, the authorization server MUST either process the 1038 request using a pre-defined default value or fail the request 1039 indicating an invalid scope. The authorization server SHOULD 1040 document its scope requirements and default value (if defined). 1042 4. Obtaining Authorization 1044 To request an access token, the client obtains authorization from the 1045 resource owner. The authorization is expressed in the form of an 1046 authorization grant, which the client uses to request the access 1047 token. OAuth defines two authorization grant types: authorization 1048 code and client credentials. It also provides an extension mechanism 1049 for defining additional grant types. 1051 4.1. Authorization Code Grant 1053 The authorization code grant type is used to obtain both access 1054 tokens and refresh tokens. 1056 Since this is a redirect-based flow, the client must be capable of 1057 interacting with the resource owner's user-agent (typically a web 1058 browser) and capable of receiving incoming requests (via redirection) 1059 from the authorization server. 1061 +----------+ 1062 | Resource | 1063 | Owner | 1064 | | 1065 +----------+ 1066 ^ 1067 | 1068 (2) 1069 +----|-----+ Client Identifier +---------------+ 1070 | -+----(1)-- & Redirect URI ---->| | 1071 | User- | | Authorization | 1072 | Agent -+----(2)-- User authenticates --->| Server | 1073 | | | | 1074 | -+----(3)-- Authorization Code ---<| | 1075 +-|----|---+ +---------------+ 1076 | | ^ v 1077 (1) (3) | | 1078 | | | | 1079 ^ v | | 1080 +---------+ | | 1081 | |>---(4)-- Authorization Code ---------' | 1082 | Client | & Redirect URI | 1083 | | | 1084 | |<---(5)----- Access Token -------------------' 1085 +---------+ (w/ Optional Refresh Token) 1087 Note: The lines illustrating steps (1), (2), and (3) are broken into 1088 two parts as they pass through the user-agent. 1090 Figure 3: Authorization Code Flow 1092 The flow illustrated in Figure 3 includes the following steps: 1094 (1) The client initiates the flow by directing the resource owner's 1095 user-agent to the authorization endpoint. The client includes its 1096 client identifier, code challenge (derived from a generated code 1097 verifier), optional requested scope, optional local state, and a 1098 redirect URI to which the authorization server will send the user- 1099 agent back once access is granted (or denied). 1101 (2) The authorization server authenticates the resource owner (via 1102 the user-agent) and establishes whether the resource owner grants or 1103 denies the client's access request. 1105 (3) Assuming the resource owner grants access, the authorization 1106 server redirects the user-agent back to the client using the redirect 1107 URI provided earlier (in the request or during client registration). 1108 The redirect URI includes an authorization code and any local state 1109 provided by the client earlier. 1111 (4) The client requests an access token from the authorization 1112 server's token endpoint by including the authorization code received 1113 in the previous step, and including its code verifier. When making 1114 the request, the client authenticates with the authorization server 1115 if it can. The client includes the redirect URI used to obtain the 1116 authorization code for verification. 1118 (5) The authorization server authenticates the client when possible, 1119 validates the authorization code, validates the code verifier, and 1120 ensures that the redirect URI received matches the URI used to 1121 redirect the client in step (3). If valid, the authorization server 1122 responds back with an access token and, optionally, a refresh token. 1124 4.1.1. Authorization Request 1126 To begin the authorization request, the client builds the 1127 authorization request URI by adding parameters to the authorization 1128 server's authorization endpoint URI. 1130 Clients use a unique secret per authorization request to protect 1131 against code injection and CSRF attacks. The client first generates 1132 this secret, which it can later use along with the authorization code 1133 to prove that the application using the authorization code is the 1134 same application that requested it. The properties "code_challenge" 1135 and "code_verifier" are adopted from the OAuth 2.0 extension known as 1136 "Proof-Key for Code Exchange", or PKCE ([RFC7636]) where this 1137 technique was originally developed. 1139 Clients MUST use "code_challenge" and "code_verifier" and 1140 authorization servers MUST enforce their use except under the 1141 conditions described in Section 9.8. In this case, using and 1142 enforcing "code_challenge" and "code_verifier" as described in the 1143 following is still RECOMMENDED. 1145 4.1.1.1. Client Creates a Code Verifier 1147 The client first creates a code verifier, "code_verifier", for each 1148 Authorization Request, in the following manner: 1150 code_verifier = high-entropy cryptographic random STRING using the 1151 unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"` 1152 from Section 2.3 of {{RFC3986}}, with a minimum length of 43 characters 1153 and a maximum length of 128 characters. 1155 ABNF for "code_verifier" is as follows. 1157 code-verifier = 43*128unreserved 1158 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1159 ALPHA = %x41-5A / %x61-7A 1160 DIGIT = %x30-39 1162 NOTE: The code verifier SHOULD have enough entropy to make it 1163 impractical to guess the value. It is RECOMMENDED that the output of 1164 a suitable random number generator be used to create a 32-octet 1165 sequence. The octet sequence is then base64url-encoded to produce a 1166 43-octet URL-safe string to use as the code verifier. 1168 4.1.1.2. Client Creates the Code Challenge 1170 The client then creates a code challenge derived from the code 1171 verifier by using one of the following transformations on the code 1172 verifier: 1174 plain 1175 code_challenge = code_verifier 1177 S256 1178 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1180 If the client is capable of using "S256", it MUST use "S256", as 1181 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1182 permitted to use "plain" only if they cannot support "S256" for some 1183 technical reason and know via out-of-band configuration or via 1184 Authorization Server Metadata ([RFC8414]) that the server supports 1185 "plain". 1187 The plain transformation is for compatibility with existing 1188 deployments and for constrained environments that can't use the 1189 "S256" transformation. 1191 ABNF for "code_challenge" is as follows. 1193 code-challenge = 43*128unreserved 1194 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1195 ALPHA = %x41-5A / %x61-7A 1196 DIGIT = %x30-39 1198 4.1.1.3. Client Initiates the Authorization Request 1200 The client constructs the request URI by adding the following 1201 parameters to the query component of the authorization endpoint URI 1202 using the "application/x-www-form-urlencoded" format, per Appendix B: 1204 "response_type": REQUIRED. Value MUST be set to "code". 1206 "client_id": REQUIRED. The client identifier as described in 1207 Section 2.2. 1209 "code_challenge": REQUIRED or RECOMMENDED (see Section 9.8). Code 1210 challenge. 1212 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1213 present in the request. Code verifier transformation method is 1214 "S256" or "plain". 1216 "redirect_uri": OPTIONAL. As described in Section 3.1.2. 1218 "scope": OPTIONAL. The scope of the access request as described by 1219 Section 3.3. 1221 "state": OPTIONAL. An opaque value used by the client to maintain 1222 state between the request and callback. The authorization server 1223 includes this value when redirecting the user-agent back to the 1224 client. 1226 The client directs the resource owner to the constructed URI using an 1227 HTTP redirection response, or by other means available to it via the 1228 user-agent. 1230 For example, the client directs the user-agent to make the following 1231 HTTP request using TLS (with extra line breaks for display purposes 1232 only): 1234 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1235 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1236 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1237 &code_challenge_method=S256 HTTP/1.1 1238 Host: server.example.com 1240 The authorization server validates the request to ensure that all 1241 required parameters are present and valid. If the request is valid, 1242 the authorization server authenticates the resource owner and obtains 1243 an authorization decision (by asking the resource owner or by 1244 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 When the server issues the authorization code in the authorization 1287 response, it MUST associate the "code_challenge" and 1288 "code_challenge_method" values with the authorization code so it can 1289 be verified later. 1291 The "code_challenge" and "code_challenge_method" values may be stored 1292 in encrypted form in the "code" itself, but could alternatively be 1293 stored on the server associated with the code. The server MUST NOT 1294 include the "code_challenge" value in client requests in a form that 1295 other entities can extract. 1297 The exact method that the server uses to associate the 1298 "code_challenge" with the issued "code" is out of scope for this 1299 specification. 1301 4.1.2.1. Error Response 1303 If the request fails due to a missing, invalid, or mismatching 1304 redirect URI, or if the client identifier is missing or invalid, the 1305 authorization server SHOULD inform the resource owner of the error 1306 and MUST NOT automatically redirect the user-agent to the invalid 1307 redirect URI. 1309 An AS MUST reject requests without a "code_challenge" from public 1310 clients, and MUST reject such requests from other clients unless 1311 there is reasonable assurance that the client mitigates authorization 1312 code injection in other ways. See Section 9.8 for details. 1314 If the server does not support the requested "code_challenge_method" 1315 transformation, the authorization endpoint MUST return the 1316 authorization error response with "error" value set to 1317 "invalid_request". The "error_description" or the response of 1318 "error_uri" SHOULD explain the nature of error, e.g., transform 1319 algorithm not supported. 1321 If the resource owner denies the access request or if the request 1322 fails for reasons other than a missing or invalid redirect URI, the 1323 authorization server informs the client by adding the following 1324 parameters to the query component of the redirect URI using the 1325 "application/x-www-form-urlencoded" format, per Appendix B: 1327 "error": REQUIRED. A single ASCII [USASCII] error code from the 1328 following: 1330 "invalid_request": The request is missing a required parameter, 1331 includes an invalid parameter value, includes a parameter more 1332 than once, or is otherwise malformed. 1334 "unauthorized_client": The client is not authorized to request an 1335 authorization code using this method. 1337 "access_denied": The resource owner or authorization server 1338 denied the request. 1340 "unsupported_response_type": The authorization server does not 1341 support obtaining an authorization code using this method. 1343 "invalid_scope": The requested scope is invalid, unknown, or 1344 malformed. 1346 "server_error": The authorization server encountered an 1347 unexpected condition that prevented it from fulfilling the 1348 request. (This error code is needed because a 500 Internal 1349 Server Error HTTP status code cannot be returned to the client 1350 via an HTTP redirect.) 1352 "temporarily_unavailable": The authorization server is currently 1353 unable to handle the request due to a temporary overloading or 1354 maintenance of the server. (This error code is needed because 1355 a 503 Service Unavailable HTTP status code cannot be returned 1356 to the client via an HTTP redirect.) 1358 Values for the "error" parameter MUST NOT include characters 1359 outside the set %x20-21 / %x23-5B / %x5D-7E. 1361 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1362 providing additional information, used to assist the client 1363 developer in understanding the error that occurred. Values for 1364 the "error_description" parameter MUST NOT include characters 1365 outside the set %x20-21 / %x23-5B / %x5D-7E. 1367 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1368 with information about the error, used to provide the client 1369 developer with additional information about the error. Values for 1370 the "error_uri" parameter MUST conform to the URI-reference syntax 1371 and thus MUST NOT include characters outside the set %x21 / 1372 %x23-5B / %x5D-7E. 1374 "state": REQUIRED if a "state" parameter was present in the client 1375 authorization request. The exact value received from the client. 1377 For example, the authorization server redirects the user-agent by 1378 sending the following HTTP response: 1380 HTTP/1.1 302 Found 1381 Location: https://client.example.com/cb?error=access_denied&state=xyz 1383 4.1.3. Access Token Request 1385 The client makes a request to the token endpoint by sending the 1386 following parameters using the "application/x-www-form-urlencoded" 1387 format per Appendix B with a character encoding of UTF-8 in the HTTP 1388 request payload: 1390 "grant_type": REQUIRED. Value MUST be set to "authorization_code". 1392 "code": REQUIRED. The authorization code received from the 1393 authorization server. 1395 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1396 included in the authorization request as described in 1397 Section 4.1.1, and their values MUST be identical. 1399 "client_id": REQUIRED, if the client is not authenticating with the 1400 authorization server as described in Section 3.2.1. 1402 "code_verifier": REQUIRED, if the "code_challenge" parameter was 1403 included in the authorization request. MUST NOT be used 1404 otherwise. The original code verifier string. 1406 If the client type is confidential or the client was issued client 1407 credentials (or assigned other authentication requirements), the 1408 client MUST authenticate with the authorization server as described 1409 in Section 3.2.1. 1411 For example, the client makes the following HTTP request using TLS 1412 (with extra line breaks for display purposes only): 1414 POST /token HTTP/1.1 1415 Host: server.example.com 1416 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1417 Content-Type: application/x-www-form-urlencoded 1419 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1420 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1421 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1423 The authorization server MUST: 1425 * require client authentication for confidential clients or for any 1426 client that was issued client credentials (or with other 1427 authentication requirements), 1429 * authenticate the client if client authentication is included, 1430 * ensure that the authorization code was issued to the authenticated 1431 confidential client, or if the client is public, ensure that the 1432 code was issued to "client_id" in the request, 1434 * verify that the authorization code is valid, 1436 * verify that the "code_verifier" parameter is present if and only 1437 if a "code_challenge" parameter was present in the authorization 1438 request, 1440 * if a "code_verifier" is present, verify the "code_verifier" by 1441 calculating the code challenge from the received "code_verifier" 1442 and comparing it with the previously associated "code_challenge", 1443 after first transforming it according to the 1444 "code_challenge_method" method specified by the client, and 1446 * ensure that the "redirect_uri" parameter is present if the 1447 "redirect_uri" parameter was included in the initial authorization 1448 request as described in Section 4.1.1.3, and if included ensure 1449 that their values are identical. 1451 4.1.4. Access Token Response 1453 If the access token request is valid and authorized, the 1454 authorization server issues an access token and optional refresh 1455 token as described in Section 5.1. If the request client 1456 authentication failed or is invalid, the authorization server returns 1457 an error response as described in Section 5.2. 1459 An example successful response: 1461 HTTP/1.1 200 OK 1462 Content-Type: application/json 1463 Cache-Control: no-store 1464 Pragma: no-cache 1466 { 1467 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1468 "token_type": "Bearer", 1469 "expires_in": 3600, 1470 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 1471 "example_parameter": "example_value" 1472 } 1474 4.2. Client Credentials Grant 1476 The client can request an access token using only its client 1477 credentials (or other supported means of authentication) when the 1478 client is requesting access to the protected resources under its 1479 control, or those of another resource owner that have been previously 1480 arranged with the authorization server (the method of which is beyond 1481 the scope of this specification). 1483 The client credentials grant type MUST only be used by confidential 1484 clients. 1486 +---------+ +---------------+ 1487 | | | | 1488 | |>--(1)- Client Authentication --->| Authorization | 1489 | Client | | Server | 1490 | |<--(2)---- Access Token ---------<| | 1491 | | | | 1492 +---------+ +---------------+ 1494 Figure 4: Client Credentials Flow 1496 The flow illustrated in Figure 4 includes the following steps: 1498 (1) The client authenticates with the authorization server and 1499 requests an access token from the token endpoint. 1501 (2) The authorization server authenticates the client, and if valid, 1502 issues an access token. 1504 4.2.1. Authorization Request and Response 1506 Since the client authentication is used as the authorization grant, 1507 no additional authorization request is needed. 1509 4.2.2. Access Token Request 1511 The client makes a request to the token endpoint by adding the 1512 following parameters using the "application/x-www-form-urlencoded" 1513 format per Appendix B with a character encoding of UTF-8 in the HTTP 1514 request payload: 1516 "grant_type": REQUIRED. Value MUST be set to "client_credentials". 1518 "scope": OPTIONAL. The scope of the access request as described by 1519 Section 3.3. 1521 The client MUST authenticate with the authorization server as 1522 described in Section 3.2.1. 1524 For example, the client makes the following HTTP request using 1525 transport-layer security (with extra line breaks for display purposes 1526 only): 1528 POST /token HTTP/1.1 1529 Host: server.example.com 1530 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1531 Content-Type: application/x-www-form-urlencoded 1533 grant_type=client_credentials 1535 The authorization server MUST authenticate the client. 1537 4.2.3. Access Token Response 1539 If the access token request is valid and authorized, the 1540 authorization server issues an access token as described in 1541 Section 5.1. A refresh token SHOULD NOT be included. If the request 1542 failed client authentication or is invalid, the authorization server 1543 returns an error response as described in Section 5.2. 1545 An example successful response: 1547 HTTP/1.1 200 OK 1548 Content-Type: application/json 1549 Cache-Control: no-store 1550 Pragma: no-cache 1552 { 1553 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1554 "token_type": "Bearer", 1555 "expires_in": 3600, 1556 "example_parameter": "example_value" 1557 } 1559 4.3. Extension Grants 1561 The client uses an extension grant type by specifying the grant type 1562 using an absolute URI (defined by the authorization server) as the 1563 value of the "grant_type" parameter of the token endpoint, and by 1564 adding any additional parameters necessary. 1566 For example, to request an access token using the Device 1567 Authorization Grant as defined by [RFC8628] after the user has 1568 authorized the client on a separate device, the client makes the 1569 following HTTP request using TLS (with extra line breaks for display 1570 purposes only): 1572 POST /token HTTP/1.1 1573 Host: server.example.com 1574 Content-Type: application/x-www-form-urlencoded 1576 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 1577 &device_code=GmRhmhcxhwEzkoEqiMEg_DnyEysNkuNhszIySk9eS 1578 &client_id=C409020731 1580 If the access token request is valid and authorized, the 1581 authorization server issues an access token and optional refresh 1582 token as described in Section 5.1. If the request failed client 1583 authentication or is invalid, the authorization server returns an 1584 error response as described in Section 5.2. 1586 5. Issuing an Access Token 1588 If the access token request is valid and authorized, the 1589 authorization server issues an access token and optional refresh 1590 token as described in Section 5.1. If the request failed client 1591 authentication or is invalid, the authorization server returns an 1592 error response as described in Section 5.2. 1594 5.1. Successful Response 1596 The authorization server issues an access token and optional refresh 1597 token, and constructs the response by adding the following parameters 1598 to the payload of the HTTP response with a 200 (OK) status code: 1600 "access_token": REQUIRED. The access token issued by the 1601 authorization server. 1603 "token_type": REQUIRED. The type of the access token issued as 1604 described in Section 7.1. Value is case insensitive. 1606 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1607 token. For example, the value "3600" denotes that the access 1608 token will expire in one hour from the time the response was 1609 generated. If omitted, the authorization server SHOULD provide 1610 the expiration time via other means or document the default value. 1612 "refresh_token": OPTIONAL. The refresh token, which can be used to 1613 obtain new access tokens using the same authorization grant as 1614 described in Section 6. 1616 "scope": OPTIONAL, if identical to the scope requested by the 1617 client; otherwise, REQUIRED. The scope of the access token as 1618 described by Section 3.3. 1620 The parameters are included in the payload of the HTTP response using 1621 the "application/json" media type as defined by [RFC7159]. The 1622 parameters are serialized into a JavaScript Object Notation (JSON) 1623 structure by adding each parameter at the highest structure level. 1624 Parameter names and string values are included as JSON strings. 1625 Numerical values are included as JSON numbers. The order of 1626 parameters does not matter and can vary. 1628 The authorization server MUST include the HTTP "Cache-Control" 1629 response header field [RFC7234] with a value of "no-store" in any 1630 response containing tokens, credentials, or other sensitive 1631 information, as well as the "Pragma" response header field [RFC7234] 1632 with a value of "no-cache". 1634 For example: 1636 HTTP/1.1 200 OK 1637 Content-Type: application/json 1638 Cache-Control: no-store 1639 Pragma: no-cache 1641 { 1642 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1643 "token_type":"Bearer", 1644 "expires_in":3600, 1645 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1646 "example_parameter":"example_value" 1647 } 1649 The client MUST ignore unrecognized value names in the response. The 1650 sizes of tokens and other values received from the authorization 1651 server are left undefined. The client should avoid making 1652 assumptions about value sizes. The authorization server SHOULD 1653 document the size of any value it issues. 1655 5.2. Error Response 1657 The authorization server responds with an HTTP 400 (Bad Request) 1658 status code (unless specified otherwise) and includes the following 1659 parameters with the response: 1661 "error": REQUIRED. A single ASCII [USASCII] error code from the 1662 following: 1664 "invalid_request": The request is missing a required parameter, 1665 includes an unsupported parameter value (other than grant 1666 type), repeats a parameter, includes multiple credentials, 1667 utilizes more than one mechanism for authenticating the client, 1668 contains a "code_verifier" although no "code_challenge" was 1669 sent in the authorization request, or is otherwise malformed. 1671 "invalid_client": Client authentication failed (e.g., unknown 1672 client, no client authentication included, or unsupported 1673 authentication method). The authorization server MAY return an 1674 HTTP 401 (Unauthorized) status code to indicate which HTTP 1675 authentication schemes are supported. If the client attempted 1676 to authenticate via the "Authorization" request header field, 1677 the authorization server MUST respond with an HTTP 401 1678 (Unauthorized) status code and include the "WWW-Authenticate" 1679 response header field matching the authentication scheme used 1680 by the client. 1682 "invalid_grant": The provided authorization grant (e.g., 1683 authorization code, resource owner credentials) or refresh 1684 token is invalid, expired, revoked, does not match the redirect 1685 URI used in the authorization request, or was issued to another 1686 client. 1688 "unauthorized_client": The authenticated client is not authorized 1689 to use this authorization grant type. 1691 "unsupported_grant_type": The authorization grant type is not 1692 supported by the authorization server. 1694 "invalid_scope": The requested scope is invalid, unknown, 1695 malformed, or exceeds the scope granted by the resource owner. 1697 Values for the "error" parameter MUST NOT include characters 1698 outside the set %x20-21 / %x23-5B / %x5D-7E. 1700 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1701 providing additional information, used to assist the client 1702 developer in understanding the error that occurred. Values for 1703 the "error_description" parameter MUST NOT include characters 1704 outside the set %x20-21 / %x23-5B / %x5D-7E. 1706 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1707 with information about the error, used to provide the client 1708 developer with additional information about the error. Values for 1709 the "error_uri" parameter MUST conform to the URI-reference syntax 1710 and thus MUST NOT include characters outside the set %x21 / 1711 %x23-5B / %x5D-7E. 1713 The parameters are included in the payload of the HTTP response using 1714 the "application/json" media type as defined by [RFC7159]. The 1715 parameters are serialized into a JSON structure by adding each 1716 parameter at the highest structure level. Parameter names and string 1717 values are included as JSON strings. Numerical values are included 1718 as JSON numbers. The order of parameters does not matter and can 1719 vary. 1721 For example: 1723 HTTP/1.1 400 Bad Request 1724 Content-Type: application/json 1725 Cache-Control: no-store 1726 Pragma: no-cache 1728 { 1729 "error":"invalid_request" 1730 } 1732 6. Refreshing an Access Token 1734 Authorization servers SHOULD determine, based on a risk assessment, 1735 whether to issue refresh tokens to a certain client. If the 1736 authorization server decides not to issue refresh tokens, the client 1737 MAY refresh access tokens by utilizing other grant types, such as the 1738 authorization code grant type. In such a case, the authorization 1739 server may utilize cookies and persistent grants to optimize the user 1740 experience. 1742 If refresh tokens are issued, those refresh tokens MUST be bound to 1743 the scope and resource servers as consented by the resource owner. 1744 This is to prevent privilege escalation by the legitimate client and 1745 reduce the impact of refresh token leakage. 1747 If the authorization server issued a refresh token to the client, the 1748 client makes a refresh request to the token endpoint by adding the 1749 following parameters using the "application/x-www-form-urlencoded" 1750 format per Appendix B with a character encoding of UTF-8 in the HTTP 1751 request payload: 1753 "grant_type": REQUIRED. Value MUST be set to "refresh_token". 1755 "refresh_token": REQUIRED. The refresh token issued to the client. 1757 "scope": OPTIONAL. The scope of the access request as described by 1758 Section 3.3. The requested scope MUST NOT include any scope not 1759 originally granted by the resource owner, and if omitted is 1760 treated as equal to the scope originally granted by the resource 1761 owner. 1763 Because refresh tokens are typically long-lasting credentials used to 1764 request additional access tokens, the refresh token is bound to the 1765 client to which it was issued. If the client type is confidential or 1766 the client was issued client credentials (or assigned other 1767 authentication requirements), the client MUST authenticate with the 1768 authorization server as described in Section 3.2.1. 1770 For example, the client makes the following HTTP request using 1771 transport-layer security (with extra line breaks for display purposes 1772 only): 1774 POST /token HTTP/1.1 1775 Host: server.example.com 1776 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1777 Content-Type: application/x-www-form-urlencoded 1779 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1781 The authorization server MUST: 1783 * require client authentication for confidential clients or for any 1784 client that was issued client credentials (or with other 1785 authentication requirements), 1787 * authenticate the client if client authentication is included and 1788 ensure that the refresh token was issued to the authenticated 1789 client, and 1791 * validate the refresh token. 1793 6.1. Refresh Token Protection 1795 Authorization servers SHOULD utilize one of these methods to detect 1796 refresh token replay by malicious actors for public clients: 1798 * _Sender-constrained refresh tokens:_ the authorization server 1799 cryptographically binds the refresh token to a certain client 1800 instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705], 1801 [I-D.ietf-oauth-dpop], or another suitable method. 1803 * _Refresh token rotation:_ the authorization server issues a new 1804 refresh token with every access token refresh response. The 1805 previous refresh token is invalidated but information about the 1806 relationship is retained by the authorization server. If a 1807 refresh token is compromised and subsequently used by both the 1808 attacker and the legitimate client, one of them will present an 1809 invalidated refresh token, which will inform the authorization 1810 server of the breach. The authorization server cannot determine 1811 which party submitted the invalid refresh token, but it will 1812 revoke the active refresh token. This stops the attack at the 1813 cost of forcing the legitimate client to obtain a fresh 1814 authorization grant. 1816 Implementation note: the grant to which a refresh token belongs may 1817 be encoded into the refresh token itself. This can enable an 1818 authorization server to efficiently determine the grant to which a 1819 refresh token belongs, and by extension, all refresh tokens that need 1820 to be revoked. Authorization servers MUST ensure the integrity of 1821 the refresh token value in this case, for example, using signatures. 1823 If valid and authorized, the authorization server issues an access 1824 token as described in Section 5.1. If the request failed 1825 verification or is invalid, the authorization server returns an error 1826 response as described in Section 5.2. 1828 The authorization server MAY issue a new refresh token, in which case 1829 the client MUST discard the old refresh token and replace it with the 1830 new refresh token. The authorization server MAY revoke the old 1831 refresh token after issuing a new refresh token to the client. If a 1832 new refresh token is issued, the refresh token scope MUST be 1833 identical to that of the refresh token included by the client in the 1834 request. 1836 Authorization servers MAY revoke refresh tokens automatically in case 1837 of a security event, such as: 1839 * password change 1841 * logout at the authorization server 1843 Refresh tokens SHOULD expire if the client has been inactive for some 1844 time, i.e., the refresh token has not been used to obtain fresh 1845 access tokens for some time. The expiration time is at the 1846 discretion of the authorization server. It might be a global value 1847 or determined based on the client policy or the grant associated with 1848 the refresh token (and its sensitivity). 1850 7. Accessing Protected Resources 1852 The client accesses protected resources by presenting the access 1853 token to the resource server. The resource server MUST validate the 1854 access token and ensure that it has not expired and that its scope 1855 covers the requested resource. The methods used by the resource 1856 server to validate the access token (as well as any error responses) 1857 are beyond the scope of this specification, but generally involve an 1858 interaction or coordination between the resource server and the 1859 authorization server, such as using Token Introspection [RFC7662] or 1860 a structured access token format such as a JWT 1861 [I-D.ietf-oauth-access-token-jwt]. 1863 The method in which the client utilizes the access token to 1864 authenticate with the resource server depends on the type of access 1865 token issued by the authorization server. Typically, it involves 1866 using the HTTP "Authorization" request header field [RFC2617] with an 1867 authentication scheme defined by the specification of the access 1868 token type used, such as "Bearer", defined below. 1870 7.1. Access Token Types 1872 The access token type provides the client with the information 1873 required to successfully utilize the access token to make a protected 1874 resource request (along with type-specific attributes). The client 1875 MUST NOT use an access token if it does not understand the token 1876 type. 1878 For example, the "Bearer" token type defined in this specification is 1879 utilized by simply including the access token string in the request: 1881 GET /resource/1 HTTP/1.1 1882 Host: example.com 1883 Authorization: Bearer mF_9.B5f-4.1JqM 1885 The above example is provided for illustration purposes only. 1887 Each access token type definition specifies the additional attributes 1888 (if any) sent to the client together with the "access_token" response 1889 parameter. It also defines the HTTP authentication method used to 1890 include the access token when making a protected resource request. 1892 7.2. Bearer Tokens 1894 A Bearer Token is a security token with the property that any party 1895 in possession of the token (a "bearer") can use the token in any way 1896 that any other party in possession of it can. Using a bearer token 1897 does not require a bearer to prove possession of cryptographic key 1898 material (proof-of-possession). 1900 Bearer tokens may be extended to include proof-of-possession 1901 techniques by other specifications. 1903 7.2.1. Authenticated Requests 1905 This section defines two methods of sending Bearer tokens in resource 1906 requests to resource servers. Clients MUST NOT use more than one 1907 method to transmit the token in each request. 1909 7.2.1.1. Authorization Request Header Field 1911 When sending the access token in the "Authorization" request header 1912 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 1913 authentication scheme to transmit the access token. 1915 For example: 1917 GET /resource HTTP/1.1 1918 Host: server.example.com 1919 Authorization: Bearer mF_9.B5f-4.1JqM 1921 The syntax of the "Authorization" header field for this scheme 1922 follows the usage of the Basic scheme defined in Section 2 of 1923 [RFC2617]. Note that, as with Basic, it does not conform to the 1924 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1925 with the general authentication framework in HTTP 1.1 Authentication 1926 [RFC7235], although it does not follow the preferred practice 1927 outlined therein in order to reflect existing deployments. The 1928 syntax for Bearer credentials is as follows: 1930 b64token = 1*( ALPHA / DIGIT / 1931 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1932 credentials = "Bearer" 1*SP b64token 1934 Clients SHOULD make authenticated requests with a bearer token using 1935 the "Authorization" request header field with the "Bearer" HTTP 1936 authorization scheme. Resource servers MUST support this method. 1938 7.2.1.2. Form-Encoded Body Parameter 1940 When sending the access token in the HTTP request payload, the client 1941 adds the access token to the request-body using the "access_token" 1942 parameter. The client MUST NOT use this method unless all of the 1943 following conditions are met: 1945 * The HTTP request entity-header includes the "Content-Type" header 1946 field set to "application/x-www-form-urlencoded". 1948 * The payload follows the encoding requirements of the "application/ 1949 x-www-form-urlencoded" content-type as defined by HTML 4.01 1950 [W3C.REC-html401-19991224]. 1952 * The HTTP request payload is single-part. 1954 * The content to be encoded in the payload MUST consist entirely of 1955 ASCII [USASCII] characters. 1957 * The HTTP request method is one for which the request-body has 1958 defined semantics. In particular, this means that the "GET" 1959 method MUST NOT be used. 1961 The payload MAY include other request-specific parameters, in which 1962 case the "access_token" parameter MUST be properly separated from the 1963 request-specific parameters using "&" character(s) (ASCII code 38). 1965 For example, the client makes the following HTTP request using 1966 transport-layer security: 1968 POST /resource HTTP/1.1 1969 Host: server.example.com 1970 Content-Type: application/x-www-form-urlencoded 1972 access_token=mF_9.B5f-4.1JqM 1974 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1975 except in application contexts where participating clients do not 1976 have access to the "Authorization" request header field. Resource 1977 servers MAY support this method. 1979 7.2.2. The WWW-Authenticate Response Header Field 1981 If the protected resource request does not include authentication 1982 credentials or does not contain an access token that enables access 1983 to the protected resource, the resource server MUST include the HTTP 1984 "WWW-Authenticate" response header field; it MAY include it in 1985 response to other conditions as well. The "WWW-Authenticate" header 1986 field uses the framework defined by HTTP/1.1 [RFC2617]. 1988 All challenges defined by this specification MUST use the auth-scheme 1989 value "Bearer". This scheme MUST be followed by one or more auth- 1990 param values. The auth-param attributes used or defined by this 1991 specification are as follows. Other auth-param attributes MAY be 1992 used as well. 1994 A "realm" attribute MAY be included to indicate the scope of 1995 protection in the manner described in HTTP/1.1 [RFC2617]. The 1996 "realm" attribute MUST NOT appear more than once. 1998 The "scope" attribute is defined in Section 3.3. The "scope" 1999 attribute is a space-delimited list of case-sensitive scope values 2000 indicating the required scope of the access token for accessing the 2001 requested resource. "scope" values are implementation defined; there 2002 is no centralized registry for them; allowed values are defined by 2003 the authorization server. The order of "scope" values is not 2004 significant. In some cases, the "scope" value will be used when 2005 requesting a new access token with sufficient scope of access to 2006 utilize the protected resource. Use of the "scope" attribute is 2007 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 2008 "scope" value is intended for programmatic use and is not meant to be 2009 displayed to end-users. 2011 Two example scope values follow; these are taken from the OpenID 2012 Connect [OpenID.Messages] and the Open Authentication Technology 2013 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 2014 OAuth 2.0 use cases, respectively: 2016 scope="openid profile email" 2017 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 2019 If the protected resource request included an access token and failed 2020 authentication, the resource server SHOULD include the "error" 2021 attribute to provide the client with the reason why the access 2022 request was declined. The parameter value is described in 2023 Section 7.2.3. In addition, the resource server MAY include the 2024 "error_description" attribute to provide developers a human-readable 2025 explanation that is not meant to be displayed to end-users. It also 2026 MAY include the "error_uri" attribute with an absolute URI 2027 identifying a human-readable web page explaining the error. The 2028 "error", "error_description", and "error_uri" attributes MUST NOT 2029 appear more than once. 2031 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 2032 include characters outside the set %x21 / %x23-5B / %x5D-7E for 2033 representing scope values and %x20 for delimiters between scope 2034 values. Values for the "error" and "error_description" attributes 2035 (specified in Appendixes A.7 and A.8) MUST NOT include characters 2036 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 2037 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 2038 the URI-reference syntax and thus MUST NOT include characters outside 2039 the set %x21 / %x23-5B / %x5D-7E. 2041 For example, in response to a protected resource request without 2042 authentication: 2044 HTTP/1.1 401 Unauthorized 2045 WWW-Authenticate: Bearer realm="example" 2047 And in response to a protected resource request with an 2048 authentication attempt using an expired access token: 2050 HTTP/1.1 401 Unauthorized 2051 WWW-Authenticate: Bearer realm="example", 2052 error="invalid_token", 2053 error_description="The access token expired" 2055 7.2.3. Error Codes 2057 When a request fails, the resource server responds using the 2058 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2059 includes one of the following error codes in the response: 2061 "invalid_request": The request is missing a required parameter, 2062 includes an unsupported parameter or parameter value, repeats the 2063 same parameter, uses more than one method for including an access 2064 token, or is otherwise malformed. The resource server SHOULD 2065 respond with the HTTP 400 (Bad Request) status code. 2067 "invalid_token": The access token provided is expired, revoked, 2068 malformed, or invalid for other reasons. The resource SHOULD 2069 respond with the HTTP 401 (Unauthorized) status code. The client 2070 MAY request a new access token and retry the protected resource 2071 request. 2073 "insufficient_scope": The request requires higher privileges than 2074 provided by the access token. The resource server SHOULD respond 2075 with the HTTP 403 (Forbidden) status code and MAY include the 2076 "scope" attribute with the scope necessary to access the protected 2077 resource. 2079 If the request lacks any authentication information (e.g., the client 2080 was unaware that authentication is necessary or attempted using an 2081 unsupported authentication method), the resource server SHOULD NOT 2082 include an error code or other error information. 2084 For example: 2086 HTTP/1.1 401 Unauthorized 2087 WWW-Authenticate: Bearer realm="example" 2089 7.3. Error Response 2091 If a resource access request fails, the resource server SHOULD inform 2092 the client of the error. The method by which the resource server 2093 does this is determined by the particular token type, such as the 2094 description of Bearer tokens in Section 7.2.3. 2096 7.3.1. Extension Token Types 2098 [RFC6750] establishes a common registry in Section 11.4 2099 (https://tools.ietf.org/html/rfc6749#section-11.4) for error values 2100 to be shared among OAuth token authentication schemes. 2102 New authentication schemes designed primarily for OAuth token 2103 authentication SHOULD define a mechanism for providing an error 2104 status code to the client, in which the error values allowed are 2105 registered in the error registry established by this specification. 2107 Such schemes MAY limit the set of valid error codes to a subset of 2108 the registered values. If the error code is returned using a named 2109 parameter, the parameter name SHOULD be "error". 2111 Other schemes capable of being used for OAuth token authentication, 2112 but not primarily designed for that purpose, MAY bind their error 2113 values to the registry in the same manner. 2115 New authentication schemes MAY choose to also specify the use of the 2116 "error_description" and "error_uri" parameters to return error 2117 information in a manner parallel to their usage in this 2118 specification. 2120 7.4. Access Token Security Considerations 2121 7.4.1. Security Threats 2123 The following list presents several common threats against protocols 2124 utilizing some form of tokens. This list of threats is based on NIST 2125 Special Publication 800-63 [NIST800-63]. 2127 7.4.1.1. Token manufacture/modification 2129 An attacker may generate a bogus token or modify the token contents 2130 (such as the authentication or attribute statements) of an existing 2131 token, causing the resource server to grant inappropriate access to 2132 the client. For example, an attacker may modify the token to extend 2133 the validity period; a malicious client may modify the assertion to 2134 gain access to information that they should not be able to view. 2136 7.4.1.2. Token disclosure 2138 Tokens may contain authentication and attribute statements that 2139 include sensitive information. 2141 7.4.1.3. Token redirect 2143 An attacker uses a token generated for consumption by one resource 2144 server to gain access to a different resource server that mistakenly 2145 believes the token to be for it. 2147 7.4.1.4. Token replay 2149 An attacker attempts to use a token that has already been used with 2150 that resource server in the past. 2152 7.4.2. Threat Mitigation 2154 A large range of threats can be mitigated by protecting the contents 2155 of the token by using a digital signature. Alternatively, a bearer 2156 token can contain a reference to authorization information, rather 2157 than encoding the information directly. Such references MUST be 2158 infeasible for an attacker to guess; using a reference may require an 2159 extra interaction between a server and the token issuer to resolve 2160 the reference to the authorization information. The mechanics of 2161 such an interaction are not defined by this specification. 2163 This document does not specify the encoding or the contents of the 2164 token; hence, detailed recommendations about the means of 2165 guaranteeing token integrity protection are outside the scope of this 2166 document. The token integrity protection MUST be sufficient to 2167 prevent the token from being modified. 2169 To deal with token redirect, it is important for the authorization 2170 server to include the identity of the intended recipients (the 2171 audience), typically a single resource server (or a list of resource 2172 servers), in the token. Restricting the use of the token to a 2173 specific scope is also RECOMMENDED. 2175 The authorization server MUST implement TLS. Which version(s) ought 2176 to be implemented will vary over time and will depend on the 2177 widespread deployment and known security vulnerabilities at the time 2178 of implementation. 2180 To protect against token disclosure, confidentiality protection MUST 2181 be applied using TLS with a ciphersuite that provides confidentiality 2182 and integrity protection. This requires that the communication 2183 interaction between the client and the authorization server, as well 2184 as the interaction between the client and the resource server, 2185 utilize confidentiality and integrity protection. Since TLS is 2186 mandatory to implement and to use with this specification, it is the 2187 preferred approach for preventing token disclosure via the 2188 communication channel. For those cases where the client is prevented 2189 from observing the contents of the token, token encryption MUST be 2190 applied in addition to the usage of TLS protection. As a further 2191 defense against token disclosure, the client MUST validate the TLS 2192 certificate chain when making requests to protected resources, 2193 including checking the Certificate Revocation List (CRL) [RFC5280]. 2195 Cookies are typically transmitted in the clear. Thus, any 2196 information contained in them is at risk of disclosure. Therefore, 2197 Bearer tokens MUST NOT be stored in cookies that can be sent in the 2198 clear, as any information in them is at risk of disclosure. See 2199 "HTTP State Management Mechanism" [RFC6265] for security 2200 considerations about cookies. 2202 In some deployments, including those utilizing load balancers, the 2203 TLS connection to the resource server terminates prior to the actual 2204 server that provides the resource. This could leave the token 2205 unprotected between the front-end server where the TLS connection 2206 terminates and the back-end server that provides the resource. In 2207 such deployments, sufficient measures MUST be employed to ensure 2208 confidentiality of the token between the front-end and back-end 2209 servers; encryption of the token is one such possible measure. 2211 To deal with token capture and replay, the following recommendations 2212 are made: First, the lifetime of the token MUST be limited; one means 2213 of achieving this is by putting a validity time field inside the 2214 protected part of the token. Note that using short-lived (one hour 2215 or less) tokens reduces the impact of them being leaked. Second, 2216 confidentiality protection of the exchanges between the client and 2217 the authorization server and between the client and the resource 2218 server MUST be applied. As a consequence, no eavesdropper along the 2219 communication path is able to observe the token exchange. 2220 Consequently, such an on-path adversary cannot replay the token. 2221 Furthermore, when presenting the token to a resource server, the 2222 client MUST verify the identity of that resource server, as per 2223 Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST 2224 validate the TLS certificate chain when making these requests to 2225 protected resources. Presenting the token to an unauthenticated and 2226 unauthorized resource server or failing to validate the certificate 2227 chain will allow adversaries to steal the token and gain unauthorized 2228 access to protected resources. 2230 7.4.3. Summary of Recommendations 2232 7.4.3.1. Safeguard bearer tokens 2234 Client implementations MUST ensure that bearer tokens are not leaked 2235 to unintended parties, as they will be able to use them to gain 2236 access to protected resources. This is the primary security 2237 consideration when using bearer tokens and underlies all the more 2238 specific recommendations that follow. 2240 7.4.3.2. Validate TLS certificate chains 2242 The client MUST validate the TLS certificate chain when making 2243 requests to protected resources. Failing to do so may enable DNS 2244 hijacking attacks to steal the token and gain unintended access. 2246 7.4.3.3. Always use TLS (https) 2248 Clients MUST always use TLS (https) or equivalent transport security 2249 when making requests with bearer tokens. Failing to do so exposes 2250 the token to numerous attacks that could give attackers unintended 2251 access. 2253 7.4.3.4. Don't store bearer tokens in HTTP cookies 2255 Implementations MUST NOT store bearer tokens within cookies that can 2256 be sent in the clear (which is the default transmission mode for 2257 cookies). Implementations that do store bearer tokens in cookies 2258 MUST take precautions against cross-site request forgery. 2260 7.4.3.5. Issue short-lived bearer tokens 2262 Authorization servers SHOULD issue short-lived (one hour or less) 2263 bearer tokens, particularly when issuing tokens to clients that run 2264 within a web browser or other environments where information leakage 2265 may occur. Using short-lived bearer tokens can reduce the impact of 2266 them being leaked. 2268 7.4.3.6. Issue scoped bearer tokens 2270 Authorization servers SHOULD issue bearer tokens that contain an 2271 audience restriction, scoping their use to the intended relying party 2272 or set of relying parties. 2274 7.4.3.7. Don't pass bearer tokens in page URLs 2276 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2277 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2278 message headers or message bodies for which confidentiality measures 2279 are taken. Browsers, web servers, and other software may not 2280 adequately secure URLs in the browser history, web server logs, and 2281 other data structures. If bearer tokens are passed in page URLs, 2282 attackers might be able to steal them from the history data, logs, or 2283 other unsecured locations. 2285 7.4.4. Token Replay Prevention 2287 A sender-constrained access token scopes the applicability of an 2288 access token to a certain sender. This sender is obliged to 2289 demonstrate knowledge of a certain secret as prerequisite for the 2290 acceptance of that access token at the recipient (e.g., a resource 2291 server). 2293 Authorization and resource servers SHOULD use mechanisms for sender- 2294 constrained access tokens to prevent token replay as described in 2295 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2296 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2298 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2299 terminated at an intermediary, refer to Section 4.11 of 2300 [I-D.ietf-oauth-security-topics] for further security advice. 2302 7.4.5. Access Token Privilege Restriction 2304 The privileges associated with an access token SHOULD be restricted 2305 to the minimum required for the particular application or use case. 2306 This prevents clients from exceeding the privileges authorized by the 2307 resource owner. It also prevents users from exceeding their 2308 privileges authorized by the respective security policy. Privilege 2309 restrictions also help to reduce the impact of access token leakage. 2311 In particular, access tokens SHOULD be restricted to certain resource 2312 servers (audience restriction), preferably to a single resource 2313 server. To put this into effect, the authorization server associates 2314 the access token with certain resource servers and every resource 2315 server is obliged to verify, for every request, whether the access 2316 token sent with that request was meant to be used for that particular 2317 resource server. If not, the resource server MUST refuse to serve 2318 the respective request. Clients and authorization servers MAY 2319 utilize the parameters "scope" or "resource" as specified in this 2320 document and [RFC8707], respectively, to determine the resource 2321 server they want to access. 2323 Additionally, access tokens SHOULD be restricted to certain resources 2324 and actions on resource servers or resources. To put this into 2325 effect, the authorization server associates the access token with the 2326 respective resource and actions and every resource server is obliged 2327 to verify, for every request, whether the access token sent with that 2328 request was meant to be used for that particular action on the 2329 particular resource. If not, the resource server must refuse to 2330 serve the respective request. Clients and authorization servers MAY 2331 utilize the parameter "scope" and "authorization_details" as 2332 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2333 actions. 2335 8. Extensibility 2337 8.1. Defining Access Token Types 2339 Access token types can be defined in one of two ways: registered in 2340 the Access Token Types registry (following the procedures in 2341 Section 11.1 of [RFC6749]), or by using a unique absolute URI as its 2342 name. 2344 Types utilizing a URI name SHOULD be limited to vendor-specific 2345 implementations that are not commonly applicable, and are specific to 2346 the implementation details of the resource server where they are 2347 used. 2349 All other types MUST be registered. Type names MUST conform to the 2350 type-name ABNF. If the type definition includes a new HTTP 2351 authentication scheme, the type name SHOULD be identical to the HTTP 2352 authentication scheme name (as defined by [RFC2617]). The token type 2353 "example" is reserved for use in examples. 2355 type-name = 1*name-char 2356 name-char = "-" / "." / "_" / DIGIT / ALPHA 2358 8.2. Defining New Endpoint Parameters 2360 New request or response parameters for use with the authorization 2361 endpoint or the token endpoint are defined and registered in the 2362 OAuth Parameters registry following the procedure in Section 11.2 of 2363 [RFC6749]. 2365 Parameter names MUST conform to the param-name ABNF, and parameter 2366 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2367 to the syntax of an existing parameter). 2369 param-name = 1*name-char 2370 name-char = "-" / "." / "_" / DIGIT / ALPHA 2372 Unregistered vendor-specific parameter extensions that are not 2373 commonly applicable and that are specific to the implementation 2374 details of the authorization server where they are used SHOULD 2375 utilize a vendor-specific prefix that is not likely to conflict with 2376 other registered values (e.g., begin with 'companyname_'). 2378 8.3. Defining New Authorization Grant Types 2380 New authorization grant types can be defined by assigning them a 2381 unique absolute URI for use with the "grant_type" parameter. If the 2382 extension grant type requires additional token endpoint parameters, 2383 they MUST be registered in the OAuth Parameters registry as described 2384 by Section 11.2 of [RFC6749]. 2386 8.4. Defining New Authorization Endpoint Response Types 2388 New response types for use with the authorization endpoint are 2389 defined and registered in the Authorization Endpoint Response Types 2390 registry following the procedure in Section 11.3 of [RFC6749]. 2391 Response type names MUST conform to the response-type ABNF. 2393 response-type = response-name *( SP response-name ) 2394 response-name = 1*response-char 2395 response-char = "_" / DIGIT / ALPHA 2396 If a response type contains one or more space characters (%x20), it 2397 is compared as a space-delimited list of values in which the order of 2398 values does not matter. Only one order of values can be registered, 2399 which covers all other arrangements of the same set of values. 2401 For example, an extension can define and register the "code 2402 other_token" response type. Once registered, the same combination 2403 cannot be registered as "other_token code", but both values can be 2404 used to denote the same response type. 2406 8.5. Defining Additional Error Codes 2408 In cases where protocol extensions (i.e., access token types, 2409 extension parameters, or extension grant types) require additional 2410 error codes to be used with the authorization code grant error 2411 response (Section 4.1.2.1), the token error response (Section 5.2), 2412 or the resource access error response (Section 7.3), such error codes 2413 MAY be defined. 2415 Extension error codes MUST be registered (following the procedures in 2416 Section 11.4 of [RFC6749]) if the extension they are used in 2417 conjunction with is a registered access token type, a registered 2418 endpoint parameter, or an extension grant type. Error codes used 2419 with unregistered extensions MAY be registered. 2421 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2422 an identifying name when possible. For example, an error identifying 2423 an invalid value set to the extension parameter "example" SHOULD be 2424 named "example_invalid". 2426 error = 1*error-char 2427 error-char = %x20-21 / %x23-5B / %x5D-7E 2429 9. Security Considerations 2431 As a flexible and extensible framework, OAuth's security 2432 considerations depend on many factors. The following sections 2433 provide implementers with security guidelines focused on the three 2434 client profiles described in Section 2.1: web application, browser- 2435 based application, and native application. 2437 A comprehensive OAuth security model and analysis, as well as 2438 background for the protocol design, is provided by [RFC6819] and 2439 [I-D.ietf-oauth-security-topics]. 2441 9.1. Client Authentication 2443 Authorization servers SHOULD use client authentication if possible. 2445 It is RECOMMENDED to use asymmetric (public-key based) methods for 2446 client authentication such as mTLS [RFC8705] or "private_key_jwt" 2447 [OpenID]. When asymmetric methods for client authentication are 2448 used, authorization servers do not need to store sensitive symmetric 2449 keys, making these methods more robust against a number of attacks. 2451 Authorization server MUST only rely on client authentication if the 2452 process of issuance/registration and distribution of the underlying 2453 credentials ensures their confidentiality. 2455 When client authentication is not possible, the authorization server 2456 SHOULD employ other means to validate the client's identity - for 2457 example, by requiring the registration of the client redirect URI or 2458 enlisting the resource owner to confirm identity. A valid redirect 2459 URI is not sufficient to verify the client's identity when asking for 2460 resource owner authorization but can be used to prevent delivering 2461 credentials to a counterfeit client after obtaining resource owner 2462 authorization. 2464 The authorization server must consider the security implications of 2465 interacting with unauthenticated clients and take measures to limit 2466 the potential exposure of other credentials (e.g., refresh tokens) 2467 issued to such clients. 2469 The privileges an authorization server associates with a certain 2470 client identity MUST depend on the assessment of the overall process 2471 for client identification and client credential lifecycle management. 2472 For example, authentication of a dynamically registered client just 2473 ensures the authorization server it is talking to the same client 2474 again. In contrast, if there is a web application whose developer's 2475 identity was verified, who signed a contract and is issued a client 2476 secret that is only used in a secure backend service, the 2477 authorization server might allow this client to access more sensible 2478 services or to use the client credential grant type. 2480 9.1.1. Client Authentication of Native Apps 2482 Secrets that are statically included as part of an app distributed to 2483 multiple users should not be treated as confidential secrets, as one 2484 user may inspect their copy and learn the shared secret. For this 2485 reason, it is NOT RECOMMENDED for authorization servers to require 2486 client authentication of public native apps clients using a shared 2487 secret, as this serves little value beyond client identification 2488 which is already provided by the "client_id" request parameter. 2490 Authorization servers that still require a statically included shared 2491 secret for native app clients MUST treat the client as a public 2492 client (as defined in Section 2.1), and not accept the secret as 2493 proof of the client's identity. Without additional measures, such 2494 clients are subject to client impersonation (see Section 9.3.1). 2496 9.2. Registration of Native App Clients 2498 Except when using a mechanism like Dynamic Client Registration 2499 [RFC7591] to provision per-instance secrets, native apps are 2500 classified as public clients, as defined in Section 2.1; they MUST be 2501 registered with the authorization server as such. Authorization 2502 servers MUST record the client type in the client registration 2503 details in order to identify and process requests accordingly. 2505 Authorization servers MUST require clients to register their complete 2506 redirect URI (including the path component) and reject authorization 2507 requests that specify a redirect URI that doesn't exactly match the 2508 one that was registered; the exception is loopback redirects, where 2509 an exact match is required except for the port URI component. 2511 For private-use URI scheme-based redirects, authorization servers 2512 SHOULD enforce the requirement in Section 10.3.1 that clients use 2513 schemes that are reverse domain name based. At a minimum, any 2514 private-use URI scheme that doesn't contain a period character (".") 2515 SHOULD be rejected. 2517 In addition to the collision-resistant properties, requiring a URI 2518 scheme based on a domain name that is under the control of the app 2519 can help to prove ownership in the event of a dispute where two apps 2520 claim the same private-use URI scheme (where one app is acting 2521 maliciously). For example, if two apps claimed "com.example.app", 2522 the owner of "example.com" could petition the app store operator to 2523 remove the counterfeit app. Such a petition is harder to prove if a 2524 generic URI scheme was used. 2526 Authorization servers MAY request the inclusion of other platform- 2527 specific information, such as the app package or bundle name, or 2528 other information that may be useful for verifying the calling app's 2529 identity on operating systems that support such functions. 2531 9.3. Client Impersonation 2533 A malicious client can impersonate another client and obtain access 2534 to protected resources if the impersonated client fails to, or is 2535 unable to, keep its client credentials confidential. 2537 The authorization server MUST authenticate the client whenever 2538 possible. If the authorization server cannot authenticate the client 2539 due to the client's nature, the authorization server MUST require the 2540 registration of any redirect URI used for receiving authorization 2541 responses and SHOULD utilize other means to protect resource owners 2542 from such potentially malicious clients. For example, the 2543 authorization server can engage the resource owner to assist in 2544 identifying the client and its origin. 2546 The authorization server SHOULD enforce explicit resource owner 2547 authentication and provide the resource owner with information about 2548 the client and the requested authorization scope and lifetime. It is 2549 up to the resource owner to review the information in the context of 2550 the current client and to authorize or deny the request. 2552 The authorization server SHOULD NOT process repeated authorization 2553 requests automatically (without active resource owner interaction) 2554 without authenticating the client or relying on other measures to 2555 ensure that the repeated request comes from the original client and 2556 not an impersonator. 2558 9.3.1. Impersonation of Native Apps 2560 As stated above, the authorization server SHOULD NOT process 2561 authorization requests automatically without user consent or 2562 interaction, except when the identity of the client can be assured. 2563 This includes the case where the user has previously approved an 2564 authorization request for a given client id - unless the identity of 2565 the client can be proven, the request SHOULD be processed as if no 2566 previous request had been approved. 2568 Measures such as claimed "https" scheme redirects MAY be accepted by 2569 authorization servers as identity proof. Some operating systems may 2570 offer alternative platform-specific identity features that MAY be 2571 accepted, as appropriate. 2573 9.4. Access Tokens 2575 Access token credentials (as well as any confidential access token 2576 attributes) MUST be kept confidential in transit and storage, and 2577 only shared among the authorization server, the resource servers the 2578 access token is valid for, and the client to whom the access token is 2579 issued. Access token credentials MUST only be transmitted using TLS 2580 as described in Section 1.6 with server authentication as defined by 2581 [RFC2818]. 2583 The authorization server MUST ensure that access tokens cannot be 2584 generated, modified, or guessed to produce valid access tokens by 2585 unauthorized parties. 2587 9.4.1. Access Token Privilege Restriction 2589 The client SHOULD request access tokens with the minimal scope 2590 necessary. The authorization server SHOULD take the client identity 2591 into account when choosing how to honor the requested scope and MAY 2592 issue an access token with less rights than requested. 2594 The privileges associated with an access token SHOULD be restricted 2595 to the minimum required for the particular application or use case. 2596 This prevents clients from exceeding the privileges authorized by the 2597 resource owner. It also prevents users from exceeding their 2598 privileges authorized by the respective security policy. Privilege 2599 restrictions also help to reduce the impact of access token leakage. 2601 In particular, access tokens SHOULD be restricted to certain resource 2602 servers (audience restriction), preferably to a single resource 2603 server. To put this into effect, the authorization server associates 2604 the access token with certain resource servers and every resource 2605 server is obliged to verify, for every request, whether the access 2606 token sent with that request was meant to be used for that particular 2607 resource server. If not, the resource server MUST refuse to serve 2608 the respective request. Clients and authorization servers MAY 2609 utilize the parameters "scope" or "resource" as specified in 2610 [RFC8707], respectively, to determine the resource server they want 2611 to access. 2613 9.4.2. Access Token Replay Prevention 2615 Additionally, access tokens SHOULD be restricted to certain resources 2616 and actions on resource servers or resources. To put this into 2617 effect, the authorization server associates the access token with the 2618 respective resource and actions and every resource server is obliged 2619 to verify, for every request, whether the access token sent with that 2620 request was meant to be used for that particular action on the 2621 particular resource. If not, the resource server must refuse to 2622 serve the respective request. Clients and authorization servers MAY 2623 utilize the parameter "scope" and "authorization_details" as 2624 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2625 actions. 2627 Authorization and resource servers SHOULD use mechanisms for sender- 2628 constrained access tokens to prevent token replay as described in 2629 (#pop_tokens). A sender-constrained access token scopes the 2630 applicability of an access token to a certain sender. This sender is 2631 obliged to demonstrate knowledge of a certain secret as prerequisite 2632 for the acceptance of that access token at the recipient (e.g., a 2633 resource server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2634 RECOMMENDED. 2636 9.5. Refresh Tokens 2638 Authorization servers MAY issue refresh tokens to clients. 2640 Refresh tokens MUST be kept confidential in transit and storage, and 2641 shared only among the authorization server and the client to whom the 2642 refresh tokens were issued. The authorization server MUST maintain 2643 the binding between a refresh token and the client to whom it was 2644 issued. Refresh tokens MUST only be transmitted using TLS as 2645 described in Section 1.6 with server authentication as defined by 2646 [RFC2818]. 2648 The authorization server MUST verify the binding between the refresh 2649 token and client identity whenever the client identity can be 2650 authenticated. When client authentication is not possible, the 2651 authorization server SHOULD issue sender-constrained refresh tokens 2652 or use refresh token rotation as described in 2653 (#refresh_token_protection). 2655 The authorization server MUST ensure that refresh tokens cannot be 2656 generated, modified, or guessed to produce valid refresh tokens by 2657 unauthorized parties. 2659 9.6. Client Impersonating Resource Owner 2661 Resource servers may make access control decisions based on the 2662 identity of the resource owner as communicated in the "sub" claim 2663 returned by the authorization server in a token introspection 2664 response [RFC7662] or other mechanisms. If a client is able to 2665 choose its own "client_id" during registration with the authorization 2666 server, then there is a risk that it can register with the same "sub" 2667 value as a privileged user. A subsequent access token obtained under 2668 the client credentials grant may be mistaken for an access token 2669 authorized by the privileged user if the resource server does not 2670 perform additional checks. 2672 Authorization servers SHOULD NOT allow clients to influence their 2673 "client_id" or "sub" value or any other claim if that can cause 2674 confusion with a genuine resource owner. Where this cannot be 2675 avoided, authorization servers MUST provide other means for the 2676 resource server to distinguish between access tokens authorized by a 2677 resource owner from access tokens authorized by the client itself. 2679 9.7. Protecting Redirect-Based Flows 2681 When comparing client redirect URIs against pre-registered URIs, 2682 authorization servers MUST utilize exact string matching. This 2683 measure contributes to the prevention of leakage of authorization 2684 codes and access tokens (see (#insufficient_uri_validation)). It can 2685 also help to detect mix-up attacks (see (#mix_up)). 2687 Clients MUST NOT expose URLs that forward the user's browser to 2688 arbitrary URIs obtained from a query parameter ("open redirector"). 2689 Open redirectors can enable exfiltration of authorization codes and 2690 access tokens, see (#open_redirector_on_client). 2692 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2693 context, CSRF refers to requests to the redirection endpoint that do 2694 not originate at the authorization server, but a malicious third 2695 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2696 have ensured that the authorization server supports the 2697 "code_challenge" parameter MAY rely the CSRF protection provided by 2698 that mechanism. In OpenID Connect flows, the "nonce" parameter 2699 provides CSRF protection. Otherwise, one-time use CSRF tokens 2700 carried in the "state" parameter that are securely bound to the user 2701 agent MUST be used for CSRF protection (see (#csrf_countermeasures)). 2703 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2704 process redirect responses of the authorization server they sent the 2705 respective request to and from the same user agent this authorization 2706 request was initiated with. Clients MUST store the authorization 2707 server they sent an authorization request to and bind this 2708 information to the user agent and check that the authorization 2709 request was received from the correct authorization server. Clients 2710 MUST ensure that the subsequent access token request, if applicable, 2711 is sent to the same authorization server. Clients SHOULD use 2712 distinct redirect URIs for each authorization server as a means to 2713 identify the authorization server a particular response came from. 2715 An AS that redirects a request potentially containing user 2716 credentials MUST avoid forwarding these user credentials accidentally 2717 (see Section 9.7.2 for details). 2719 9.7.1. Loopback Redirect Considerations in Native Apps 2721 Loopback interface redirect URIs use the "http" scheme (i.e., without 2722 Transport Layer Security (TLS)). This is acceptable for loopback 2723 interface redirect URIs as the HTTP request never leaves the device. 2725 Clients should open the network port only when starting the 2726 authorization request and close it once the response is returned. 2728 Clients should listen on the loopback network interface only, in 2729 order to avoid interference by other network actors. 2731 While redirect URIs using localhost (i.e., 2732 "http://localhost:{port}/{path}") function similarly to loopback IP 2733 redirects described in Section 10.3.3, the use of "localhost" is NOT 2734 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2735 rather than "localhost" avoids inadvertently listening on network 2736 interfaces other than the loopback interface. It is also less 2737 susceptible to client-side firewalls and misconfigured host name 2738 resolution on the user's device. 2740 9.7.2. HTTP 307 Redirect 2742 An AS which redirects a request that potentially contains user 2743 credentials MUST NOT use the HTTP 307 status code for redirection. 2744 If an HTTP redirection (and not, for example, JavaScript) is used for 2745 such a request, AS SHOULD use HTTP status code 303 "See Other". 2747 At the authorization endpoint, a typical protocol flow is that the AS 2748 prompts the user to enter their credentials in a form that is then 2749 submitted (using the HTTP POST method) back to the authorization 2750 server. The AS checks the credentials and, if successful, redirects 2751 the user agent to the client's redirect URI. 2753 If the status code 307 were used for redirection, the user agent 2754 would send the user credentials via HTTP POST to the client. 2756 This discloses the sensitive credentials to the client. If the 2757 relying party is malicious, it can use the credentials to impersonate 2758 the user at the AS. 2760 The behavior might be unexpected for developers, but is defined in 2761 [RFC7231], Section 6.4.7. This status code does not require the user 2762 agent to rewrite the POST request to a GET request and thereby drop 2763 the form data in the POST request body. 2765 In the HTTP standard [RFC7231], only the status code 303 2766 unambigiously enforces rewriting the HTTP POST request to an HTTP GET 2767 request. For all other status codes, including the popular 302, user 2768 agents can opt not to rewrite POST to GET requests and therefore to 2769 reveal the user credentials to the client. (In practice, however, 2770 most user agents will only show this behaviour for 307 redirects.) 2772 Therefore, the RECOMMENDED status code for HTTP redirects is 303. 2774 9.8. Authorization Codes 2776 The transmission of authorization codes MUST be made over a secure 2777 channel, and the client MUST require the use of TLS with its redirect 2778 URI if the URI identifies a network resource. Since authorization 2779 codes are transmitted via user-agent redirections, they could 2780 potentially be disclosed through user-agent history and HTTP referrer 2781 headers. 2783 Authorization codes MUST be short lived and single-use. If the 2784 authorization server observes multiple attempts to exchange an 2785 authorization code for an access token, the authorization server 2786 SHOULD attempt to revoke all refresh and access tokens already 2787 granted based on the compromised authorization code. 2789 If the client can be authenticated, the authorization servers MUST 2790 authenticate the client and ensure that the authorization code was 2791 issued to the same client. 2793 Clients MUST prevent injection (replay) of authorization codes into 2794 the authorization response by attackers. To this end, using 2795 "code_challenge" and "code_verifier" is REQUIRED for clients and 2796 authorization servers MUST enforce their use, unless both of the 2797 following criteria are met: 2799 * The client is a confidential client. 2801 * In the specific deployment and the specific request, there is 2802 reasonable assurance for authorization server that the client 2803 implements the OpenID Connect "nonce" mechanism properly. 2805 In this case, using and enforcing "code_challenge" and 2806 "code_verifier" is still RECOMMENDED. 2808 The "code_challenge" or OpenID Connect "nonce" value MUST be 2809 transaction-specific and securely bound to the client and the user 2810 agent in which the transaction was started. If a transaction leads 2811 to an error, fresh values for "code_challenge" or "nonce" MUST be 2812 chosen. 2814 Historic note: Although PKCE [RFC7636] was originally designed as a 2815 mechanism to protect native apps, this advice applies to all kinds of 2816 OAuth clients, including web applications and other confidential 2817 clients. 2819 Clients SHOULD use code challenge methods that do not expose the 2820 "code_verifier" in the authorization request. Otherwise, attackers 2821 that can read the authorization request (cf. Attacker A4 in 2822 (#secmodel)) can break the security provided by this mechanism. 2823 Currently, "S256" is the only such method. 2825 When an authorization code arrives at the token endpoint, the 2826 authorization server MUST do the following check: 2828 1. If there was a "code_challenge" in the authorization request for 2829 which this code was issued, there must be a "code_verifier" in 2830 the token request, and it MUST be verified according to the steps 2831 in Section 4.1.3. (This is no change from the current behavior 2832 in [RFC7636].) 2834 2. If there was no "code_challenge" in the authorization request, 2835 any request to the token endpoint containing a "code_verifier" 2836 MUST be rejected. 2838 Authorization servers MUST support the "code_challenge" and 2839 "code_verifier" parameters. 2841 Authorization servers MUST provide a way to detect their support for 2842 the "code_challenge" mechanism. To this end, they MUST either (a) 2843 publish the element "code_challenge_methods_supported" in their AS 2844 metadata ([RFC8414]) containing the supported 2845 "code_challenge_method"s (which can be used by the client to detect 2846 support) or (b) provide a deployment-specific way to ensure or 2847 determine support by the AS. 2849 9.9. Request Confidentiality 2851 Access tokens, refresh tokens, authorization codes, and client 2852 credentials MUST NOT be transmitted in the clear. 2854 The "state" and "scope" parameters SHOULD NOT include sensitive 2855 client or resource owner information in plain text, as they can be 2856 transmitted over insecure channels or stored insecurely. 2858 9.10. Ensuring Endpoint Authenticity 2860 In order to prevent man-in-the-middle attacks, the authorization 2861 server MUST require the use of TLS with server authentication as 2862 defined by [RFC2818] for any request sent to the authorization and 2863 token endpoints. The client MUST validate the authorization server's 2864 TLS certificate as defined by [RFC6125] and in accordance with its 2865 requirements for server identity authentication. 2867 9.11. Credentials-Guessing Attacks 2869 The authorization server MUST prevent attackers from guessing access 2870 tokens, authorization codes, refresh tokens, resource owner 2871 passwords, and client credentials. 2873 The probability of an attacker guessing generated tokens (and other 2874 credentials not intended for handling by end-users) MUST be less than 2875 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2877 The authorization server MUST utilize other means to protect 2878 credentials intended for end-user usage. 2880 9.12. Phishing Attacks 2882 Wide deployment of this and similar protocols may cause end-users to 2883 become inured to the practice of being redirected to websites where 2884 they are asked to enter their passwords. If end-users are not 2885 careful to verify the authenticity of these websites before entering 2886 their credentials, it will be possible for attackers to exploit this 2887 practice to steal resource owners' passwords. 2889 Service providers should attempt to educate end-users about the risks 2890 phishing attacks pose and should provide mechanisms that make it easy 2891 for end-users to confirm the authenticity of their sites. Client 2892 developers should consider the security implications of how they 2893 interact with the user-agent (e.g., external, embedded), and the 2894 ability of the end-user to verify the authenticity of the 2895 authorization server. 2897 To reduce the risk of phishing attacks, the authorization servers 2898 MUST require the use of TLS on every endpoint used for end-user 2899 interaction. 2901 9.13. Fake External User-Agents in Native Apps 2903 The native app that is initiating the authorization request has a 2904 large degree of control over the user interface and can potentially 2905 present a fake external user-agent, that is, an embedded user-agent 2906 made to appear as an external user-agent. 2908 When all good actors are using external user-agents, the advantage is 2909 that it is possible for security experts to detect bad actors, as 2910 anyone faking an external user-agent is provably bad. On the other 2911 hand, if good and bad actors alike are using embedded user-agents, 2912 bad actors don't need to fake anything, making them harder to detect. 2913 Once a malicious app is detected, it may be possible to use this 2914 knowledge to blacklist the app's signature in malware scanning 2915 software, take removal action (in the case of apps distributed by app 2916 stores) and other steps to reduce the impact and spread of the 2917 malicious app. 2919 Authorization servers can also directly protect against fake external 2920 user-agents by requiring an authentication factor only available to 2921 true external user-agents. 2923 Users who are particularly concerned about their security when using 2924 in-app browser tabs may also take the additional step of opening the 2925 request in the full browser from the in-app browser tab and complete 2926 the authorization there, as most implementations of the in-app 2927 browser tab pattern offer such functionality. 2929 9.14. Malicious External User-Agents in Native Apps 2931 If a malicious app is able to configure itself as the default handler 2932 for "https" scheme URIs in the operating system, it will be able to 2933 intercept authorization requests that use the default browser and 2934 abuse this position of trust for malicious ends such as phishing the 2935 user. 2937 This attack is not confined to OAuth; a malicious app configured in 2938 this way would present a general and ongoing risk to the user beyond 2939 OAuth usage by native apps. Many operating systems mitigate this 2940 issue by requiring an explicit user action to change the default 2941 handler for "http" and "https" scheme URIs. 2943 9.15. Cross-Site Request Forgery 2945 An attacker might attempt to inject a request to the redirect URI of 2946 the legitimate client on the victim's device, e.g., to cause the 2947 client to access resources under the attacker's control. This is a 2948 variant of an attack known as Cross-Site Request Forgery (CSRF). 2950 The traditional countermeasure are CSRF tokens that are bound to the 2951 user agent and passed in the "state" parameter to the authorization 2952 server as described in [RFC6819]. The same protection is provided by 2953 the "code_verifier" parameter or the OpenID Connect "nonce" value. 2955 When using "code_verifier" instead of "state" or "nonce" for CSRF 2956 protection, it is important to note that: 2958 * Clients MUST ensure that the AS supports the 2959 "code_challenge_method" intended to be used by the client. If an 2960 authorization server does not support the requested method, 2961 "state" or "nonce" MUST be used for CSRF protection instead. 2963 * If "state" is used for carrying application state, and integrity 2964 of its contents is a concern, clients MUST protect "state" against 2965 tampering and swapping. This can be achieved by binding the 2966 contents of state to the browser session and/or signed/encrypted 2967 state values [I-D.bradley-oauth-jwt-encoded-state]. 2969 AS therefore MUST provide a way to detect their supported code 2970 challenge methods either via AS metadata according to [RFC8414] or 2971 provide a deployment-specific way to ensure or determine support. 2973 9.16. Clickjacking 2975 As described in Section 4.4.1.9 of [RFC6819], the authorization 2976 request is susceptible to clickjacking. An attacker can use this 2977 vector to obtain the user's authentication credentials, change the 2978 scope of access granted to the client, and potentially access the 2979 user's resources. 2981 Authorization servers MUST prevent clickjacking attacks. Multiple 2982 countermeasures are described in [RFC6819], including the use of the 2983 X-Frame-Options HTTP response header field and frame-busting 2984 JavaScript. In addition to those, authorization servers SHOULD also 2985 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2987 To be effective, CSP must be used on the authorization endpoint and, 2988 if applicable, other endpoints used to authenticate the user and 2989 authorize the client (e.g., the device authorization endpoint, login 2990 pages, error pages, etc.). This prevents framing by unauthorized 2991 origins in user agents that support CSP. The client MAY permit being 2992 framed by some other origin than the one used in its redirection 2993 endpoint. For this reason, authorization servers SHOULD allow 2994 administrators to configure allowed origins for particular clients 2995 and/or for clients to register these dynamically. 2997 Using CSP allows authorization servers to specify multiple origins in 2998 a single response header field and to constrain these using flexible 2999 patterns (see [CSP-2] for details). Level 2 of this standard 3000 provides a robust mechanism for protecting against clickjacking by 3001 using policies that restrict the origin of frames (using "frame- 3002 ancestors") together with those that restrict the sources of scripts 3003 allowed to execute on an HTML page (by using "script-src"). A non- 3004 normative example of such a policy is shown in the following listing: 3006 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 3007 https://ext.example.org:8000 Content-Security-Policy: script-src 3008 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 3009 Because some user agents do not support [CSP-2], this technique 3010 SHOULD be combined with others, including those described in 3011 [RFC6819], unless such legacy user agents are explicitly unsupported 3012 by the authorization server. Even in such cases, additional 3013 countermeasures SHOULD still be employed. 3015 9.17. Code Injection and Input Validation 3017 A code injection attack occurs when an input or otherwise external 3018 variable is used by an application unsanitized and causes 3019 modification to the application logic. This may allow an attacker to 3020 gain access to the application device or its data, cause denial of 3021 service, or introduce a wide range of malicious side-effects. 3023 The authorization server and client MUST sanitize (and validate when 3024 possible) any value received - in particular, the value of the 3025 "state" and "redirect_uri" parameters. 3027 9.18. Open Redirectors 3029 The following attacks can occur when an AS or client has an open 3030 redirector. An open redirector is an endpoint that forwards a user's 3031 browser to an arbitrary URI obtained from a query parameter. 3033 9.18.1. Client as Open Redirector 3035 Clients MUST NOT expose open redirectors. Attackers may use open 3036 redirectors to produce URLs pointing to the client and utilize them 3037 to exfiltrate authorization codes and access tokens, as described in 3038 (#redir_uri_open_redir). Another abuse case is to produce URLs that 3039 appear to point to the client. This might trick users into trusting 3040 the URL and follow it in their browser. This can be abused for 3041 phishing. 3043 In order to prevent open redirection, clients should only redirect if 3044 the target URLs are whitelisted or if the origin and integrity of a 3045 request can be authenticated. Countermeasures against open 3046 redirection are described by OWASP [owasp_redir]. 3048 9.18.2. Authorization Server as Open Redirector 3050 Just as with clients, attackers could try to utilize a user's trust 3051 in the authorization server (and its URL in particular) for 3052 performing phishing attacks. OAuth authorization servers regularly 3053 redirect users to other web sites (the clients), but must do so in a 3054 safe way. 3056 Section 4.1.2.1 already prevents open redirects by stating that the 3057 AS MUST NOT automatically redirect the user agent in case of an 3058 invalid combination of "client_id" and "redirect_uri". 3060 However, an attacker could also utilize a correctly registered 3061 redirect URI to perform phishing attacks. The attacker could, for 3062 example, register a client via dynamic client registration [RFC7591] 3063 and intentionally send an erroneous authorization request, e.g., by 3064 using an invalid scope value, thus instructing the AS to redirect the 3065 user agent to its phishing site. 3067 The AS MUST take precautions to prevent this threat. Based on its 3068 risk assessment, the AS needs to decide whether it can trust the 3069 redirect URI and SHOULD only automatically redirect the user agent if 3070 it trusts the redirect URI. If the URI is not trusted, the AS MAY 3071 inform the user and rely on the user to make the correct decision. 3073 9.19. Authorization Server Mix-Up Mitigation in Native Apps 3075 (TODO: merge this with the regular mix-up section when it is brought 3076 in) 3078 To protect against a compromised or malicious authorization server 3079 attacking another authorization server used by the same app, it is 3080 REQUIRED that a unique redirect URI is used for each authorization 3081 server used by the app (for example, by varying the path component), 3082 and that authorization responses are rejected if the redirect URI 3083 they were received on doesn't match the redirect URI in an outgoing 3084 authorization request. 3086 The native app MUST store the redirect URI used in the authorization 3087 request with the authorization session data (i.e., along with "state" 3088 and other related data) and MUST verify that the URI on which the 3089 authorization response was received exactly matches it. 3091 The requirement of Section 9.2, specifically that authorization 3092 servers reject requests with URIs that don't match what was 3093 registered, is also required to prevent such attacks. 3095 9.20. Embedded User Agents in Native Apps 3097 Embedded user-agents are a technically possible method for 3098 authorizing native apps. These embedded user-agents are unsafe for 3099 use by third parties to the authorization server by definition, as 3100 the app that hosts the embedded user-agent can access the user's full 3101 authentication credential, not just the OAuth authorization grant 3102 that was intended for the app. 3104 In typical web-view-based implementations of embedded user-agents, 3105 the host application can record every keystroke entered in the login 3106 form to capture usernames and passwords, automatically submit forms 3107 to bypass user consent, and copy session cookies and use them to 3108 perform authenticated actions as the user. 3110 Even when used by trusted apps belonging to the same party as the 3111 authorization server, embedded user-agents violate the principle of 3112 least privilege by having access to more powerful credentials than 3113 they need, potentially increasing the attack surface. 3115 Encouraging users to enter credentials in an embedded user-agent 3116 without the usual address bar and visible certificate validation 3117 features that browsers have makes it impossible for the user to know 3118 if they are signing in to the legitimate site; even when they are, it 3119 trains them that it's OK to enter credentials without validating the 3120 site first. 3122 Aside from the security concerns, embedded user-agents do not share 3123 the authentication state with other apps or the browser, requiring 3124 the user to log in for every authorization request, which is often 3125 considered an inferior user experience. 3127 9.21. Other Recommendations 3129 Authorization servers SHOULD NOT allow clients to influence their 3130 "client_id" or "sub" value or any other claim if that can cause 3131 confusion with a genuine resource owner (see 3132 (#client_impersonating)). 3134 10. Native Applications 3136 Native applications are clients installed and executed on the device 3137 used by the resource owner (i.e., desktop application, native mobile 3138 application). Native applications require special consideration 3139 related to security, platform capabilities, and overall end-user 3140 experience. 3142 The authorization endpoint requires interaction between the client 3143 and the resource owner's user-agent. The best current practice is to 3144 perform the OAuth authorization request in an external user-agent 3145 (typically the browser) rather than an embedded user-agent (such as 3146 one implemented with web-views). 3148 The native application can capture the response from the 3149 authorization server using a redirect URI with a scheme registered 3150 with the operating system to invoke the client as the handler, manual 3151 copy-and-paste of the credentials, running a local web server, 3152 installing a user-agent extension, or by providing a redirect URI 3153 identifying a server-hosted resource under the client's control, 3154 which in turn makes the response available to the native application. 3156 Previously, it was common for native apps to use embedded user-agents 3157 (commonly implemented with web-views) for OAuth authorization 3158 requests. That approach has many drawbacks, including the host app 3159 being able to copy user credentials and cookies as well as the user 3160 needing to authenticate from scratch in each app. See Section 9.20 3161 for a deeper analysis of the drawbacks of using embedded user-agents 3162 for OAuth. 3164 Native app authorization requests that use the browser are more 3165 secure and can take advantage of the user's authentication state. 3166 Being able to use the existing authentication session in the browser 3167 enables single sign-on, as users don't need to authenticate to the 3168 authorization server each time they use a new app (unless required by 3169 the authorization server policy). 3171 Supporting authorization flows between a native app and the browser 3172 is possible without changing the OAuth protocol itself, as the OAuth 3173 authorization request and response are already defined in terms of 3174 URIs. This encompasses URIs that can be used for inter-app 3175 communication. Some OAuth server implementations that assume all 3176 clients are confidential web clients will need to add an 3177 understanding of public native app clients and the types of redirect 3178 URIs they use to support this best practice. 3180 10.1. Using Inter-App URI Communication for OAuth in Native Apps 3182 Just as URIs are used for OAuth on the web to initiate the 3183 authorization request and return the authorization response to the 3184 requesting website, URIs can be used by native apps to initiate the 3185 authorization request in the device's browser and return the response 3186 to the requesting native app. 3188 By adopting the same methods used on the web for OAuth, benefits seen 3189 in the web context like the usability of a single sign-on session and 3190 the security of a separate authentication context are likewise gained 3191 in the native app context. Reusing the same approach also reduces 3192 the implementation complexity and increases interoperability by 3193 relying on standards-based web flows that are not specific to a 3194 particular platform. 3196 Native apps MUST use an external user-agent to perform OAuth 3197 authorization requests. This is achieved by opening the 3198 authorization request in the browser (detailed in Section 10.2) and 3199 using a redirect URI that will return the authorization response back 3200 to the native app (defined in Section 10.3). 3202 10.2. Initiating the Authorization Request from a Native App 3204 Native apps needing user authorization create an authorization 3205 request URI with the authorization code grant type per Section 4.1 3206 using a redirect URI capable of being received by the native app. 3208 The function of the redirect URI for a native app authorization 3209 request is similar to that of a web-based authorization request. 3210 Rather than returning the authorization response to the OAuth 3211 client's server, the redirect URI used by a native app returns the 3212 response to the app. Several options for a redirect URI that will 3213 return the authorization response to the native app in different 3214 platforms are documented in Section 10.3. Any redirect URI that 3215 allows the app to receive the URI and inspect its parameters is 3216 viable. 3218 After constructing the authorization request URI, the app uses 3219 platform-specific APIs to open the URI in an external user-agent. 3220 Typically, the external user-agent used is the default browser, that 3221 is, the application configured for handling "http" and "https" scheme 3222 URIs on the system; however, different browser selection criteria and 3223 other categories of external user-agents MAY be used. 3225 This best practice focuses on the browser as the RECOMMENDED external 3226 user-agent for native apps. An external user-agent designed 3227 specifically for user authorization and capable of processing 3228 authorization requests and responses like a browser MAY also be used. 3229 Other external user-agents, such as a native app provided by the 3230 authorization server may meet the criteria set out in this best 3231 practice, including using the same redirect URI properties, but their 3232 use is out of scope for this specification. 3234 Some platforms support a browser feature known as "in-app browser 3235 tabs", where an app can present a tab of the browser within the app 3236 context without switching apps, but still retain key benefits of the 3237 browser such as a shared authentication state and security context. 3238 On platforms where they are supported, it is RECOMMENDED, for 3239 usability reasons, that apps use in-app browser tabs for the 3240 authorization request. 3242 10.3. Receiving the Authorization Response in a Native App 3244 There are several redirect URI options available to native apps for 3245 receiving the authorization response from the browser, the 3246 availability and user experience of which varies by platform. 3248 To fully support native apps, authorization servers MUST offer at 3249 least the three redirect URI options described in the following 3250 subsections to native apps. Native apps MAY use whichever redirect 3251 option suits their needs best, taking into account platform-specific 3252 implementation details. 3254 10.3.1. Private-Use URI Scheme Redirection 3256 Many mobile and desktop computing platforms support inter-app 3257 communication via URIs by allowing apps to register private-use URI 3258 schemes (sometimes colloquially referred to as "custom URL schemes") 3259 like "com.example.app". When the browser or another app attempts to 3260 load a URI with a private-use URI scheme, the app that registered it 3261 is launched to handle the request. 3263 To perform an authorization request with a private-use URI scheme 3264 redirect, the native app launches the browser with a standard 3265 authorization request, but one where the redirect URI utilizes a 3266 private-use URI scheme it registered with the operating system. 3268 When choosing a URI scheme to associate with the app, apps MUST use a 3269 URI scheme based on a domain name under their control, expressed in 3270 reverse order, as recommended by Section 3.8 of [RFC7595] for 3271 private-use URI schemes. 3273 For example, an app that controls the domain name "app.example.com" 3274 can use "com.example.app" as their scheme. Some authorization 3275 servers assign client identifiers based on domain names, for example, 3276 "client1234.usercontent.example.net", which can also be used as the 3277 domain name for the scheme when reversed in the same manner. A 3278 scheme such as "myapp", however, would not meet this requirement, as 3279 it is not based on a domain name. 3281 When there are multiple apps by the same publisher, care must be 3282 taken so that each scheme is unique within that group. On platforms 3283 that use app identifiers based on reverse-order domain names, those 3284 identifiers can be reused as the private-use URI scheme for the OAuth 3285 redirect to help avoid this problem. 3287 Following the requirements of Section 3.2 of [RFC3986], as there is 3288 no naming authority for private-use URI scheme redirects, only a 3289 single slash ("/") appears after the scheme component. A complete 3290 example of a redirect URI utilizing a private-use URI scheme is: 3292 com.example.app:/oauth2redirect/example-provider 3294 When the authorization server completes the request, it redirects to 3295 the client's redirect URI as it would normally. As the redirect URI 3296 uses a private-use URI scheme, it results in the operating system 3297 launching the native app, passing in the URI as a launch parameter. 3298 Then, the native app uses normal processing for the authorization 3299 response. 3301 10.3.2. Claimed "https" Scheme URI Redirection 3303 Some operating systems allow apps to claim "https" scheme [RFC7230] 3304 URIs in the domains they control. When the browser encounters a 3305 claimed URI, instead of the page being loaded in the browser, the 3306 native app is launched with the URI supplied as a launch parameter. 3308 Such URIs can be used as redirect URIs by native apps. They are 3309 indistinguishable to the authorization server from a regular web- 3310 based client redirect URI. An example is: 3312 https://app.example.com/oauth2redirect/example-provider 3314 As the redirect URI alone is not enough to distinguish public native 3315 app clients from confidential web clients, it is REQUIRED in 3316 Section 9.2 that the client type be recorded during client 3317 registration to enable the server to determine the client type and 3318 act accordingly. 3320 App-claimed "https" scheme redirect URIs have some advantages 3321 compared to other native app redirect options in that the identity of 3322 the destination app is guaranteed to the authorization server by the 3323 operating system. For this reason, native apps SHOULD use them over 3324 the other options where possible. 3326 10.3.3. Loopback Interface Redirection 3328 Native apps that are able to open a port on the loopback network 3329 interface without needing special permissions (typically, those on 3330 desktop operating systems) can use the loopback interface to receive 3331 the OAuth redirect. 3333 Loopback redirect URIs use the "http" scheme and are constructed with 3334 the loopback IP literal and whatever port the client is listening on. 3336 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3337 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3338 IPv4 loopback interface with a randomly assigned port: 3340 http://127.0.0.1:51004/oauth2redirect/example-provider 3342 An example redirect using the IPv6 loopback interface with a randomly 3343 assigned port: 3345 http://[::1]:61023/oauth2redirect/example-provider 3347 The authorization server MUST allow any port to be specified at the 3348 time of the request for loopback IP redirect URIs, to accommodate 3349 clients that obtain an available ephemeral port from the operating 3350 system at the time of the request. 3352 Clients SHOULD NOT assume that the device supports a particular 3353 version of the Internet Protocol. It is RECOMMENDED that clients 3354 attempt to bind to the loopback interface using both IPv4 and IPv6 3355 and use whichever is available. 3357 11. Browser-Based Apps 3359 Browser-based apps are are clients that run in a web browser, 3360 typically written in JavaScript, also known as "single-page apps". 3361 These types of apps have particular security considerations similar 3362 to native apps. 3364 TODO: Bring in the normative text of the browser-based apps BCP when 3365 it is finalized. 3367 12. Differences from OAuth 2.0 3369 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3370 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3371 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3372 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3373 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3374 ([RFC6750]). 3376 Where a later draft updates or obsoletes functionality found in the 3377 original [RFC6749], that functionality in this draft is updated with 3378 the normative changes described in a later draft, or removed 3379 entirely. 3381 A non-normative list of changes from OAuth 2.0 is listed below: 3383 * The authorization code grant is extended with the functionality 3384 from PKCE ([RFC7636]) such that the default method of using the 3385 authorization code grant according to this specification requires 3386 the addition of the PKCE parameters 3388 * Redirect URIs must be compared using exact string matching as per 3389 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3391 * The Implicit grant ("response_type=token") is omitted from this 3392 specification as per Section 2.1.2 of 3393 [I-D.ietf-oauth-security-topics] 3395 * The Resource Owner Password Credentials grant is omitted from this 3396 specification as per Section 2.4 of 3397 [I-D.ietf-oauth-security-topics] 3399 * Bearer token usage omits the use of bearer tokens in the query 3400 string of URIs as per Section 4.3.2 of 3401 [I-D.ietf-oauth-security-topics] 3403 * Refresh tokens should either be sender-constrained or one-time use 3404 as per Section 4.12.2 of [I-D.ietf-oauth-security-topics] 3406 13. IANA Considerations 3408 This document does not require any IANA actions. 3410 All referenced registries are defined by RFC6749 and related 3411 documents that this work is based upon. No changes to those 3412 registries are required by this specification. 3414 14. References 3416 14.1. Normative References 3418 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 3419 "Recommendations for Secure Use of Transport Layer 3420 Security (TLS)", n.d.. 3422 [I-D.ietf-oauth-security-topics] 3423 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3424 "OAuth 2.0 Security Best Current Practice", Work in 3425 Progress, Internet-Draft, draft-ietf-oauth-security- 3426 topics-16, 5 October 2020, . 3429 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3430 Requirement Levels", BCP 14, RFC 2119, 3431 DOI 10.17487/RFC2119, March 1997, 3432 . 3434 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3435 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3436 Authentication: Basic and Digest Access Authentication", 3437 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3438 . 3440 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3441 DOI 10.17487/RFC2818, May 2000, 3442 . 3444 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3445 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3446 2003, . 3448 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3449 Resource Identifier (URI): Generic Syntax", STD 66, 3450 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3451 . 3453 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3454 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3455 . 3457 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3458 Specifications: ABNF", STD 68, RFC 5234, 3459 DOI 10.17487/RFC5234, January 2008, 3460 . 3462 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3463 Housley, R., and W. Polk, "Internet X.509 Public Key 3464 Infrastructure Certificate and Certificate Revocation List 3465 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3466 . 3468 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3469 Verification of Domain-Based Application Service Identity 3470 within Internet Public Key Infrastructure Using X.509 3471 (PKIX) Certificates in the Context of Transport Layer 3472 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3473 2011, . 3475 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3476 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3477 . 3479 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3480 Framework: Bearer Token Usage", RFC 6750, 3481 DOI 10.17487/RFC6750, October 2012, 3482 . 3484 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3485 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3486 2014, . 3488 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3489 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3490 DOI 10.17487/RFC7231, June 2014, 3491 . 3493 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3494 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3495 RFC 7234, DOI 10.17487/RFC7234, June 2014, 3496 . 3498 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3499 and Registration Procedures for URI Schemes", BCP 35, 3500 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3501 . 3503 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3504 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3505 May 2017, . 3507 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3508 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3509 . 3511 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3512 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3513 . 3515 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3516 Standard Code for Information Interchange, ANSI X3.4", 3517 1986. 3519 [W3C.REC-html401-19991224] 3520 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3521 Specification", World Wide Web Consortium Recommendation 3522 REC-html401-19991224, 24 December 1999, 3523 . 3525 [W3C.REC-xml-20081126] 3526 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3527 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3528 Edition)", World Wide Web Consortium Recommendation REC- 3529 xml-20081126, 26 November 2008, 3530 . 3532 14.2. Informative References 3534 [CSP-2] "Content Security Policy Level 2", December 2016, 3535 . 3537 [I-D.bradley-oauth-jwt-encoded-state] 3538 Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding 3539 claims in the OAuth 2 state parameter using a JWT", Work 3540 in Progress, Internet-Draft, draft-bradley-oauth-jwt- 3541 encoded-state-09, 4 November 2018, . 3545 [I-D.ietf-oauth-access-token-jwt] 3546 Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 3547 Access Tokens", Work in Progress, Internet-Draft, draft- 3548 ietf-oauth-access-token-jwt-11, 22 January 2021, 3549 . 3552 [I-D.ietf-oauth-browser-based-apps] 3553 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3554 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3555 browser-based-apps-07, 2 October 2020, 3556 . 3559 [I-D.ietf-oauth-dpop] 3560 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 3561 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 3562 of-Possession at the Application Layer (DPoP)", Work in 3563 Progress, Internet-Draft, draft-ietf-oauth-dpop-02, 18 3564 November 2020, . 3567 [I-D.ietf-oauth-par] 3568 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 3569 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 3570 Work in Progress, Internet-Draft, draft-ietf-oauth-par-05, 3571 14 December 2020, . 3574 [I-D.ietf-oauth-rar] 3575 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3576 Rich Authorization Requests", Work in Progress, Internet- 3577 Draft, draft-ietf-oauth-rar-03, 18 October 2020, 3578 . 3581 [I-D.ietf-oauth-token-binding] 3582 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 3583 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3584 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3585 . 3588 [NIST800-63] 3589 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3590 Gupta, S., and E. Nabbus, "NIST Special Publication 3591 800-63-1, INFORMATION SECURITY", December 2011, 3592 . 3594 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3595 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3596 and B. Boyer, "Online Multimedia Authorization Protocol: 3597 An Industry Standard for Authorized Access to Internet 3598 Multimedia Resources", April 2012, 3599 . 3601 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3602 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3603 . 3605 [OpenID.Messages] 3606 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3607 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3608 June 2012, . 3611 [owasp_redir] 3612 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3613 Forwards", 2020, 3614 . 3617 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3618 DOI 10.17487/RFC6265, April 2011, 3619 . 3621 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3622 Threat Model and Security Considerations", RFC 6819, 3623 DOI 10.17487/RFC6819, January 2013, 3624 . 3626 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 3627 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 3628 August 2013, . 3630 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3631 Protocol (HTTP/1.1): Message Syntax and Routing", 3632 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3633 . 3635 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3636 Protocol (HTTP/1.1): Authentication", RFC 7235, 3637 DOI 10.17487/RFC7235, June 2014, 3638 . 3640 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3641 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3642 . 3644 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3645 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3646 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3647 . 3649 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 3650 "OAuth 2.0 Dynamic Client Registration Management 3651 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 3652 . 3654 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3655 for Code Exchange by OAuth Public Clients", RFC 7636, 3656 DOI 10.17487/RFC7636, September 2015, 3657 . 3659 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 3660 RFC 7662, DOI 10.17487/RFC7662, October 2015, 3661 . 3663 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3664 Authorization Server Metadata", RFC 8414, 3665 DOI 10.17487/RFC8414, June 2018, 3666 . 3668 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 3669 "OAuth 2.0 Device Authorization Grant", RFC 8628, 3670 DOI 10.17487/RFC8628, August 2019, 3671 . 3673 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3674 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3675 and Certificate-Bound Access Tokens", RFC 8705, 3676 DOI 10.17487/RFC8705, February 2020, 3677 . 3679 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3680 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3681 February 2020, . 3683 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3685 This section provides Augmented Backus-Naur Form (ABNF) syntax 3686 descriptions for the elements defined in this specification using the 3687 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3688 code points [W3C.REC-xml-20081126]; these characters are typically 3689 encoded in UTF-8. Elements are presented in the order first defined. 3691 Some of the definitions that follow use the "URI-reference" 3692 definition from [RFC3986]. 3694 Some of the definitions that follow use these common definitions: 3696 VSCHAR = %x20-7E 3697 NQCHAR = %x21 / %x23-5B / %x5D-7E 3698 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3699 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3700 %xE000-FFFD / %x10000-10FFFF 3702 (The UNICODECHARNOCRLF definition is based upon the Char definition 3703 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3704 Return and Linefeed characters.) 3706 A.1. "client_id" Syntax 3708 The "client_id" element is defined in Section 2.3.1: 3710 client-id = *VSCHAR 3712 A.2. "client_secret" Syntax 3714 The "client_secret" element is defined in Section 2.3.1: 3716 client-secret = *VSCHAR 3718 A.3. "response_type" Syntax 3720 The "response_type" element is defined in Section 3.1.1 and 3721 Section 8.4: 3723 response-type = response-name *( SP response-name ) 3724 response-name = 1*response-char 3725 response-char = "_" / DIGIT / ALPHA 3727 A.4. "scope" Syntax 3729 The "scope" element is defined in Section 3.3: 3731 scope = scope-token *( SP scope-token ) 3732 scope-token = 1*NQCHAR 3734 A.5. "state" Syntax 3736 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3737 Section 4.1.2.1: 3739 state = 1*VSCHAR 3741 A.6. "redirect_uri" Syntax 3743 The "redirect_uri" element is defined in Section 4.1.1, and 3744 Section 4.1.3: 3746 redirect-uri = URI-reference 3748 A.7. "error" Syntax 3750 The "error" element is defined in Sections Section 4.1.2.1, 3751 Section 5.2, 7.2, and 8.5: 3753 error = 1*NQSCHAR 3755 A.8. "error_description" Syntax 3757 The "error_description" element is defined in Sections 3758 Section 4.1.2.1, Section 5.2, and Section 7.3: 3760 error-description = 1*NQSCHAR 3762 A.9. "error_uri" Syntax 3764 The "error_uri" element is defined in Sections Section 4.1.2.1, 3765 Section 5.2, and 7.2: 3767 error-uri = URI-reference 3769 A.10. "grant_type" Syntax 3771 The "grant_type" element is defined in Sections Section 4.1.3, 3772 Section 4.2.3, Section 4.2.2, Section 4.3, and Section 6: 3774 grant-type = grant-name / URI-reference 3775 grant-name = 1*name-char 3776 name-char = "-" / "." / "_" / DIGIT / ALPHA 3778 A.11. "code" Syntax 3780 The "code" element is defined in Section 4.1.3: 3782 code = 1*VSCHAR 3784 A.12. "access_token" Syntax 3786 The "access_token" element is defined in Section 4.2.3 and 3787 Section 5.1: 3789 access-token = 1*VSCHAR 3791 A.13. "token_type" Syntax 3793 The "token_type" element is defined in Section 5.1, and Section 8.1: 3795 token-type = type-name / URI-reference 3796 type-name = 1*name-char 3797 name-char = "-" / "." / "_" / DIGIT / ALPHA 3799 A.14. "expires_in" Syntax 3801 The "expires_in" element is defined in Section 5.1: 3803 expires-in = 1*DIGIT 3805 A.15. "refresh_token" Syntax 3807 The "refresh_token" element is defined in Section 5.1 and Section 6: 3809 refresh-token = 1*VSCHAR 3811 A.16. Endpoint Parameter Syntax 3813 The syntax for new endpoint parameters is defined in Section 8.2: 3815 param-name = 1*name-char 3816 name-char = "-" / "." / "_" / DIGIT / ALPHA 3818 A.17. "code_verifier" Syntax 3820 ABNF for "code_verifier" is as follows. 3822 code-verifier = 43*128unreserved 3823 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3824 ALPHA = %x41-5A / %x61-7A 3825 DIGIT = %x30-39 3827 A.18. "code_challenge" Syntax 3829 ABNF for "code_challenge" is as follows. 3831 code-challenge = 43*128unreserved 3832 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3833 ALPHA = %x41-5A / %x61-7A 3834 DIGIT = %x30-39 3836 Appendix B. Use of application/x-www-form-urlencoded Media Type 3838 At the time of publication of this specification, the "application/x- 3839 www-form-urlencoded" media type was defined in Section 17.13.4 of 3840 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 3841 Types registry (http://www.iana.org/assignments/media-types 3842 (http://www.iana.org/assignments/media-types)). Furthermore, that 3843 definition is incomplete, as it does not consider non-US-ASCII 3844 characters. 3846 To address this shortcoming when generating payloads using this media 3847 type, names and values MUST be encoded using the UTF-8 character 3848 encoding scheme [RFC3629] first; the resulting octet sequence then 3849 needs to be further encoded using the escaping rules defined in 3850 [W3C.REC-html401-19991224]. 3852 When parsing data from a payload using this media type, the names and 3853 values resulting from reversing the name/value encoding consequently 3854 need to be treated as octet sequences, to be decoded using the UTF-8 3855 character encoding scheme. 3857 For example, the value consisting of the six Unicode code points (1) 3858 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3859 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3860 SIGN) would be encoded into the octet sequence below (using 3861 hexadecimal notation): 3863 20 25 26 2B C2 A3 E2 82 AC 3865 and then represented in the payload as: 3867 +%25%26%2B%C2%A3%E2%82%AC 3869 Appendix C. Extensions 3871 Below is a list of well-established extensions at the time of 3872 publication: 3874 * [RFC8628]: OAuth 2.0 Device Authorization Grant 3876 - The Device Authorization Grant (formerly known as the Device 3877 Flow) is an extension that enables devices with no browser or 3878 limited input capability to obtain an access token. This is 3879 commonly used by smart TV apps, or devices like hardware video 3880 encoders that can stream video to a streaming video service. 3882 * [RFC8414]: Authorization Server Metadata 3884 - Authorization Server Metadata (also known as OAuth Discovery) 3885 defines an endpoint clients can use to look up the information 3886 needed to interact with a particular OAuth server, such as the 3887 location of the authorization and token endpoints and the 3888 supported grant types. 3890 * [RFC8707]: Resource Indicators 3892 - Provides a way for the client to explicitly signal to the 3893 authorization server where it intends to use the access token 3894 it is requesting. 3896 * [RFC7591]: Dynamic Client Registration 3897 - Dynamic Client Registration provides a mechanism for 3898 programmatically registering clients with an authorization 3899 server. 3901 * [RFC7592]: Dynamic Client Management 3903 - Dynamic Client Management provides a mechanism for updating 3904 dynamically registered client information. 3906 * [I-D.ietf-oauth-access-token-jwt]: JSON Web Token (JWT) Profile 3907 for OAuth 2.0 Access Tokens 3909 - This specification defines a profile for issuing OAuth access 3910 tokens in JSON Web Token (JWT) format. 3912 * [RFC8705]: Mutual TLS 3914 - Mutual TLS describes a mechanism of binding access tokens and 3915 refresh tokens to the clients they were issued to, as well as a 3916 client authentication mechanism, via TLS certificate 3917 authentication. 3919 * [RFC7662]: Token Introspection 3921 - The Token Introspection extension defines a mechanism for 3922 resource servers to obtain information about access tokens. 3924 * [RFC7009]: Token Revocation 3926 - The Token Revocation extension defines a mechanism for clients 3927 to indicate to the authorization server that an access token is 3928 no longer needed. 3930 * [I-D.ietf-oauth-par]: Pushed Authorization Requests 3932 - The Pushed Authorization Requsts extension describes a 3933 technique of initiating an OAuth flow from the back channel, 3934 providing better security and more flexibility for building 3935 complex authorization requests. 3937 * [I-D.ietf-oauth-rar]: Rich Authorization Requests 3939 - Rich Authorization Requests specifies a new parameter 3940 "authorization_details" that is used to carry fine-grained 3941 authorization data in the OAuth authorization request. 3943 Appendix D. Acknowledgements 3945 TBD 3947 Authors' Addresses 3949 Dick Hardt 3950 SignIn.Org 3952 Email: dick.hardt@gmail.com 3954 Aaron Parecki 3955 Okta 3957 Email: aaron@parecki.com 3958 URI: https://aaronparecki.com 3960 Torsten Lodderstedt 3961 yes.com 3963 Email: torsten@lodderstedt.net