idnits 2.17.00 (12 Aug 2021) /tmp/idnits7638/draft-ietf-oauth-v2-1-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 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 (8 September 2021) is 255 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 1395, but not defined == Missing Reference: '0-9' is mentioned on line 1395, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-19) exists of draft-ietf-oauth-security-topics-18 ** 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-08 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-dpop-03 == Outdated reference: draft-ietf-oauth-par has been published as RFC 9126 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-rar-05 Summary: 4 errors (**), 0 flaws (~~), 10 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: 12 March 2022 Okta 6 T. Lodderstedt 7 yes.com 8 8 September 2021 10 The OAuth 2.1 Authorization Framework 11 draft-ietf-oauth-v2-1-03 13 Abstract 15 The OAuth 2.1 authorization framework enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and 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 12 March 2022. 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. Refresh Token . . . . . . . . . . . . . . . . . . . . 9 62 1.3.3. Client Credentials . . . . . . . . . . . . . . . . . 10 63 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 11 64 1.5. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 65 1.6. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 66 1.7. Interoperability . . . . . . . . . . . . . . . . . . . . 12 67 1.8. Compatibility with OAuth 2.0 . . . . . . . . . . . . . . 13 68 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 13 69 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 14 70 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14 71 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 16 72 2.3. Client Redirection Endpoint . . . . . . . . . . . . . . . 16 73 2.3.1. Endpoint Request Confidentiality . . . . . . . . . . 16 74 2.3.2. Registration Requirements . . . . . . . . . . . . . . 17 75 2.3.3. Multiple Redirect URIs . . . . . . . . . . . . . . . 17 76 2.3.4. Invalid Endpoint . . . . . . . . . . . . . . . . . . 17 77 2.3.5. Endpoint Content . . . . . . . . . . . . . . . . . . 17 78 2.4. Client Authentication . . . . . . . . . . . . . . . . . . 18 79 2.4.1. Client Secret . . . . . . . . . . . . . . . . . . . . 19 80 2.4.2. Other Authentication Methods . . . . . . . . . . . . 20 81 2.5. Unregistered Clients . . . . . . . . . . . . . . . . . . 20 82 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 20 83 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 21 84 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 21 85 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 22 86 3.2.2. Token Request . . . . . . . . . . . . . . . . . . . . 22 87 3.2.3. Token Response . . . . . . . . . . . . . . . . . . . 24 88 4. Grant Types . . . . . . . . . . . . . . . . . . . . . . . . . 27 89 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 28 90 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 29 91 4.1.2. Authorization Response . . . . . . . . . . . . . . . 32 92 4.1.3. Token Endpoint Extension . . . . . . . . . . . . . . 35 93 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 36 94 4.2.1. Token Endpoint Extension . . . . . . . . . . . . . . 37 95 4.3. Refresh Token Grant . . . . . . . . . . . . . . . . . . . 38 96 4.3.1. Token Endpoint Extension . . . . . . . . . . . . . . 38 97 4.3.2. Refresh Token Response . . . . . . . . . . . . . . . 39 98 4.4. Extension Grants . . . . . . . . . . . . . . . . . . . . 40 99 5. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 100 5.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 101 5.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42 102 5.2.1. Authenticated Requests . . . . . . . . . . . . . . . 42 103 5.2.2. The WWW-Authenticate Response Header Field . . . . . 44 104 5.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 45 105 5.3. Error Response . . . . . . . . . . . . . . . . . . . . . 46 106 5.3.1. Extension Token Types . . . . . . . . . . . . . . . . 46 107 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46 108 6.1. Defining Access Token Types . . . . . . . . . . . . . . . 47 109 6.2. Defining New Endpoint Parameters . . . . . . . . . . . . 47 110 6.3. Defining New Authorization Grant Types . . . . . . . . . 47 111 6.4. Defining New Authorization Endpoint Response Types . . . 48 112 6.5. Defining Additional Error Codes . . . . . . . . . . . . . 48 113 7. Security Considerations . . . . . . . . . . . . . . . . . . . 49 114 7.1. Access Token Security Considerations . . . . . . . . . . 49 115 7.1.1. Security Threats . . . . . . . . . . . . . . . . . . 49 116 7.1.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 50 117 7.1.3. Summary of Recommendations . . . . . . . . . . . . . 52 118 7.1.4. Token Replay Prevention . . . . . . . . . . . . . . . 53 119 7.1.5. Access Token Privilege Restriction . . . . . . . . . 54 120 7.2. Client Authentication . . . . . . . . . . . . . . . . . . 54 121 7.2.1. Client Authentication of Native Apps . . . . . . . . 55 122 7.3. Registration of Native App Clients . . . . . . . . . . . 55 123 7.4. Client Impersonation . . . . . . . . . . . . . . . . . . 56 124 7.4.1. Impersonation of Native Apps . . . . . . . . . . . . 56 125 7.4.2. Access Token Privilege Restriction . . . . . . . . . 57 126 7.4.3. Access Token Replay Prevention . . . . . . . . . . . 57 127 7.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 58 128 7.6. Client Impersonating Resource Owner . . . . . . . . . . . 58 129 7.7. Protecting the Authorization Code Flow . . . . . . . . . 59 130 7.7.1. Loopback Redirect Considerations in Native Apps . . . 59 131 7.7.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 60 132 7.8. Authorization Codes . . . . . . . . . . . . . . . . . . . 61 133 7.9. Request Confidentiality . . . . . . . . . . . . . . . . . 62 134 7.10. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 62 135 7.11. Credentials-Guessing Attacks . . . . . . . . . . . . . . 62 136 7.12. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 63 137 7.13. Fake External User-Agents in Native Apps . . . . . . . . 63 138 7.14. Malicious External User-Agents in Native Apps . . . . . . 64 139 7.15. Cross-Site Request Forgery . . . . . . . . . . . . . . . 64 140 7.16. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 65 141 7.17. Code Injection and Input Validation . . . . . . . . . . . 66 142 7.18. Open Redirectors . . . . . . . . . . . . . . . . . . . . 66 143 7.18.1. Client as Open Redirector . . . . . . . . . . . . . 66 144 7.18.2. Authorization Server as Open Redirector . . . . . . 66 146 7.19. Authorization Server Mix-Up Mitigation in Native Apps . . 67 147 7.20. Embedded User Agents in Native Apps . . . . . . . . . . . 67 148 7.21. Other Recommendations . . . . . . . . . . . . . . . . . . 68 149 8. Native Applications . . . . . . . . . . . . . . . . . . . . . 68 150 8.1. Using Inter-App URI Communication for OAuth in Native 151 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 69 152 8.2. Initiating the Authorization Request from a Native App . 70 153 8.3. Receiving the Authorization Response in a Native App . . 70 154 8.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 71 155 8.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 72 156 8.3.3. Loopback Interface Redirection . . . . . . . . . . . 72 157 9. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 73 158 10. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 73 159 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 160 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 161 12.1. Normative References . . . . . . . . . . . . . . . . . . 74 162 12.2. Informative References . . . . . . . . . . . . . . . . . 77 163 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 80 164 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 80 165 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 80 166 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 80 167 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 81 168 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 81 169 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 81 170 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 81 171 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 81 172 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 81 173 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 81 174 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 82 175 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 82 176 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 82 177 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 82 178 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 82 179 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 82 180 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 83 181 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 83 182 Appendix B. Use of application/x-www-form-urlencoded Media 183 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 83 184 Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 84 185 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 85 186 Appendix E. Document History . . . . . . . . . . . . . . . . . . 85 187 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 189 1. Introduction 191 In the traditional client-server authentication model, the client 192 requests an access-restricted resource (protected resource) on the 193 server by authenticating with the server using the resource owner's 194 credentials. In order to provide third-party applications access to 195 restricted resources, the resource owner shares its credentials with 196 the third party. This creates several problems and limitations: 198 * Third-party applications are required to store the resource 199 owner's credentials for future use, typically a password in clear- 200 text. 202 * Servers are required to support password authentication, despite 203 the security weaknesses inherent in passwords. 205 * Third-party applications gain overly broad access to the resource 206 owner's protected resources, leaving resource owners without any 207 ability to restrict duration or access to a limited subset of 208 resources. 210 * Resource owners often reuse passwords with other unrelated 211 services, despite best security practices. This password reuse 212 means a vulnerability or exposure in one service may have security 213 implications in completely unrelated services. 215 * Resource owners cannot revoke access to an individual third party 216 without revoking access to all third parties, and must do so by 217 changing their password. 219 * Compromise of any third-party application results in compromise of 220 the end-user's password and all of the data protected by that 221 password. 223 OAuth addresses these issues by introducing an authorization layer 224 and separating the role of the client from that of the resource 225 owner. In OAuth, the client requests access to resources controlled 226 by the resource owner and hosted by the resource server. Instead of 227 using the resource owner's credentials to access protected resources, 228 the client obtains an access token - a credential representing a 229 specific set of access attributes such as scope and lifetime. Access 230 tokens are issued to clients by an authorization server with the 231 approval of the resource owner. The client uses the access token to 232 access the protected resources hosted by the resource server. 234 For example, an end-user (resource owner) can grant a printing 235 service (client) access to their protected photos stored at a photo- 236 sharing service (resource server), without sharing their username and 237 password with the printing service. Instead, they authenticate 238 directly with a server trusted by the photo-sharing service 239 (authorization server), which issues the printing service delegation- 240 specific credentials (access token). 242 This specification is designed for use with HTTP ([RFC7231]). The 243 use of OAuth over any protocol other than HTTP is out of scope. 245 Since the publication of the OAuth 2.0 Authorization Framework 246 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 247 Native Apps ([RFC8252]), OAuth Security Best Current Practice 248 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 249 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 250 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 251 updated with ([I-D.ietf-oauth-security-topics]). This Standards 252 Track specification consolidates the information in all of these 253 documents and removes features that have been found to be insecure in 254 [I-D.ietf-oauth-security-topics]. 256 1.1. Roles 258 OAuth defines four roles: 260 "resource owner": An entity capable of granting access to a 261 protected resource. When the resource owner is a person, it is 262 referred to as an end-user. This is sometimes abbreviated as 263 "RO". 265 "resource server": The server hosting the protected resources, 266 capable of accepting and responding to protected resource requests 267 using access tokens. The resource server is often accessible via 268 an API. This is sometimes abbreviated as "RS". 270 "client": An application making protected resource requests on 271 behalf of the resource owner and with its authorization. The term 272 "client" does not imply any particular implementation 273 characteristics (e.g., whether the application executes on a 274 server, a desktop, or other devices). 276 "authorization server": The server issuing access tokens to the 277 client after successfully authenticating the resource owner and 278 obtaining authorization. This is sometimes abbreviated as "AS". 280 The interaction between the authorization server and resource server 281 is beyond the scope of this specification, however several extensions 282 have been defined to provide an option for interoperability between 283 resource servers and authorization servers. The authorization server 284 may be the same server as the resource server or a separate entity. 285 A single authorization server may issue access tokens accepted by 286 multiple resource servers. 288 1.2. Protocol Flow 290 +--------+ +---------------+ 291 | |--(1)- Authorization Request ->| Resource | 292 | | | Owner | 293 | |<-(2)-- Authorization Grant ---| | 294 | | +---------------+ 295 | | 296 | | +---------------+ 297 | |--(3)-- Authorization Grant -->| Authorization | 298 | Client | | Server | 299 | |<-(4)----- Access Token -------| | 300 | | +---------------+ 301 | | 302 | | +---------------+ 303 | |--(5)----- Access Token ------>| Resource | 304 | | | Server | 305 | |<-(6)--- Protected Resource ---| | 306 +--------+ +---------------+ 308 Figure 1: Abstract Protocol Flow 310 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 311 interaction between the four roles and includes the following steps: 313 1. The client requests authorization from the resource owner. The 314 authorization request can be made directly to the resource owner 315 (as shown), or preferably indirectly via the authorization server 316 as an intermediary. 318 2. The client receives an authorization grant, which is a credential 319 representing the resource owner's authorization, expressed using 320 one of the authorization grant types defined in this 321 specification or using an extension grant type. The 322 authorization grant type depends on the method used by the client 323 to request authorization and the types supported by the 324 authorization server. 326 3. The client requests an access token by authenticating with the 327 authorization server and presenting the authorization grant. 329 4. The authorization server authenticates the client and validates 330 the authorization grant, and if valid, issues an access token. 332 5. The client requests the protected resource from the resource 333 server and authenticates by presenting the access token. 335 6. The resource server validates the access token, and if valid, 336 serves the request. 338 The preferred method for the client to obtain an authorization grant 339 from the resource owner (depicted in steps (1) and (2)) is to use the 340 authorization server as an intermediary, which is illustrated in 341 Figure 3 in Section 4.1. 343 1.3. Authorization Grant 345 An authorization grant is a credential representing the resource 346 owner's authorization (to access its protected resources) used by the 347 client to obtain an access token. This specification defines three 348 grant types - authorization code, refresh token, and client 349 credentials - as well as an extensibility mechanism for defining 350 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, which in turn 358 directs the resource owner back to the client with the authorization 359 code. The client can then exchange the authorization code for an 360 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. Refresh Token 379 Refresh tokens are credentials used to obtain access tokens. Refresh 380 tokens are issued to the client by the authorization server and are 381 used to obtain a new access token when the current access token 382 becomes invalid or expires, or to obtain additional access tokens 383 with identical or narrower scope (access tokens may have a shorter 384 lifetime and fewer permissions than authorized by the resource 385 owner). Issuing a refresh token is optional at the discretion of the 386 authorization server, and may be issued based on properties of the 387 client, properties of the request, policies within the authorization 388 server, or any other criteria. If the authorization server issues a 389 refresh token, it is included when issuing an access token (i.e., 390 step (2) in Figure 2). 392 A refresh token is a string representing the authorization granted to 393 the client by the resource owner. The string is considered opaque to 394 the client. The refresh token may be an identifier used to retrieve 395 the authorization information or may encode this information into the 396 string itself. Unlike access tokens, refresh tokens are intended for 397 use only with authorization servers and are never sent to resource 398 servers. 400 +--------+ +---------------+ 401 | |--(1)------- Authorization Grant --------->| | 402 | | | | 403 | |<-(2)----------- Access Token -------------| | 404 | | & Refresh Token | | 405 | | | | 406 | | +----------+ | | 407 | |--(3)---- Access Token ---->| | | | 408 | | | | | | 409 | |<-(4)- Protected Resource --| Resource | | Authorization | 410 | Client | | Server | | Server | 411 | |--(5)---- Access Token ---->| | | | 412 | | | | | | 413 | |<-(6)- Invalid Token Error -| | | | 414 | | +----------+ | | 415 | | | | 416 | |--(7)----------- Refresh Token ----------->| | 417 | | | | 418 | |<-(8)----------- Access Token -------------| | 419 +--------+ & Optional Refresh Token +---------------+ 421 Figure 2: Refreshing an Expired Access Token 423 The flow illustrated in Figure 2 includes the following steps: 425 1. The client requests an access token by authenticating with the 426 authorization server and presenting an authorization grant. 428 2. The authorization server authenticates the client and validates 429 the authorization grant, and if valid, issues an access token and 430 optionally a refresh token. 432 3. The client makes a protected resource request to the resource 433 server by presenting the access token. 435 4. The resource server validates the access token, and if valid, 436 serves the request. 438 5. Steps (3) and (4) repeat until the access token expires. If the 439 client knows the access token expired, it skips to step (7); 440 otherwise, it makes another protected resource request. 442 6. Since the access token is invalid, the resource server returns an 443 invalid token error. 445 7. The client requests a new access token by presenting the refresh 446 token and providing client authentication if it has been issued 447 credentials. The client authentication requirements are based on 448 the client type and on the authorization server policies. 450 8. The authorization server authenticates the client and validates 451 the refresh token, and if valid, issues a new access token (and, 452 optionally, a new refresh token). 454 1.3.3. Client Credentials 456 The client credentials or other forms of client authentication (e.g. 457 a "client_secret" or a private key used to sign a JWT) can be used as 458 an authorization grant when the authorization scope is limited to the 459 protected resources under the control of the client, or to protected 460 resources previously arranged with the authorization server. Client 461 credentials are used as an authorization grant typically when the 462 client is acting on its own behalf (the client is also the resource 463 owner) or is requesting access to protected resources based on an 464 authorization previously arranged with the authorization server. 466 1.4. Access Token 468 Access tokens are credentials used to access protected resources. An 469 access token is a string representing an authorization issued to the 470 client. The string is considered opaque to the client, even if it 471 has a structure. Depending on the authorization server, the access 472 token string may be parseable by the resource server, such as when 473 using the JSON Web Token Profile for Access Tokens 474 ([I-D.ietf-oauth-access-token-jwt]). 476 Access tokens represent specific scopes and durations of access, 477 granted by the resource owner, and enforced by the resource server 478 and authorization server. 480 The token may be used by the RS to retrieve the authorization 481 information, or the token may self-contain the authorization 482 information in a verifiable manner (i.e., a token string consisting 483 of a signed data payload). One example of a token retrieval 484 mechanism is Token Introspection [RFC7662], in which the RS calls an 485 endpoint on the AS to validate the token presented by the client. 486 One example of a structured token format is 487 [I-D.ietf-oauth-access-token-jwt], a method of encoding access token 488 data as a JSON Web Token [RFC7519]. 490 Additional authentication credentials, which are beyond the scope of 491 this specification, may be required in order for the client to use an 492 access token. This is typically referred to as a sender-constrained 493 access token, such as Mutual TLS Access Tokens [RFC8705]. 495 The access token provides an abstraction layer, replacing different 496 authorization constructs (e.g., username and password) with a single 497 token understood by the resource server. This abstraction enables 498 issuing access tokens more restrictive than the authorization grant 499 used to obtain them, as well as removing the resource server's need 500 to understand a wide range of authentication methods. 502 Access tokens can have different formats, structures, and methods of 503 utilization (e.g., cryptographic properties) based on the resource 504 server security requirements. Access token attributes and the 505 methods used to access protected resources may be extended beyond 506 what is described in this specification. 508 Access tokens (as well as any confidential access token attributes) 509 MUST be kept confidential in transit and storage, and only shared 510 among the authorization server, the resource servers the access token 511 is valid for, and the client to whom the access token is issued. 512 Access token credentials MUST only be transmitted using TLS as 513 described in Section 1.5 with server authentication as defined by 514 [RFC2818]. 516 The authorization server MUST ensure that access tokens cannot be 517 generated, modified, or guessed to produce valid access tokens by 518 unauthorized parties. 520 1.5. TLS Version 522 Whenever Transport Layer Security (TLS) is used by this 523 specification, the appropriate version (or versions) of TLS will vary 524 over time, based on the widespread deployment and known security 525 vulnerabilities. Refer to [BCP195] for up to date recommendations on 526 transport layer security. 528 Implementations MAY also support additional transport-layer security 529 mechanisms that meet their security requirements. 531 1.6. HTTP Redirections 533 This specification makes extensive use of HTTP redirections, in which 534 the client or the authorization server directs the resource owner's 535 user agent to another destination. While the examples in this 536 specification show the use of the HTTP 302 status code, any other 537 method available via the user agent to accomplish this redirection, 538 with the exception of HTTP 307, is allowed and is considered to be an 539 implementation detail. See Section 7.7.2 for details. 541 1.7. Interoperability 543 OAuth 2.1 provides a rich authorization framework with well-defined 544 security properties. 546 This specification leaves a few required components partially or 547 fully undefined (e.g., client registration, authorization server 548 capabilities, endpoint discovery). Some of these behaviors are 549 defined in optional extensions which implementations can choose to 550 use, such as: 552 * [RFC8414]: Authorization Server Metadata, defining an endpoint 553 clients can use to look up the information needed to interact with 554 a particular OAuth server 556 * [RFC7591]: Dynamic Client Registration, providing a mechanism for 557 programmatically registering clients with an authorization server 559 * [RFC7592]: Dynamic Client Management, providing a mechanism for 560 updating dynamically registered client information 562 * [RFC7662]: Token Introspection, defining a mechanism for resource 563 servers to obtain information about access tokens 565 Please refer to Appendix C for a list of current known extensions at 566 the time of this publication. 568 1.8. Compatibility with OAuth 2.0 570 OAuth 2.1 is compatible with OAuth 2.0 with the extensions and 571 restrictions from known best current practices applied. 572 Specifically, features not specified in OAuth 2.0 core, such as PKCE, 573 are required in OAuth 2.1. Additionally, some features available in 574 OAuth 2.0, such as the Implicit or Resource Owner Credentials grant 575 types, are not specified in OAuth 2.1. Furthermore, some behaviors 576 allowed in OAuth 2.0 are restricted in OAuth 2.1, such as the strict 577 string matching of redirect URIs required by OAuth 2.1. 579 See Section 10 for more details on the differences from OAuth 2.0. 581 1.9. Notational Conventions 583 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 584 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 585 "OPTIONAL" in this document are to be interpreted as described in 586 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 587 capitals, as shown here. 589 This specification uses the Augmented Backus-Naur Form (ABNF) 590 notation of [RFC5234]. Additionally, the rule URI-reference is 591 included from "Uniform Resource Identifier (URI): Generic Syntax" 592 [RFC3986]. 594 Certain security-related terms are to be understood in the sense 595 defined in [RFC4949]. These terms include, but are not limited to, 596 "attack", "authentication", "authorization", "certificate", 597 "confidentiality", "credential", "encryption", "identity", "sign", 598 "signature", "trust", "validate", and "verify". 600 The term "payload" is to be interpreted as described in Section 3.3 601 of [RFC7231]. 603 The term "user agent" is to be interpreted as described in [RFC7230]. 605 Unless otherwise noted, all the protocol parameter names and values 606 are case sensitive. 608 2. Client Registration 610 Before initiating the protocol, the client must establish its 611 registration with the authorization server. The means through which 612 the client registers with the authorization server are beyond the 613 scope of this specification but typically involve the client 614 developer manually registering the client at the authorization 615 server's website after creating an account and agreeing to the 616 service's Terms of Service, or by using Dynamic Client Registration 617 ([RFC7591]). 619 Client registration does not require a direct interaction between the 620 client and the authorization server. When supported by the 621 authorization server, registration can rely on other means for 622 establishing trust and obtaining the required client properties 623 (e.g., redirect URI, client type). For example, registration can be 624 accomplished using a self-issued or third-party-issued assertion, or 625 by the authorization server performing client discovery using a 626 trusted channel. 628 When registering a client, the client developer SHALL: 630 * specify the client type as described in Section 2.1, 632 * provide client details needed by the grant type in use, such as 633 redirect URIs as described in Section 2.3, and 635 * include any other information required by the authorization server 636 (e.g., application name, website, description, logo image, the 637 acceptance of legal terms). 639 Dynamic Client Registration ([RFC7591]) defines a common general data 640 model for clients that may be used even with manual client 641 registration. 643 2.1. Client Types 645 OAuth 2.1 defines three client types based on their ability to 646 authenticate securely with the authorization server as well as the 647 authorization server's assurance of the client's identity. 649 "confidential": Clients that have credentials and their identity has 650 been confirmed by the AS are designated as "confidential clients" 652 "credentialed": Clients that have credentials and their identity has 653 been not been confirmed by the AS are designated as "credentialed 654 clients" 656 "public": Clients without credentials are called "public clients" 658 Any clients with credentials MUST take precautions to prevent leakage 659 and abuse of their credentials. 661 Authorization servers SHOULD consider the level of confidence in a 662 client's identity when deciding whether they allow such a client 663 access to more critical functions, such as the Client Credentials 664 grant type. 666 A single "client_id" MUST NOT be treated as more than one type of 667 client. 669 This specification has been designed around the following client 670 profiles: 672 "web application": A web application is a confidential client 673 running on a web server. Resource owners access the client via an 674 HTML user interface rendered in a user agent on the device used by 675 the resource owner. The client credentials as well as any access 676 tokens issued to the client are stored on the web server and are 677 not exposed to or accessible by the resource owner. 679 "browser-based application": A browser-based application is a public 680 client in which the client code is downloaded from a web server 681 and executes within a user agent (e.g., web browser) on the device 682 used by the resource owner. Protocol data and credentials are 683 easily accessible (and often visible) to the resource owner. 684 Since such applications reside within the user agent, they can 685 make seamless use of the user agent capabilities when requesting 686 authorization. 688 "native application": A native application is a public client 689 installed and executed on the device used by the resource owner. 690 Protocol data and credentials are accessible to the resource 691 owner. It is assumed that any client authentication credentials 692 included in the application can be extracted. On the other hand, 693 dynamically issued credentials such as access tokens or refresh 694 tokens can receive an acceptable level of protection. At a 695 minimum, these credentials are protected from hostile servers with 696 which the application may interact. On some platforms, these 697 credentials might be protected from other applications residing on 698 the same device. 700 2.2. Client Identifier 702 The authorization server issues the registered client a client 703 identifier - a unique string representing the registration 704 information provided by the client. The client identifier is not a 705 secret; it is exposed to the resource owner and MUST NOT be used 706 alone for client authentication. The client identifier is unique to 707 the authorization server. 709 The client identifier string size is left undefined by this 710 specification. The client should avoid making assumptions about the 711 identifier size. The authorization server SHOULD document the size 712 of any identifier it issues. 714 Authorization servers SHOULD NOT allow clients to choose or influence 715 their "client_id" value. See Section 7.6 for details. 717 2.3. Client Redirection Endpoint 719 The client redirection endpoint (also referred to as "redirect 720 endpoint") is the URI of the client that the authorization server 721 redirects the user agent back to after completing its interaction 722 with the resource owner. 724 The authorization server redirects the user agent to one of the 725 client's redirection endpoints previously established with the 726 authorization server during the client registration process. 728 The redirect URI MUST be an absolute URI as defined by [RFC3986] 729 Section 4.3. The endpoint URI MAY include an "application/x-www- 730 form-urlencoded" formatted (per Appendix B) query component 731 ([RFC3986] Section 3.4), which MUST be retained when adding 732 additional query parameters. The endpoint URI MUST NOT include a 733 fragment component. 735 2.3.1. Endpoint Request Confidentiality 737 The redirection endpoint SHOULD require the use of TLS as described 738 in Section 1.5 when the requested response type is "code", or when 739 the redirection request will result in the transmission of sensitive 740 credentials over an open network. If TLS is not available, the 741 authorization server SHOULD warn the resource owner about the 742 insecure endpoint prior to redirection (e.g., display a message 743 during the authorization request). 745 2.3.2. Registration Requirements 747 Authorization servers MUST require clients to register their complete 748 redirect URI (including the path component) and reject authorization 749 requests that specify a redirect URI that doesn't exactly match one 750 that was registered; the exception is loopback redirects, where an 751 exact match is required except for the port URI component. 753 For private-use URI scheme-based redirect URIs, authorization servers 754 SHOULD enforce the requirement in Section 8.3.1 that clients use 755 schemes that are reverse domain name based. At a minimum, any 756 private-use URI scheme that doesn't contain a period character (".") 757 SHOULD be rejected. 759 The client MAY use the "state" request parameter to achieve per- 760 request customization if needed rather than varying the redirect URI 761 per request. 763 The authorization server MAY allow the client to register multiple 764 redirect URIs. 766 Without requiring registration of redirect URIs, attackers can use 767 the authorization endpoint as an open redirector as described in 768 Section 7.18. 770 2.3.3. Multiple Redirect URIs 772 If multiple redirect URIs have been registered, the client MUST 773 include a redirect URI with the authorization request using the 774 "redirect_uri" request parameter. 776 2.3.4. Invalid Endpoint 778 If an authorization request fails validation due to a missing, 779 invalid, or mismatching redirect URI, the authorization server SHOULD 780 inform the resource owner of the error and MUST NOT automatically 781 redirect the user agent to the invalid redirect URI. 783 2.3.5. Endpoint Content 785 The redirection request to the client's endpoint typically results in 786 an HTML document response, processed by the user agent. If the HTML 787 response is served directly as the result of the redirection request, 788 any script included in the HTML document will execute with full 789 access to the redirect URI and the credentials (e.g. authorization 790 code) it contains. Additionally, the request URL containing the 791 authorization code may be sent in the HTTP Referer header to any 792 embedded images, stylesheets and other elements loaded in the page. 794 The client SHOULD NOT include any third-party scripts (e.g., third- 795 party analytics, social plug-ins, ad networks) in the redirection 796 endpoint response. Instead, it SHOULD extract the credentials from 797 the URI and redirect the user agent again to another endpoint without 798 exposing the credentials (in the URI or elsewhere). If third-party 799 scripts are included, the client MUST ensure that its own scripts 800 (used to extract and remove the credentials from the URI) will 801 execute first. 803 2.4. Client Authentication 805 Confidential and credentialed clients establish a client 806 authentication method with the authorization server suitable for the 807 security requirements of the authorization server. The authorization 808 server MAY accept any form of client authentication meeting its 809 security requirements. 811 Confidential and credentialed clients are typically issued (or 812 establish) a set of client credentials used for authenticating with 813 the authorization server (e.g., password, public/private key pair). 815 The authorization server MUST authenticate the client whenever 816 possible. If the authorization server cannot authenticate the client 817 due to the client's nature, the authorization server SHOULD utilize 818 other means to protect resource owners from such potentially 819 malicious clients. For example, the authorization server can engage 820 the resource owner to assist in identifying the client and its 821 origin. 823 It is RECOMMENDED to use asymmetric (public-key based) methods for 824 client authentication such as mTLS [RFC8705] or "private_key_jwt" 825 [OpenID]. When asymmetric methods for client authentication are 826 used, authorization servers do not need to store sensitive symmetric 827 keys, making these methods more robust against a number of attacks. 829 The authorization server MAY establish a client authentication method 830 with public clients, which converts them to credentialed clients. 831 However, the authorization server MUST NOT rely on credentialed 832 client authentication for the purpose of identifying the client. 834 The client MUST NOT use more than one authentication method in each 835 request. 837 2.4.1. Client Secret 839 Clients in possession of a client secret, sometimes known as a client 840 password, MAY use the HTTP Basic authentication scheme as defined in 841 [RFC7235] to authenticate with the authorization server. The client 842 identifier is encoded using the "application/x-www-form-urlencoded" 843 encoding algorithm per Appendix B, and the encoded value is used as 844 the username; the client secret is encoded using the same algorithm 845 and used as the password. The authorization server MUST support the 846 HTTP Basic authentication scheme for authenticating clients that were 847 issued a client secret. 849 For example (with extra line breaks for display purposes only): 851 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 853 In addition to that, the authorization server MAY support including 854 the client credentials in the request-body using the following 855 parameters: 857 "client_id": REQUIRED. The client identifier issued to the client 858 during the registration process described by Section 2.2. 860 "client_secret": REQUIRED. The client secret. 862 Including the client credentials in the request-body using the two 863 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 864 to directly utilize the HTTP Basic authentication scheme (or other 865 password-based HTTP authentication schemes). The parameters can only 866 be transmitted in the request-body and MUST NOT be included in the 867 request URI. 869 For example, a request to refresh an access token (Section 4.3) using 870 the body parameters (with extra line breaks for display purposes 871 only): 873 POST /token HTTP/1.1 874 Host: server.example.com 875 Content-Type: application/x-www-form-urlencoded 877 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 878 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 880 The authorization server MUST require the use of TLS as described in 881 Section 1.5 when sending requests using password authentication. 883 Since this client authentication method involves a password, the 884 authorization server MUST protect any endpoint utilizing it against 885 brute force attacks. 887 2.4.2. Other Authentication Methods 889 The authorization server MAY support any suitable authentication 890 scheme matching its security requirements. When using other 891 authentication methods, the authorization server MUST define a 892 mapping between the client identifier (registration record) and 893 authentication scheme. 895 Some additional authentication methods such as mTLS [RFC8705] and 896 "private_key_jwt" [OpenID] are defined in the "OAuth Token Endpoint 897 Authentication Methods (https://www.iana.org/assignments/oauth- 898 parameters/oauth-parameters.xhtml#token-endpoint-auth-method)" 899 registry, and may be useful as generic client authentication methods 900 beyond the specific use of protecting the token endpoint. 902 2.5. Unregistered Clients 904 This specification does not exclude the use of unregistered clients. 905 However, the use of such clients is beyond the scope of this 906 specification and requires additional security analysis and review of 907 its interoperability impact. 909 3. Protocol Endpoints 911 The authorization process utilizes two authorization server endpoints 912 (HTTP resources): 914 * Authorization endpoint - used by the client to obtain 915 authorization from the resource owner via user agent redirection. 917 * Token endpoint - used by the client to exchange an authorization 918 grant for an access token, typically with client authentication. 920 As well as one client endpoint: 922 * Redirection endpoint - used by the authorization server to return 923 responses containing authorization credentials to the client via 924 the resource owner user agent. 926 Not every authorization grant type utilizes both endpoints. 927 Extension grant types MAY define additional endpoints as needed. 929 3.1. Authorization Endpoint 931 The authorization endpoint is used to interact with the resource 932 owner and obtain an authorization grant. The authorization server 933 MUST first verify the identity of the resource owner. The way in 934 which the authorization server authenticates the resource owner 935 (e.g., username and password login, session cookies) is beyond the 936 scope of this specification. 938 The means through which the client obtains the location of the 939 authorization endpoint are beyond the scope of this specification, 940 but the location is typically provided in the service documentation, 941 or in the authorization server's metadata document ([RFC8414]). 943 The endpoint URI MAY include an "application/x-www-form-urlencoded" 944 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 945 which MUST be retained when adding additional query parameters. The 946 endpoint URI MUST NOT include a fragment component. 948 Since requests to the authorization endpoint result in user 949 authentication and the transmission of clear-text credentials (in the 950 HTTP response), the authorization server MUST require the use of TLS 951 as described in Section 1.5 when sending requests to the 952 authorization endpoint. 954 The authorization server MUST support the use of the HTTP "GET" 955 method [RFC7231] for the authorization endpoint and MAY support the 956 use of the "POST" method as well. 958 The authorization server MUST ignore unrecognized request parameters. 960 Request and response parameters defined by this specification MUST 961 NOT be included more than once. Parameters sent without a value MUST 962 be treated as if they were omitted from the request. 964 3.2. Token Endpoint 966 The token endpoint is used by the client to obtain an access token 967 using a grant such as those described in Section 4 and Section 4.3. 969 The means through which the client obtains the location of the token 970 endpoint are beyond the scope of this specification, but the location 971 is typically provided in the service documentation and configured 972 during development of the client, or provided in the authorization 973 server's metadata document ([RFC8414]) and fetched programmatically 974 at runtime. 976 The endpoint URI MAY include an "application/x-www-form-urlencoded" 977 formatted (per Appendix B) query component ([RFC3986] Section 3.4) 978 and MUST NOT include a fragment component. 980 Since requests to the token endpoint result in the transmission of 981 clear-text credentials (in the HTTP request and response), the 982 authorization server MUST require the use of TLS as described in 983 Section 1.5 when sending requests to the token endpoint. 985 The client MUST use the HTTP "POST" method when making access token 986 requests. 988 The authorization server MUST ignore unrecognized request parameters. 990 Parameters sent without a value MUST be treated as if they were 991 omitted from the request. Request and response parameters defined by 992 this specification MUST NOT be included more than once. 994 3.2.1. Client Authentication 996 Confidential or credentialed clients MUST authenticate with the 997 authorization server as described in Section 2.4 when making requests 998 to the token endpoint. 1000 Client authentication is used for: 1002 * Enforcing the binding of refresh tokens and authorization codes to 1003 the client they were issued to. Client authentication adds an 1004 additional layer of security when an authorization code is 1005 transmitted to the redirection endpoint over an insecure channel. 1007 * Recovering from a compromised client by disabling the client or 1008 changing its credentials, thus preventing an attacker from abusing 1009 stolen refresh tokens. Changing a single set of client 1010 credentials is significantly faster than revoking an entire set of 1011 refresh tokens. 1013 * Implementing authentication management best practices, which 1014 require periodic credential rotation. Rotation of an entire set 1015 of refresh tokens can be challenging, while rotation of a single 1016 set of client credentials is significantly easier. 1018 3.2.2. Token Request 1020 The client makes a request to the token endpoint by sending the 1021 following parameters using the "application/x-www-form-urlencoded" 1022 format per Appendix B with a character encoding of UTF-8 in the HTTP 1023 request payload: 1025 "client_id": REQUIRED, if the client is not authenticating with the 1026 authorization server as described in Section 3.2.1. 1028 "scope": OPTIONAL. The scope of the access request as described by 1029 Section 3.2.2.1. 1031 "grant_type": REQUIRED. Identifier of the grant type the client 1032 uses with the particular token request. This specification 1033 defines the values "authorization_code", "refresh_token", and 1034 "client_credentials". The grant type determines the further 1035 parameters required or supported by the token request. The 1036 details of those grant types are defined below. 1038 Confidential or credentialed clients MUST authenticate with the 1039 authorization server as described in Section 3.2.1. 1041 For example, the client makes the following HTTP request using TLS 1042 (with extra line breaks for display purposes only): 1044 POST /token HTTP/1.1 1045 Host: server.example.com 1046 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1047 Content-Type: application/x-www-form-urlencoded 1049 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1050 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1051 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1053 The authorization server MUST: 1055 * require client authentication for confidential and credentialed 1056 clients (or clients with other authentication requirements), 1058 * authenticate the client if client authentication is included 1060 Further grant type specific processing rules apply and are specified 1061 with the respective grant type. 1063 3.2.2.1. Access Token Scope 1065 The authorization and token endpoints allow the client to specify the 1066 scope of the access request using the "scope" request parameter. In 1067 turn, the authorization server uses the "scope" response parameter to 1068 inform the client of the scope of the access token issued. 1070 The value of the scope parameter is expressed as a list of space- 1071 delimited, case-sensitive strings. The strings are defined by the 1072 authorization server. If the value contains multiple space-delimited 1073 strings, their order does not matter, and each string adds an 1074 additional access range to the requested scope. 1076 scope = scope-token *( SP scope-token ) 1077 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 1079 The authorization server MAY fully or partially ignore the scope 1080 requested by the client, based on the authorization server policy or 1081 the resource owner's instructions. If the issued access token scope 1082 is different from the one requested by the client, the authorization 1083 server MUST include the "scope" response parameter to inform the 1084 client of the actual scope granted. 1086 If the client omits the scope parameter when requesting 1087 authorization, the authorization server MUST either process the 1088 request using a pre-defined default value or fail the request 1089 indicating an invalid scope. The authorization server SHOULD 1090 document its scope requirements and default value (if defined). 1092 3.2.3. Token Response 1094 If the access token request is valid and authorized, the 1095 authorization server issues an access token and optional refresh 1096 token. 1098 If the request client authentication failed or is invalid, the 1099 authorization server returns an error response as described in 1100 Section 3.2.3.1. 1102 The authorization server issues an access token and optional refresh 1103 token by creating an HTTP response body using the "application/json" 1104 media type as defined by [RFC8259] with the following parameters and 1105 an HTTP 200 (OK) status code: 1107 "access_token": REQUIRED. The access token issued by the 1108 authorization server. 1110 "token_type": REQUIRED. The type of the access token issued as 1111 described in Section 5.1. Value is case insensitive. 1113 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1114 token. For example, the value "3600" denotes that the access 1115 token will expire in one hour from the time the response was 1116 generated. If omitted, the authorization server SHOULD provide 1117 the expiration time via other means or document the default value. 1119 "scope": OPTIONAL, if identical to the scope requested by the 1120 client; otherwise, REQUIRED. The scope of the access token as 1121 described by Section 3.2.2.1. 1123 "refresh_token": OPTIONAL. The refresh token, which can be used to 1124 obtain new access tokens based on the grant passed in the 1125 corresponding token request. 1127 Authorization servers SHOULD determine, based on a risk assessment 1128 and their own policies, whether to issue refresh tokens to a certain 1129 client. If the authorization server decides not to issue refresh 1130 tokens, the client MAY obtain new access tokens by starting the OAuth 1131 flow over, for example initiating a new authorization code request. 1132 In such a case, the authorization server may utilize cookies and 1133 persistent grants to optimize the user experience. 1135 If refresh tokens are issued, those refresh tokens MUST be bound to 1136 the scope and resource servers as consented by the resource owner. 1137 This is to prevent privilege escalation by the legitimate client and 1138 reduce the impact of refresh token leakage. 1140 The parameters are serialized into a JavaScript Object Notation 1141 (JSON) structure by adding each parameter at the highest structure 1142 level. Parameter names and string values are included as JSON 1143 strings. Numerical values are included as JSON numbers. The order 1144 of parameters does not matter and can vary. 1146 The authorization server MUST include the HTTP "Cache-Control" 1147 response header field [RFC7234] with a value of "no-store" in any 1148 response containing tokens, credentials, or other sensitive 1149 information. 1151 For example: 1153 HTTP/1.1 200 OK 1154 Content-Type: application/json 1155 Cache-Control: no-store 1157 { 1158 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1159 "token_type":"Bearer", 1160 "expires_in":3600, 1161 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1162 "example_parameter":"example_value" 1163 } 1164 The client MUST ignore unrecognized value names in the response. The 1165 sizes of tokens and other values received from the authorization 1166 server are left undefined. The client should avoid making 1167 assumptions about value sizes. The authorization server SHOULD 1168 document the size of any value it issues. 1170 3.2.3.1. Error Response 1172 The authorization server responds with an HTTP 400 (Bad Request) 1173 status code (unless specified otherwise) and includes the following 1174 parameters with the response: 1176 "error": REQUIRED. A single ASCII [USASCII] error code from the 1177 following: 1179 "invalid_request": The request is missing a required parameter, 1180 includes an unsupported parameter value (other than grant 1181 type), repeats a parameter, includes multiple credentials, 1182 utilizes more than one mechanism for authenticating the client, 1183 contains a "code_verifier" although no "code_challenge" was 1184 sent in the authorization request, or is otherwise malformed. 1186 "invalid_client": Client authentication failed (e.g., unknown 1187 client, no client authentication included, or unsupported 1188 authentication method). The authorization server MAY return an 1189 HTTP 401 (Unauthorized) status code to indicate which HTTP 1190 authentication schemes are supported. If the client attempted 1191 to authenticate via the "Authorization" request header field, 1192 the authorization server MUST respond with an HTTP 401 1193 (Unauthorized) status code and include the "WWW-Authenticate" 1194 response header field matching the authentication scheme used 1195 by the client. 1197 "invalid_grant": The provided authorization grant (e.g., 1198 authorization code, resource owner credentials) or refresh 1199 token is invalid, expired, revoked, does not match the redirect 1200 URI used in the authorization request, or was issued to another 1201 client. 1203 "unauthorized_client": The authenticated client is not authorized 1204 to use this authorization grant type. 1206 "unsupported_grant_type": The authorization grant type is not 1207 supported by the authorization server. 1209 "invalid_scope": The requested scope is invalid, unknown, 1210 malformed, or exceeds the scope granted by the resource owner. 1212 Values for the "error" parameter MUST NOT include characters 1213 outside the set %x20-21 / %x23-5B / %x5D-7E. 1215 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1216 providing additional information, used to assist the client 1217 developer in understanding the error that occurred. Values for 1218 the "error_description" parameter MUST NOT include characters 1219 outside the set %x20-21 / %x23-5B / %x5D-7E. 1221 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1222 with information about the error, used to provide the client 1223 developer with additional information about the error. Values for 1224 the "error_uri" parameter MUST conform to the URI-reference syntax 1225 and thus MUST NOT include characters outside the set %x21 / 1226 %x23-5B / %x5D-7E. 1228 The parameters are included in the payload of the HTTP response using 1229 the "application/json" media type as defined by [RFC7159]. The 1230 parameters are serialized into a JSON structure by adding each 1231 parameter at the highest structure level. Parameter names and string 1232 values are included as JSON strings. Numerical values are included 1233 as JSON numbers. The order of parameters does not matter and can 1234 vary. 1236 For example: 1238 HTTP/1.1 400 Bad Request 1239 Content-Type: application/json 1240 Cache-Control: no-store 1242 { 1243 "error":"invalid_request" 1244 } 1246 4. Grant Types 1248 To request an access token, the client obtains authorization from the 1249 resource owner. This specification defines the following 1250 authorization grant types: 1252 * authorization code 1254 * client credentials, and 1256 * refresh token 1258 It also provides an extension mechanism for defining additional grant 1259 types. 1261 4.1. Authorization Code Grant 1263 The authorization code grant type is used to obtain both access 1264 tokens and refresh tokens. 1266 The grant type uses the additional authorization endpoint to let the 1267 authorization server interact with the resource owner in order to get 1268 consent for resource access. 1270 Since this is a redirect-based flow, the client must be capable of 1271 initiating the flow with the resource owner's user agent (typically a 1272 web browser) and capable of being redirected back to from the 1273 authorization server. 1275 +----------+ 1276 | Resource | 1277 | Owner | 1278 | | 1279 +----------+ 1280 ^ 1281 | 1282 (2) 1283 +----|-----+ Client Identifier +---------------+ 1284 | -+----(1)-- & Redirect URI ---->| | 1285 | User- | | Authorization | 1286 | Agent -+----(2)-- User authenticates --->| Server | 1287 | | | | 1288 | -+----(3)-- Authorization Code ---<| | 1289 +-|----|---+ +---------------+ 1290 | | ^ v 1291 (1) (3) | | 1292 | | | | 1293 ^ v | | 1294 +---------+ | | 1295 | |>---(4)-- Authorization Code ---------' | 1296 | Client | & Redirect URI | 1297 | | | 1298 | |<---(5)----- Access Token -------------------' 1299 +---------+ (w/ Optional Refresh Token) 1301 Note: The lines illustrating steps (1), (2), and (3) are broken into 1302 two parts as they pass through the user agent. 1304 Figure 3: Authorization Code Flow 1306 The flow illustrated in Figure 3 includes the following steps: 1308 (1) The client initiates the flow by directing the resource owner's 1309 user agent to the authorization endpoint. The client includes its 1310 client identifier, code challenge (derived from a generated code 1311 verifier), optional requested scope, optional local state, and a 1312 redirect URI to which the authorization server will send the user 1313 agent back once access is granted (or denied). 1315 (2) The authorization server authenticates the resource owner (via 1316 the user agent) and establishes whether the resource owner grants or 1317 denies the client's access request. 1319 (3) Assuming the resource owner grants access, the authorization 1320 server redirects the user agent back to the client using the redirect 1321 URI provided earlier (in the request or during client registration). 1322 The redirect URI includes an authorization code and any local state 1323 provided by the client earlier. 1325 (4) The client requests an access token from the authorization 1326 server's token endpoint by including the authorization code received 1327 in the previous step, and including its code verifier. When making 1328 the request, the client authenticates with the authorization server 1329 if it can. The client includes the redirect URI used to obtain the 1330 authorization code for verification. 1332 (5) The authorization server authenticates the client when possible, 1333 validates the authorization code, validates the code verifier, and 1334 ensures that the redirect URI received matches the URI used to 1335 redirect the client in step (3). If valid, the authorization server 1336 responds back with an access token and, optionally, a refresh token. 1338 4.1.1. Authorization Request 1340 To begin the authorization request, the client builds the 1341 authorization request URI by adding parameters to the authorization 1342 server's authorization endpoint URI. The client will eventually 1343 redirect the user agent to this URI to initiate the request. 1345 Clients use a unique secret per authorization request to protect 1346 against authorization code injection and CSRF attacks. The client 1347 first generates this secret, which it can use at the time of 1348 redeeming the authorization code to prove that the client using the 1349 authorization code is the same client that requested it. 1351 The client constructs the request URI by adding the following 1352 parameters to the query component of the authorization endpoint URI 1353 using the "application/x-www-form-urlencoded" format, per Appendix B: 1355 "response_type": REQUIRED. The authorization endpoint supports 1356 different sets of request and response pameters. The client 1357 determines the type of flow by using a certain "response_type" 1358 value. This specification defines the value "code", which must be 1359 used to signal that the client wants to use the authorization code 1360 flow. 1362 Extension response types MAY contain a space-delimited (%x20) list of 1363 values, where the order of values does not matter (e.g., response 1364 type "a b" is the same as "b a"). The meaning of such composite 1365 response types is defined by their respective specifications. 1367 Some extension response types are defined by ([OpenID]). 1369 If an authorization request is missing the "response_type" parameter, 1370 or if the response type is not understood, the authorization server 1371 MUST return an error response as described in Section 4.1.2.1. 1373 "client_id": REQUIRED. The client identifier as described in 1374 Section 2.2. 1376 "code_challenge": REQUIRED or RECOMMENDED (see Section 7.8). Code 1377 challenge. 1379 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1380 present in the request. Code verifier transformation method is 1381 "S256" or "plain". 1383 "redirect_uri": OPTIONAL. As described in Section 2.3. 1385 "scope": OPTIONAL. The scope of the access request as described by 1386 Section 3.2.2.1. 1388 "state": OPTIONAL. An opaque value used by the client to maintain 1389 state between the request and callback. The authorization server 1390 includes this value when redirecting the user agent back to the 1391 client. 1393 The "code_verifier" is a unique high-entropy cryptographically random 1394 string generated for each authorization request, using the unreserved 1395 characters "[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"", with a 1396 minimum length of 43 characters and a maximum length of 128 1397 characters. 1399 The client stores the "code_verifier" temporarily, and calculates the 1400 "code_challenge" which it uses in the authorization request. 1402 ABNF for "code_verifier" is as follows. 1404 code-verifier = 43*128unreserved 1405 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1406 ALPHA = %x41-5A / %x61-7A 1407 DIGIT = %x30-39 1409 NOTE: The code verifier SHOULD have enough entropy to make it 1410 impractical to guess the value. It is RECOMMENDED that the output of 1411 a suitable random number generator be used to create a 32-octet 1412 sequence. The octet sequence is then base64url-encoded to produce a 1413 43-octet URL-safe string to use as the code verifier. 1415 The client then creates a "code_challenge" derived from the code 1416 verifier by using one of the following transformations on the code 1417 verifier: 1419 S256 1420 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1422 plain 1423 code_challenge = code_verifier 1425 If the client is capable of using "S256", it MUST use "S256", as 1426 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1427 permitted to use "plain" only if they cannot support "S256" for some 1428 technical reason, for example constrained environments that do not 1429 have a hashing function available, and know via out-of-band 1430 configuration or via Authorization Server Metadata ([RFC8414]) that 1431 the server supports "plain". 1433 ABNF for "code_challenge" is as follows. 1435 code-challenge = 43*128unreserved 1436 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1437 ALPHA = %x41-5A / %x61-7A 1438 DIGIT = %x30-39 1440 The properties "code_challenge" and "code_verifier" are adopted from 1441 the OAuth 2.0 extension known as "Proof-Key for Code Exchange", or 1442 PKCE ([RFC7636]) where this technique was originally developed. 1444 Clients MUST use "code_challenge" and "code_verifier" and 1445 authorization servers MUST enforce their use except under the 1446 conditions described in Section 7.8. In this case, using and 1447 enforcing "code_challenge" and "code_verifier" as described in the 1448 following is still RECOMMENDED. 1450 The client directs the resource owner to the constructed URI using an 1451 HTTP redirection, or by other means available to it via the user 1452 agent. 1454 For example, the client directs the user agent to make the following 1455 HTTP request using TLS (with extra line breaks for display purposes 1456 only): 1458 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1459 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1460 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1461 &code_challenge_method=S256 HTTP/1.1 1462 Host: server.example.com 1464 The authorization server validates the request to ensure that all 1465 required parameters are present and valid. 1467 In particular, the authorization server MUST validate the 1468 "redirect_uri" in the request if present, ensuring that it matches 1469 one of the registered redirect URIs previously established during 1470 client registration (Section 2). When comparing the two URIs the 1471 authorization server MUST using simple character-by-character string 1472 comparison as defined in [RFC3986], Section 6.2.1. 1474 If the request is valid, the authorization server authenticates the 1475 resource owner and obtains an authorization decision (by asking the 1476 resource owner or by establishing approval via other means). 1478 When a decision is established, the authorization server directs the 1479 user agent to the provided client redirect URI using an HTTP 1480 redirection response, or by other means available to it via the user 1481 agent. 1483 4.1.2. Authorization Response 1485 If the resource owner grants the access request, the authorization 1486 server issues an authorization code and delivers it to the client by 1487 adding the following parameters to the query component of the 1488 redirect URI using the "application/x-www-form-urlencoded" format, 1489 per Appendix B: 1491 "code": REQUIRED. The authorization code generated by the 1492 authorization server. The authorization code MUST expire shortly 1493 after it is issued to mitigate the risk of leaks. A maximum 1494 authorization code lifetime of 10 minutes is RECOMMENDED. The 1495 client MUST NOT use the authorization code more than once. If an 1496 authorization code is used more than once, the authorization 1497 server MUST deny the request and SHOULD revoke (when possible) all 1498 access tokens and refresh tokens previously issued based on that 1499 authorization code. The authorization code is bound to the client 1500 identifier and redirect URI. 1502 "state": REQUIRED if the "state" parameter was present in the client 1503 authorization request. The exact value received from the client. 1505 For example, the authorization server redirects the user agent by 1506 sending the following HTTP response: 1508 HTTP/1.1 302 Found 1509 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1510 &state=xyz 1512 The client MUST ignore unrecognized response parameters. The 1513 authorization code string size is left undefined by this 1514 specification. The client should avoid making assumptions about code 1515 value sizes. The authorization server SHOULD document the size of 1516 any value it issues. 1518 The authorization server MUST associate the "code_challenge" and 1519 "code_challenge_method" values with the issued authorization code so 1520 the code challenge can be verified later. 1522 The exact method that the server uses to associate the 1523 "code_challenge" with the issued code is out of scope for this 1524 specification. The code challenge could be stored on the server and 1525 associated with the code there. The "code_challenge" and 1526 "code_challenge_method" values may be stored in encrypted form in the 1527 code itself, but the server MUST NOT include the "code_challenge" 1528 value in a response parameter in a form that entities other than the 1529 AS can extract. 1531 4.1.2.1. Error Response 1533 If the request fails due to a missing, invalid, or mismatching 1534 redirect URI, or if the client identifier is missing or invalid, the 1535 authorization server SHOULD inform the resource owner of the error 1536 and MUST NOT automatically redirect the user agent to the invalid 1537 redirect URI. 1539 An AS MUST reject requests without a "code_challenge" from public 1540 clients, and MUST reject such requests from other clients unless 1541 there is reasonable assurance that the client mitigates authorization 1542 code injection in other ways. See Section 7.8 for details. 1544 If the server does not support the requested "code_challenge_method" 1545 transformation, the authorization endpoint MUST return the 1546 authorization error response with "error" value set to 1547 "invalid_request". The "error_description" or the response of 1548 "error_uri" SHOULD explain the nature of error, e.g., transform 1549 algorithm not supported. 1551 If the resource owner denies the access request or if the request 1552 fails for reasons other than a missing or invalid redirect URI, the 1553 authorization server informs the client by adding the following 1554 parameters to the query component of the redirect URI using the 1555 "application/x-www-form-urlencoded" format, per Appendix B: 1557 "error": REQUIRED. A single ASCII [USASCII] error code from the 1558 following: 1560 "invalid_request": The request is missing a required parameter, 1561 includes an invalid parameter value, includes a parameter more 1562 than once, or is otherwise malformed. 1564 "unauthorized_client": The client is not authorized to request an 1565 authorization code using this method. 1567 "access_denied": The resource owner or authorization server 1568 denied the request. 1570 "unsupported_response_type": The authorization server does not 1571 support obtaining an authorization code using this method. 1573 "invalid_scope": The requested scope is invalid, unknown, or 1574 malformed. 1576 "server_error": The authorization server encountered an 1577 unexpected condition that prevented it from fulfilling the 1578 request. (This error code is needed because a 500 Internal 1579 Server Error HTTP status code cannot be returned to the client 1580 via an HTTP redirect.) 1582 "temporarily_unavailable": The authorization server is currently 1583 unable to handle the request due to a temporary overloading or 1584 maintenance of the server. (This error code is needed because 1585 a 503 Service Unavailable HTTP status code cannot be returned 1586 to the client via an HTTP redirect.) 1588 Values for the "error" parameter MUST NOT include characters 1589 outside the set %x20-21 / %x23-5B / %x5D-7E. 1591 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1592 providing additional information, used to assist the client 1593 developer in understanding the error that occurred. Values for 1594 the "error_description" parameter MUST NOT include characters 1595 outside the set %x20-21 / %x23-5B / %x5D-7E. 1597 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1598 with information about the error, used to provide the client 1599 developer with additional information about the error. Values for 1600 the "error_uri" parameter MUST conform to the URI-reference syntax 1601 and thus MUST NOT include characters outside the set %x21 / 1602 %x23-5B / %x5D-7E. 1604 "state": REQUIRED if a "state" parameter was present in the client 1605 authorization request. The exact value received from the client. 1607 For example, the authorization server redirects the user agent by 1608 sending the following HTTP response: 1610 HTTP/1.1 302 Found 1611 Location: https://client.example.com/cb?error=access_denied&state=xyz 1613 4.1.3. Token Endpoint Extension 1615 The authorization grant type is identified at the token endpoint with 1616 the "grant_type" value of "authorization_code". 1618 If this value is set, the following additional token request 1619 parameters beyond Section 3.2.2 are required: 1621 "code": REQUIRED. The authorization code received from the 1622 authorization server. 1624 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1625 included in the authorization request as described in 1626 Section 4.1.1, and their values MUST be identical. 1628 "code_verifier": REQUIRED, if the "code_challenge" parameter was 1629 included in the authorization request. MUST NOT be used 1630 otherwise. The original code verifier string. 1632 For example, the client makes the following HTTP request using TLS 1633 (with extra line breaks for display purposes only): 1635 POST /token HTTP/1.1 1636 Host: server.example.com 1637 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1638 Content-Type: application/x-www-form-urlencoded 1640 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1641 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1642 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1644 In addition to the processing rules in Section 3.2.2, the 1645 authorization server MUST: 1647 * ensure that the authorization code was issued to the authenticated 1648 confidential or credentialed client, or if the client is public, 1649 ensure that the code was issued to "client_id" in the request, 1651 * verify that the authorization code is valid, 1653 * verify that the "code_verifier" parameter is present if and only 1654 if a "code_challenge" parameter was present in the authorization 1655 request, 1657 * if a "code_verifier" is present, verify the "code_verifier" by 1658 calculating the code challenge from the received "code_verifier" 1659 and comparing it with the previously associated "code_challenge", 1660 after first transforming it according to the 1661 "code_challenge_method" method specified by the client, and 1663 * ensure that the "redirect_uri" parameter is present if the 1664 "redirect_uri" parameter was included in the initial authorization 1665 request as described in Section 4.1.1, and if included ensure that 1666 their values are identical. 1668 4.2. Client Credentials Grant 1670 The client can request an access token using only its client 1671 credentials (or other supported means of authentication) when the 1672 client is requesting access to the protected resources under its 1673 control, or those of another resource owner that have been previously 1674 arranged with the authorization server (the method of which is beyond 1675 the scope of this specification). 1677 The client credentials grant type MUST only be used by confidential 1678 or credentialed clients. 1680 +---------+ +---------------+ 1681 | | | | 1682 | |>--(1)- Client Authentication --->| Authorization | 1683 | Client | | Server | 1684 | |<--(2)---- Access Token ---------<| | 1685 | | | | 1686 +---------+ +---------------+ 1688 Figure 4: Client Credentials Grant 1690 The use of the client credentials grant illustrated in Figure 4 1691 includes the following steps: 1693 (1) The client authenticates with the authorization server and 1694 requests an access token from the token endpoint. 1696 (2) The authorization server authenticates the client, and if valid, 1697 issues an access token. 1699 4.2.1. Token Endpoint Extension 1701 The authorization grant type is identified at the token endpoint with 1702 the "grant_type" value of "client_credentials". 1704 If this value is set, no additional parameters beyond Section 3.2.2 1705 are required/supported: 1707 For example, the client makes the following HTTP request using 1708 transport-layer security (with extra line breaks for display purposes 1709 only): 1711 POST /token HTTP/1.1 1712 Host: server.example.com 1713 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1714 Content-Type: application/x-www-form-urlencoded 1716 grant_type=client_credentials 1718 The authorization server MUST authenticate the client. 1720 4.3. Refresh Token Grant 1722 The refresh token is a credential issued by the authorization server 1723 to a client, which can be used to obtain new (fresh) access tokens 1724 based on an existing grant. The client uses this option either 1725 because the previous access token has expired or the client 1726 previously obtained an access token with a scope more narrow than 1727 approved by the respective grant and later requires an access token 1728 with a different scope under the same grant. 1730 4.3.1. Token Endpoint Extension 1732 The authorization grant type is identified at the token endpoint with 1733 the "grant_type" value of "refresh_token". 1735 If this value is set, the following additional parameters beyond 1736 Section 3.2.2 are required/supported: 1738 "refresh_token": REQUIRED. The refresh token issued to the client. 1740 Because refresh tokens are typically long-lasting credentials used to 1741 request additional access tokens, the refresh token is bound to the 1742 client to which it was issued. Confidential or credentialed clients 1743 MUST authenticate with the authorization server as described in 1744 Section 3.2.1. 1746 For example, the client makes the following HTTP request using 1747 transport-layer security (with extra line breaks for display purposes 1748 only): 1750 POST /token HTTP/1.1 1751 Host: server.example.com 1752 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1753 Content-Type: application/x-www-form-urlencoded 1755 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1757 In addition to the processing rules in Section 3.2.2, the 1758 authorization server MUST: 1760 * validate the refresh token. 1762 Authorization servers SHOULD utilize one of these methods to detect 1763 refresh token replay by malicious actors for public clients: 1765 * _Sender-constrained refresh tokens:_ the authorization server 1766 cryptographically binds the refresh token to a certain client 1767 instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705], 1768 [I-D.ietf-oauth-dpop], or another suitable method. 1770 * _Refresh token rotation:_ the authorization server issues a new 1771 refresh token with every access token refresh response. The 1772 previous refresh token is invalidated but information about the 1773 relationship is retained by the authorization server. If a 1774 refresh token is compromised and subsequently used by both the 1775 attacker and the legitimate client, one of them will present an 1776 invalidated refresh token, which will inform the authorization 1777 server of the breach. The authorization server cannot determine 1778 which party submitted the invalid refresh token, but it will 1779 revoke the active refresh token. This stops the attack at the 1780 cost of forcing the legitimate client to obtain a fresh 1781 authorization grant. 1783 Implementation note: the grant to which a refresh token belongs may 1784 be encoded into the refresh token itself. This can enable an 1785 authorization server to efficiently determine the grant to which a 1786 refresh token belongs, and by extension, all refresh tokens that need 1787 to be revoked. Authorization servers MUST ensure the integrity of 1788 the refresh token value in this case, for example, using signatures. 1790 4.3.2. Refresh Token Response 1792 If valid and authorized, the authorization server issues an access 1793 token as described in Section 3.2.3. 1795 The authorization server MAY issue a new refresh token, in which case 1796 the client MUST discard the old refresh token and replace it with the 1797 new refresh token. 1799 The authorization server MAY revoke the old refresh token after 1800 issuing a new refresh token to the client. If a new refresh token is 1801 issued, the refresh token scope MUST be identical to that of the 1802 refresh token included by the client in the request. 1804 Authorization servers MAY revoke refresh tokens automatically in case 1805 of a security event, such as: 1807 * password change 1809 * logout at the authorization server 1810 Refresh tokens SHOULD expire if the client has been inactive for some 1811 time, i.e., the refresh token has not been used to obtain new access 1812 tokens for some time. The expiration time is at the discretion of 1813 the authorization server. It might be a global value or determined 1814 based on the client policy or the grant associated with the refresh 1815 token (and its sensitivity). 1817 4.4. Extension Grants 1819 The client uses an extension grant type by specifying the grant type 1820 using an absolute URI (defined by the authorization server) as the 1821 value of the "grant_type" parameter of the token endpoint, and by 1822 adding any additional parameters necessary. 1824 For example, to request an access token using the Device 1825 Authorization Grant as defined by [RFC8628] after the user has 1826 authorized the client on a separate device, the client makes the 1827 following HTTP request using TLS (with extra line breaks for display 1828 purposes only): 1830 POST /token HTTP/1.1 1831 Host: server.example.com 1832 Content-Type: application/x-www-form-urlencoded 1834 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 1835 &device_code=GmRhmhcxhwEzkoEqiMEg_DnyEysNkuNhszIySk9eS 1836 &client_id=C409020731 1838 If the access token request is valid and authorized, the 1839 authorization server issues an access token and optional refresh 1840 token as described in Section 3.2.3. If the request failed client 1841 authentication or is invalid, the authorization server returns an 1842 error response as described in Section 3.2.3.1. 1844 5. Accessing Protected Resources 1846 The client accesses protected resources by presenting the access 1847 token to the resource server. The resource server MUST validate the 1848 access token and ensure that it has not expired and that its scope 1849 covers the requested resource. The methods used by the resource 1850 server to validate the access token (as well as any error responses) 1851 are beyond the scope of this specification, but generally involve an 1852 interaction or coordination between the resource server and the 1853 authorization server. For example, when the resource server and 1854 authorization server are colocated or are part of the same system, 1855 they may share a database or other storage; when the two components 1856 are operated independently, they may use Token Introspection 1857 [RFC7662] or a structured access token format such as a JWT 1858 [I-D.ietf-oauth-access-token-jwt]. 1860 The method in which the client utilizes the access token to access 1861 protected resources at the resource server depends on the type of 1862 access token issued by the authorization server. Typically, it 1863 involves using the HTTP "Authorization" request header field 1864 [RFC7235] with an authentication scheme defined by the specification 1865 of the access token type used, such as "Bearer", defined below. 1867 5.1. Access Token Types 1869 The access token type provides the client with the information 1870 required to successfully utilize the access token to make a protected 1871 resource request (along with type-specific attributes). The client 1872 MUST NOT use an access token if it does not understand the token 1873 type. 1875 For example, the "Bearer" token type defined in this specification is 1876 utilized by simply including the access token string in the request: 1878 GET /resource/1 HTTP/1.1 1879 Host: example.com 1880 Authorization: Bearer mF_9.B5f-4.1JqM 1882 The above example is provided for illustration purposes only. 1884 Each access token type definition specifies the additional attributes 1885 (if any) sent to the client together with the "access_token" response 1886 parameter. It also defines the HTTP authentication method used to 1887 include the access token when making a protected resource request. 1889 5.2. Bearer Tokens 1891 A Bearer Token is a security token with the property that any party 1892 in possession of the token (a "bearer") can use the token in any way 1893 that any other party in possession of it can. Using a bearer token 1894 does not require a bearer to prove possession of cryptographic key 1895 material (proof-of-possession). 1897 Bearer tokens may be extended to include proof-of-possession 1898 techniques by other specifications. 1900 5.2.1. Authenticated Requests 1902 This section defines two methods of sending Bearer tokens in resource 1903 requests to resource servers. Clients MUST NOT use more than one 1904 method to transmit the token in each request. 1906 5.2.1.1. Authorization Request Header Field 1908 When sending the access token in the "Authorization" request header 1909 field defined by HTTP/1.1 [RFC7235], the client uses the "Bearer" 1910 authentication scheme to transmit the access token. 1912 For example: 1914 GET /resource HTTP/1.1 1915 Host: server.example.com 1916 Authorization: Bearer mF_9.B5f-4.1JqM 1918 The syntax of the "Authorization" header field for this scheme 1919 follows the usage of the Basic scheme defined in Section 2 of 1920 [RFC2617]. Note that, as with Basic, it does not conform to the 1921 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1922 with the general authentication framework in HTTP 1.1 Authentication 1923 [RFC7235], although it does not follow the preferred practice 1924 outlined therein in order to reflect existing deployments. The 1925 syntax for Bearer credentials is as follows: 1927 b64token = 1*( ALPHA / DIGIT / 1928 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1929 credentials = "Bearer" 1*SP b64token 1931 Clients SHOULD make authenticated requests with a bearer token using 1932 the "Authorization" request header field with the "Bearer" HTTP 1933 authorization scheme. Resource servers MUST support this method. 1935 5.2.1.2. Form-Encoded Body Parameter 1937 When sending the access token in the HTTP request payload, the client 1938 adds the access token to the request-body using the "access_token" 1939 parameter. The client MUST NOT use this method unless all of the 1940 following conditions are met: 1942 * The HTTP request entity-header includes the "Content-Type" header 1943 field set to "application/x-www-form-urlencoded". 1945 * The payload follows the encoding requirements of the "application/ 1946 x-www-form-urlencoded" content-type as defined by HTML 4.01 1947 [W3C.REC-html401-19991224]. 1949 * The HTTP request payload is single-part. 1951 * The content to be encoded in the payload MUST consist entirely of 1952 ASCII [USASCII] characters. 1954 * The HTTP request method is one for which the request-body has 1955 defined semantics. In particular, this means that the "GET" 1956 method MUST NOT be used. 1958 The payload MAY include other request-specific parameters, in which 1959 case the "access_token" parameter MUST be properly separated from the 1960 request-specific parameters using "&" character(s) (ASCII code 38). 1962 For example, the client makes the following HTTP request using 1963 transport-layer security: 1965 POST /resource HTTP/1.1 1966 Host: server.example.com 1967 Content-Type: application/x-www-form-urlencoded 1969 access_token=mF_9.B5f-4.1JqM 1971 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1972 except in application contexts where participating clients do not 1973 have access to the "Authorization" request header field. Resource 1974 servers MAY support this method. 1976 5.2.2. The WWW-Authenticate Response Header Field 1978 If the protected resource request does not include authentication 1979 credentials or does not contain an access token that enables access 1980 to the protected resource, the resource server MUST include the HTTP 1981 "WWW-Authenticate" response header field; it MAY include it in 1982 response to other conditions as well. The "WWW-Authenticate" header 1983 field uses the framework defined by HTTP/1.1 [RFC7235]. 1985 All challenges for this token type MUST use the auth-scheme value 1986 "Bearer". This scheme MUST be followed by one or more auth-param 1987 values. The auth-param attributes used or defined by this 1988 specification for this token type are as follows. Other auth-param 1989 attributes MAY be used as well. 1991 A "realm" attribute MAY be included to indicate the scope of 1992 protection in the manner described in HTTP/1.1 [RFC7235]. The 1993 "realm" attribute MUST NOT appear more than once. 1995 The "scope" attribute is defined in Section 3.2.2.1. The "scope" 1996 attribute is a space-delimited list of case-sensitive scope values 1997 indicating the required scope of the access token for accessing the 1998 requested resource. "scope" values are implementation defined; there 1999 is no centralized registry for them; allowed values are defined by 2000 the authorization server. The order of "scope" values is not 2001 significant. In some cases, the "scope" value will be used when 2002 requesting a new access token with sufficient scope of access to 2003 utilize the protected resource. Use of the "scope" attribute is 2004 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 2005 "scope" value is intended for programmatic use and is not meant to be 2006 displayed to end-users. 2008 Two example scope values follow; these are taken from the OpenID 2009 Connect [OpenID.Messages] and the Open Authentication Technology 2010 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 2011 OAuth 2.0 use cases, respectively: 2013 scope="openid profile email" 2014 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 2016 If the protected resource request included an access token and failed 2017 authentication, the resource server SHOULD include the "error" 2018 attribute to provide the client with the reason why the access 2019 request was declined. The parameter value is described in 2020 Section 5.2.3. In addition, the resource server MAY include the 2021 "error_description" attribute to provide developers a human-readable 2022 explanation that is not meant to be displayed to end-users. It also 2023 MAY include the "error_uri" attribute with an absolute URI 2024 identifying a human-readable web page explaining the error. The 2025 "error", "error_description", and "error_uri" attributes MUST NOT 2026 appear more than once. 2028 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 2029 include characters outside the set %x21 / %x23-5B / %x5D-7E for 2030 representing scope values and %x20 for delimiters between scope 2031 values. Values for the "error" and "error_description" attributes 2032 (specified in Appendixes A.7 and A.8) MUST NOT include characters 2033 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 2034 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 2035 the URI-reference syntax and thus MUST NOT include characters outside 2036 the set %x21 / %x23-5B / %x5D-7E. 2038 For example, in response to a protected resource request without 2039 authentication: 2041 HTTP/1.1 401 Unauthorized 2042 WWW-Authenticate: Bearer realm="example" 2044 And in response to a protected resource request with an 2045 authentication attempt using an expired access token: 2047 HTTP/1.1 401 Unauthorized 2048 WWW-Authenticate: Bearer realm="example", 2049 error="invalid_token", 2050 error_description="The access token expired" 2052 5.2.3. Error Codes 2054 When a request fails, the resource server responds using the 2055 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2056 includes one of the following error codes in the response: 2058 "invalid_request": The request is missing a required parameter, 2059 includes an unsupported parameter or parameter value, repeats the 2060 same parameter, uses more than one method for including an access 2061 token, or is otherwise malformed. The resource server SHOULD 2062 respond with the HTTP 400 (Bad Request) status code. 2064 "invalid_token": The access token provided is expired, revoked, 2065 malformed, or invalid for other reasons. The resource SHOULD 2066 respond with the HTTP 401 (Unauthorized) status code. The client 2067 MAY request a new access token and retry the protected resource 2068 request. 2070 "insufficient_scope": The request requires higher privileges than 2071 provided by the access token. The resource server SHOULD respond 2072 with the HTTP 403 (Forbidden) status code and MAY include the 2073 "scope" attribute with the scope necessary to access the protected 2074 resource. 2076 If the request lacks any authentication information (e.g., the client 2077 was unaware that authentication is necessary or attempted using an 2078 unsupported authentication method), the resource server SHOULD NOT 2079 include an error code or other error information. 2081 For example: 2083 HTTP/1.1 401 Unauthorized 2084 WWW-Authenticate: Bearer realm="example" 2086 5.3. Error Response 2088 If a resource access request fails, the resource server SHOULD inform 2089 the client of the error. The method by which the resource server 2090 does this is determined by the particular token type, such as the 2091 description of Bearer tokens in Section 5.2.3. 2093 5.3.1. Extension Token Types 2095 [RFC6750] establishes a common registry in Section 11.4 2096 (https://tools.ietf.org/html/rfc6749#section-11.4) for error values 2097 to be shared among OAuth token authentication schemes. 2099 New authentication schemes designed primarily for OAuth token 2100 authentication SHOULD define a mechanism for providing an error 2101 status code to the client, in which the error values allowed are 2102 registered in the error registry established by this specification. 2104 Such schemes MAY limit the set of valid error codes to a subset of 2105 the registered values. If the error code is returned using a named 2106 parameter, the parameter name SHOULD be "error". 2108 Other schemes capable of being used for OAuth token authentication, 2109 but not primarily designed for that purpose, MAY bind their error 2110 values to the registry in the same manner. 2112 New authentication schemes MAY choose to also specify the use of the 2113 "error_description" and "error_uri" parameters to return error 2114 information in a manner parallel to their usage in this 2115 specification. 2117 6. Extensibility 2118 6.1. Defining Access Token Types 2120 Access token types can be defined in one of two ways: registered in 2121 the Access Token Types registry (following the procedures in 2122 Section 11.1 of [RFC6749]), or by using a unique absolute URI as its 2123 name. 2125 Types utilizing a URI name SHOULD be limited to vendor-specific 2126 implementations that are not commonly applicable, and are specific to 2127 the implementation details of the resource server where they are 2128 used. 2130 All other types MUST be registered. Type names MUST conform to the 2131 type-name ABNF. If the type definition includes a new HTTP 2132 authentication scheme, the type name SHOULD be identical to the HTTP 2133 authentication scheme name (as defined by [RFC2617]). The token type 2134 "example" is reserved for use in examples. 2136 type-name = 1*name-char 2137 name-char = "-" / "." / "_" / DIGIT / ALPHA 2139 6.2. Defining New Endpoint Parameters 2141 New request or response parameters for use with the authorization 2142 endpoint or the token endpoint are defined and registered in the 2143 OAuth Parameters registry following the procedure in Section 11.2 of 2144 [RFC6749]. 2146 Parameter names MUST conform to the param-name ABNF, and parameter 2147 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2148 to the syntax of an existing parameter). 2150 param-name = 1*name-char 2151 name-char = "-" / "." / "_" / DIGIT / ALPHA 2153 Unregistered vendor-specific parameter extensions that are not 2154 commonly applicable and that are specific to the implementation 2155 details of the authorization server where they are used SHOULD 2156 utilize a vendor-specific prefix that is not likely to conflict with 2157 other registered values (e.g., begin with 'companyname_'). 2159 6.3. Defining New Authorization Grant Types 2161 New authorization grant types can be defined by assigning them a 2162 unique absolute URI for use with the "grant_type" parameter. If the 2163 extension grant type requires additional token endpoint parameters, 2164 they MUST be registered in the OAuth Parameters registry as described 2165 by Section 11.2 of [RFC6749]. 2167 6.4. Defining New Authorization Endpoint Response Types 2169 New response types for use with the authorization endpoint are 2170 defined and registered in the Authorization Endpoint Response Types 2171 registry following the procedure in Section 11.3 of [RFC6749]. 2172 Response type names MUST conform to the response-type ABNF. 2174 response-type = response-name *( SP response-name ) 2175 response-name = 1*response-char 2176 response-char = "_" / DIGIT / ALPHA 2178 If a response type contains one or more space characters (%x20), it 2179 is compared as a space-delimited list of values in which the order of 2180 values does not matter. Only one order of values can be registered, 2181 which covers all other arrangements of the same set of values. 2183 For example, an extension can define and register the "code 2184 other_token" response type. Once registered, the same combination 2185 cannot be registered as "other_token code", but both values can be 2186 used to denote the same response type. 2188 6.5. Defining Additional Error Codes 2190 In cases where protocol extensions (i.e., access token types, 2191 extension parameters, or extension grant types) require additional 2192 error codes to be used with the authorization code grant error 2193 response (Section 4.1.2.1), the token error response 2194 (Section 3.2.3.1), or the resource access error response 2195 (Section 5.3), such error codes MAY be defined. 2197 Extension error codes MUST be registered (following the procedures in 2198 Section 11.4 of [RFC6749]) if the extension they are used in 2199 conjunction with is a registered access token type, a registered 2200 endpoint parameter, or an extension grant type. Error codes used 2201 with unregistered extensions MAY be registered. 2203 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2204 an identifying name when possible. For example, an error identifying 2205 an invalid value set to the extension parameter "example" SHOULD be 2206 named "example_invalid". 2208 error = 1*error-char 2209 error-char = %x20-21 / %x23-5B / %x5D-7E 2211 7. Security Considerations 2213 As a flexible and extensible framework, OAuth's security 2214 considerations depend on many factors. The following sections 2215 provide implementers with security guidelines focused on the three 2216 client profiles described in Section 2.1: web application, browser- 2217 based application, and native application. 2219 A comprehensive OAuth security model and analysis, as well as 2220 background for the protocol design, is provided by [RFC6819] and 2221 [I-D.ietf-oauth-security-topics]. 2223 7.1. Access Token Security Considerations 2225 7.1.1. Security Threats 2227 The following list presents several common threats against protocols 2228 utilizing some form of tokens. This list of threats is based on NIST 2229 Special Publication 800-63 [NIST800-63]. 2231 7.1.1.1. Access token manufacture/modification 2233 An attacker may generate a bogus access token or modify the token 2234 contents (such as the authentication or attribute statements) of an 2235 existing token, causing the resource server to grant inappropriate 2236 access to the client. For example, an attacker may modify the token 2237 to extend the validity period; a malicious client may modify the 2238 assertion to gain access to information that they should not be able 2239 to view. 2241 7.1.1.2. Access token disclosure 2243 Access tokens may contain authentication and attribute statements 2244 that include sensitive information. 2246 7.1.1.3. Access token redirect 2248 An attacker uses an access token generated for consumption by one 2249 resource server to gain access to a different resource server that 2250 mistakenly believes the token to be for it. 2252 7.1.1.4. Access token replay 2254 An attacker attempts to use an access token that has already been 2255 used with that resource server in the past. 2257 7.1.2. Threat Mitigation 2259 A large range of threats can be mitigated by protecting the contents 2260 of the access token by using a digital signature. 2262 Alternatively, a bearer token can contain a reference to 2263 authorization information, rather than encoding the information 2264 directly. Such references MUST be infeasible for an attacker to 2265 guess; using a reference may require an extra interaction between a 2266 server and the access token issuer to resolve the reference to the 2267 authorization information. The mechanics of such an interaction are 2268 not defined by this specification. 2270 This document does not specify the encoding or the contents of the 2271 access token; hence, detailed recommendations about the means of 2272 guaranteeing access token integrity protection are outside the scope 2273 of this specification. The access token integrity protection MUST be 2274 sufficient to prevent the token from being modified. One example of 2275 an encoding and signing mechanism for access tokens is described in 2276 [I-D.ietf-oauth-access-token-jwt]. 2278 To deal with access token redirects, it is important for the 2279 authorization server to include the identity of the intended 2280 recipients (the audience), typically a single resource server (or a 2281 list of resource servers), in the token. Restricting the use of the 2282 token to a specific scope is also RECOMMENDED. 2284 The authorization server MUST implement TLS as described in Which 2285 version(s) ought to be implemented will vary over time and will 2286 depend on the widespread deployment and known security 2287 vulnerabilities at the time of implementation. Refer to 2288 Section 1.5.[BCP195] for up to date recommendations on transport 2289 layer security. 2291 To protect against access token disclosure, confidentiality 2292 protection MUST be applied using TLS with a ciphersuite that provides 2293 confidentiality and integrity protection. This requires that the 2294 communication interaction between the client and the authorization 2295 server, as well as the interaction between the client and the 2296 resource server, utilize confidentiality and integrity protection. 2297 Since TLS is mandatory to implement and to use with this 2298 specification, it is the preferred approach for preventing token 2299 disclosure via the communication channel. For those cases where the 2300 client is prevented from observing the contents of the access token, 2301 token encryption MUST be applied in addition to the usage of TLS 2302 protection. As a further defense against token disclosure, the 2303 client MUST validate the TLS certificate chain when making requests 2304 to protected resources, including checking the Certificate Revocation 2305 List (CRL) [RFC5280]. 2307 If cookies are transmitted without TLS protection, any information 2308 contained in them is at risk of disclosure. Therefore, Bearer tokens 2309 MUST NOT be stored in cookies that can be sent in the clear, as any 2310 information in them is at risk of disclosure. See "HTTP State 2311 Management Mechanism" [RFC6265] for security considerations about 2312 cookies. 2314 In some deployments, including those utilizing load balancers, the 2315 TLS connection to the resource server terminates prior to the actual 2316 server that provides the resource. This could leave the token 2317 unprotected between the front-end server where the TLS connection 2318 terminates and the back-end server that provides the resource. In 2319 such deployments, sufficient measures MUST be employed to ensure 2320 confidentiality of the access token between the front-end and back- 2321 end servers; encryption of the token is one such possible measure. 2323 To deal with access token capture and replay, the following 2324 recommendations are made: First, the lifetime of the token MUST be 2325 limited; one means of achieving this is by putting a validity time 2326 field inside the protected part of the token. Note that using short- 2327 lived tokens reduces the impact of them being leaked. Second, 2328 confidentiality protection of the exchanges between the client and 2329 the authorization server and between the client and the resource 2330 server MUST be applied. As a consequence, no eavesdropper along the 2331 communication path is able to observe the token exchange. 2332 Consequently, such an on-path adversary cannot replay the token. 2333 Furthermore, when presenting the token to a resource server, the 2334 client MUST verify the identity of that resource server, as per 2335 [BCP195] and Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the 2336 client MUST validate the TLS certificate chain when making these 2337 requests to protected resources. Presenting the token to an 2338 unauthenticated and unauthorized resource server or failing to 2339 validate the certificate chain will allow adversaries to steal the 2340 token and gain unauthorized access to protected resources. 2342 7.1.3. Summary of Recommendations 2344 7.1.3.1. Safeguard bearer tokens 2346 Client implementations MUST ensure that bearer tokens are not leaked 2347 to unintended parties, as they will be able to use them to gain 2348 access to protected resources. This is the primary security 2349 consideration when using bearer tokens and underlies all the more 2350 specific recommendations that follow. 2352 7.1.3.2. Validate TLS certificate chains 2354 The client MUST validate the TLS certificate chain when making 2355 requests to protected resources. Failing to do so may enable DNS 2356 hijacking attacks to steal the token and gain unintended access. 2358 7.1.3.3. Always use TLS (https) 2360 Clients MUST always use TLS (https) or equivalent transport security 2361 when making requests with bearer tokens. Failing to do so exposes 2362 the token to numerous attacks that could give attackers unintended 2363 access. 2365 7.1.3.4. Don't store bearer tokens in HTTP cookies 2367 Implementations MUST NOT store bearer tokens within cookies that can 2368 be sent in the clear (which is the default transmission mode for 2369 cookies). Implementations that do store bearer tokens in cookies 2370 MUST take precautions against cross-site request forgery. 2372 7.1.3.5. Issue short-lived bearer tokens 2374 Authorization servers SHOULD issue short-lived bearer tokens, 2375 particularly when issuing tokens to clients that run within a web 2376 browser or other environments where information leakage may occur. 2377 Using short-lived bearer tokens can reduce the impact of them being 2378 leaked. 2380 7.1.3.6. Issue scoped bearer tokens 2382 Authorization servers SHOULD issue bearer tokens that contain an 2383 audience restriction, scoping their use to the intended relying party 2384 or set of relying parties. 2386 7.1.3.7. Don't pass bearer tokens in page URLs 2388 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2389 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2390 message headers or message bodies for which confidentiality measures 2391 are taken. Browsers, web servers, and other software may not 2392 adequately secure URLs in the browser history, web server logs, and 2393 other data structures. If bearer tokens are passed in page URLs, 2394 attackers might be able to steal them from the history data, logs, or 2395 other unsecured locations. 2397 7.1.4. Token Replay Prevention 2399 A sender-constrained access token scopes the applicability of an 2400 access token to a certain sender. This sender is obliged to 2401 demonstrate knowledge of a certain secret as prerequisite for the 2402 acceptance of that access token at the recipient (e.g., a resource 2403 server). 2405 Authorization and resource servers SHOULD use mechanisms for sender- 2406 constrained access tokens to prevent token replay as described in 2407 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2408 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2410 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2411 terminated at an intermediary, refer to Section 4.11 of 2412 [I-D.ietf-oauth-security-topics] for further security advice. 2414 7.1.5. Access Token Privilege Restriction 2416 The privileges associated with an access token SHOULD be restricted 2417 to the minimum required for the particular application or use case. 2418 This prevents clients from exceeding the privileges authorized by the 2419 resource owner. It also prevents users from exceeding their 2420 privileges authorized by the respective security policy. Privilege 2421 restrictions also help to reduce the impact of access token leakage. 2423 In particular, access tokens SHOULD be restricted to certain resource 2424 servers (audience restriction), preferably to a single resource 2425 server. To put this into effect, the authorization server associates 2426 the access token with certain resource servers and every resource 2427 server is obliged to verify, for every request, whether the access 2428 token sent with that request was meant to be used for that particular 2429 resource server. If not, the resource server MUST refuse to serve 2430 the respective request. Clients and authorization servers MAY 2431 utilize the parameters "scope" or "resource" as specified in this 2432 document and [RFC8707], respectively, to determine the resource 2433 server they want to access. 2435 Additionally, access tokens SHOULD be restricted to certain resources 2436 and actions on resource servers or resources. To put this into 2437 effect, the authorization server associates the access token with the 2438 respective resource and actions and every resource server is obliged 2439 to verify, for every request, whether the access token sent with that 2440 request was meant to be used for that particular action on the 2441 particular resource. If not, the resource server must refuse to 2442 serve the respective request. Clients and authorization servers MAY 2443 utilize the parameter "scope" and "authorization_details" as 2444 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2445 actions. 2447 7.2. Client Authentication 2449 The authorization server MUST only rely on client authentication if 2450 the process of issuance/registration and distribution of the 2451 underlying credentials ensures their confidentiality. 2453 When client authentication is not possible, the authorization server 2454 SHOULD employ other means to validate the client's identity - for 2455 example, by requiring the registration of the client redirect URI or 2456 enlisting the resource owner to confirm identity. A valid redirect 2457 URI is not sufficient to verify the client's identity when asking for 2458 resource owner authorization but can be used to prevent delivering 2459 credentials to a counterfeit client after obtaining resource owner 2460 authorization. 2462 The authorization server must consider the security implications of 2463 interacting with unauthenticated clients and take measures to limit 2464 the potential exposure of other credentials (e.g., refresh tokens) 2465 issued to such clients. 2467 The privileges an authorization server associates with a certain 2468 client identity MUST depend on the assessment of the overall process 2469 for client identification and client credential lifecycle management. 2470 For example, authentication of a dynamically registered client just 2471 ensures the authorization server it is talking to the same client 2472 again. In contrast, if there is a web application whose developer's 2473 identity was verified, who signed a contract and is issued a client 2474 secret that is only used in a secure backend service, the 2475 authorization server might allow this client to access more sensitive 2476 services or to use the client credentials grant type. 2478 7.2.1. Client Authentication of Native Apps 2480 Secrets that are statically included as part of an app distributed to 2481 multiple users should not be treated as confidential secrets, as one 2482 user may inspect their copy and learn the shared secret. For this 2483 reason, it is NOT RECOMMENDED for authorization servers to require 2484 client authentication of public native apps clients using a shared 2485 secret, as this serves little value beyond client identification 2486 which is already provided by the "client_id" request parameter. 2488 Authorization servers that still require a statically included shared 2489 secret for native app clients MUST treat the client as a public 2490 client (as defined in Section 2.1), and not accept the secret as 2491 proof of the client's identity. Without additional measures, such 2492 clients are subject to client impersonation (see Section 7.4.1). 2494 7.3. Registration of Native App Clients 2496 Except when using a mechanism like Dynamic Client Registration 2497 [RFC7591] to provision per-instance secrets, native apps are 2498 classified as public clients, as defined in Section 2.1; they MUST be 2499 registered with the authorization server as such. Authorization 2500 servers MUST record the client type in the client registration 2501 details in order to identify and process requests accordingly. 2503 Authorization servers MAY request the inclusion of other platform- 2504 specific information, such as the app package or bundle name, or 2505 other information that may be useful for verifying the calling app's 2506 identity on operating systems that support such functions. 2508 For private-use URI scheme-based redirect URIs, authorization servers 2509 SHOULD require that the URI scheme be based on a domain name that is 2510 under the control of the app. In addition to the collision-resistant 2511 properties, this can help to prove ownership in the event of a 2512 dispute where two apps claim the same private-use URI scheme (where 2513 one app is acting maliciously). For example, if two apps claimed 2514 "com.example.app", the owner of "example.com" could petition the app 2515 store operator to remove the counterfeit app. Such a petition is 2516 harder to prove if a generic URI scheme was used. 2518 7.4. Client Impersonation 2520 A malicious client can impersonate another client and obtain access 2521 to protected resources if the impersonated client fails to, or is 2522 unable to, keep its client credentials confidential. 2524 The authorization server SHOULD enforce explicit resource owner 2525 authentication and provide the resource owner with information about 2526 the client and the requested authorization scope and lifetime. It is 2527 up to the resource owner to review the information in the context of 2528 the current client and to authorize or deny the request. 2530 The authorization server SHOULD NOT process repeated authorization 2531 requests automatically (without active resource owner interaction) 2532 without authenticating the client or relying on other measures to 2533 ensure that the repeated request comes from the original client and 2534 not an impersonator. 2536 7.4.1. Impersonation of Native Apps 2538 As stated above, the authorization server SHOULD NOT process 2539 authorization requests automatically without user consent or 2540 interaction, except when the identity of the client can be assured. 2541 This includes the case where the user has previously approved an 2542 authorization request for a given client ID - unless the identity of 2543 the client can be proven, the request SHOULD be processed as if no 2544 previous request had been approved. 2546 Measures such as claimed "https" scheme redirects MAY be accepted by 2547 authorization servers as identity proof. Some operating systems may 2548 offer alternative platform-specific identity features that MAY be 2549 accepted, as appropriate. 2551 7.4.2. Access Token Privilege Restriction 2553 The client SHOULD request access tokens with the minimal scope 2554 necessary. The authorization server SHOULD take the client identity 2555 into account when choosing how to honor the requested scope and MAY 2556 issue an access token with less rights than requested. 2558 The privileges associated with an access token SHOULD be restricted 2559 to the minimum required for the particular application or use case. 2560 This prevents clients from exceeding the privileges authorized by the 2561 resource owner. It also prevents users from exceeding their 2562 privileges authorized by the respective security policy. Privilege 2563 restrictions also help to reduce the impact of access token leakage. 2565 In particular, access tokens SHOULD be restricted to certain resource 2566 servers (audience restriction), preferably to a single resource 2567 server. To put this into effect, the authorization server associates 2568 the access token with certain resource servers and every resource 2569 server is obliged to verify, for every request, whether the access 2570 token sent with that request was meant to be used for that particular 2571 resource server. If not, the resource server MUST refuse to serve 2572 the respective request. Clients and authorization servers MAY 2573 utilize the parameters "scope" or "resource" as specified in 2574 [RFC8707], respectively, to determine the resource server they want 2575 to access. 2577 7.4.3. Access Token Replay Prevention 2579 Additionally, access tokens SHOULD be restricted to certain resources 2580 and actions on resource servers or resources. To put this into 2581 effect, the authorization server associates the access token with the 2582 respective resource and actions and every resource server is obliged 2583 to verify, for every request, whether the access token sent with that 2584 request was meant to be used for that particular action on the 2585 particular resource. If not, the resource server must refuse to 2586 serve the respective request. Clients and authorization servers MAY 2587 utilize the parameter "scope" and "authorization_details" as 2588 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2589 actions. 2591 Authorization and resource servers SHOULD use mechanisms for sender- 2592 constrained access tokens to prevent token replay as described in 2593 (#pop_tokens). A sender-constrained access token scopes the 2594 applicability of an access token to a certain sender. This sender is 2595 obliged to demonstrate knowledge of a certain secret as prerequisite 2596 for the acceptance of that access token at the recipient (e.g., a 2597 resource server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2598 RECOMMENDED. 2600 7.5. Refresh Tokens 2602 Authorization servers MAY issue refresh tokens to clients. 2604 Refresh tokens MUST be kept confidential in transit and storage, and 2605 shared only among the authorization server and the client to whom the 2606 refresh tokens were issued. The authorization server MUST maintain 2607 the binding between a refresh token and the client to whom it was 2608 issued. Refresh tokens MUST only be transmitted using TLS as 2609 described in Section 1.5 with server authentication as defined by 2610 [RFC2818]. 2612 The authorization server MUST verify the binding between the refresh 2613 token and client identity whenever the client identity can be 2614 authenticated. When client authentication is not possible, the 2615 authorization server SHOULD issue sender-constrained refresh tokens 2616 or use refresh token rotation as described in (#refreshing-an-access- 2617 token). 2619 The authorization server MUST ensure that refresh tokens cannot be 2620 generated, modified, or guessed to produce valid refresh tokens by 2621 unauthorized parties. 2623 7.6. Client Impersonating Resource Owner 2625 Resource servers may make access control decisions based on the 2626 identity of the resource owner as communicated in the "sub" claim 2627 returned by the authorization server in a token introspection 2628 response [RFC7662] or other mechanisms. If a client is able to 2629 choose its own "client_id" during registration with the authorization 2630 server, then there is a risk that it can register with the same "sub" 2631 value as a privileged user. A subsequent access token obtained under 2632 the client credentials grant may be mistaken for an access token 2633 authorized by the privileged user if the resource server does not 2634 perform additional checks. 2636 Authorization servers SHOULD NOT allow clients to influence their 2637 "client_id" or "sub" value or any other claim if that can cause 2638 confusion with a genuine resource owner. Where this cannot be 2639 avoided, authorization servers MUST provide other means for the 2640 resource server to distinguish between access tokens authorized by a 2641 resource owner from access tokens authorized by the client itself. 2643 7.7. Protecting the Authorization Code Flow 2645 When comparing client redirect URIs against pre-registered URIs, 2646 authorization servers MUST utilize exact string matching. This 2647 measure contributes to the prevention of leakage of authorization 2648 codes and access tokens (see (#insufficient_uri_validation)). It can 2649 also help to detect mix-up attacks (see (#mix_up)). 2651 Clients MUST NOT expose URLs that forward the user's browser to 2652 arbitrary URIs obtained from a query parameter ("open redirector"). 2653 Open redirectors can enable exfiltration of authorization codes and 2654 access tokens, see (#open_redirector_on_client). 2656 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2657 context, CSRF refers to requests to the redirection endpoint that do 2658 not originate at the authorization server, but a malicious third 2659 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2660 have ensured that the authorization server supports the 2661 "code_challenge" parameter MAY rely the CSRF protection provided by 2662 that mechanism. In OpenID Connect flows, the "nonce" parameter 2663 provides CSRF protection. Otherwise, one-time use CSRF tokens 2664 carried in the "state" parameter that are securely bound to the user 2665 agent MUST be used for CSRF protection (see (#csrf_countermeasures)). 2667 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2668 process redirect responses of the authorization server they sent the 2669 respective request to and from the same user agent this authorization 2670 request was initiated with. Clients MUST store the authorization 2671 server they sent an authorization request to and bind this 2672 information to the user agent and check that the authorization 2673 response was received from the correct authorization server. Clients 2674 MUST ensure that the subsequent access token request, if applicable, 2675 is sent to the same authorization server. Clients SHOULD use 2676 distinct redirect URIs for each authorization server as a means to 2677 identify the authorization server a particular response came from. 2679 An AS that redirects a request potentially containing user 2680 credentials MUST avoid forwarding these user credentials accidentally 2681 (see Section 7.7.2 for details). 2683 7.7.1. Loopback Redirect Considerations in Native Apps 2685 Loopback interface redirect URIs use the "http" scheme (i.e., without 2686 Transport Layer Security (TLS)). This is acceptable for loopback 2687 interface redirect URIs as the HTTP request never leaves the device. 2689 Clients should open the network port only when starting the 2690 authorization request and close it once the response is returned. 2692 Clients should listen on the loopback network interface only, in 2693 order to avoid interference by other network actors. 2695 While redirect URIs using localhost (i.e., 2696 "http://localhost:{port}/{path}") function similarly to loopback IP 2697 redirects described in Section 8.3.3, the use of "localhost" is NOT 2698 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2699 rather than "localhost" avoids inadvertently listening on network 2700 interfaces other than the loopback interface. It is also less 2701 susceptible to client-side firewalls and misconfigured host name 2702 resolution on the user's device. 2704 7.7.2. HTTP 307 Redirect 2706 An AS which redirects a request that potentially contains user 2707 credentials MUST NOT use the HTTP 307 status code for redirection. 2708 If an HTTP redirection (and not, for example, JavaScript) is used for 2709 such a request, AS SHOULD use HTTP status code 303 "See Other". 2711 At the authorization endpoint, a typical protocol flow is that the AS 2712 prompts the user to enter their credentials in a form that is then 2713 submitted (using the HTTP POST method) back to the authorization 2714 server. The AS checks the credentials and, if successful, redirects 2715 the user agent to the client's redirect URI. 2717 If the status code 307 were used for redirection, the user agent 2718 would send the user credentials via HTTP POST to the client. 2720 This discloses the sensitive credentials to the client. If the 2721 relying party is malicious, it can use the credentials to impersonate 2722 the user at the AS. 2724 The behavior might be unexpected for developers, but is defined in 2725 [RFC7231], Section 6.4.7. This status code does not require the user 2726 agent to rewrite the POST request to a GET request and thereby drop 2727 the form data in the POST request body. 2729 In the HTTP standard [RFC7231], only the status code 303 2730 unambigiously enforces rewriting the HTTP POST request to an HTTP GET 2731 request. For all other status codes, including the popular 302, user 2732 agents can opt not to rewrite POST to GET requests and therefore to 2733 reveal the user credentials to the client. (In practice, however, 2734 most user agents will only show this behaviour for 307 redirects.) 2736 Therefore, the RECOMMENDED status code for HTTP redirects is 303. 2738 7.8. Authorization Codes 2740 Authorization codes MUST be short lived and single-use. If the 2741 authorization server observes multiple attempts to exchange an 2742 authorization code for an access token, the authorization server 2743 SHOULD attempt to revoke all refresh and access tokens already 2744 granted based on the compromised authorization code. 2746 If the client can be authenticated, the authorization servers MUST 2747 authenticate the client and ensure that the authorization code was 2748 issued to the same client. 2750 Clients MUST prevent injection (replay) of authorization codes into 2751 the authorization response by attackers. To this end, using 2752 "code_challenge" and "code_verifier" is REQUIRED for clients and 2753 authorization servers MUST enforce their use, unless both of the 2754 following criteria are met: 2756 * The client is a confidential client. 2758 * In the specific deployment and the specific request, there is 2759 reasonable assurance for authorization server that the client 2760 implements the OpenID Connect "nonce" mechanism properly. 2762 In this case, using and enforcing "code_challenge" and 2763 "code_verifier" is still RECOMMENDED. 2765 The "code_challenge" or OpenID Connect "nonce" value MUST be 2766 transaction-specific and securely bound to the client and the user 2767 agent in which the transaction was started. If a transaction leads 2768 to an error, fresh values for "code_challenge" or "nonce" MUST be 2769 chosen. 2771 Historic note: Although PKCE [RFC7636] was originally designed as a 2772 mechanism to protect native apps, this advice applies to all kinds of 2773 OAuth clients, including web applications and other confidential 2774 clients. 2776 Clients SHOULD use code challenge methods that do not expose the 2777 "code_verifier" in the authorization request. Otherwise, attackers 2778 that can read the authorization request (cf. Attacker A4 in 2779 (#secmodel)) can break the security provided by this mechanism. 2780 Currently, "S256" is the only such method. 2782 When an authorization code arrives at the token endpoint, the 2783 authorization server MUST do the following check: 2785 1. If there was a "code_challenge" in the authorization request for 2786 which this code was issued, there must be a "code_verifier" in 2787 the token request, and it MUST be verified according to the steps 2788 in Section 3.2.2. (This is no change from the current behavior 2789 in [RFC7636].) 2791 2. If there was no "code_challenge" in the authorization request, 2792 any request to the token endpoint containing a "code_verifier" 2793 MUST be rejected. 2795 Authorization servers MUST support the "code_challenge" and 2796 "code_verifier" parameters. 2798 Authorization servers MUST provide a way to detect their support for 2799 the "code_challenge" mechanism. To this end, they MUST either (a) 2800 publish the element "code_challenge_methods_supported" in their AS 2801 metadata ([RFC8414]) containing the supported 2802 "code_challenge_method"s (which can be used by the client to detect 2803 support) or (b) provide a deployment-specific way to ensure or 2804 determine support by the AS. 2806 7.9. Request Confidentiality 2808 Access tokens, refresh tokens, authorization codes, and client 2809 credentials MUST NOT be transmitted in the clear. 2811 The "state" and "scope" parameters SHOULD NOT include sensitive 2812 client or resource owner information in plain text, as they can be 2813 transmitted over insecure channels or stored insecurely. 2815 7.10. Ensuring Endpoint Authenticity 2817 In order to prevent man-in-the-middle attacks, the authorization 2818 server MUST require the use of TLS with server authentication as 2819 defined by [RFC2818] for any request sent to the authorization and 2820 token endpoints. The client MUST validate the authorization server's 2821 TLS certificate as defined by [RFC6125] and in accordance with its 2822 requirements for server identity authentication. 2824 7.11. Credentials-Guessing Attacks 2826 The authorization server MUST prevent attackers from guessing access 2827 tokens, authorization codes, refresh tokens, resource owner 2828 passwords, and client credentials. 2830 The probability of an attacker guessing generated tokens (and other 2831 credentials not intended for handling by end-users) MUST be less than 2832 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2834 The authorization server MUST utilize other means to protect 2835 credentials intended for end-user usage. 2837 7.12. Phishing Attacks 2839 Wide deployment of this and similar protocols may cause end-users to 2840 become inured to the practice of being redirected to websites where 2841 they are asked to enter their passwords. If end-users are not 2842 careful to verify the authenticity of these websites before entering 2843 their credentials, it will be possible for attackers to exploit this 2844 practice to steal resource owners' passwords. 2846 Service providers should attempt to educate end-users about the risks 2847 phishing attacks pose and should provide mechanisms that make it easy 2848 for end-users to confirm the authenticity of their sites. Client 2849 developers should consider the security implications of how they 2850 interact with the user agent (e.g., external, embedded), and the 2851 ability of the end-user to verify the authenticity of the 2852 authorization server. 2854 To reduce the risk of phishing attacks, the authorization servers 2855 MUST require the use of TLS on every endpoint used for end-user 2856 interaction. 2858 7.13. Fake External User-Agents in Native Apps 2860 The native app that is initiating the authorization request has a 2861 large degree of control over the user interface and can potentially 2862 present a fake external user agent, that is, an embedded user agent 2863 made to appear as an external user agent. 2865 When all good actors are using external user agents, the advantage is 2866 that it is possible for security experts to detect bad actors, as 2867 anyone faking an external user agent is provably bad. On the other 2868 hand, if good and bad actors alike are using embedded user agents, 2869 bad actors don't need to fake anything, making them harder to detect. 2870 Once a malicious app is detected, it may be possible to use this 2871 knowledge to blacklist the app's signature in malware scanning 2872 software, take removal action (in the case of apps distributed by app 2873 stores) and other steps to reduce the impact and spread of the 2874 malicious app. 2876 Authorization servers can also directly protect against fake external 2877 user agents by requiring an authentication factor only available to 2878 true external user agents. 2880 Users who are particularly concerned about their security when using 2881 in-app browser tabs may also take the additional step of opening the 2882 request in the full browser from the in-app browser tab and complete 2883 the authorization there, as most implementations of the in-app 2884 browser tab pattern offer such functionality. 2886 7.14. Malicious External User-Agents in Native Apps 2888 If a malicious app is able to configure itself as the default handler 2889 for "https" scheme URIs in the operating system, it will be able to 2890 intercept authorization requests that use the default browser and 2891 abuse this position of trust for malicious ends such as phishing the 2892 user. 2894 This attack is not confined to OAuth; a malicious app configured in 2895 this way would present a general and ongoing risk to the user beyond 2896 OAuth usage by native apps. Many operating systems mitigate this 2897 issue by requiring an explicit user action to change the default 2898 handler for "http" and "https" scheme URIs. 2900 7.15. Cross-Site Request Forgery 2902 An attacker might attempt to inject a request to the redirect URI of 2903 the legitimate client on the victim's device, e.g., to cause the 2904 client to access resources under the attacker's control. This is a 2905 variant of an attack known as Cross-Site Request Forgery (CSRF). 2907 The traditional countermeasure are CSRF tokens that are bound to the 2908 user agent and passed in the "state" parameter to the authorization 2909 server as described in [RFC6819]. The same protection is provided by 2910 the "code_verifier" parameter or the OpenID Connect "nonce" value. 2912 When using "code_verifier" instead of "state" or "nonce" for CSRF 2913 protection, it is important to note that: 2915 * Clients MUST ensure that the AS supports the 2916 "code_challenge_method" intended to be used by the client. If an 2917 authorization server does not support the requested method, 2918 "state" or "nonce" MUST be used for CSRF protection instead. 2920 * If "state" is used for carrying application state, and integrity 2921 of its contents is a concern, clients MUST protect "state" against 2922 tampering and swapping. This can be achieved by binding the 2923 contents of state to the browser session and/or signed/encrypted 2924 state values [I-D.bradley-oauth-jwt-encoded-state]. 2926 AS therefore MUST provide a way to detect their supported code 2927 challenge methods either via AS metadata according to [RFC8414] or 2928 provide a deployment-specific way to ensure or determine support. 2930 7.16. Clickjacking 2932 As described in Section 4.4.1.9 of [RFC6819], the authorization 2933 request is susceptible to clickjacking. An attacker can use this 2934 vector to obtain the user's authentication credentials, change the 2935 scope of access granted to the client, and potentially access the 2936 user's resources. 2938 Authorization servers MUST prevent clickjacking attacks. Multiple 2939 countermeasures are described in [RFC6819], including the use of the 2940 X-Frame-Options HTTP response header field and frame-busting 2941 JavaScript. In addition to those, authorization servers SHOULD also 2942 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2944 To be effective, CSP must be used on the authorization endpoint and, 2945 if applicable, other endpoints used to authenticate the user and 2946 authorize the client (e.g., the device authorization endpoint, login 2947 pages, error pages, etc.). This prevents framing by unauthorized 2948 origins in user agents that support CSP. The client MAY permit being 2949 framed by some other origin than the one used in its redirection 2950 endpoint. For this reason, authorization servers SHOULD allow 2951 administrators to configure allowed origins for particular clients 2952 and/or for clients to register these dynamically. 2954 Using CSP allows authorization servers to specify multiple origins in 2955 a single response header field and to constrain these using flexible 2956 patterns (see [CSP-2] for details). Level 2 of this standard 2957 provides a robust mechanism for protecting against clickjacking by 2958 using policies that restrict the origin of frames (using "frame- 2959 ancestors") together with those that restrict the sources of scripts 2960 allowed to execute on an HTML page (by using "script-src"). A non- 2961 normative example of such a policy is shown in the following listing: 2963 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 2964 https://ext.example.org:8000 Content-Security-Policy: script-src 2965 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 2967 Because some user agents do not support [CSP-2], this technique 2968 SHOULD be combined with others, including those described in 2969 [RFC6819], unless such legacy user agents are explicitly unsupported 2970 by the authorization server. Even in such cases, additional 2971 countermeasures SHOULD still be employed. 2973 7.17. Code Injection and Input Validation 2975 A code injection attack occurs when an input or otherwise external 2976 variable is used by an application unsanitized and causes 2977 modification to the application logic. This may allow an attacker to 2978 gain access to the application device or its data, cause denial of 2979 service, or introduce a wide range of malicious side-effects. 2981 The authorization server and client MUST sanitize (and validate when 2982 possible) any value received - in particular, the value of the 2983 "state" and "redirect_uri" parameters. 2985 7.18. Open Redirectors 2987 The following attacks can occur when an AS or client has an open 2988 redirector. An open redirector is an endpoint that forwards a user's 2989 browser to an arbitrary URI obtained from a query parameter. 2991 7.18.1. Client as Open Redirector 2993 Clients MUST NOT expose open redirectors. Attackers may use open 2994 redirectors to produce URLs pointing to the client and utilize them 2995 to exfiltrate authorization codes and access tokens, as described in 2996 (#redir_uri_open_redir). Another abuse case is to produce URLs that 2997 appear to point to the client. This might trick users into trusting 2998 the URL and follow it in their browser. This can be abused for 2999 phishing. 3001 In order to prevent open redirection, clients should only redirect if 3002 the target URLs are whitelisted or if the origin and integrity of a 3003 request can be authenticated. Countermeasures against open 3004 redirection are described by OWASP [owasp_redir]. 3006 7.18.2. Authorization Server as Open Redirector 3008 Just as with clients, attackers could try to utilize a user's trust 3009 in the authorization server (and its URL in particular) for 3010 performing phishing attacks. OAuth authorization servers regularly 3011 redirect users to other web sites (the clients), but must do so in a 3012 safe way. 3014 Section 4.1.2.1 already prevents open redirects by stating that the 3015 AS MUST NOT automatically redirect the user agent in case of an 3016 invalid combination of "client_id" and "redirect_uri". 3018 However, an attacker could also utilize a correctly registered 3019 redirect URI to perform phishing attacks. The attacker could, for 3020 example, register a client via dynamic client registration [RFC7591] 3021 and intentionally send an erroneous authorization request, e.g., by 3022 using an invalid scope value, thus instructing the AS to redirect the 3023 user agent to its phishing site. 3025 The AS MUST take precautions to prevent this threat. Based on its 3026 risk assessment, the AS needs to decide whether it can trust the 3027 redirect URI and SHOULD only automatically redirect the user agent if 3028 it trusts the redirect URI. If the URI is not trusted, the AS MAY 3029 inform the user and rely on the user to make the correct decision. 3031 7.19. Authorization Server Mix-Up Mitigation in Native Apps 3033 (TODO: merge this with the regular mix-up section when it is brought 3034 in) 3036 To protect against a compromised or malicious authorization server 3037 attacking another authorization server used by the same app, it is 3038 REQUIRED that a unique redirect URI is used for each authorization 3039 server used by the app (for example, by varying the path component), 3040 and that authorization responses are rejected if the redirect URI 3041 they were received on doesn't match the redirect URI in an outgoing 3042 authorization request. 3044 The native app MUST store the redirect URI used in the authorization 3045 request with the authorization session data (i.e., along with "state" 3046 and other related data) and MUST verify that the URI on which the 3047 authorization response was received exactly matches it. 3049 The requirement of Section 7.3, specifically that authorization 3050 servers reject requests with URIs that don't match what was 3051 registered, is also required to prevent such attacks. 3053 7.20. Embedded User Agents in Native Apps 3055 Embedded user agents are a technically possible method for 3056 authorizing native apps. These embedded user agents are unsafe for 3057 use by third parties to the authorization server by definition, as 3058 the app that hosts the embedded user agent can access the user's full 3059 authentication credential, not just the OAuth authorization grant 3060 that was intended for the app. 3062 In typical web-view-based implementations of embedded user agents, 3063 the host application can record every keystroke entered in the login 3064 form to capture usernames and passwords, automatically submit forms 3065 to bypass user consent, and copy session cookies and use them to 3066 perform authenticated actions as the user. 3068 Even when used by trusted apps belonging to the same party as the 3069 authorization server, embedded user agents violate the principle of 3070 least privilege by having access to more powerful credentials than 3071 they need, potentially increasing the attack surface. 3073 Encouraging users to enter credentials in an embedded user agent 3074 without the usual address bar and visible certificate validation 3075 features that browsers have makes it impossible for the user to know 3076 if they are signing in to the legitimate site; even when they are, it 3077 trains them that it's OK to enter credentials without validating the 3078 site first. 3080 Aside from the security concerns, embedded user agents do not share 3081 the authentication state with other apps or the browser, requiring 3082 the user to log in for every authorization request, which is often 3083 considered an inferior user experience. 3085 7.21. Other Recommendations 3087 Authorization servers SHOULD NOT allow clients to influence their 3088 "client_id" or "sub" value or any other claim if that can cause 3089 confusion with a genuine resource owner (see 3090 (#client_impersonating)). 3092 8. Native Applications 3094 Native applications are clients installed and executed on the device 3095 used by the resource owner (i.e., desktop application, native mobile 3096 application). Native applications require special consideration 3097 related to security, platform capabilities, and overall end-user 3098 experience. 3100 The authorization endpoint requires interaction between the client 3101 and the resource owner's user agent. The best current practice is to 3102 perform the OAuth authorization request in an external user agent 3103 (typically the browser) rather than an embedded user agent (such as 3104 one implemented with web-views). 3106 The native application can capture the response from the 3107 authorization server using a redirect URI with a scheme registered 3108 with the operating system to invoke the client as the handler, manual 3109 copy-and-paste of the credentials, running a local web server, 3110 installing a user agent extension, or by providing a redirect URI 3111 identifying a server-hosted resource under the client's control, 3112 which in turn makes the response available to the native application. 3114 Previously, it was common for native apps to use embedded user agents 3115 (commonly implemented with web-views) for OAuth authorization 3116 requests. That approach has many drawbacks, including the host app 3117 being able to copy user credentials and cookies as well as the user 3118 needing to authenticate from scratch in each app. See Section 7.20 3119 for a deeper analysis of the drawbacks of using embedded user agents 3120 for OAuth. 3122 Native app authorization requests that use the browser are more 3123 secure and can take advantage of the user's authentication state. 3124 Being able to use the existing authentication session in the browser 3125 enables single sign-on, as users don't need to authenticate to the 3126 authorization server each time they use a new app (unless required by 3127 the authorization server policy). 3129 Supporting authorization flows between a native app and the browser 3130 is possible without changing the OAuth protocol itself, as the OAuth 3131 authorization request and response are already defined in terms of 3132 URIs. This encompasses URIs that can be used for inter-app 3133 communication. Some OAuth server implementations that assume all 3134 clients are confidential web clients will need to add an 3135 understanding of public native app clients and the types of redirect 3136 URIs they use to support this best practice. 3138 8.1. Using Inter-App URI Communication for OAuth in Native Apps 3140 Just as URIs are used for OAuth on the web to initiate the 3141 authorization request and return the authorization response to the 3142 requesting website, URIs can be used by native apps to initiate the 3143 authorization request in the device's browser and return the response 3144 to the requesting native app. 3146 By adopting the same methods used on the web for OAuth, benefits seen 3147 in the web context like the usability of a single sign-on session and 3148 the security of a separate authentication context are likewise gained 3149 in the native app context. Reusing the same approach also reduces 3150 the implementation complexity and increases interoperability by 3151 relying on standards-based web flows that are not specific to a 3152 particular platform. 3154 Native apps MUST use an external user agent to perform OAuth 3155 authorization requests. This is achieved by opening the 3156 authorization request in the browser (detailed in Section 8.2) and 3157 using a redirect URI that will return the authorization response back 3158 to the native app (defined in Section 8.3). 3160 8.2. Initiating the Authorization Request from a Native App 3162 Native apps needing user authorization create an authorization 3163 request URI with the authorization code grant type per Section 4.1 3164 using a redirect URI capable of being received by the native app. 3166 The function of the redirect URI for a native app authorization 3167 request is similar to that of a web-based authorization request. 3168 Rather than returning the authorization response to the OAuth 3169 client's server, the redirect URI used by a native app returns the 3170 response to the app. Several options for a redirect URI that will 3171 return the authorization response to the native app in different 3172 platforms are documented in Section 8.3. Any redirect URI that 3173 allows the app to receive the URI and inspect its parameters is 3174 viable. 3176 After constructing the authorization request URI, the app uses 3177 platform-specific APIs to open the URI in an external user agent. 3178 Typically, the external user agent used is the default browser, that 3179 is, the application configured for handling "http" and "https" scheme 3180 URIs on the system; however, different browser selection criteria and 3181 other categories of external user agents MAY be used. 3183 This best practice focuses on the browser as the RECOMMENDED external 3184 user agent for native apps. An external user agent designed 3185 specifically for user authorization and capable of processing 3186 authorization requests and responses like a browser MAY also be used. 3187 Other external user agents, such as a native app provided by the 3188 authorization server may meet the criteria set out in this best 3189 practice, including using the same redirect URI properties, but their 3190 use is out of scope for this specification. 3192 Some platforms support a browser feature known as "in-app browser 3193 tabs", where an app can present a tab of the browser within the app 3194 context without switching apps, but still retain key benefits of the 3195 browser such as a shared authentication state and security context. 3196 On platforms where they are supported, it is RECOMMENDED, for 3197 usability reasons, that apps use in-app browser tabs for the 3198 authorization request. 3200 8.3. Receiving the Authorization Response in a Native App 3202 There are several redirect URI options available to native apps for 3203 receiving the authorization response from the browser, the 3204 availability and user experience of which varies by platform. 3206 To fully support native apps, authorization servers MUST offer at 3207 least the three redirect URI options described in the following 3208 subsections to native apps. Native apps MAY use whichever redirect 3209 option suits their needs best, taking into account platform-specific 3210 implementation details. 3212 8.3.1. Private-Use URI Scheme Redirection 3214 Many mobile and desktop computing platforms support inter-app 3215 communication via URIs by allowing apps to register private-use URI 3216 schemes (sometimes colloquially referred to as "custom URL schemes") 3217 like "com.example.app". When the browser or another app attempts to 3218 load a URI with a private-use URI scheme, the app that registered it 3219 is launched to handle the request. 3221 To perform an authorization request with a private-use URI scheme 3222 redirect, the native app launches the browser with a standard 3223 authorization request, but one where the redirect URI utilizes a 3224 private-use URI scheme it registered with the operating system. 3226 When choosing a URI scheme to associate with the app, apps MUST use a 3227 URI scheme based on a domain name under their control, expressed in 3228 reverse order, as recommended by Section 3.8 of [RFC7595] for 3229 private-use URI schemes. 3231 For example, an app that controls the domain name "app.example.com" 3232 can use "com.example.app" as their scheme. Some authorization 3233 servers assign client identifiers based on domain names, for example, 3234 "client1234.usercontent.example.net", which can also be used as the 3235 domain name for the scheme when reversed in the same manner. A 3236 scheme such as "myapp", however, would not meet this requirement, as 3237 it is not based on a domain name. 3239 When there are multiple apps by the same publisher, care must be 3240 taken so that each scheme is unique within that group. On platforms 3241 that use app identifiers based on reverse-order domain names, those 3242 identifiers can be reused as the private-use URI scheme for the OAuth 3243 redirect to help avoid this problem. 3245 Following the requirements of Section 3.2 of [RFC3986], as there is 3246 no naming authority for private-use URI scheme redirects, only a 3247 single slash ("/") appears after the scheme component. A complete 3248 example of a redirect URI utilizing a private-use URI scheme is: 3250 com.example.app:/oauth2redirect/example-provider 3251 When the authorization server completes the request, it redirects to 3252 the client's redirect URI as it would normally. As the redirect URI 3253 uses a private-use URI scheme, it results in the operating system 3254 launching the native app, passing in the URI as a launch parameter. 3255 Then, the native app uses normal processing for the authorization 3256 response. 3258 8.3.2. Claimed "https" Scheme URI Redirection 3260 Some operating systems allow apps to claim "https" scheme [RFC7230] 3261 URIs in the domains they control. When the browser encounters a 3262 claimed URI, instead of the page being loaded in the browser, the 3263 native app is launched with the URI supplied as a launch parameter. 3265 Such URIs can be used as redirect URIs by native apps. They are 3266 indistinguishable to the authorization server from a regular web- 3267 based client redirect URI. An example is: 3269 https://app.example.com/oauth2redirect/example-provider 3271 As the redirect URI alone is not enough to distinguish public native 3272 app clients from confidential web clients, it is REQUIRED in 3273 Section 7.3 that the client type be recorded during client 3274 registration to enable the server to determine the client type and 3275 act accordingly. 3277 App-claimed "https" scheme redirect URIs have some advantages 3278 compared to other native app redirect options in that the identity of 3279 the destination app is guaranteed to the authorization server by the 3280 operating system. For this reason, native apps SHOULD use them over 3281 the other options where possible. 3283 8.3.3. Loopback Interface Redirection 3285 Native apps that are able to open a port on the loopback network 3286 interface without needing special permissions (typically, those on 3287 desktop operating systems) can use the loopback interface to receive 3288 the OAuth redirect. 3290 Loopback redirect URIs use the "http" scheme and are constructed with 3291 the loopback IP literal and whatever port the client is listening on. 3293 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3294 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3295 IPv4 loopback interface with a randomly assigned port: 3297 http://127.0.0.1:51004/oauth2redirect/example-provider 3298 An example redirect using the IPv6 loopback interface with a randomly 3299 assigned port: 3301 http://[::1]:61023/oauth2redirect/example-provider 3303 The authorization server MUST allow any port to be specified at the 3304 time of the request for loopback IP redirect URIs, to accommodate 3305 clients that obtain an available ephemeral port from the operating 3306 system at the time of the request. 3308 Clients SHOULD NOT assume that the device supports a particular 3309 version of the Internet Protocol. It is RECOMMENDED that clients 3310 attempt to bind to the loopback interface using both IPv4 and IPv6 3311 and use whichever is available. 3313 9. Browser-Based Apps 3315 Browser-based apps are are clients that run in a web browser, 3316 typically written in JavaScript, also known as "single-page apps". 3317 These types of apps have particular security considerations similar 3318 to native apps. 3320 TODO: Bring in the normative text of the browser-based apps BCP when 3321 it is finalized. 3323 10. Differences from OAuth 2.0 3325 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3326 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3327 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3328 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3329 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3330 ([RFC6750]). 3332 Where a later draft updates or obsoletes functionality found in the 3333 original [RFC6749], that functionality in this draft is updated with 3334 the normative changes described in a later draft, or removed 3335 entirely. 3337 A non-normative list of changes from OAuth 2.0 is listed below: 3339 * The authorization code grant is extended with the functionality 3340 from PKCE ([RFC7636]) such that the default method of using the 3341 authorization code grant according to this specification requires 3342 the addition of the PKCE parameters 3344 * Redirect URIs must be compared using exact string matching as per 3345 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3347 * The Implicit grant ("response_type=token") is omitted from this 3348 specification as per Section 2.1.2 of 3349 [I-D.ietf-oauth-security-topics] 3351 * The Resource Owner Password Credentials grant is omitted from this 3352 specification as per Section 2.4 of 3353 [I-D.ietf-oauth-security-topics] 3355 * Bearer token usage omits the use of bearer tokens in the query 3356 string of URIs as per Section 4.3.2 of 3357 [I-D.ietf-oauth-security-topics] 3359 * Refresh tokens should either be sender-constrained or one-time use 3360 as per Section 4.12.2 of [I-D.ietf-oauth-security-topics] 3362 11. IANA Considerations 3364 This document does not require any IANA actions. 3366 All referenced registries are defined by [RFC6749] and related 3367 documents that this work is based upon. No changes to those 3368 registries are required by this specification. 3370 12. References 3372 12.1. Normative References 3374 [BCP195] Saint-Andre, P., "Recommendations for Secure Use of 3375 Transport Layer Security (TLS)", 2015. 3377 [I-D.ietf-oauth-security-topics] 3378 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3379 "OAuth 2.0 Security Best Current Practice", Work in 3380 Progress, Internet-Draft, draft-ietf-oauth-security- 3381 topics-18, 13 April 2021, 3382 . 3385 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3386 Requirement Levels", BCP 14, RFC 2119, 3387 DOI 10.17487/RFC2119, March 1997, 3388 . 3390 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3391 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3392 Authentication: Basic and Digest Access Authentication", 3393 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3394 . 3396 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3397 DOI 10.17487/RFC2818, May 2000, 3398 . 3400 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3401 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3402 2003, . 3404 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3405 Resource Identifier (URI): Generic Syntax", STD 66, 3406 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3407 . 3409 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3410 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3411 . 3413 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3414 Specifications: ABNF", STD 68, RFC 5234, 3415 DOI 10.17487/RFC5234, January 2008, 3416 . 3418 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3419 Housley, R., and W. Polk, "Internet X.509 Public Key 3420 Infrastructure Certificate and Certificate Revocation List 3421 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3422 . 3424 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3425 Verification of Domain-Based Application Service Identity 3426 within Internet Public Key Infrastructure Using X.509 3427 (PKIX) Certificates in the Context of Transport Layer 3428 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3429 2011, . 3431 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3432 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3433 . 3435 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3436 Framework: Bearer Token Usage", RFC 6750, 3437 DOI 10.17487/RFC6750, October 2012, 3438 . 3440 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3441 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3442 2014, . 3444 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3445 Protocol (HTTP/1.1): Message Syntax and Routing", 3446 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3447 . 3449 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3450 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3451 DOI 10.17487/RFC7231, June 2014, 3452 . 3454 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3455 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3456 RFC 7234, DOI 10.17487/RFC7234, June 2014, 3457 . 3459 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3460 Protocol (HTTP/1.1): Authentication", RFC 7235, 3461 DOI 10.17487/RFC7235, June 2014, 3462 . 3464 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3465 and Registration Procedures for URI Schemes", BCP 35, 3466 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3467 . 3469 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3470 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3471 May 2017, . 3473 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3474 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3475 . 3477 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3478 Interchange Format", STD 90, RFC 8259, 3479 DOI 10.17487/RFC8259, December 2017, 3480 . 3482 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3483 Standard Code for Information Interchange, ANSI X3.4", 3484 1986. 3486 [W3C.REC-html401-19991224] 3487 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3488 Specification", World Wide Web Consortium Recommendation 3489 REC-html401-19991224, 24 December 1999, 3490 . 3492 [W3C.REC-xml-20081126] 3493 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3494 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3495 Edition)", World Wide Web Consortium Recommendation REC- 3496 xml-20081126, 26 November 2008, 3497 . 3499 12.2. Informative References 3501 [CSP-2] "Content Security Policy Level 2", December 2016, 3502 . 3504 [I-D.bradley-oauth-jwt-encoded-state] 3505 Bradley, J., Lodderstedt, D. T., and H. Zandbelt, 3506 "Encoding claims in the OAuth 2 state parameter using a 3507 JWT", Work in Progress, Internet-Draft, draft-bradley- 3508 oauth-jwt-encoded-state-09, 4 November 2018, 3509 . 3512 [I-D.ietf-oauth-access-token-jwt] 3513 Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 3514 Access Tokens", Work in Progress, Internet-Draft, draft- 3515 ietf-oauth-access-token-jwt-13, 25 May 2021, 3516 . 3519 [I-D.ietf-oauth-browser-based-apps] 3520 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3521 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3522 browser-based-apps-08, 17 May 2021, 3523 . 3526 [I-D.ietf-oauth-dpop] 3527 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 3528 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 3529 of-Possession at the Application Layer (DPoP)", Work in 3530 Progress, Internet-Draft, draft-ietf-oauth-dpop-03, 7 3531 April 2021, . 3534 [I-D.ietf-oauth-par] 3535 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 3536 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 3537 Work in Progress, Internet-Draft, draft-ietf-oauth-par-10, 3538 29 July 2021, . 3541 [I-D.ietf-oauth-rar] 3542 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3543 Rich Authorization Requests", Work in Progress, Internet- 3544 Draft, draft-ietf-oauth-rar-05, 15 May 2021, 3545 . 3548 [I-D.ietf-oauth-token-binding] 3549 Jones, M. B., Campbell, B., Bradley, J., and W. Denniss, 3550 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3551 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3552 . 3555 [NIST800-63] 3556 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3557 Gupta, S., and E. Nabbus, "NIST Special Publication 3558 800-63-1, INFORMATION SECURITY", December 2011, 3559 . 3561 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3562 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3563 and B. Boyer, "Online Multimedia Authorization Protocol: 3564 An Industry Standard for Authorized Access to Internet 3565 Multimedia Resources", April 2012, 3566 . 3568 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3569 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3570 . 3572 [OpenID.Messages] 3573 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3574 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3575 June 2012, . 3578 [owasp_redir] 3579 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3580 Forwards", 2020, 3581 . 3584 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3585 DOI 10.17487/RFC6265, April 2011, 3586 . 3588 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3589 Threat Model and Security Considerations", RFC 6819, 3590 DOI 10.17487/RFC6819, January 2013, 3591 . 3593 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 3594 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 3595 August 2013, . 3597 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3598 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3599 . 3601 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3602 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3603 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3604 . 3606 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 3607 "OAuth 2.0 Dynamic Client Registration Management 3608 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 3609 . 3611 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3612 for Code Exchange by OAuth Public Clients", RFC 7636, 3613 DOI 10.17487/RFC7636, September 2015, 3614 . 3616 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 3617 RFC 7662, DOI 10.17487/RFC7662, October 2015, 3618 . 3620 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3621 Authorization Server Metadata", RFC 8414, 3622 DOI 10.17487/RFC8414, June 2018, 3623 . 3625 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 3626 "OAuth 2.0 Device Authorization Grant", RFC 8628, 3627 DOI 10.17487/RFC8628, August 2019, 3628 . 3630 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3631 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3632 and Certificate-Bound Access Tokens", RFC 8705, 3633 DOI 10.17487/RFC8705, February 2020, 3634 . 3636 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3637 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3638 February 2020, . 3640 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3642 This section provides Augmented Backus-Naur Form (ABNF) syntax 3643 descriptions for the elements defined in this specification using the 3644 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3645 code points [W3C.REC-xml-20081126]; these characters are typically 3646 encoded in UTF-8. Elements are presented in the order first defined. 3648 Some of the definitions that follow use the "URI-reference" 3649 definition from [RFC3986]. 3651 Some of the definitions that follow use these common definitions: 3653 VSCHAR = %x20-7E 3654 NQCHAR = %x21 / %x23-5B / %x5D-7E 3655 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3656 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3657 %xE000-FFFD / %x10000-10FFFF 3659 (The UNICODECHARNOCRLF definition is based upon the Char definition 3660 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3661 Return and Linefeed characters.) 3663 A.1. "client_id" Syntax 3665 The "client_id" element is defined in Section 2.4.1: 3667 client-id = *VSCHAR 3669 A.2. "client_secret" Syntax 3671 The "client_secret" element is defined in Section 2.4.1: 3673 client-secret = *VSCHAR 3675 A.3. "response_type" Syntax 3677 The "response_type" element is defined in Section 4.1.1 and 3678 Section 6.4: 3680 response-type = response-name *( SP response-name ) 3681 response-name = 1*response-char 3682 response-char = "_" / DIGIT / ALPHA 3684 A.4. "scope" Syntax 3686 The "scope" element is defined in Section 3.2.2.1: 3688 scope = scope-token *( SP scope-token ) 3689 scope-token = 1*NQCHAR 3691 A.5. "state" Syntax 3693 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3694 Section 4.1.2.1: 3696 state = 1*VSCHAR 3698 A.6. "redirect_uri" Syntax 3700 The "redirect_uri" element is defined in Section 4.1.1, and 3701 Section 4.1.3: 3703 redirect-uri = URI-reference 3705 A.7. "error" Syntax 3707 The "error" element is defined in Sections Section 4.1.2.1, 3708 Section 3.2.3.1, 7.2, and 8.5: 3710 error = 1*NQSCHAR 3712 A.8. "error_description" Syntax 3714 The "error_description" element is defined in Sections 3715 Section 4.1.2.1, Section 3.2.3.1, and Section 5.3: 3717 error-description = 1*NQSCHAR 3719 A.9. "error_uri" Syntax 3721 The "error_uri" element is defined in Sections Section 4.1.2.1, 3722 Section 3.2.3.1, and 7.2: 3724 error-uri = URI-reference 3726 A.10. "grant_type" Syntax 3728 The "grant_type" element is defined in Section Section 3.2.2: 3730 grant-type = grant-name / URI-reference 3731 grant-name = 1*name-char 3732 name-char = "-" / "." / "_" / DIGIT / ALPHA 3734 A.11. "code" Syntax 3736 The "code" element is defined in Section 4.1.3: 3738 code = 1*VSCHAR 3740 A.12. "access_token" Syntax 3742 The "access_token" element is defined in Section 3.2.3: 3744 access-token = 1*VSCHAR 3746 A.13. "token_type" Syntax 3748 The "token_type" element is defined in Section 3.2.3, and 3749 Section 6.1: 3751 token-type = type-name / URI-reference 3752 type-name = 1*name-char 3753 name-char = "-" / "." / "_" / DIGIT / ALPHA 3755 A.14. "expires_in" Syntax 3757 The "expires_in" element is defined in Section 3.2.3: 3759 expires-in = 1*DIGIT 3761 A.15. "refresh_token" Syntax 3763 The "refresh_token" element is defined in Section 3.2.3 and 3764 Section 4.3: 3766 refresh-token = 1*VSCHAR 3768 A.16. Endpoint Parameter Syntax 3770 The syntax for new endpoint parameters is defined in Section 6.2: 3772 param-name = 1*name-char 3773 name-char = "-" / "." / "_" / DIGIT / ALPHA 3775 A.17. "code_verifier" Syntax 3777 ABNF for "code_verifier" is as follows. 3779 code-verifier = 43*128unreserved 3780 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3781 ALPHA = %x41-5A / %x61-7A 3782 DIGIT = %x30-39 3784 A.18. "code_challenge" Syntax 3786 ABNF for "code_challenge" is as follows. 3788 code-challenge = 43*128unreserved 3789 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3790 ALPHA = %x41-5A / %x61-7A 3791 DIGIT = %x30-39 3793 Appendix B. Use of application/x-www-form-urlencoded Media Type 3795 At the time of publication of this specification, the "application/x- 3796 www-form-urlencoded" media type was defined in Section 17.13.4 of 3797 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 3798 Types registry (http://www.iana.org/assignments/media-types 3799 (http://www.iana.org/assignments/media-types)). Furthermore, that 3800 definition is incomplete, as it does not consider non-US-ASCII 3801 characters. 3803 To address this shortcoming when generating payloads using this media 3804 type, names and values MUST be encoded using the UTF-8 character 3805 encoding scheme [RFC3629] first; the resulting octet sequence then 3806 needs to be further encoded using the escaping rules defined in 3807 [W3C.REC-html401-19991224]. 3809 When parsing data from a payload using this media type, the names and 3810 values resulting from reversing the name/value encoding consequently 3811 need to be treated as octet sequences, to be decoded using the UTF-8 3812 character encoding scheme. 3814 For example, the value consisting of the six Unicode code points (1) 3815 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3816 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3817 SIGN) would be encoded into the octet sequence below (using 3818 hexadecimal notation): 3820 20 25 26 2B C2 A3 E2 82 AC 3822 and then represented in the payload as: 3824 +%25%26%2B%C2%A3%E2%82%AC 3826 Appendix C. Extensions 3828 Below is a list of well-established extensions at the time of 3829 publication: 3831 * [RFC8628]: OAuth 2.0 Device Authorization Grant 3833 - The Device Authorization Grant (formerly known as the Device 3834 Flow) is an extension that enables devices with no browser or 3835 limited input capability to obtain an access token. This is 3836 commonly used by smart TV apps, or devices like hardware video 3837 encoders that can stream video to a streaming video service. 3839 * [RFC8414]: Authorization Server Metadata 3841 - Authorization Server Metadata (also known as OAuth Discovery) 3842 defines an endpoint clients can use to look up the information 3843 needed to interact with a particular OAuth server, such as the 3844 location of the authorization and token endpoints and the 3845 supported grant types. 3847 * [RFC8707]: Resource Indicators 3849 - Provides a way for the client to explicitly signal to the 3850 authorization server where it intends to use the access token 3851 it is requesting. 3853 * [RFC7591]: Dynamic Client Registration 3855 - Dynamic Client Registration provides a mechanism for 3856 programmatically registering clients with an authorization 3857 server. 3859 * [RFC7592]: Dynamic Client Management 3861 - Dynamic Client Management provides a mechanism for updating 3862 dynamically registered client information. 3864 * [I-D.ietf-oauth-access-token-jwt]: JSON Web Token (JWT) Profile 3865 for OAuth 2.0 Access Tokens 3867 - This specification defines a profile for issuing OAuth access 3868 tokens in JSON Web Token (JWT) format. 3870 * [RFC8705]: Mutual TLS 3871 - Mutual TLS describes a mechanism of binding access tokens and 3872 refresh tokens to the clients they were issued to, as well as a 3873 client authentication mechanism, via TLS certificate 3874 authentication. 3876 * [RFC7662]: Token Introspection 3878 - The Token Introspection extension defines a mechanism for 3879 resource servers to obtain information about access tokens. 3881 * [RFC7009]: Token Revocation 3883 - The Token Revocation extension defines a mechanism for clients 3884 to indicate to the authorization server that an access token is 3885 no longer needed. 3887 * [I-D.ietf-oauth-par]: Pushed Authorization Requests 3889 - The Pushed Authorization Requests extension describes a 3890 technique of initiating an OAuth flow from the back channel, 3891 providing better security and more flexibility for building 3892 complex authorization requests. 3894 * [I-D.ietf-oauth-rar]: Rich Authorization Requests 3896 - Rich Authorization Requests specifies a new parameter 3897 "authorization_details" that is used to carry fine-grained 3898 authorization data in the OAuth authorization request. 3900 Appendix D. Acknowledgements 3902 TBD 3904 Appendix E. Document History 3906 [[ To be removed from the final specification ]] 3908 -03 3910 * refactored structure 3912 -02 3914 -01 3916 -00 3918 * initial revision 3920 Authors' Addresses 3922 Dick Hardt 3923 SignIn.Org 3925 Email: dick.hardt@gmail.com 3927 Aaron Parecki 3928 Okta 3930 Email: aaron@parecki.com 3931 URI: https://aaronparecki.com 3933 Torsten Lodderstedt 3934 yes.com 3936 Email: torsten@lodderstedt.net