idnits 2.17.1 draft-ietf-oauth-v2-1-05.txt: -(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 4 instances 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 (7 March 2022) is 780 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 1441, but not defined == Missing Reference: '0-9' is mentioned on line 1441, but not defined == Unused Reference: 'RFC5280' is defined on line 3379, but no explicit reference was found in the text == Unused Reference: 'RFC6125' is defined on line 3385, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-19 ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-17) exists of draft-ietf-oauth-browser-based-apps-08 == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-06 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-10 Summary: 9 errors (**), 0 flaws (~~), 11 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group D. Hardt 3 Internet-Draft Hellō 4 Intended status: Standards Track A. Parecki 5 Expires: 8 September 2022 Okta 6 T. Lodderstedt 7 yes.com 8 7 March 2022 10 The OAuth 2.1 Authorization Framework 11 draft-ietf-oauth-v2-1-05 13 Abstract 15 The OAuth 2.1 authorization framework enables a third-party 16 application to obtain limited access to a protected resource, either 17 on behalf of a resource owner by orchestrating an approval 18 interaction between the resource owner and an authorization service, 19 or by allowing the third-party application to obtain access on its 20 own 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 8 September 2022. 40 Copyright Notice 42 Copyright (c) 2022 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 Revised BSD License text as 51 described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Revised 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. Communication security . . . . . . . . . . . . . . . . . 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. Registration Requirements . . . . . . . . . . . . . . 17 74 2.3.2. Multiple Redirect URIs . . . . . . . . . . . . . . . 17 75 2.3.3. Preventing CSRF Attacks . . . . . . . . . . . . . . . 18 76 2.3.4. Preventing Mix-Up Attacks . . . . . . . . . . . . . . 18 77 2.3.5. Invalid Endpoint . . . . . . . . . . . . . . . . . . 18 78 2.3.6. Endpoint Content . . . . . . . . . . . . . . . . . . 18 79 2.4. Client Authentication . . . . . . . . . . . . . . . . . . 19 80 2.4.1. Client Secret . . . . . . . . . . . . . . . . . . . . 20 81 2.4.2. Other Authentication Methods . . . . . . . . . . . . 21 82 2.5. Unregistered Clients . . . . . . . . . . . . . . . . . . 21 83 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 21 84 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 22 85 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 22 86 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 23 87 3.2.2. Token Request . . . . . . . . . . . . . . . . . . . . 23 88 3.2.3. Token Response . . . . . . . . . . . . . . . . . . . 25 89 4. Grant Types . . . . . . . . . . . . . . . . . . . . . . . . . 28 90 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 28 91 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 30 92 4.1.2. Authorization Response . . . . . . . . . . . . . . . 33 93 4.1.3. Token Endpoint Extension . . . . . . . . . . . . . . 36 94 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 37 95 4.2.1. Token Endpoint Extension . . . . . . . . . . . . . . 38 96 4.3. Refresh Token Grant . . . . . . . . . . . . . . . . . . . 38 97 4.3.1. Token Endpoint Extension . . . . . . . . . . . . . . 39 98 4.3.2. Refresh Token Response . . . . . . . . . . . . . . . 40 99 4.4. Extension Grants . . . . . . . . . . . . . . . . . . . . 41 100 5. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 101 5.1. Access Token Types . . . . . . . . . . . . . . . . . . . 42 102 5.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42 103 5.2.1. Authenticated Requests . . . . . . . . . . . . . . . 43 104 5.2.2. The WWW-Authenticate Response Header Field . . . . . 45 105 5.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 46 106 5.3. Error Response . . . . . . . . . . . . . . . . . . . . . 47 107 5.3.1. Extension Token Types . . . . . . . . . . . . . . . . 47 108 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 48 109 6.1. Defining Access Token Types . . . . . . . . . . . . . . . 48 110 6.2. Defining New Endpoint Parameters . . . . . . . . . . . . 48 111 6.3. Defining New Authorization Grant Types . . . . . . . . . 49 112 6.4. Defining New Authorization Endpoint Response Types . . . 49 113 6.5. Defining Additional Error Codes . . . . . . . . . . . . . 49 114 7. Security Considerations . . . . . . . . . . . . . . . . . . . 50 115 7.1. Access Token Security Considerations . . . . . . . . . . 50 116 7.1.1. Security Threats . . . . . . . . . . . . . . . . . . 50 117 7.1.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 51 118 7.1.3. Summary of Recommendations . . . . . . . . . . . . . 51 119 7.1.4. Token Replay Prevention . . . . . . . . . . . . . . . 53 120 7.1.5. Access Token Privilege Restriction . . . . . . . . . 53 121 7.2. Client Authentication . . . . . . . . . . . . . . . . . . 54 122 7.3. Client Impersonation . . . . . . . . . . . . . . . . . . 54 123 7.3.1. Impersonation of Native Apps . . . . . . . . . . . . 55 124 7.3.2. Access Token Privilege Restriction . . . . . . . . . 55 125 7.3.3. Access Token Replay Prevention . . . . . . . . . . . 55 126 7.4. Client Impersonating Resource Owner . . . . . . . . . . . 56 127 7.5. Protecting the Authorization Code Flow . . . . . . . . . 56 128 7.5.1. Loopback Redirect Considerations in Native Apps . . . 56 129 7.5.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 57 130 7.6. Authorization Codes . . . . . . . . . . . . . . . . . . . 57 131 7.7. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 59 132 7.8. Credentials-Guessing Attacks . . . . . . . . . . . . . . 59 133 7.9. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 59 134 7.10. Cross-Site Request Forgery . . . . . . . . . . . . . . . 59 135 7.11. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 60 136 7.12. Code Injection and Input Validation . . . . . . . . . . . 61 137 7.13. Open Redirectors . . . . . . . . . . . . . . . . . . . . 61 138 7.13.1. Client as Open Redirector . . . . . . . . . . . . . 61 139 7.13.2. Authorization Server as Open Redirector . . . . . . 62 140 7.14. Authorization Server Mix-Up Mitigation in Native Apps . . 62 141 7.15. Other Recommendations . . . . . . . . . . . . . . . . . . 63 142 8. Native Applications . . . . . . . . . . . . . . . . . . . . . 63 143 8.1. Registration of Native App Clients . . . . . . . . . . . 64 144 8.1.1. Client Authentication of Native Apps . . . . . . . . 64 146 8.2. Using Inter-App URI Communication for OAuth in Native 147 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 64 148 8.3. Initiating the Authorization Request from a Native App . 65 149 8.4. Receiving the Authorization Response in a Native App . . 66 150 8.4.1. Private-Use URI Scheme Redirection . . . . . . . . . 66 151 8.4.2. Claimed "https" Scheme URI Redirection . . . . . . . 67 152 8.4.3. Loopback Interface Redirection . . . . . . . . . . . 68 153 8.5. Security Considerations in Native Apps . . . . . . . . . 68 154 8.5.1. Embedded User Agents in Native Apps . . . . . . . . . 69 155 8.5.2. Fake External User-Agents in Native Apps . . . . . . 69 156 8.5.3. Malicious External User-Agents in Native Apps . . . . 70 157 9. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 70 158 10. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 71 159 10.1. Removal of the OAuth 2.0 Implicit grant . . . . . . . . 71 160 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 161 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 162 12.1. Normative References . . . . . . . . . . . . . . . . . . 72 163 12.2. Informative References . . . . . . . . . . . . . . . . . 75 164 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 78 165 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 78 166 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 78 167 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 78 168 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 78 169 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 79 170 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 79 171 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 79 172 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 79 173 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 79 174 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 79 175 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 80 176 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 80 177 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 80 178 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 80 179 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 80 180 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 80 181 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 80 182 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 81 183 Appendix B. Use of application/x-www-form-urlencoded Media 184 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 81 185 Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 81 186 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 83 187 Appendix E. Document History . . . . . . . . . . . . . . . . . . 83 188 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 190 1. Introduction 192 In the traditional client-server authentication model, the client 193 requests an access-restricted resource (protected resource) on the 194 server by authenticating with the server using the resource owner's 195 credentials. In order to provide third-party applications access to 196 restricted resources, the resource owner shares its credentials with 197 the third party. This creates several problems and limitations: 199 * Third-party applications are required to store the resource 200 owner's credentials for future use, typically a password in clear- 201 text. 203 * Servers are required to support password authentication, despite 204 the security weaknesses inherent in passwords. 206 * Third-party applications gain overly broad access to the resource 207 owner's protected resources, leaving resource owners without any 208 ability to restrict duration or access to a limited subset of 209 resources. 211 * Resource owners often reuse passwords with other unrelated 212 services, despite best security practices. This password reuse 213 means a vulnerability or exposure in one service may have security 214 implications in completely unrelated services. 216 * Resource owners cannot revoke access to an individual third party 217 without revoking access to all third parties, and must do so by 218 changing their password. 220 * Compromise of any third-party application results in compromise of 221 the end-user's password and all of the data protected by that 222 password. 224 OAuth addresses these issues by introducing an authorization layer 225 and separating the role of the client from that of the resource 226 owner. In OAuth, the client requests access to resources controlled 227 by the resource owner and hosted by the resource server. Instead of 228 using the resource owner's credentials to access protected resources, 229 the client obtains an access token - a credential representing a 230 specific set of access attributes such as scope and lifetime. Access 231 tokens are issued to clients by an authorization server with the 232 approval of the resource owner. The client uses the access token to 233 access the protected resources hosted by the resource server. 235 For example, an end-user (resource owner) can grant a printing 236 service (client) access to their protected photos stored at a photo- 237 sharing service (resource server), without sharing their username and 238 password with the printing service. Instead, they authenticate 239 directly with a server trusted by the photo-sharing service 240 (authorization server), which issues the printing service delegation- 241 specific credentials (access token). 243 This specification is designed for use with HTTP ([RFC7231]). The 244 use of OAuth over any protocol other than HTTP is out of scope. 246 Since the publication of the OAuth 2.0 Authorization Framework 247 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 248 Native Apps ([RFC8252]), OAuth Security Best Current Practice 249 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 250 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 251 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 252 updated with ([I-D.ietf-oauth-security-topics]). This Standards 253 Track specification consolidates the information in all of these 254 documents and removes features that have been found to be insecure in 255 [I-D.ietf-oauth-security-topics]. 257 1.1. Roles 259 OAuth defines four roles: 261 "resource owner": An entity capable of granting access to a 262 protected resource. When the resource owner is a person, it is 263 referred to as an end-user. This is sometimes abbreviated as 264 "RO". 266 "resource server": The server hosting the protected resources, 267 capable of accepting and responding to protected resource requests 268 using access tokens. The resource server is often accessible via 269 an API. This is sometimes abbreviated as "RS". 271 "client": An application making protected resource requests on 272 behalf of the resource owner and with its authorization. The term 273 "client" does not imply any particular implementation 274 characteristics (e.g., whether the application executes on a 275 server, a desktop, or other devices). 277 "authorization server": The server issuing access tokens to the 278 client after successfully authenticating the resource owner and 279 obtaining authorization. This is sometimes abbreviated as "AS". 281 The interaction between the authorization server and resource server 282 is beyond the scope of this specification, however several extensions 283 have been defined to provide an option for interoperability between 284 resource servers and authorization servers. The authorization server 285 may be the same server as the resource server or a separate entity. 286 A single authorization server may issue access tokens accepted by 287 multiple resource servers. 289 1.2. Protocol Flow 291 +--------+ +---------------+ 292 | |--(1)- Authorization Request ->| Resource | 293 | | | Owner | 294 | |<-(2)-- Authorization Grant ---| | 295 | | +---------------+ 296 | | 297 | | +---------------+ 298 | |--(3)-- Authorization Grant -->| Authorization | 299 | Client | | Server | 300 | |<-(4)----- Access Token -------| | 301 | | +---------------+ 302 | | 303 | | +---------------+ 304 | |--(5)----- Access Token ------>| Resource | 305 | | | Server | 306 | |<-(6)--- Protected Resource ---| | 307 +--------+ +---------------+ 309 Figure 1: Abstract Protocol Flow 311 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 312 interaction between the four roles and includes the following steps: 314 1. The client requests authorization from the resource owner. The 315 authorization request can be made directly to the resource owner 316 (as shown), or preferably indirectly via the authorization server 317 as an intermediary. 319 2. The client receives an authorization grant, which is a credential 320 representing the resource owner's authorization, expressed using 321 one of the authorization grant types defined in this 322 specification or using an extension grant type. The 323 authorization grant type depends on the method used by the client 324 to request authorization and the types supported by the 325 authorization server. 327 3. The client requests an access token by authenticating with the 328 authorization server and presenting the authorization grant. 330 4. The authorization server authenticates the client and validates 331 the authorization grant, and if valid, issues an access token. 333 5. The client requests the protected resource from the resource 334 server and authenticates by presenting the access token. 336 6. The resource server validates the access token, and if valid, 337 serves the request. 339 The preferred method for the client to obtain an authorization grant 340 from the resource owner (depicted in steps (1) and (2)) is to use the 341 authorization server as an intermediary, which is illustrated in 342 Figure 3 in Section 4.1. 344 1.3. Authorization Grant 346 An authorization grant is a credential representing the resource 347 owner's authorization (to access its protected resources) used by the 348 client to obtain an access token. This specification defines three 349 grant types - authorization code, refresh token, and client 350 credentials - as well as an extensibility mechanism for defining 351 additional types. 353 1.3.1. Authorization Code 355 An authorization code is a temporary credential used to obtain an 356 access token. Instead of the client requesting authorization 357 directly from the resource owner, the client directs the resource 358 owner to an authorization server (via its user agent, which in turn 359 directs the resource owner back to the client with the authorization 360 code. The client can then exchange the authorization code for an 361 access token. 363 Before directing the resource owner back to the client with the 364 authorization code, the authorization server authenticates the 365 resource owner, and may request the resource owner's consent or 366 otherwise inform them of the client's request. Because the resource 367 owner only authenticates with the authorization server, the resource 368 owner's credentials are never shared with the client, and the client 369 does not need to have knowledge of any additional authentication 370 steps such as multi-factor authentication or delegated accounts. 372 The authorization code provides a few important security benefits, 373 such as the ability to authenticate the client, as well as the 374 transmission of the access token directly to the client without 375 passing it through the resource owner's user agent and potentially 376 exposing it to others, including the resource owner. 378 1.3.2. Refresh Token 380 Refresh tokens are credentials used to obtain access tokens. Refresh 381 tokens are issued to the client by the authorization server and are 382 used to obtain a new access token when the current access token 383 becomes invalid or expires, or to obtain additional access tokens 384 with identical or narrower scope (access tokens may have a shorter 385 lifetime and fewer permissions than authorized by the resource 386 owner). Issuing a refresh token is optional at the discretion of the 387 authorization server, and may be issued based on properties of the 388 client, properties of the request, policies within the authorization 389 server, or any other criteria. If the authorization server issues a 390 refresh token, it is included when issuing an access token (i.e., 391 step (2) in Figure 2). 393 A refresh token is a string representing the authorization granted to 394 the client by the resource owner. The string is considered opaque to 395 the client. The refresh token may be an identifier used to retrieve 396 the authorization information or may encode this information into the 397 string itself. Unlike access tokens, refresh tokens are intended for 398 use only with authorization servers and are never sent to resource 399 servers. 401 +--------+ +---------------+ 402 | |--(1)------- Authorization Grant --------->| | 403 | | | | 404 | |<-(2)----------- Access Token -------------| | 405 | | & Refresh Token | | 406 | | | | 407 | | +----------+ | | 408 | |--(3)---- Access Token ---->| | | | 409 | | | | | | 410 | |<-(4)- Protected Resource --| Resource | | Authorization | 411 | Client | | Server | | Server | 412 | |--(5)---- Access Token ---->| | | | 413 | | | | | | 414 | |<-(6)- Invalid Token Error -| | | | 415 | | +----------+ | | 416 | | | | 417 | |--(7)----------- Refresh Token ----------->| | 418 | | | | 419 | |<-(8)----------- Access Token -------------| | 420 +--------+ & Optional Refresh Token +---------------+ 422 Figure 2: Refreshing an Expired Access Token 424 The flow illustrated in Figure 2 includes the following steps: 426 1. The client requests an access token by authenticating with the 427 authorization server and presenting an authorization grant. 429 2. The authorization server authenticates the client and validates 430 the authorization grant, and if valid, issues an access token and 431 optionally a refresh token. 433 3. The client makes a protected resource request to the resource 434 server by presenting the access token. 436 4. The resource server validates the access token, and if valid, 437 serves the request. 439 5. Steps (3) and (4) repeat until the access token expires. If the 440 client knows the access token expired, it skips to step (7); 441 otherwise, it makes another protected resource request. 443 6. Since the access token is invalid, the resource server returns an 444 invalid token error. 446 7. The client requests a new access token by presenting the refresh 447 token and providing client authentication if it has been issued 448 credentials. The client authentication requirements are based on 449 the client type and on the authorization server policies. 451 8. The authorization server authenticates the client and validates 452 the refresh token, and if valid, issues a new access token (and, 453 optionally, a new refresh token). 455 1.3.3. Client Credentials 457 The client credentials or other forms of client authentication (e.g. 458 a client_secret or a private key used to sign a JWT) can be used as 459 an authorization grant when the authorization scope is limited to the 460 protected resources under the control of the client, or to protected 461 resources previously arranged with the authorization server. Client 462 credentials are used as an authorization grant typically when the 463 client is acting on its own behalf (the client is also the resource 464 owner) or is requesting access to protected resources based on an 465 authorization previously arranged with the authorization server. 467 1.4. Access Token 469 Access tokens are credentials used to access protected resources. An 470 access token is a string representing an authorization issued to the 471 client. The string is considered opaque to the client, even if it 472 has a structure. Depending on the authorization server, the access 473 token string may be parseable by the resource server, such as when 474 using the JSON Web Token Profile for Access Tokens ([RFC9068]). 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 [RFC9068], a method of 487 encoding access token data as a JSON Web Token [RFC7519]. 489 Additional authentication credentials, which are beyond the scope of 490 this specification, may be required in order for the client to use an 491 access token. This is typically referred to as a sender-constrained 492 access token, such as Mutual TLS Access Tokens [RFC8705]. 494 The access token provides an abstraction layer, replacing different 495 authorization constructs (e.g., username and password) with a single 496 token understood by the resource server. This abstraction enables 497 issuing access tokens more restrictive than the authorization grant 498 used to obtain them, as well as removing the resource server's need 499 to understand a wide range of authentication methods. 501 Access tokens can have different formats, structures, and methods of 502 utilization (e.g., cryptographic properties) based on the resource 503 server security requirements. Access token attributes and the 504 methods used to access protected resources may be extended beyond 505 what is described in this specification. 507 Access tokens (as well as any confidential access token attributes) 508 MUST be kept confidential in transit and storage, and only shared 509 among the authorization server, the resource servers the access token 510 is valid for, and the client to whom the access token is issued. 512 The authorization server MUST ensure that access tokens cannot be 513 generated, modified, or guessed to produce valid access tokens by 514 unauthorized parties. 516 1.5. Communication security 518 Implementations MUST use a mechanism to provide communication 519 authentication, integrity and confidentiality such as Transport-Layer 520 Security [RFC8446], to protect the exchange of clear-text credentials 521 and tokens either in the payload body or in header fields from 522 eavesdropping, tampering, and message forgery (eg. see Section 2.4.1, 523 Section 7.6, Section 3.2, and Section 5.2). 525 OAuth URLs MUST use the https scheme except for loopback interface 526 redirect URIs, which MAY use the http scheme. When using https, TLS 527 certificates MUST be checked according to [RFC2818]. At the time of 528 this writing, TLS version 1.3 [RFC8446] is the most recent version. 530 Implementations MAY also support additional transport-layer security 531 mechanisms that meet their security requirements. 533 The identification of the TLS versions and algorithms is outside the 534 scope of this specification. Refer to [BCP195] for up to date 535 recommendations on transport layer security, and to the relevant 536 specifications for certificate validation and other security 537 considerations. 539 1.6. HTTP Redirections 541 This specification makes extensive use of HTTP redirections, in which 542 the client or the authorization server directs the resource owner's 543 user agent to another destination. While the examples in this 544 specification show the use of the HTTP 302 status code, any other 545 method available via the user agent to accomplish this redirection, 546 with the exception of HTTP 307, is allowed and is considered to be an 547 implementation detail. See Section 7.5.2 for details. 549 1.7. Interoperability 551 OAuth 2.1 provides a rich authorization framework with well-defined 552 security properties. 554 This specification leaves a few required components partially or 555 fully undefined (e.g., client registration, authorization server 556 capabilities, endpoint discovery). Some of these behaviors are 557 defined in optional extensions which implementations can choose to 558 use, such as: 560 * [RFC8414]: Authorization Server Metadata, defining an endpoint 561 clients can use to look up the information needed to interact with 562 a particular OAuth server 564 * [RFC7591]: Dynamic Client Registration, providing a mechanism for 565 programmatically registering clients with an authorization server 567 * [RFC7592]: Dynamic Client Management, providing a mechanism for 568 updating dynamically registered client information 570 * [RFC7662]: Token Introspection, defining a mechanism for resource 571 servers to obtain information about access tokens 573 Please refer to Appendix C for a list of current known extensions at 574 the time of this publication. 576 1.8. Compatibility with OAuth 2.0 578 OAuth 2.1 is compatible with OAuth 2.0 with the extensions and 579 restrictions from known best current practices applied. 580 Specifically, features not specified in OAuth 2.0 core, such as PKCE, 581 are required in OAuth 2.1. Additionally, some features available in 582 OAuth 2.0, such as the Implicit or Resource Owner Credentials grant 583 types, are not specified in OAuth 2.1. Furthermore, some behaviors 584 allowed in OAuth 2.0 are restricted in OAuth 2.1, such as the strict 585 string matching of redirect URIs required by OAuth 2.1. 587 See Section 10 for more details on the differences from OAuth 2.0. 589 1.9. Notational Conventions 591 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 592 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 593 "OPTIONAL" in this document are to be interpreted as described in 594 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 595 capitals, as shown here. 597 This specification uses the Augmented Backus-Naur Form (ABNF) 598 notation of [RFC5234]. Additionally, the rule URI-reference is 599 included from "Uniform Resource Identifier (URI): Generic Syntax" 600 [RFC3986]. 602 Certain security-related terms are to be understood in the sense 603 defined in [RFC4949]. These terms include, but are not limited to, 604 "attack", "authentication", "authorization", "certificate", 605 "confidentiality", "credential", "encryption", "identity", "sign", 606 "signature", "trust", "validate", and "verify". 608 The term "payload" is to be interpreted as described in Section 3.3 609 of [RFC7231]. 611 The term "user agent" is to be interpreted as described in [RFC7230]. 613 Unless otherwise noted, all the protocol parameter names and values 614 are case sensitive. 616 2. Client Registration 618 Before initiating the protocol, the client must establish its 619 registration with the authorization server. The means through which 620 the client registers with the authorization server are beyond the 621 scope of this specification but typically involve the client 622 developer manually registering the client at the authorization 623 server's website after creating an account and agreeing to the 624 service's Terms of Service, or by using Dynamic Client Registration 625 ([RFC7591]). 627 Client registration does not require a direct interaction between the 628 client and the authorization server. When supported by the 629 authorization server, registration can rely on other means for 630 establishing trust and obtaining the required client properties 631 (e.g., redirect URI, client type). For example, registration can be 632 accomplished using a self-issued or third-party-issued assertion, or 633 by the authorization server performing client discovery using a 634 trusted channel. 636 When registering a client, the client developer SHALL: 638 * specify the client type as described in Section 2.1, 640 * provide client details needed by the grant type in use, such as 641 redirect URIs as described in Section 2.3, and 643 * include any other information required by the authorization server 644 (e.g., application name, website, description, logo image, the 645 acceptance of legal terms). 647 Dynamic Client Registration ([RFC7591]) defines a common general data 648 model for clients that may be used even with manual client 649 registration. 651 2.1. Client Types 653 OAuth 2.1 defines three client types based on their ability to 654 authenticate securely with the authorization server as well as the 655 authorization server's assurance of the client's identity. 657 "confidential": Clients that have credentials and have a prior 658 relationship with the AS are designated as "confidential clients" 660 "credentialed": Clients that have credentials but no prior 661 relationship with the AS are designated as "credentialed clients" 663 "public": Clients without credentials are called "public clients" 665 Any clients with credentials MUST take precautions to prevent leakage 666 and abuse of their credentials. 668 Authorization servers SHOULD consider the level of confidence in a 669 client's identity when deciding whether they allow such a client 670 access to more critical functions, such as the Client Credentials 671 grant type. 673 A single client_id MUST NOT be treated as more than one type of 674 client. 676 For example, a client that has been registered at the authorization 677 server by a registered application developer, where the client is 678 expected to be run as server-side code, would be considered a 679 confidential client. A client that runs on an end-user's device, and 680 uses Dynamic Client Registration ([RFC7591]) to establish credentials 681 the first time the app runs, would be considered a credentialed 682 client. An application deployed as a single-page app on a static web 683 host would be considered a public client. 685 This specification has been designed around the following client 686 profiles: 688 "web application": A web application is a confidential client 689 running on a web server. Resource owners access the client via an 690 HTML user interface rendered in a user agent on the device used by 691 the resource owner. The client credentials as well as any access 692 tokens issued to the client are stored on the web server and are 693 not exposed to or accessible by the resource owner. 695 "browser-based application": A browser-based application is a public 696 client in which the client code is downloaded from a web server 697 and executes within a user agent (e.g., web browser) on the device 698 used by the resource owner. Protocol data and credentials are 699 easily accessible (and often visible) to the resource owner. 700 Since such applications reside within the user agent, they can 701 make seamless use of the user agent capabilities when requesting 702 authorization. 704 "native application": A native application is a public client 705 installed and executed on the device used by the resource owner. 706 Protocol data and credentials are accessible to the resource 707 owner. It is assumed that any client authentication credentials 708 included in the application can be extracted. On the other hand, 709 dynamically issued credentials such as access tokens or refresh 710 tokens can receive an acceptable level of protection. At a 711 minimum, these credentials are protected from hostile servers with 712 which the application may interact. On some platforms, these 713 credentials might be protected from other applications residing on 714 the same device. 716 2.2. Client Identifier 718 The authorization server issues the registered client a client 719 identifier - a unique string representing the registration 720 information provided by the client. The client identifier is not a 721 secret; it is exposed to the resource owner and MUST NOT be used 722 alone for client authentication. The client identifier is unique to 723 the authorization server. 725 The client identifier string size is left undefined by this 726 specification. The client should avoid making assumptions about the 727 identifier size. The authorization server SHOULD document the size 728 of any identifier it issues. 730 Authorization servers SHOULD NOT allow clients to choose or influence 731 their client_id value. See Section 7.4 for details. 733 2.3. Client Redirection Endpoint 735 The client redirection endpoint (also referred to as "redirect 736 endpoint") is the URI of the client that the authorization server 737 redirects the user agent back to after completing its interaction 738 with the resource owner. 740 The authorization server redirects the user agent to one of the 741 client's redirection endpoints previously established with the 742 authorization server during the client registration process. 744 The redirect URI MUST be an absolute URI as defined by [RFC3986] 745 Section 4.3. The endpoint URI MAY include an "application/x-www- 746 form-urlencoded" formatted (per Appendix B) query component 747 ([RFC3986] Section 3.4), which MUST be retained when adding 748 additional query parameters. The endpoint URI MUST NOT include a 749 fragment component. 751 2.3.1. Registration Requirements 753 Authorization servers MUST require clients to register their complete 754 redirect URI (including the path component) and reject authorization 755 requests that specify a redirect URI that doesn't exactly match one 756 that was registered; the exception is loopback redirects, where an 757 exact match is required except for the port URI component. 759 The authorization server MAY allow the client to register multiple 760 redirect URIs. 762 For private-use URI scheme-based redirect URIs, authorization servers 763 SHOULD enforce the requirement in Section 8.4.1 that clients use 764 schemes that are reverse domain name based. At a minimum, any 765 private-use URI scheme that doesn't contain a period character (.) 766 SHOULD be rejected. 768 In addition to the collision-resistant properties, this can help to 769 prove ownership in the event of a dispute where two apps claim the 770 same private-use URI scheme (where one app is acting maliciously). 771 For example, if two apps claimed com.example.app, the owner of 772 example.com could petition the app store operator to remove the 773 counterfeit app. Such a petition is harder to prove if a generic URI 774 scheme was used. 776 Clients MUST NOT expose URLs that forward the user's browser to 777 arbitrary URIs obtained from a query parameter ("open redirector"). 778 Open redirectors can enable exfiltration of authorization codes and 779 access tokens, see (#open_redirector_on_client). 781 The client MAY use the state request parameter to achieve per-request 782 customization if needed rather than varying the redirect URI per 783 request. 785 Without requiring registration of redirect URIs, attackers can use 786 the authorization endpoint as an open redirector as described in 787 Section 7.13. 789 2.3.2. Multiple Redirect URIs 791 If multiple redirect URIs have been registered, the client MUST 792 include a redirect URI with the authorization request using the 793 redirect_uri request parameter. 795 2.3.3. Preventing CSRF Attacks 797 Clients MUST prevent Cross-Site Request Forgery (CSRF) attacks. In 798 this context, CSRF refers to requests to the redirection endpoint 799 that do not originate at the authorization server, but a malicious 800 third party (see Section 4.4.1.8. of [RFC6819] for details). Clients 801 that have ensured that the authorization server supports the 802 code_challenge parameter MAY rely the CSRF protection provided by 803 that mechanism. In OpenID Connect flows, validating the nonce 804 parameter provides CSRF protection. Otherwise, one-time use CSRF 805 tokens carried in the state parameter that are securely bound to the 806 user agent MUST be used for CSRF protection (see 807 (#csrf_countermeasures)). 809 2.3.4. Preventing Mix-Up Attacks 811 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 812 process redirect responses of the authorization server they sent the 813 respective request to and from the same user agent this authorization 814 request was initiated with. Clients MUST store the authorization 815 server they sent an authorization request to and bind this 816 information to the user agent and check that the authorization 817 response was received from the correct authorization server. Clients 818 MUST ensure that the subsequent access token request, if applicable, 819 is sent to the same authorization server. Clients SHOULD use 820 distinct redirect URIs for each authorization server as a means to 821 identify the authorization server a particular response came from. 823 2.3.5. Invalid Endpoint 825 If an authorization request fails validation due to a missing, 826 invalid, or mismatching redirect URI, the authorization server SHOULD 827 inform the resource owner of the error and MUST NOT automatically 828 redirect the user agent to the invalid redirect URI. 830 2.3.6. Endpoint Content 832 The redirection request to the client's endpoint typically results in 833 an HTML document response, processed by the user agent. If the HTML 834 response is served directly as the result of the redirection request, 835 any script included in the HTML document will execute with full 836 access to the redirect URI and the credentials (e.g. authorization 837 code) it contains. Additionally, the request URL containing the 838 authorization code may be sent in the HTTP Referer header to any 839 embedded images, stylesheets and other elements loaded in the page. 841 The client SHOULD NOT include any third-party scripts (e.g., third- 842 party analytics, social plug-ins, ad networks) in the redirection 843 endpoint response. Instead, it SHOULD extract the credentials from 844 the URI and redirect the user agent again to another endpoint without 845 exposing the credentials (in the URI or elsewhere). If third-party 846 scripts are included, the client MUST ensure that its own scripts 847 (used to extract and remove the credentials from the URI) will 848 execute first. 850 2.4. Client Authentication 852 The authorization server MUST only rely on client authentication if 853 the process of issuance/registration and distribution of the 854 underlying credentials ensures their confidentiality. 856 If the client is confidential or credentialed, the authorization 857 server MAY accept any form of client authentication meeting its 858 security requirements (e.g., password, public/private key pair). 860 It is RECOMMENDED to use asymmetric (public-key based) methods for 861 client authentication such as mTLS [RFC8705] or "private_key_jwt" 862 [OpenID]. When asymmetric methods for client authentication are 863 used, authorization servers do not need to store sensitive symmetric 864 keys, making these methods more robust against a number of attacks. 866 When client authentication is not possible, the authorization server 867 SHOULD employ other means to validate the client's identity - for 868 example, by requiring the registration of the client redirect URI or 869 enlisting the resource owner to confirm identity. A valid redirect 870 URI is not sufficient to verify the client's identity when asking for 871 resource owner authorization but can be used to prevent delivering 872 credentials to a counterfeit client after obtaining resource owner 873 authorization. 875 The authorization server MAY establish a client authentication method 876 with public clients, which converts them to credentialed clients. 877 However, the authorization server MUST NOT rely on credentialed 878 client authentication for the purpose of identifying the client. 880 The client MUST NOT use more than one authentication method in each 881 request to prevent a conflict of which authentication mechanism is 882 authoritative for the request. 884 The authorization server MUST consider the security implications of 885 interacting with unauthenticated clients and take measures to limit 886 the potential exposure of tokens issued to such clients, (e.g., 887 limiting the lifetime of refresh tokens). 889 The privileges an authorization server associates with a certain 890 client identity MUST depend on the assessment of the overall process 891 for client identification and client credential lifecycle management. 892 See Section 7.2 for additional details. 894 2.4.1. Client Secret 896 Clients in possession of a client secret, sometimes known as a client 897 password, MAY use the HTTP Basic authentication scheme as defined in 898 [RFC7235] to authenticate with the authorization server. The client 899 identifier is encoded using the application/x-www-form-urlencoded 900 encoding algorithm per Appendix B, and the encoded value is used as 901 the username; the client secret is encoded using the same algorithm 902 and used as the password. The authorization server MUST support the 903 HTTP Basic authentication scheme for authenticating clients that were 904 issued a client secret. 906 For example (with extra line breaks for display purposes only): 908 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 910 In addition to that, the authorization server MAY support including 911 the client credentials in the request-body using the following 912 parameters: 914 "client_id": REQUIRED. The client identifier issued to the client 915 during the registration process described by Section 2.2. 917 "client_secret": REQUIRED. The client secret. 919 Including the client credentials in the request-body using the two 920 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 921 to directly utilize the HTTP Basic authentication scheme (or other 922 password-based HTTP authentication schemes). The parameters can only 923 be transmitted in the request-body and MUST NOT be included in the 924 request URI. 926 For example, a request to refresh an access token (Section 4.3) using 927 the body parameters (with extra line breaks for display purposes 928 only): 930 POST /token HTTP/1.1 931 Host: server.example.com 932 Content-Type: application/x-www-form-urlencoded 934 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 935 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 936 Since this client authentication method involves a password, the 937 authorization server MUST protect any endpoint utilizing it against 938 brute force attacks. 940 2.4.2. Other Authentication Methods 942 The authorization server MAY support any suitable authentication 943 scheme matching its security requirements. When using other 944 authentication methods, the authorization server MUST define a 945 mapping between the client identifier (registration record) and 946 authentication scheme. 948 Some additional authentication methods such as mTLS [RFC8705] and 949 "private_key_jwt" [OpenID] are defined in the "OAuth Token Endpoint 950 Authentication Methods (https://www.iana.org/assignments/oauth- 951 parameters/oauth-parameters.xhtml#token-endpoint-auth-method)" 952 registry, and may be useful as generic client authentication methods 953 beyond the specific use of protecting the token endpoint. 955 2.5. Unregistered Clients 957 This specification does not exclude the use of unregistered clients. 958 However, the use of such clients is beyond the scope of this 959 specification and requires additional security analysis and review of 960 its interoperability impact. 962 3. Protocol Endpoints 964 The authorization process utilizes two authorization server endpoints 965 (HTTP resources): 967 * Authorization endpoint - used by the client to obtain 968 authorization from the resource owner via user agent redirection. 970 * Token endpoint - used by the client to exchange an authorization 971 grant for an access token, typically with client authentication. 973 As well as one client endpoint: 975 * Redirection endpoint - used by the authorization server to return 976 responses containing authorization credentials to the client via 977 the resource owner user agent. 979 Not every authorization grant type utilizes both endpoints. 980 Extension grant types MAY define additional endpoints as needed. 982 3.1. Authorization Endpoint 984 The authorization endpoint is used to interact with the resource 985 owner and obtain an authorization grant. The authorization server 986 MUST first verify the identity of the resource owner. The way in 987 which the authorization server authenticates the resource owner 988 (e.g., username and password login, session cookies) is beyond the 989 scope of this specification. 991 The means through which the client obtains the location of the 992 authorization endpoint are beyond the scope of this specification, 993 but the location is typically provided in the service documentation, 994 or in the authorization server's metadata document ([RFC8414]). 996 The endpoint URI MAY include an "application/x-www-form-urlencoded" 997 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 998 which MUST be retained when adding additional query parameters. The 999 endpoint URI MUST NOT include a fragment component. 1001 The authorization server MUST support the use of the HTTP GET method 1002 [RFC7231] for the authorization endpoint and MAY support the use of 1003 the POST method as well. 1005 The authorization server MUST ignore unrecognized request parameters. 1007 Request and response parameters defined by this specification MUST 1008 NOT be included more than once. Parameters sent without a value MUST 1009 be treated as if they were omitted from the request. 1011 An authorization server that redirects a request potentially 1012 containing user credentials MUST avoid forwarding these user 1013 credentials accidentally (see Section 7.5.2 for details). 1015 3.2. Token Endpoint 1017 The token endpoint is used by the client to obtain an access token 1018 using a grant such as those described in Section 4 and Section 4.3. 1020 The means through which the client obtains the location of the token 1021 endpoint are beyond the scope of this specification, but the location 1022 is typically provided in the service documentation and configured 1023 during development of the client, or provided in the authorization 1024 server's metadata document ([RFC8414]) and fetched programmatically 1025 at runtime. 1027 The endpoint URI MAY include an application/x-www-form-urlencoded 1028 formatted (per Appendix B) query component ([RFC3986] Section 3.4) 1029 and MUST NOT include a fragment component. 1031 The client MUST use the HTTP POST method when making access token 1032 requests. 1034 The authorization server MUST ignore unrecognized request parameters. 1036 Parameters sent without a value MUST be treated as if they were 1037 omitted from the request. Request and response parameters defined by 1038 this specification MUST NOT be included more than once. 1040 3.2.1. Client Authentication 1042 Confidential or credentialed clients MUST authenticate with the 1043 authorization server as described in Section 2.4 when making requests 1044 to the token endpoint. 1046 Client authentication is used for: 1048 * Enforcing the binding of refresh tokens and authorization codes to 1049 the client they were issued to. Client authentication adds an 1050 additional layer of security when an authorization code is 1051 transmitted to the redirection endpoint over an insecure channel. 1053 * Recovering from a compromised client by disabling the client or 1054 changing its credentials, thus preventing an attacker from abusing 1055 stolen refresh tokens. Changing a single set of client 1056 credentials is significantly faster than revoking an entire set of 1057 refresh tokens. 1059 * Implementing authentication management best practices, which 1060 require periodic credential rotation. Rotation of an entire set 1061 of refresh tokens can be challenging, while rotation of a single 1062 set of client credentials is significantly easier. 1064 3.2.2. Token Request 1066 The client makes a request to the token endpoint by sending the 1067 following parameters using the application/x-www-form-urlencoded 1068 format per Appendix B with a character encoding of UTF-8 in the HTTP 1069 request payload: 1071 "client_id": REQUIRED, if the client is not authenticating with the 1072 authorization server as described in Section 3.2.1. 1074 "scope": OPTIONAL. The scope of the access request as described by 1075 Section 3.2.2.1. 1077 "grant_type": REQUIRED. Identifier of the grant type the client 1078 uses with the particular token request. This specification 1079 defines the values authorization_code, refresh_token, and 1080 client_credentials. The grant type determines the further 1081 parameters required or supported by the token request. The 1082 details of those grant types are defined below. 1084 Confidential or credentialed clients MUST authenticate with the 1085 authorization server as described in Section 3.2.1. 1087 For example, the client makes the following HTTP request (with extra 1088 line breaks for display purposes only): 1090 POST /token HTTP/1.1 1091 Host: server.example.com 1092 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1093 Content-Type: application/x-www-form-urlencoded 1095 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1096 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1097 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1099 The authorization server MUST: 1101 * require client authentication for confidential and credentialed 1102 clients (or clients with other authentication requirements), 1104 * authenticate the client if client authentication is included 1106 Further grant type specific processing rules apply and are specified 1107 with the respective grant type. 1109 3.2.2.1. Access Token Scope 1111 The authorization and token endpoints allow the client to specify the 1112 scope of the access request using the scope request parameter. In 1113 turn, the authorization server uses the scope response parameter to 1114 inform the client of the scope of the access token issued. 1116 The value of the scope parameter is expressed as a list of space- 1117 delimited, case-sensitive strings. The strings are defined by the 1118 authorization server. If the value contains multiple space-delimited 1119 strings, their order does not matter, and each string adds an 1120 additional access range to the requested scope. 1122 scope = scope-token *( SP scope-token ) 1123 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 1125 The authorization server MAY fully or partially ignore the scope 1126 requested by the client, based on the authorization server policy or 1127 the resource owner's instructions. If the issued access token scope 1128 is different from the one requested by the client, the authorization 1129 server MUST include the scope response parameter to inform the client 1130 of the actual scope granted. 1132 If the client omits the scope parameter when requesting 1133 authorization, the authorization server MUST either process the 1134 request using a pre-defined default value or fail the request 1135 indicating an invalid scope. The authorization server SHOULD 1136 document its scope requirements and default value (if defined). 1138 3.2.3. Token Response 1140 If the access token request is valid and authorized, the 1141 authorization server issues an access token and optional refresh 1142 token. 1144 If the request client authentication failed or is invalid, the 1145 authorization server returns an error response as described in 1146 Section 3.2.3.1. 1148 The authorization server issues an access token and optional refresh 1149 token by creating an HTTP response body using the application/json 1150 media type as defined by [RFC8259] with the following parameters and 1151 an HTTP 200 (OK) status code: 1153 "access_token": REQUIRED. The access token issued by the 1154 authorization server. 1156 "token_type": REQUIRED. The type of the access token issued as 1157 described in Section 5.1. Value is case insensitive. 1159 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1160 token. For example, the value 3600 denotes that the access token 1161 will expire in one hour from the time the response was generated. 1162 If omitted, the authorization server SHOULD provide the expiration 1163 time via other means or document the default value. 1165 "scope": RECOMMENDED, if identical to the scope requested by the 1166 client; otherwise, REQUIRED. The scope of the access token as 1167 described by Section 3.2.2.1. 1169 "refresh_token": OPTIONAL. The refresh token, which can be used to 1170 obtain new access tokens based on the grant passed in the 1171 corresponding token request. 1173 Authorization servers SHOULD determine, based on a risk assessment 1174 and their own policies, whether to issue refresh tokens to a certain 1175 client. If the authorization server decides not to issue refresh 1176 tokens, the client MAY obtain new access tokens by starting the OAuth 1177 flow over, for example initiating a new authorization code request. 1178 In such a case, the authorization server may utilize cookies and 1179 persistent grants to optimize the user experience. 1181 If refresh tokens are issued, those refresh tokens MUST be bound to 1182 the scope and resource servers as consented by the resource owner. 1183 This is to prevent privilege escalation by the legitimate client and 1184 reduce the impact of refresh token leakage. 1186 The parameters are serialized into a JavaScript Object Notation 1187 (JSON) structure by adding each parameter at the highest structure 1188 level. Parameter names and string values are included as JSON 1189 strings. Numerical values are included as JSON numbers. The order 1190 of parameters does not matter and can vary. 1192 The authorization server MUST include the HTTP Cache-Control response 1193 header field [RFC7234] with a value of no-store in any response 1194 containing tokens, credentials, or other sensitive information. 1196 For example: 1198 HTTP/1.1 200 OK 1199 Content-Type: application/json 1200 Cache-Control: no-store 1202 { 1203 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1204 "token_type":"Bearer", 1205 "expires_in":3600, 1206 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1207 "example_parameter":"example_value" 1208 } 1210 The client MUST ignore unrecognized value names in the response. The 1211 sizes of tokens and other values received from the authorization 1212 server are left undefined. The client should avoid making 1213 assumptions about value sizes. The authorization server SHOULD 1214 document the size of any value it issues. 1216 3.2.3.1. Error Response 1218 The authorization server responds with an HTTP 400 (Bad Request) 1219 status code (unless specified otherwise) and includes the following 1220 parameters with the response: 1222 "error": REQUIRED. A single ASCII [USASCII] error code from the 1223 following: 1225 "invalid_request": The request is missing a required parameter, 1226 includes an unsupported parameter value (other than grant 1227 type), repeats a parameter, includes multiple credentials, 1228 utilizes more than one mechanism for authenticating the client, 1229 contains a code_verifier although no code_challenge was sent in 1230 the authorization request, or is otherwise malformed. 1232 "invalid_client": Client authentication failed (e.g., unknown 1233 client, no client authentication included, or unsupported 1234 authentication method). The authorization server MAY return an 1235 HTTP 401 (Unauthorized) status code to indicate which HTTP 1236 authentication schemes are supported. If the client attempted 1237 to authenticate via the Authorization request header field, the 1238 authorization server MUST respond with an HTTP 401 1239 (Unauthorized) status code and include the WWW-Authenticate 1240 response header field matching the authentication scheme used 1241 by the client. 1243 "invalid_grant": The provided authorization grant (e.g., 1244 authorization code, resource owner credentials) or refresh 1245 token is invalid, expired, revoked, does not match the redirect 1246 URI used in the authorization request, or was issued to another 1247 client. 1249 "unauthorized_client": The authenticated client is not authorized 1250 to use this authorization grant type. 1252 "unsupported_grant_type": The authorization grant type is not 1253 supported by the authorization server. 1255 "invalid_scope": The requested scope is invalid, unknown, 1256 malformed, or exceeds the scope granted by the resource owner. 1258 Values for the error parameter MUST NOT include characters outside 1259 the set %x20-21 / %x23-5B / %x5D-7E. 1261 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1262 providing additional information, used to assist the client 1263 developer in understanding the error that occurred. Values for 1264 the error_description parameter MUST NOT include characters 1265 outside the set %x20-21 / %x23-5B / %x5D-7E. 1267 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1268 with information about the error, used to provide the client 1269 developer with additional information about the error. Values for 1270 the error_uri parameter MUST conform to the URI-reference syntax 1271 and thus MUST NOT include characters outside the set %x21 / 1272 %x23-5B / %x5D-7E. 1274 The parameters are included in the payload of the HTTP response using 1275 the application/json media type as defined by [RFC7159]. The 1276 parameters are serialized into a JSON structure by adding each 1277 parameter at the highest structure level. Parameter names and string 1278 values are included as JSON strings. Numerical values are included 1279 as JSON numbers. The order of parameters does not matter and can 1280 vary. 1282 For example: 1284 HTTP/1.1 400 Bad Request 1285 Content-Type: application/json 1286 Cache-Control: no-store 1288 { 1289 "error":"invalid_request" 1290 } 1292 4. Grant Types 1294 To request an access token, the client obtains authorization from the 1295 resource owner. This specification defines the following 1296 authorization grant types: 1298 * authorization code 1300 * client credentials, and 1302 * refresh token 1304 It also provides an extension mechanism for defining additional grant 1305 types. 1307 4.1. Authorization Code Grant 1309 The authorization code grant type is used to obtain both access 1310 tokens and refresh tokens. 1312 The grant type uses the additional authorization endpoint to let the 1313 authorization server interact with the resource owner in order to get 1314 consent for resource access. 1316 Since this is a redirect-based flow, the client must be capable of 1317 initiating the flow with the resource owner's user agent (typically a 1318 web browser) and capable of being redirected back to from the 1319 authorization server. 1321 +----------+ 1322 | Resource | 1323 | Owner | 1324 | | 1325 +----------+ 1326 ^ 1327 | 1328 (2) 1329 +----|-----+ Client Identifier +---------------+ 1330 | -+----(1)-- & Redirect URI ---->| | 1331 | User- | | Authorization | 1332 | Agent -+----(2)-- User authenticates --->| Server | 1333 | | | | 1334 | -+----(3)-- Authorization Code ---<| | 1335 +-|----|---+ +---------------+ 1336 | | ^ v 1337 (1) (3) | | 1338 | | | | 1339 ^ v | | 1340 +---------+ | | 1341 | |>---(4)-- Authorization Code ---------' | 1342 | Client | & Redirect URI | 1343 | | | 1344 | |<---(5)----- Access Token -------------------' 1345 +---------+ (w/ Optional Refresh Token) 1347 Note: The lines illustrating steps (1), (2), and (3) are broken into 1348 two parts as they pass through the user agent. 1350 Figure 3: Authorization Code Flow 1352 The flow illustrated in Figure 3 includes the following steps: 1354 (1) The client initiates the flow by directing the resource owner's 1355 user agent to the authorization endpoint. The client includes its 1356 client identifier, code challenge (derived from a generated code 1357 verifier), optional requested scope, optional local state, and a 1358 redirect URI to which the authorization server will send the user 1359 agent back once access is granted (or denied). 1361 (2) The authorization server authenticates the resource owner (via 1362 the user agent) and establishes whether the resource owner grants or 1363 denies the client's access request. 1365 (3) Assuming the resource owner grants access, the authorization 1366 server redirects the user agent back to the client using the redirect 1367 URI provided earlier (in the request or during client registration). 1368 The redirect URI includes an authorization code and any local state 1369 provided by the client earlier. 1371 (4) The client requests an access token from the authorization 1372 server's token endpoint by including the authorization code received 1373 in the previous step, and including its code verifier. When making 1374 the request, the client authenticates with the authorization server 1375 if it can. The client includes the redirect URI used to obtain the 1376 authorization code for verification. 1378 (5) The authorization server authenticates the client when possible, 1379 validates the authorization code, validates the code verifier, and 1380 ensures that the redirect URI received matches the URI used to 1381 redirect the client in step (3). If valid, the authorization server 1382 responds back with an access token and, optionally, a refresh token. 1384 4.1.1. Authorization Request 1386 To begin the authorization request, the client builds the 1387 authorization request URI by adding parameters to the authorization 1388 server's authorization endpoint URI. The client will eventually 1389 redirect the user agent to this URI to initiate the request. 1391 Clients use a unique secret per authorization request to protect 1392 against authorization code injection and CSRF attacks. The client 1393 first generates this secret, which it can use at the time of 1394 redeeming the authorization code to prove that the client using the 1395 authorization code is the same client that requested it. 1397 The client constructs the request URI by adding the following 1398 parameters to the query component of the authorization endpoint URI 1399 using the application/x-www-form-urlencoded format, per Appendix B: 1401 "response_type": REQUIRED. The authorization endpoint supports 1402 different sets of request and response pameters. The client 1403 determines the type of flow by using a certain response_type 1404 value. This specification defines the value code, which must be 1405 used to signal that the client wants to use the authorization code 1406 flow. 1408 Extension response types MAY contain a space-delimited (%x20) list of 1409 values, where the order of values does not matter (e.g., response 1410 type a b is the same as b a). The meaning of such composite response 1411 types is defined by their respective specifications. 1413 Some extension response types are defined by ([OpenID]). 1415 If an authorization request is missing the response_type parameter, 1416 or if the response type is not understood, the authorization server 1417 MUST return an error response as described in Section 4.1.2.1. 1419 "client_id": REQUIRED. The client identifier as described in 1420 Section 2.2. 1422 "code_challenge": REQUIRED or RECOMMENDED (see Section 7.6). Code 1423 challenge. 1425 "code_challenge_method": OPTIONAL, defaults to plain if not present 1426 in the request. Code verifier transformation method is S256 or 1427 plain. 1429 "redirect_uri": OPTIONAL. As described in Section 2.3. 1431 "scope": OPTIONAL. The scope of the access request as described by 1432 Section 3.2.2.1. 1434 "state": OPTIONAL. An opaque value used by the client to maintain 1435 state between the request and callback. The authorization server 1436 includes this value when redirecting the user agent back to the 1437 client. 1439 The code_verifier is a unique high-entropy cryptographically random 1440 string generated for each authorization request, using the unreserved 1441 characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a 1442 minimum length of 43 characters and a maximum length of 128 1443 characters. 1445 The client stores the code_verifier temporarily, and calculates the 1446 code_challenge which it uses in the authorization request. 1448 ABNF for code_verifier is as follows. 1450 code-verifier = 43*128unreserved 1451 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1452 ALPHA = %x41-5A / %x61-7A 1453 DIGIT = %x30-39 1455 NOTE: The code verifier SHOULD have enough entropy to make it 1456 impractical to guess the value. It is RECOMMENDED that the output of 1457 a suitable random number generator be used to create a 32-octet 1458 sequence. The octet sequence is then base64url-encoded to produce a 1459 43-octet URL-safe string to use as the code verifier. 1461 The client then creates a code_challenge derived from the code 1462 verifier by using one of the following transformations on the code 1463 verifier: 1465 S256 1466 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1468 plain 1469 code_challenge = code_verifier 1471 If the client is capable of using S256, it MUST use S256, as S256 is 1472 Mandatory To Implement (MTI) on the server. Clients are permitted to 1473 use plain only if they cannot support S256 for some technical reason, 1474 for example constrained environments that do not have a hashing 1475 function available, and know via out-of-band configuration or via 1476 Authorization Server Metadata ([RFC8414]) that the server supports 1477 plain. 1479 ABNF for code_challenge is as follows. 1481 code-challenge = 43*128unreserved 1482 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1483 ALPHA = %x41-5A / %x61-7A 1484 DIGIT = %x30-39 1486 The properties code_challenge and code_verifier are adopted from the 1487 OAuth 2.0 extension known as "Proof-Key for Code Exchange", or PKCE 1488 ([RFC7636]) where this technique was originally developed. 1490 Authorization servers MUST support the code_challenge and 1491 code_verifier parameters. 1493 Clients MUST use code_challenge and code_verifier and authorization 1494 servers MUST enforce their use except under the conditions described 1495 in Section 7.6. In this case, using and enforcing code_challenge and 1496 code_verifier as described in the following is still RECOMMENDED. 1498 The state and scope parameters SHOULD NOT include sensitive client or 1499 resource owner information in plain text, as they can be transmitted 1500 over insecure channels or stored insecurely. 1502 The client directs the resource owner to the constructed URI using an 1503 HTTP redirection, or by other means available to it via the user 1504 agent. 1506 For example, the client directs the user agent to make the following 1507 HTTP request (with extra line breaks for display purposes only): 1509 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1510 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1511 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1512 &code_challenge_method=S256 HTTP/1.1 1513 Host: server.example.com 1515 The authorization server validates the request to ensure that all 1516 required parameters are present and valid. 1518 In particular, the authorization server MUST validate the 1519 redirect_uri in the request if present, ensuring that it matches one 1520 of the registered redirect URIs previously established during client 1521 registration (Section 2). When comparing the two URIs the 1522 authorization server MUST using simple character-by-character string 1523 comparison as defined in [RFC3986], Section 6.2.1. 1525 If the request is valid, the authorization server authenticates the 1526 resource owner and obtains an authorization decision (by asking the 1527 resource owner or by establishing approval via other means). 1529 When a decision is established, the authorization server directs the 1530 user agent to the provided client redirect URI using an HTTP 1531 redirection response, or by other means available to it via the user 1532 agent. 1534 4.1.2. Authorization Response 1536 If the resource owner grants the access request, the authorization 1537 server issues an authorization code and delivers it to the client by 1538 adding the following parameters to the query component of the 1539 redirect URI using the application/x-www-form-urlencoded format, per 1540 Appendix B: 1542 "code": REQUIRED. The authorization code generated by the 1543 authorization server and is opqaue to the client. The 1544 authorization code MUST expire shortly after it is issued to 1545 mitigate the risk of leaks. A maximum authorization code lifetime 1546 of 10 minutes is RECOMMENDED. The client MUST NOT use the 1547 authorization code more than once. If an authorization code is 1548 used more than once, the authorization server MUST deny the 1549 request and SHOULD revoke (when possible) all access tokens and 1550 refresh tokens previously issued based on that authorization code. 1551 The authorization code is bound to the client identifier, code 1552 challenge and redirect URI. 1554 "state": REQUIRED if the state parameter was present in the client 1555 authorization request. The exact value received from the client. 1557 For example, the authorization server redirects the user agent by 1558 sending the following HTTP response: 1560 HTTP/1.1 302 Found 1561 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1562 &state=xyz 1564 The client MUST ignore unrecognized response parameters. The 1565 authorization code string size is left undefined by this 1566 specification. The client should avoid making assumptions about code 1567 value sizes. The authorization server SHOULD document the size of 1568 any value it issues. 1570 The authorization server MUST associate the code_challenge and 1571 code_challenge_method values with the issued authorization code so 1572 the code challenge can be verified later. 1574 The exact method that the server uses to associate the code_challenge 1575 with the issued code is out of scope for this specification. The 1576 code challenge could be stored on the server and associated with the 1577 code there. The code_challenge and code_challenge_method values may 1578 be stored in encrypted form in the code itself, but the server MUST 1579 NOT include the code_challenge value in a response parameter in a 1580 form that entities other than the AS can extract. 1582 Clients MUST prevent injection (replay) of authorization codes into 1583 the authorization response by attackers. Using code_challenge and 1584 code_verifier prevents injection of authorization codes since the 1585 authorization server will reject a token request with a mismatched 1586 code_verifier. See Section 7.6 for more details. 1588 4.1.2.1. Error Response 1590 If the request fails due to a missing, invalid, or mismatching 1591 redirect URI, or if the client identifier is missing or invalid, the 1592 authorization server SHOULD inform the resource owner of the error 1593 and MUST NOT automatically redirect the user agent to the invalid 1594 redirect URI. 1596 An AS MUST reject requests without a code_challenge from public 1597 clients, and MUST reject such requests from other clients unless 1598 there is reasonable assurance that the client mitigates authorization 1599 code injection in other ways. See Section 7.6 for details. 1601 If the server does not support the requested code_challenge_method 1602 transformation, the authorization endpoint MUST return the 1603 authorization error response with error value set to invalid_request. 1604 The error_description or the response of error_uri SHOULD explain the 1605 nature of error, e.g., transform algorithm not supported. 1607 If the resource owner denies the access request or if the request 1608 fails for reasons other than a missing or invalid redirect URI, the 1609 authorization server informs the client by adding the following 1610 parameters to the query component of the redirect URI using the 1611 application/x-www-form-urlencoded format, per Appendix B: 1613 "error": REQUIRED. A single ASCII [USASCII] error code from the 1614 following: 1616 "invalid_request": The request is missing a required parameter, 1617 includes an invalid parameter value, includes a parameter more 1618 than once, or is otherwise malformed. 1620 "unauthorized_client": The client is not authorized to request an 1621 authorization code using this method. 1623 "access_denied": The resource owner or authorization server 1624 denied the request. 1626 "unsupported_response_type": The authorization server does not 1627 support obtaining an authorization code using this method. 1629 "invalid_scope": The requested scope is invalid, unknown, or 1630 malformed. 1632 "server_error": The authorization server encountered an 1633 unexpected condition that prevented it from fulfilling the 1634 request. (This error code is needed because a 500 Internal 1635 Server Error HTTP status code cannot be returned to the client 1636 via an HTTP redirect.) 1638 "temporarily_unavailable": The authorization server is currently 1639 unable to handle the request due to a temporary overloading or 1640 maintenance of the server. (This error code is needed because 1641 a 503 Service Unavailable HTTP status code cannot be returned 1642 to the client via an HTTP redirect.) 1644 Values for the error parameter MUST NOT include characters outside 1645 the set %x20-21 / %x23-5B / %x5D-7E. 1647 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1648 providing additional information, used to assist the client 1649 developer in understanding the error that occurred. Values for 1650 the error_description parameter MUST NOT include characters 1651 outside the set %x20-21 / %x23-5B / %x5D-7E. 1653 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1654 with information about the error, used to provide the client 1655 developer with additional information about the error. Values for 1656 the error_uri parameter MUST conform to the URI-reference syntax 1657 and thus MUST NOT include characters outside the set %x21 / 1658 %x23-5B / %x5D-7E. 1660 "state": REQUIRED if a state parameter was present in the client 1661 authorization request. The exact value received from the client. 1663 For example, the authorization server redirects the user agent by 1664 sending the following HTTP response: 1666 HTTP/1.1 302 Found 1667 Location: https://client.example.com/cb?error=access_denied&state=xyz 1669 4.1.3. Token Endpoint Extension 1671 The authorization grant type is identified at the token endpoint with 1672 the grant_type value of authorization_code. 1674 If this value is set, the following additional token request 1675 parameters beyond Section 3.2.2 are required: 1677 "code": REQUIRED. The authorization code received from the 1678 authorization server. 1680 "redirect_uri": REQUIRED, if the redirect_uri parameter was included 1681 in the authorization request as described in Section 4.1.1, in 1682 which case their values MUST be identical. If no redirect_uri was 1683 included in the authorization request, this parameter is OPTIONAL. 1685 "code_verifier": REQUIRED, if the code_challenge parameter was 1686 included in the authorization request. MUST NOT be used 1687 otherwise. The original code verifier string. 1689 For example, the client makes the following HTTP request (with extra 1690 line breaks for display purposes only): 1692 POST /token HTTP/1.1 1693 Host: server.example.com 1694 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1695 Content-Type: application/x-www-form-urlencoded 1697 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1698 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1699 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1701 In addition to the processing rules in Section 3.2.2, the 1702 authorization server MUST: 1704 * ensure that the authorization code was issued to the authenticated 1705 confidential or credentialed client, or if the client is public, 1706 ensure that the code was issued to client_id in the request, 1708 * verify that the authorization code is valid, 1710 * verify that the code_verifier parameter is present if and only if 1711 a code_challenge parameter was present in the authorization 1712 request, 1714 * if a code_verifier is present, verify the code_verifier by 1715 calculating the code challenge from the received code_verifier and 1716 comparing it with the previously associated code_challenge, after 1717 first transforming it according to the code_challenge_method 1718 method specified by the client, and 1720 * ensure that the redirect_uri parameter is present if the 1721 redirect_uri parameter was included in the initial authorization 1722 request as described in Section 4.1.1, and if included ensure that 1723 their values are identical. 1725 4.2. Client Credentials Grant 1727 The client can request an access token using only its client 1728 credentials (or other supported means of authentication) when the 1729 client is requesting access to the protected resources under its 1730 control, or those of another resource owner that have been previously 1731 arranged with the authorization server (the method of which is beyond 1732 the scope of this specification). 1734 The client credentials grant type MUST only be used by confidential 1735 or credentialed clients. 1737 +---------+ +---------------+ 1738 | | | | 1739 | |>--(1)- Client Authentication --->| Authorization | 1740 | Client | | Server | 1741 | |<--(2)---- Access Token ---------<| | 1742 | | | | 1743 +---------+ +---------------+ 1745 Figure 4: Client Credentials Grant 1747 The use of the client credentials grant illustrated in Figure 4 1748 includes the following steps: 1750 (1) The client authenticates with the authorization server and 1751 requests an access token from the token endpoint. 1753 (2) The authorization server authenticates the client, and if valid, 1754 issues an access token. 1756 4.2.1. Token Endpoint Extension 1758 The authorization grant type is identified at the token endpoint with 1759 the grant_type value of client_credentials. 1761 If this value is set, no additional parameters beyond Section 3.2.2 1762 are required/supported: 1764 For example, the client makes the following HTTP request using 1765 transport-layer security (with extra line breaks for display purposes 1766 only): 1768 POST /token HTTP/1.1 1769 Host: server.example.com 1770 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1771 Content-Type: application/x-www-form-urlencoded 1773 grant_type=client_credentials 1775 The authorization server MUST authenticate the client. 1777 4.3. Refresh Token Grant 1779 The refresh token is a credential issued by the authorization server 1780 to a client, which can be used to obtain new (fresh) access tokens 1781 based on an existing grant. The client uses this option either 1782 because the previous access token has expired or the client 1783 previously obtained an access token with a scope more narrow than 1784 approved by the respective grant and later requires an access token 1785 with a different scope under the same grant. 1787 Refresh tokens MUST be kept confidential in transit and storage, and 1788 shared only among the authorization server and the client to whom the 1789 refresh tokens were issued. The authorization server MUST maintain 1790 the binding between a refresh token and the client to whom it was 1791 issued. 1793 The authorization server MUST verify the binding between the refresh 1794 token and client identity whenever the client identity can be 1795 authenticated. When client authentication is not possible, the 1796 authorization server SHOULD issue sender-constrained refresh tokens 1797 or use refresh token rotation as described in (#refreshing-an-access- 1798 token). 1800 The authorization server MUST ensure that refresh tokens cannot be 1801 generated, modified, or guessed to produce valid refresh tokens by 1802 unauthorized parties. 1804 4.3.1. Token Endpoint Extension 1806 The authorization grant type is identified at the token endpoint with 1807 the grant_type value of refresh_token. 1809 If this value is set, the following additional parameters beyond 1810 Section 3.2.2 are required/supported: 1812 "refresh_token": REQUIRED. The refresh token issued to the client. 1814 Because refresh tokens are typically long-lasting credentials used to 1815 request additional access tokens, the refresh token is bound to the 1816 client to which it was issued. Confidential or credentialed clients 1817 MUST authenticate with the authorization server as described in 1818 Section 3.2.1. 1820 For example, the client makes the following HTTP request using 1821 transport-layer security (with extra line breaks for display purposes 1822 only): 1824 POST /token HTTP/1.1 1825 Host: server.example.com 1826 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1827 Content-Type: application/x-www-form-urlencoded 1829 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1831 In addition to the processing rules in Section 3.2.2, the 1832 authorization server MUST: 1834 * validate the refresh token. 1836 Authorization servers SHOULD utilize one of these methods to detect 1837 refresh token replay by malicious actors for public clients: 1839 * _Sender-constrained refresh tokens:_ the authorization server 1840 cryptographically binds the refresh token to a certain client 1841 instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705], 1842 [I-D.ietf-oauth-dpop], or another suitable method. 1844 * _Refresh token rotation:_ the authorization server issues a new 1845 refresh token with every access token refresh response. The 1846 previous refresh token is invalidated but information about the 1847 relationship is retained by the authorization server. If a 1848 refresh token is compromised and subsequently used by both the 1849 attacker and the legitimate client, one of them will present an 1850 invalidated refresh token, which will inform the authorization 1851 server of the breach. The authorization server cannot determine 1852 which party submitted the invalid refresh token, but it will 1853 revoke the active refresh token. This stops the attack at the 1854 cost of forcing the legitimate client to obtain a fresh 1855 authorization grant. 1857 Implementation note: the grant to which a refresh token belongs may 1858 be encoded into the refresh token itself. This can enable an 1859 authorization server to efficiently determine the grant to which a 1860 refresh token belongs, and by extension, all refresh tokens that need 1861 to be revoked. Authorization servers MUST ensure the integrity of 1862 the refresh token value in this case, for example, using signatures. 1864 4.3.2. Refresh Token Response 1866 If valid and authorized, the authorization server issues an access 1867 token as described in Section 3.2.3. 1869 The authorization server MAY issue a new refresh token, in which case 1870 the client MUST discard the old refresh token and replace it with the 1871 new refresh token. 1873 The authorization server MAY revoke the old refresh token after 1874 issuing a new refresh token to the client. If a new refresh token is 1875 issued, the refresh token scope MUST be identical to that of the 1876 refresh token included by the client in the request. 1878 Authorization servers MAY revoke refresh tokens automatically in case 1879 of a security event, such as: 1881 * password change 1882 * logout at the authorization server 1884 Refresh tokens SHOULD expire if the client has been inactive for some 1885 time, i.e., the refresh token has not been used to obtain new access 1886 tokens for some time. The expiration time is at the discretion of 1887 the authorization server. It might be a global value or determined 1888 based on the client policy or the grant associated with the refresh 1889 token (and its sensitivity). 1891 4.4. Extension Grants 1893 The client uses an extension grant type by specifying the grant type 1894 using an absolute URI (defined by the authorization server) as the 1895 value of the grant_type parameter of the token endpoint, and by 1896 adding any additional parameters necessary. 1898 For example, to request an access token using the Device 1899 Authorization Grant as defined by [RFC8628] after the user has 1900 authorized the client on a separate device, the client makes the 1901 following HTTP request (with extra line breaks for display purposes 1902 only): 1904 POST /token HTTP/1.1 1905 Host: server.example.com 1906 Content-Type: application/x-www-form-urlencoded 1908 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code 1909 &device_code=GmRhmhcxhwEzkoEqiMEg_DnyEysNkuNhszIySk9eS 1910 &client_id=C409020731 1912 If the access token request is valid and authorized, the 1913 authorization server issues an access token and optional refresh 1914 token as described in Section 3.2.3. If the request failed client 1915 authentication or is invalid, the authorization server returns an 1916 error response as described in Section 3.2.3.1. 1918 5. Accessing Protected Resources 1920 The client accesses protected resources by presenting the access 1921 token to the resource server. The resource server MUST validate the 1922 access token and ensure that it has not expired and that its scope 1923 covers the requested resource. The methods used by the resource 1924 server to validate the access token (as well as any error responses) 1925 are beyond the scope of this specification, but generally involve an 1926 interaction or coordination between the resource server and the 1927 authorization server. For example, when the resource server and 1928 authorization server are colocated or are part of the same system, 1929 they may share a database or other storage; when the two components 1930 are operated independently, they may use Token Introspection 1931 [RFC7662] or a structured access token format such as a JWT 1932 [RFC9068]. 1934 The method in which the client utilizes the access token to access 1935 protected resources at the resource server depends on the type of 1936 access token issued by the authorization server. Typically, it 1937 involves using the HTTP Authorization request header field [RFC7235] 1938 with an authentication scheme defined by the specification of the 1939 access token type used, such as Bearer, defined below. 1941 5.1. Access Token Types 1943 The access token type provides the client with the information 1944 required to successfully utilize the access token to make a protected 1945 resource request (along with type-specific attributes). The client 1946 MUST NOT use an access token if it does not understand the token 1947 type. 1949 For example, the Bearer token type defined in this specification is 1950 utilized by simply including the access token string in the request: 1952 GET /resource/1 HTTP/1.1 1953 Host: example.com 1954 Authorization: Bearer mF_9.B5f-4.1JqM 1956 The above example is provided for illustration purposes only. 1958 Each access token type definition specifies the additional attributes 1959 (if any) sent to the client together with the access_token response 1960 parameter. It also defines the HTTP authentication method used to 1961 include the access token when making a protected resource request. 1963 5.2. Bearer Tokens 1965 A Bearer Token is a security token with the property that any party 1966 in possession of the token (a "bearer") can use the token in any way 1967 that any other party in possession of it can. Using a Bearer Token 1968 does not require a bearer to prove possession of cryptographic key 1969 material (proof-of-possession). 1971 Bearer Tokens may be enhanced with proof-of-possession specifications 1972 such as mTLS [RFC8705] to provide proof-of-possession 1973 characteristics. 1975 To protect against access token disclosure, the communication 1976 interaction between the client and the resource server MUST utilize 1977 confidentiality and integrity protection as described in Section 1.5. 1979 To mitigate the risk of access token capture and replay, the lifetime 1980 of the token MUST be limited. One means of achieving this is by 1981 putting a validity time field inside the protected part of the token. 1982 Note that using short-lived tokens reduces the impact of them being 1983 leaked. 1985 There is no requirement on the particular structure or format of a 1986 bearer token, as described in Section 5. If a bearer token is a 1987 reference to authorization information, such references MUST be 1988 infeasible for an attacker to guess, such as using a sufficiently 1989 long cryptographically random string. If a bearer token uses an 1990 encoding mechanism to contain the authorization information in the 1991 token itself, the access token MUST use integrity protection 1992 sufficient to prevent the token from being modified. One example of 1993 an encoding and signing mechanism for access tokens is described in 1994 JSON Web Token Profile for Access Tokens [RFC9068]. 1996 5.2.1. Authenticated Requests 1998 This section defines two methods of sending Bearer tokens in resource 1999 requests to resource servers. Clients MUST use one of the two 2000 methods defined below, and MUST NOT use more than one method to 2001 transmit the token in each request. 2003 In particular, clients MUST NOT send the access token in a URI query 2004 parameter, and resource servers MUST ignore access tokens in a URI 2005 query parameter. 2007 5.2.1.1. Authorization Request Header Field 2009 When sending the access token in the Authorization request header 2010 field defined by HTTP/1.1 [RFC7235], the client uses the Bearer 2011 authentication scheme to transmit the access token. 2013 For example: 2015 GET /resource HTTP/1.1 2016 Host: server.example.com 2017 Authorization: Bearer mF_9.B5f-4.1JqM 2019 The syntax of the Authorization header field for this scheme follows 2020 the usage of the Basic scheme defined in Section 2 of [RFC2617]. 2021 Note that, as with Basic, it does not conform to the generic syntax 2022 defined in Section 1.2 of [RFC2617] but is compatible with the 2023 general authentication framework in HTTP 1.1 Authentication 2024 [RFC7235], although it does not follow the preferred practice 2025 outlined therein in order to reflect existing deployments. The 2026 syntax for Bearer credentials is as follows: 2028 b64token = 1*( ALPHA / DIGIT / 2029 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 2030 credentials = "Bearer" 1*SP b64token 2032 Clients SHOULD make authenticated requests with a bearer token using 2033 the Authorization request header field with the Bearer HTTP 2034 authorization scheme. Resource servers MUST support this method. 2036 5.2.1.2. Form-Encoded Body Parameter 2038 When sending the access token in the HTTP request payload, the client 2039 adds the access token to the request-body using the access_token 2040 parameter. The client MUST NOT use this method unless all of the 2041 following conditions are met: 2043 * The HTTP request entity-header includes the Content-Type header 2044 field set to application/x-www-form-urlencoded. 2046 * The payload follows the encoding requirements of the application/ 2047 x-www-form-urlencoded content-type as defined by HTML 4.01 2048 [W3C.REC-html401-19991224]. 2050 * The HTTP request payload is single-part. 2052 * The content to be encoded in the payload MUST consist entirely of 2053 ASCII [USASCII] characters. 2055 * The HTTP request method is one for which the request-body has 2056 defined semantics. In particular, this means that the GET method 2057 MUST NOT be used. 2059 The payload MAY include other request-specific parameters, in which 2060 case the access_token parameter MUST be properly separated from the 2061 request-specific parameters using & character(s) (ASCII code 38). 2063 For example, the client makes the following HTTP request using 2064 transport-layer security: 2066 POST /resource HTTP/1.1 2067 Host: server.example.com 2068 Content-Type: application/x-www-form-urlencoded 2070 access_token=mF_9.B5f-4.1JqM 2072 The application/x-www-form-urlencoded method SHOULD NOT be used 2073 except in application contexts where participating clients do not 2074 have access to the Authorization request header field. Resource 2075 servers MAY support this method. 2077 5.2.2. The WWW-Authenticate Response Header Field 2079 If the protected resource request does not include authentication 2080 credentials or does not contain an access token that enables access 2081 to the protected resource, the resource server MUST include the HTTP 2082 WWW-Authenticate response header field; it MAY include it in response 2083 to other conditions as well. The WWW-Authenticate header field uses 2084 the framework defined by HTTP/1.1 [RFC7235]. 2086 All challenges for this token type MUST use the auth-scheme value 2087 Bearer. This scheme MUST be followed by one or more auth-param 2088 values. The auth-param attributes used or defined by this 2089 specification for this token type are as follows. Other auth-param 2090 attributes MAY be used as well. 2092 A realm attribute MAY be included to indicate the scope of protection 2093 in the manner described in HTTP/1.1 [RFC7235]. The realm attribute 2094 MUST NOT appear more than once. 2096 The scope attribute is defined in Section 3.2.2.1. The scope 2097 attribute is a space-delimited list of case-sensitive scope values 2098 indicating the required scope of the access token for accessing the 2099 requested resource. scope values are implementation defined; there is 2100 no centralized registry for them; allowed values are defined by the 2101 authorization server. The order of scope values is not significant. 2102 In some cases, the scope value will be used when requesting a new 2103 access token with sufficient scope of access to utilize the protected 2104 resource. Use of the scope attribute is OPTIONAL. The scope 2105 attribute MUST NOT appear more than once. The scope value is 2106 intended for programmatic use and is not meant to be displayed to 2107 end-users. 2109 Two example scope values follow; these are taken from the OpenID 2110 Connect [OpenID.Messages] and the Open Authentication Technology 2111 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 2112 OAuth 2.0 use cases, respectively: 2114 scope="openid profile email" 2115 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 2117 If the protected resource request included an access token and failed 2118 authentication, the resource server SHOULD include the error 2119 attribute to provide the client with the reason why the access 2120 request was declined. The parameter value is described in 2121 Section 5.2.3. In addition, the resource server MAY include the 2122 error_description attribute to provide developers a human-readable 2123 explanation that is not meant to be displayed to end-users. It also 2124 MAY include the error_uri attribute with an absolute URI identifying 2125 a human-readable web page explaining the error. The error, 2126 error_description, and error_uri attributes MUST NOT appear more than 2127 once. 2129 Values for the scope attribute (specified in Appendix A.4) MUST NOT 2130 include characters outside the set %x21 / %x23-5B / %x5D-7E for 2131 representing scope values and %x20 for delimiters between scope 2132 values. Values for the error and error_description attributes 2133 (specified in Appendixes A.7 and A.8) MUST NOT include characters 2134 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 2135 error_uri attribute (specified in Appendix A.9 of) MUST conform to 2136 the URI-reference syntax and thus MUST NOT include characters outside 2137 the set %x21 / %x23-5B / %x5D-7E. 2139 For example, in response to a protected resource request without 2140 authentication: 2142 HTTP/1.1 401 Unauthorized 2143 WWW-Authenticate: Bearer realm="example" 2145 And in response to a protected resource request with an 2146 authentication attempt using an expired access token: 2148 HTTP/1.1 401 Unauthorized 2149 WWW-Authenticate: Bearer realm="example", 2150 error="invalid_token", 2151 error_description="The access token expired" 2153 5.2.3. Error Codes 2155 When a request fails, the resource server responds using the 2156 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2157 includes one of the following error codes in the response: 2159 "invalid_request": The request is missing a required parameter, 2160 includes an unsupported parameter or parameter value, repeats the 2161 same parameter, uses more than one method for including an access 2162 token, or is otherwise malformed. The resource server SHOULD 2163 respond with the HTTP 400 (Bad Request) status code. 2165 "invalid_token": The access token provided is expired, revoked, 2166 malformed, or invalid for other reasons. The resource SHOULD 2167 respond with the HTTP 401 (Unauthorized) status code. The client 2168 MAY request a new access token and retry the protected resource 2169 request. 2171 "insufficient_scope": The request requires higher privileges 2172 (scopes) than provided by the scopes granted to the client and 2173 represented by the access token. 2175 The resource server SHOULD respond with the HTTP 403 (Forbidden) 2176 status code and MAY include the scope attribute with the scope 2177 necessary to access the protected resource. 2179 If the request lacks any authentication information (e.g., the client 2180 was unaware that authentication is necessary or attempted using an 2181 unsupported authentication method), the resource server SHOULD NOT 2182 include an error code or other error information. 2184 For example: 2186 HTTP/1.1 401 Unauthorized 2187 WWW-Authenticate: Bearer realm="example" 2189 5.3. Error Response 2191 If a resource access request fails, the resource server SHOULD inform 2192 the client of the error. The method by which the resource server 2193 does this is determined by the particular token type, such as the 2194 description of Bearer tokens in Section 5.2.3. 2196 5.3.1. Extension Token Types 2198 [RFC6750] establishes a common registry in Section 11.4 2199 (https://tools.ietf.org/html/rfc6749#section-11.4) for error values 2200 to be shared among OAuth token authentication schemes. 2202 New authentication schemes designed primarily for OAuth token 2203 authentication SHOULD define a mechanism for providing an error 2204 status code to the client, in which the error values allowed are 2205 registered in the error registry established by this specification. 2207 Such schemes MAY limit the set of valid error codes to a subset of 2208 the registered values. If the error code is returned using a named 2209 parameter, the parameter name SHOULD be error. 2211 Other schemes capable of being used for OAuth token authentication, 2212 but not primarily designed for that purpose, MAY bind their error 2213 values to the registry in the same manner. 2215 New authentication schemes MAY choose to also specify the use of the 2216 error_description and error_uri parameters to return error 2217 information in a manner parallel to their usage in this 2218 specification. 2220 6. Extensibility 2222 6.1. Defining Access Token Types 2224 Access token types can be defined in one of two ways: registered in 2225 the Access Token Types registry (following the procedures in 2226 Section 11.1 of [RFC6749]), or by using a unique absolute URI as its 2227 name. 2229 Types utilizing a URI name SHOULD be limited to vendor-specific 2230 implementations that are not commonly applicable, and are specific to 2231 the implementation details of the resource server where they are 2232 used. 2234 All other types MUST be registered. Type names MUST conform to the 2235 type-name ABNF. If the type definition includes a new HTTP 2236 authentication scheme, the type name SHOULD be identical to the HTTP 2237 authentication scheme name (as defined by [RFC2617]). The token type 2238 example is reserved for use in examples. 2240 type-name = 1*name-char 2241 name-char = "-" / "." / "_" / DIGIT / ALPHA 2243 6.2. Defining New Endpoint Parameters 2245 New request or response parameters for use with the authorization 2246 endpoint or the token endpoint are defined and registered in the 2247 OAuth Parameters registry following the procedure in Section 11.2 of 2248 [RFC6749]. 2250 Parameter names MUST conform to the param-name ABNF, and parameter 2251 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2252 to the syntax of an existing parameter). 2254 param-name = 1*name-char 2255 name-char = "-" / "." / "_" / DIGIT / ALPHA 2257 Unregistered vendor-specific parameter extensions that are not 2258 commonly applicable and that are specific to the implementation 2259 details of the authorization server where they are used SHOULD 2260 utilize a vendor-specific prefix that is not likely to conflict with 2261 other registered values (e.g., begin with 'companyname_'). 2263 6.3. Defining New Authorization Grant Types 2265 New authorization grant types can be defined by assigning them a 2266 unique absolute URI for use with the grant_type parameter. If the 2267 extension grant type requires additional token endpoint parameters, 2268 they MUST be registered in the OAuth Parameters registry as described 2269 by Section 11.2 of [RFC6749]. 2271 6.4. Defining New Authorization Endpoint Response Types 2273 New response types for use with the authorization endpoint are 2274 defined and registered in the Authorization Endpoint Response Types 2275 registry following the procedure in Section 11.3 of [RFC6749]. 2276 Response type names MUST conform to the response-type ABNF. 2278 response-type = response-name *( SP response-name ) 2279 response-name = 1*response-char 2280 response-char = "_" / DIGIT / ALPHA 2282 If a response type contains one or more space characters (%x20), it 2283 is compared as a space-delimited list of values in which the order of 2284 values does not matter. Only one order of values can be registered, 2285 which covers all other arrangements of the same set of values. 2287 For example, an extension can define and register the code 2288 other_token response type. Once registered, the same combination 2289 cannot be registered as other_token code, but both values can be used 2290 to denote the same response type. 2292 6.5. Defining Additional Error Codes 2294 In cases where protocol extensions (i.e., access token types, 2295 extension parameters, or extension grant types) require additional 2296 error codes to be used with the authorization code grant error 2297 response (Section 4.1.2.1), the token error response 2298 (Section 3.2.3.1), or the resource access error response 2299 (Section 5.3), such error codes MAY be defined. 2301 Extension error codes MUST be registered (following the procedures in 2302 Section 11.4 of [RFC6749]) if the extension they are used in 2303 conjunction with is a registered access token type, a registered 2304 endpoint parameter, or an extension grant type. Error codes used 2305 with unregistered extensions MAY be registered. 2307 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2308 an identifying name when possible. For example, an error identifying 2309 an invalid value set to the extension parameter example SHOULD be 2310 named example_invalid. 2312 error = 1*error-char 2313 error-char = %x20-21 / %x23-5B / %x5D-7E 2315 7. Security Considerations 2317 As a flexible and extensible framework, OAuth's security 2318 considerations depend on many factors. The following sections 2319 provide implementers with security guidelines focused on the three 2320 client profiles described in Section 2.1: web application, browser- 2321 based application, and native application. 2323 A comprehensive OAuth security model and analysis, as well as 2324 background for the protocol design, is provided by [RFC6819] and 2325 [I-D.ietf-oauth-security-topics]. 2327 7.1. Access Token Security Considerations 2329 7.1.1. Security Threats 2331 The following list presents several common threats against protocols 2332 utilizing some form of tokens. This list of threats is based on NIST 2333 Special Publication 800-63 [NIST800-63]. 2335 7.1.1.1. Access token manufacture/modification 2337 An attacker may generate a bogus access token or modify the token 2338 contents (such as the authentication or attribute statements) of an 2339 existing token, causing the resource server to grant inappropriate 2340 access to the client. For example, an attacker may modify the token 2341 to extend the validity period; a malicious client may modify the 2342 assertion to gain access to information that they should not be able 2343 to view. 2345 7.1.1.2. Access token disclosure 2347 Access tokens may contain authentication and attribute statements 2348 that include sensitive information. 2350 7.1.1.3. Access token redirect 2352 An attacker uses an access token generated for consumption by one 2353 resource server to gain access to a different resource server that 2354 mistakenly believes the token to be for it. 2356 7.1.1.4. Access token replay 2358 An attacker attempts to use an access token that has already been 2359 used with that resource server in the past. 2361 7.1.2. Threat Mitigation 2363 A large range of threats can be mitigated by protecting the contents 2364 of the access token by using a digital signature. 2366 Alternatively, a bearer token can contain a reference to 2367 authorization information, rather than encoding the information 2368 directly. Using a reference may require an extra interaction between 2369 a server and the access token issuer to resolve the reference to the 2370 authorization information. The mechanics of such an interaction are 2371 not defined by this specification. 2373 This document does not specify the encoding or the contents of the 2374 access token; hence, detailed recommendations about the means of 2375 guaranteeing access token integrity protection are outside the scope 2376 of this specification. One example of an encoding and signing 2377 mechanism for access tokens is described in JSON Web Token Profile 2378 for Access Tokens [RFC9068]. 2380 To deal with access token redirects, it is important for the 2381 authorization server to include the identity of the intended 2382 recipients (the audience), typically a single resource server (or a 2383 list of resource servers), in the token. Restricting the use of the 2384 token to a specific scope is also RECOMMENDED. 2386 If cookies are transmitted without TLS protection, any information 2387 contained in them is at risk of disclosure. Therefore, Bearer tokens 2388 MUST NOT be stored in cookies that can be sent in the clear, as any 2389 information in them is at risk of disclosure. See "HTTP State 2390 Management Mechanism" [RFC6265] for security considerations about 2391 cookies. 2393 In some deployments, including those utilizing load balancers, the 2394 TLS connection to the resource server terminates prior to the actual 2395 server that provides the resource. This could leave the token 2396 unprotected between the front-end server where the TLS connection 2397 terminates and the back-end server that provides the resource. In 2398 such deployments, sufficient measures MUST be employed to ensure 2399 confidentiality of the access token between the front-end and back- 2400 end servers; encryption of the token is one such possible measure. 2402 7.1.3. Summary of Recommendations 2403 7.1.3.1. Safeguard bearer tokens 2405 Client implementations MUST ensure that bearer tokens are not leaked 2406 to unintended parties, as they will be able to use them to gain 2407 access to protected resources. This is the primary security 2408 consideration when using bearer tokens and underlies all the more 2409 specific recommendations that follow. 2411 7.1.3.2. Validate TLS certificate chains 2413 The client MUST validate the TLS certificate chain when making 2414 requests to protected resources. Failing to do so may enable DNS 2415 hijacking attacks to steal the token and gain unintended access. 2417 7.1.3.3. Always use TLS (https) 2419 Clients MUST always use TLS (https) or equivalent transport security 2420 when making requests with bearer tokens. Failing to do so exposes 2421 the token to numerous attacks that could give attackers unintended 2422 access. 2424 7.1.3.4. Don't store bearer tokens in HTTP cookies 2426 Implementations MUST NOT store bearer tokens within cookies that can 2427 be sent in the clear (which is the default transmission mode for 2428 cookies). Implementations that do store bearer tokens in cookies 2429 MUST take precautions against cross-site request forgery. 2431 7.1.3.5. Issue short-lived bearer tokens 2433 Authorization servers SHOULD issue short-lived bearer tokens, 2434 particularly when issuing tokens to clients that run within a web 2435 browser or other environments where information leakage may occur. 2436 Using short-lived bearer tokens can reduce the impact of them being 2437 leaked. 2439 7.1.3.6. Issue scoped bearer tokens 2441 Authorization servers SHOULD issue bearer tokens that contain an 2442 audience restriction, scoping their use to the intended relying party 2443 or set of relying parties. 2445 7.1.3.7. Don't pass bearer tokens in page URLs 2447 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2448 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2449 message headers or message bodies for which confidentiality measures 2450 are taken. Browsers, web servers, and other software may not 2451 adequately secure URLs in the browser history, web server logs, and 2452 other data structures. If bearer tokens are passed in page URLs, 2453 attackers might be able to steal them from the history data, logs, or 2454 other unsecured locations. 2456 7.1.4. Token Replay Prevention 2458 A sender-constrained access token scopes the applicability of an 2459 access token to a certain sender. This sender is obliged to 2460 demonstrate knowledge of a certain secret as prerequisite for the 2461 acceptance of that access token at the recipient (e.g., a resource 2462 server). 2464 Authorization and resource servers SHOULD use mechanisms for sender- 2465 constrained access tokens to prevent token replay as described in 2466 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2467 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2469 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2470 terminated at an intermediary, refer to Section 4.11 of 2471 [I-D.ietf-oauth-security-topics] for further security advice. 2473 7.1.5. Access Token Privilege Restriction 2475 The privileges associated with an access token SHOULD be restricted 2476 to the minimum required for the particular application or use case. 2477 This prevents clients from exceeding the privileges authorized by the 2478 resource owner. It also prevents users from exceeding their 2479 privileges authorized by the respective security policy. Privilege 2480 restrictions also help to reduce the impact of access token leakage. 2482 In particular, access tokens SHOULD be restricted to certain resource 2483 servers (audience restriction), preferably to a single resource 2484 server. To put this into effect, the authorization server associates 2485 the access token with certain resource servers and every resource 2486 server is obliged to verify, for every request, whether the access 2487 token sent with that request was meant to be used for that particular 2488 resource server. If not, the resource server MUST refuse to serve 2489 the respective request. Clients and authorization servers MAY 2490 utilize the parameters scope or resource as specified in this 2491 document and [RFC8707], respectively, to determine the resource 2492 server they want to access. 2494 Additionally, access tokens SHOULD be restricted to certain resources 2495 and actions on resource servers or resources. To put this into 2496 effect, the authorization server associates the access token with the 2497 respective resource and actions and every resource server is obliged 2498 to verify, for every request, whether the access token sent with that 2499 request was meant to be used for that particular action on the 2500 particular resource. If not, the resource server must refuse to 2501 serve the respective request. Clients and authorization servers MAY 2502 utilize the parameter scope and authorization_details as specified in 2503 [I-D.ietf-oauth-rar] to determine those resources and/or actions. 2505 7.2. Client Authentication 2507 Depending on the overall process of client registration and 2508 credential lifecycle management, this may affect the confidence an 2509 authorization server has in a particular client. For example, 2510 authentication of a dynamically registered client does not prove the 2511 identity of the client, it only ensures that repeated requests to the 2512 authorization server were made from the same client instance. Such 2513 clients may be limited in terms of which scopes they are allowed to 2514 request, or may have other limitations such as shorter token 2515 lifetimes. In contrast, if there is a registered application whose 2516 developer's identity was verified, who signed a contract and is 2517 issued a client secret that is only used in a secure backend service, 2518 the authorization server might allow this client to request more 2519 sensitive scopes or to be issued longer-lasting tokens. 2521 7.3. Client Impersonation 2523 A malicious client can impersonate another client and obtain access 2524 to protected resources if the impersonated client fails to, or is 2525 unable to, keep its client credentials confidential. 2527 The authorization server SHOULD enforce explicit resource owner 2528 authentication and provide the resource owner with information about 2529 the client and the requested authorization scope and lifetime. It is 2530 up to the resource owner to review the information in the context of 2531 the current client and to authorize or deny the request. 2533 The authorization server SHOULD NOT process repeated authorization 2534 requests automatically (without active resource owner interaction) 2535 without authenticating the client or relying on other measures to 2536 ensure that the repeated request comes from the original client and 2537 not an impersonator. 2539 7.3.1. Impersonation of Native Apps 2541 As stated above, the authorization server SHOULD NOT process 2542 authorization requests automatically without user consent or 2543 interaction, except when the identity of the client can be assured. 2544 This includes the case where the user has previously approved an 2545 authorization request for a given client ID - unless the identity of 2546 the client can be proven, the request SHOULD be processed as if no 2547 previous request had been approved. 2549 Measures such as claimed https scheme redirects MAY be accepted by 2550 authorization servers as identity proof. Some operating systems may 2551 offer alternative platform-specific identity features that MAY be 2552 accepted, as appropriate. 2554 7.3.2. Access Token Privilege Restriction 2556 The client SHOULD request access tokens with the minimal scope 2557 necessary. The authorization server SHOULD take the client identity 2558 into account when choosing how to honor the requested scope and MAY 2559 issue an access token with less rights than requested. 2561 The privileges associated with an access token SHOULD be restricted 2562 to the minimum required for the particular application or use case. 2563 This prevents clients from exceeding the privileges authorized by the 2564 resource owner. It also prevents users from exceeding their 2565 privileges authorized by the respective security policy. Privilege 2566 restrictions also help to reduce the impact of access token leakage. 2568 In particular, access tokens SHOULD be restricted to certain resource 2569 servers (audience restriction), preferably to a single resource 2570 server. To put this into effect, the authorization server associates 2571 the access token with certain resource servers and every resource 2572 server is obliged to verify, for every request, whether the access 2573 token sent with that request was meant to be used for that particular 2574 resource server. If not, the resource server MUST refuse to serve 2575 the respective request. Clients and authorization servers MAY 2576 utilize the parameters scope or resource as specified in [RFC8707], 2577 respectively, to determine the resource server they want to access. 2579 7.3.3. Access Token Replay Prevention 2581 Additionally, access tokens SHOULD be restricted to certain resources 2582 and actions on resource servers or resources. To put this into 2583 effect, the authorization server associates the access token with the 2584 respective resource and actions and every resource server is obliged 2585 to verify, for every request, whether the access token sent with that 2586 request was meant to be used for that particular action on the 2587 particular resource. If not, the resource server must refuse to 2588 serve the respective request. Clients and authorization servers MAY 2589 utilize the parameter scope and authorization_details as specified in 2590 [I-D.ietf-oauth-rar] to determine those resources and/or actions. 2592 Authorization and resource servers SHOULD use mechanisms for sender- 2593 constrained access tokens to prevent token replay as described in 2594 (#pop_tokens). A sender-constrained access token scopes the 2595 applicability of an access token to a certain sender. This sender is 2596 obliged to demonstrate knowledge of a certain secret as prerequisite 2597 for the acceptance of that access token at the recipient (e.g., a 2598 resource server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2599 RECOMMENDED. 2601 7.4. Client Impersonating Resource Owner 2603 Resource servers may make access control decisions based on the 2604 identity of the resource owner as communicated in the sub claim 2605 returned by the authorization server in a token introspection 2606 response [RFC7662] or other mechanisms. If a client is able to 2607 choose its own client_id during registration with the authorization 2608 server, then there is a risk that it can register with the same sub 2609 value as a privileged user. A subsequent access token obtained under 2610 the client credentials grant may be mistaken for an access token 2611 authorized by the privileged user if the resource server does not 2612 perform additional checks. 2614 Authorization servers SHOULD NOT allow clients to influence their 2615 client_id or sub value or any other claim if that can cause confusion 2616 with a genuine resource owner. Where this cannot be avoided, 2617 authorization servers MUST provide other means for the resource 2618 server to distinguish between access tokens authorized by a resource 2619 owner from access tokens authorized by the client itself. 2621 7.5. Protecting the Authorization Code Flow 2623 7.5.1. Loopback Redirect Considerations in Native Apps 2625 Loopback interface redirect URIs MAY use the http scheme (i.e., 2626 without TLS). This is acceptable for loopback interface redirect 2627 URIs as the HTTP request never leaves the device. 2629 Clients should open the network port only when starting the 2630 authorization request and close it once the response is returned. 2632 Clients should listen on the loopback network interface only, in 2633 order to avoid interference by other network actors. 2635 Clients should use loopback IP literals rather than the string 2636 localhost as described in Section 8.4.3. 2638 7.5.2. HTTP 307 Redirect 2640 An AS which redirects a request that potentially contains user 2641 credentials MUST NOT use the HTTP 307 status code for redirection. 2642 If an HTTP redirection (and not, for example, JavaScript) is used for 2643 such a request, AS SHOULD use HTTP status code 303 "See Other". 2645 At the authorization endpoint, a typical protocol flow is that the AS 2646 prompts the user to enter their credentials in a form that is then 2647 submitted (using the HTTP POST method) back to the authorization 2648 server. The AS checks the credentials and, if successful, redirects 2649 the user agent to the client's redirect URI. 2651 If the status code 307 were used for redirection, the user agent 2652 would send the user credentials via HTTP POST to the client. 2654 This discloses the sensitive credentials to the client. If the 2655 relying party is malicious, it can use the credentials to impersonate 2656 the user at the AS. 2658 The behavior might be unexpected for developers, but is defined in 2659 [RFC7231], Section 6.4.7. This status code does not require the user 2660 agent to rewrite the POST request to a GET request and thereby drop 2661 the form data in the POST request body. 2663 In the HTTP standard [RFC7231], only the status code 303 2664 unambigiously enforces rewriting the HTTP POST request to an HTTP GET 2665 request. For all other status codes, including the popular 302, user 2666 agents can opt not to rewrite POST to GET requests and therefore to 2667 reveal the user credentials to the client. (In practice, however, 2668 most user agents will only show this behaviour for 307 redirects.) 2670 Therefore, the RECOMMENDED status code for HTTP redirects is 303. 2672 7.6. Authorization Codes 2674 To prevent injection of authorization codes into the client, using 2675 code_challenge and code_verifier is REQUIRED for clients, and 2676 authorization servers MUST enforce their use, unless both of the 2677 following criteria are met: 2679 * The client is a confidential client. 2681 * In the specific deployment and the specific request, there is 2682 reasonable assurance by the authorization server that the client 2683 implements the OpenID Connect nonce mechanism properly. 2685 In this case, using and enforcing code_challenge and code_verifier is 2686 still RECOMMENDED. 2688 The code_challenge or OpenID Connect nonce value MUST be transaction- 2689 specific and securely bound to the client and the user agent in which 2690 the transaction was started. If a transaction leads to an error, 2691 fresh values for code_challenge or nonce MUST be chosen. 2693 Historic note: Although PKCE [RFC7636] (where the code_challenge and 2694 code_verifier parameters were created) was originally designed as a 2695 mechanism to protect native apps, this advice applies to all kinds of 2696 OAuth clients, including web applications and other confidential 2697 clients. 2699 Clients SHOULD use code challenge methods that do not expose the 2700 code_verifier in the authorization request. Otherwise, attackers 2701 that can read the authorization request (cf. Attacker A4 in 2702 (#secmodel)) can break the security provided by this mechanism. 2703 Currently, S256 is the only such method. 2705 When an authorization code arrives at the token endpoint, the 2706 authorization server MUST do the following check: 2708 1. If there was a code_challenge in the authorization request for 2709 which this code was issued, there must be a code_verifier in the 2710 token request, and it MUST be verified according to the steps in 2711 Section 3.2.2. (This is no change from the current behavior in 2712 [RFC7636].) 2714 2. If there was no code_challenge in the authorization request, any 2715 request to the token endpoint containing a code_verifier MUST be 2716 rejected. 2718 Authorization servers MUST provide a way to detect their support for 2719 the code_challenge mechanism. To this end, they MUST either (a) 2720 publish the element code_challenge_methods_supported in their AS 2721 metadata ([RFC8414]) containing the supported code_challenge_methods 2722 (which can be used by the client to detect support) or (b) provide a 2723 deployment-specific way to ensure or determine support by the AS. 2725 7.7. Ensuring Endpoint Authenticity 2727 The risk related to man-in-the-middle attacks is mitigated by the 2728 mandatory use of channel security mechanisms such as [RFC8446] for 2729 communicating with the Authorization and Token Endpoints. See 2730 Section 1.5 for further details. 2732 7.8. Credentials-Guessing Attacks 2734 The authorization server MUST prevent attackers from guessing access 2735 tokens, authorization codes, refresh tokens, resource owner 2736 passwords, and client credentials. 2738 The probability of an attacker guessing generated tokens (and other 2739 credentials not intended for handling by end-users) MUST be less than 2740 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2742 The authorization server MUST utilize other means to protect 2743 credentials intended for end-user usage. 2745 7.9. Phishing Attacks 2747 Wide deployment of this and similar protocols may cause end-users to 2748 become inured to the practice of being redirected to websites where 2749 they are asked to enter their passwords. If end-users are not 2750 careful to verify the authenticity of these websites before entering 2751 their credentials, it will be possible for attackers to exploit this 2752 practice to steal resource owners' passwords. 2754 Service providers should attempt to educate end-users about the risks 2755 phishing attacks pose and should provide mechanisms that make it easy 2756 for end-users to confirm the authenticity of their sites. Client 2757 developers should consider the security implications of how they 2758 interact with the user agent (e.g., external, embedded), and the 2759 ability of the end-user to verify the authenticity of the 2760 authorization server. 2762 See Section 1.5 for further details on mitigating the risk of 2763 phishing attacks. 2765 7.10. Cross-Site Request Forgery 2767 An attacker might attempt to inject a request to the redirect URI of 2768 the legitimate client on the victim's device, e.g., to cause the 2769 client to access resources under the attacker's control. This is a 2770 variant of an attack known as Cross-Site Request Forgery (CSRF). 2772 The traditional countermeasure are CSRF tokens that are bound to the 2773 user agent and passed in the state parameter to the authorization 2774 server as described in [RFC6819]. The same protection is provided by 2775 the code_verifier parameter or the OpenID Connect nonce value. 2777 When using code_verifier instead of state or nonce for CSRF 2778 protection, it is important to note that: 2780 * Clients MUST ensure that the AS supports the code_challenge_method 2781 intended to be used by the client. If an authorization server 2782 does not support the requested method, state or nonce MUST be used 2783 for CSRF protection instead. 2785 * If state is used for carrying application state, and integrity of 2786 its contents is a concern, clients MUST protect state against 2787 tampering and swapping. This can be achieved by binding the 2788 contents of state to the browser session and/or signed/encrypted 2789 state values [I-D.bradley-oauth-jwt-encoded-state]. 2791 AS therefore MUST provide a way to detect their supported code 2792 challenge methods either via AS metadata according to [RFC8414] or 2793 provide a deployment-specific way to ensure or determine support. 2795 7.11. Clickjacking 2797 As described in Section 4.4.1.9 of [RFC6819], the authorization 2798 request is susceptible to clickjacking. An attacker can use this 2799 vector to obtain the user's authentication credentials, change the 2800 scope of access granted to the client, and potentially access the 2801 user's resources. 2803 Authorization servers MUST prevent clickjacking attacks. Multiple 2804 countermeasures are described in [RFC6819], including the use of the 2805 X-Frame-Options HTTP response header field and frame-busting 2806 JavaScript. In addition to those, authorization servers SHOULD also 2807 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2809 To be effective, CSP must be used on the authorization endpoint and, 2810 if applicable, other endpoints used to authenticate the user and 2811 authorize the client (e.g., the device authorization endpoint, login 2812 pages, error pages, etc.). This prevents framing by unauthorized 2813 origins in user agents that support CSP. The client MAY permit being 2814 framed by some other origin than the one used in its redirection 2815 endpoint. For this reason, authorization servers SHOULD allow 2816 administrators to configure allowed origins for particular clients 2817 and/or for clients to register these dynamically. 2819 Using CSP allows authorization servers to specify multiple origins in 2820 a single response header field and to constrain these using flexible 2821 patterns (see [CSP-2] for details). Level 2 of this standard 2822 provides a robust mechanism for protecting against clickjacking by 2823 using policies that restrict the origin of frames (using frame- 2824 ancestors) together with those that restrict the sources of scripts 2825 allowed to execute on an HTML page (by using script-src). A non- 2826 normative example of such a policy is shown in the following listing: 2828 HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 2829 https://ext.example.org:8000 Content-Security-Policy: script-src 2830 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ... 2832 Because some user agents do not support [CSP-2], this technique 2833 SHOULD be combined with others, including those described in 2834 [RFC6819], unless such legacy user agents are explicitly unsupported 2835 by the authorization server. Even in such cases, additional 2836 countermeasures SHOULD still be employed. 2838 7.12. Code Injection and Input Validation 2840 A code injection attack occurs when an input or otherwise external 2841 variable is used by an application unsanitized and causes 2842 modification to the application logic. This may allow an attacker to 2843 gain access to the application device or its data, cause denial of 2844 service, or introduce a wide range of malicious side-effects. 2846 The authorization server and client MUST sanitize (and validate when 2847 possible) any value received - in particular, the value of the state 2848 and redirect_uri parameters. 2850 7.13. Open Redirectors 2852 The following attacks can occur when an AS or client has an open 2853 redirector. An open redirector is an endpoint that forwards a user's 2854 browser to an arbitrary URI obtained from a query parameter. 2856 7.13.1. Client as Open Redirector 2858 Clients MUST NOT expose open redirectors. Attackers may use open 2859 redirectors to produce URLs pointing to the client and utilize them 2860 to exfiltrate authorization codes and access tokens, as described in 2861 (#redir_uri_open_redir). Another abuse case is to produce URLs that 2862 appear to point to the client. This might trick users into trusting 2863 the URL and follow it in their browser. This can be abused for 2864 phishing. 2866 In order to prevent open redirection, clients should only redirect if 2867 the target URLs are whitelisted or if the origin and integrity of a 2868 request can be authenticated. Countermeasures against open 2869 redirection are described by OWASP [owasp_redir]. 2871 7.13.2. Authorization Server as Open Redirector 2873 Just as with clients, attackers could try to utilize a user's trust 2874 in the authorization server (and its URL in particular) for 2875 performing phishing attacks. OAuth authorization servers regularly 2876 redirect users to other web sites (the clients), but must do so in a 2877 safe way. 2879 Section 4.1.2.1 already prevents open redirects by stating that the 2880 AS MUST NOT automatically redirect the user agent in case of an 2881 invalid combination of client_id and redirect_uri. 2883 However, an attacker could also utilize a correctly registered 2884 redirect URI to perform phishing attacks. The attacker could, for 2885 example, register a client via dynamic client registration [RFC7591] 2886 and intentionally send an erroneous authorization request, e.g., by 2887 using an invalid scope value, thus instructing the AS to redirect the 2888 user agent to its phishing site. 2890 The AS MUST take precautions to prevent this threat. Based on its 2891 risk assessment, the AS needs to decide whether it can trust the 2892 redirect URI and SHOULD only automatically redirect the user agent if 2893 it trusts the redirect URI. If the URI is not trusted, the AS MAY 2894 inform the user and rely on the user to make the correct decision. 2896 7.14. Authorization Server Mix-Up Mitigation in Native Apps 2898 (TODO: merge this with the regular mix-up section when it is brought 2899 in) 2901 To protect against a compromised or malicious authorization server 2902 attacking another authorization server used by the same app, it is 2903 REQUIRED that a unique redirect URI is used for each authorization 2904 server used by the app (for example, by varying the path component), 2905 and that authorization responses are rejected if the redirect URI 2906 they were received on doesn't match the redirect URI in an outgoing 2907 authorization request. 2909 The native app MUST store the redirect URI used in the authorization 2910 request with the authorization session data (i.e., along with state 2911 and other related data) and MUST verify that the URI on which the 2912 authorization response was received exactly matches it. 2914 The requirement of Section 8.1, specifically that authorization 2915 servers reject requests with URIs that don't match what was 2916 registered, is also required to prevent such attacks. 2918 7.15. Other Recommendations 2920 Authorization servers SHOULD NOT allow clients to influence their 2921 client_id or sub value or any other claim if that can cause confusion 2922 with a genuine resource owner (see (#client_impersonating)). 2924 8. Native Applications 2926 Native applications are clients installed and executed on the device 2927 used by the resource owner (i.e., desktop application, native mobile 2928 application). Native applications require special consideration 2929 related to security, platform capabilities, and overall end-user 2930 experience. 2932 The authorization endpoint requires interaction between the client 2933 and the resource owner's user agent. The best current practice is to 2934 perform the OAuth authorization request in an external user agent 2935 (typically the browser) rather than an embedded user agent (such as 2936 one implemented with web-views). 2938 The native application can capture the response from the 2939 authorization server using a redirect URI with a scheme registered 2940 with the operating system to invoke the client as the handler, manual 2941 copy-and-paste of the credentials, running a local web server, 2942 installing a user agent extension, or by providing a redirect URI 2943 identifying a server-hosted resource under the client's control, 2944 which in turn makes the response available to the native application. 2946 Previously, it was common for native apps to use embedded user agents 2947 (commonly implemented with web-views) for OAuth authorization 2948 requests. That approach has many drawbacks, including the host app 2949 being able to copy user credentials and cookies as well as the user 2950 needing to authenticate from scratch in each app. See Section 8.5.1 2951 for a deeper analysis of the drawbacks of using embedded user agents 2952 for OAuth. 2954 Native app authorization requests that use the browser are more 2955 secure and can take advantage of the user's authentication state. 2956 Being able to use the existing authentication session in the browser 2957 enables single sign-on, as users don't need to authenticate to the 2958 authorization server each time they use a new app (unless required by 2959 the authorization server policy). 2961 Supporting authorization flows between a native app and the browser 2962 is possible without changing the OAuth protocol itself, as the OAuth 2963 authorization request and response are already defined in terms of 2964 URIs. This encompasses URIs that can be used for inter-app 2965 communication. Some OAuth server implementations that assume all 2966 clients are confidential web clients will need to add an 2967 understanding of public native app clients and the types of redirect 2968 URIs they use to support this best practice. 2970 8.1. Registration of Native App Clients 2972 Except when using a mechanism like Dynamic Client Registration 2973 [RFC7591] to provision per-instance secrets, native apps are 2974 classified as public clients, as defined in Section 2.1; they MUST be 2975 registered with the authorization server as such. Authorization 2976 servers MUST record the client type in the client registration 2977 details in order to identify and process requests accordingly. 2979 8.1.1. Client Authentication of Native Apps 2981 Secrets that are statically included as part of an app distributed to 2982 multiple users should not be treated as confidential secrets, as one 2983 user may inspect their copy and learn the shared secret. For this 2984 reason, it is NOT RECOMMENDED for authorization servers to require 2985 client authentication of public native apps clients using a shared 2986 secret, as this serves little value beyond client identification 2987 which is already provided by the client_id request parameter. 2989 Authorization servers that still require a statically included shared 2990 secret for native app clients MUST treat the client as a public 2991 client (as defined in Section 2.1), and not accept the secret as 2992 proof of the client's identity. Without additional measures, such 2993 clients are subject to client impersonation (see Section 7.3.1). 2995 8.2. Using Inter-App URI Communication for OAuth in Native Apps 2997 Just as URIs are used for OAuth on the web to initiate the 2998 authorization request and return the authorization response to the 2999 requesting website, URIs can be used by native apps to initiate the 3000 authorization request in the device's browser and return the response 3001 to the requesting native app. 3003 By adopting the same methods used on the web for OAuth, benefits seen 3004 in the web context like the usability of a single sign-on session and 3005 the security of a separate authentication context are likewise gained 3006 in the native app context. Reusing the same approach also reduces 3007 the implementation complexity and increases interoperability by 3008 relying on standards-based web flows that are not specific to a 3009 particular platform. 3011 Native apps MUST use an external user agent to perform OAuth 3012 authorization requests. This is achieved by opening the 3013 authorization request in the browser (detailed in Section 8.3) and 3014 using a redirect URI that will return the authorization response back 3015 to the native app (defined in Section 8.4). 3017 8.3. Initiating the Authorization Request from a Native App 3019 Native apps needing user authorization create an authorization 3020 request URI with the authorization code grant type per Section 4.1 3021 using a redirect URI capable of being received by the native app. 3023 The function of the redirect URI for a native app authorization 3024 request is similar to that of a web-based authorization request. 3025 Rather than returning the authorization response to the OAuth 3026 client's server, the redirect URI used by a native app returns the 3027 response to the app. Several options for a redirect URI that will 3028 return the authorization response to the native app in different 3029 platforms are documented in Section 8.4. Any redirect URI that 3030 allows the app to receive the URI and inspect its parameters is 3031 viable. 3033 After constructing the authorization request URI, the app uses 3034 platform-specific APIs to open the URI in an external user agent. 3035 Typically, the external user agent used is the default browser, that 3036 is, the application configured for handling http and https scheme 3037 URIs on the system; however, different browser selection criteria and 3038 other categories of external user agents MAY be used. 3040 This best practice focuses on the browser as the RECOMMENDED external 3041 user agent for native apps. An external user agent designed 3042 specifically for user authorization and capable of processing 3043 authorization requests and responses like a browser MAY also be used. 3044 Other external user agents, such as a native app provided by the 3045 authorization server may meet the criteria set out in this best 3046 practice, including using the same redirect URI properties, but their 3047 use is out of scope for this specification. 3049 Some platforms support a browser feature known as "in-app browser 3050 tabs", where an app can present a tab of the browser within the app 3051 context without switching apps, but still retain key benefits of the 3052 browser such as a shared authentication state and security context. 3053 On platforms where they are supported, it is RECOMMENDED, for 3054 usability reasons, that apps use in-app browser tabs for the 3055 authorization request. 3057 8.4. Receiving the Authorization Response in a Native App 3059 There are several redirect URI options available to native apps for 3060 receiving the authorization response from the browser, the 3061 availability and user experience of which varies by platform. 3063 To fully support native apps, authorization servers MUST offer at 3064 least the three redirect URI options described in the following 3065 subsections to native apps. Native apps MAY use whichever redirect 3066 option suits their needs best, taking into account platform-specific 3067 implementation details. 3069 8.4.1. Private-Use URI Scheme Redirection 3071 Many mobile and desktop computing platforms support inter-app 3072 communication via URIs by allowing apps to register private-use URI 3073 schemes (sometimes colloquially referred to as "custom URL schemes") 3074 like com.example.app. When the browser or another app attempts to 3075 load a URI with a private-use URI scheme, the app that registered it 3076 is launched to handle the request. 3078 To perform an authorization request with a private-use URI scheme 3079 redirect, the native app launches the browser with a standard 3080 authorization request, but one where the redirect URI utilizes a 3081 private-use URI scheme it registered with the operating system. 3083 When choosing a URI scheme to associate with the app, apps MUST use a 3084 URI scheme based on a domain name under their control, expressed in 3085 reverse order, as recommended by Section 3.8 of [RFC7595] for 3086 private-use URI schemes. 3088 For example, an app that controls the domain name app.example.com can 3089 use com.example.app as their scheme. Some authorization servers 3090 assign client identifiers based on domain names, for example, 3091 client1234.usercontent.example.net, which can also be used as the 3092 domain name for the scheme when reversed in the same manner. A 3093 scheme such as myapp, however, would not meet this requirement, as it 3094 is not based on a domain name. 3096 When there are multiple apps by the same publisher, care must be 3097 taken so that each scheme is unique within that group. On platforms 3098 that use app identifiers based on reverse-order domain names, those 3099 identifiers can be reused as the private-use URI scheme for the OAuth 3100 redirect to help avoid this problem. 3102 Following the requirements of Section 3.2 of [RFC3986], as there is 3103 no naming authority for private-use URI scheme redirects, only a 3104 single slash (/) appears after the scheme component. A complete 3105 example of a redirect URI utilizing a private-use URI scheme is: 3107 com.example.app:/oauth2redirect/example-provider 3109 When the authorization server completes the request, it redirects to 3110 the client's redirect URI as it would normally. As the redirect URI 3111 uses a private-use URI scheme, it results in the operating system 3112 launching the native app, passing in the URI as a launch parameter. 3113 Then, the native app uses normal processing for the authorization 3114 response. 3116 8.4.2. Claimed "https" Scheme URI Redirection 3118 Some operating systems allow apps to claim https scheme [RFC7230] 3119 URIs in the domains they control. When the browser encounters a 3120 claimed URI, instead of the page being loaded in the browser, the 3121 native app is launched with the URI supplied as a launch parameter. 3123 Such URIs can be used as redirect URIs by native apps. They are 3124 indistinguishable to the authorization server from a regular web- 3125 based client redirect URI. An example is: 3127 https://app.example.com/oauth2redirect/example-provider 3129 As the redirect URI alone is not enough to distinguish public native 3130 app clients from confidential web clients, it is REQUIRED in 3131 Section 8.1 that the client type be recorded during client 3132 registration to enable the server to determine the client type and 3133 act accordingly. 3135 App-claimed https scheme redirect URIs have some advantages compared 3136 to other native app redirect options in that the identity of the 3137 destination app is guaranteed to the authorization server by the 3138 operating system. For this reason, native apps SHOULD use them over 3139 the other options where possible. 3141 8.4.3. Loopback Interface Redirection 3143 Native apps that are able to open a port on the loopback network 3144 interface without needing special permissions (typically, those on 3145 desktop operating systems) can use the loopback interface to receive 3146 the OAuth redirect. 3148 Loopback redirect URIs use the http scheme and are constructed with 3149 the loopback IP literal and whatever port the client is listening on. 3151 That is, http://127.0.0.1:{port}/{path} for IPv4, and 3152 http://[::1]:{port}/{path} for IPv6. An example redirect using the 3153 IPv4 loopback interface with a randomly assigned port: 3155 http://127.0.0.1:51004/oauth2redirect/example-provider 3157 An example redirect using the IPv6 loopback interface with a randomly 3158 assigned port: 3160 http://[::1]:61023/oauth2redirect/example-provider 3162 While redirect URIs using the name localhost (i.e., 3163 http://localhost:{port}/{path}) function similarly to loopback IP 3164 redirects, the use of localhost is NOT RECOMMENDED. Specifying a 3165 redirect URI with the loopback IP literal rather than localhost 3166 avoids inadvertently listening on network interfaces other than the 3167 loopback interface. It is also less susceptible to client-side 3168 firewalls and misconfigured host name resolution on the user's 3169 device. 3171 The authorization server MUST allow any port to be specified at the 3172 time of the request for loopback IP redirect URIs, to accommodate 3173 clients that obtain an available ephemeral port from the operating 3174 system at the time of the request. 3176 Clients SHOULD NOT assume that the device supports a particular 3177 version of the Internet Protocol. It is RECOMMENDED that clients 3178 attempt to bind to the loopback interface using both IPv4 and IPv6 3179 and use whichever is available. 3181 8.5. Security Considerations in Native Apps 3182 8.5.1. Embedded User Agents in Native Apps 3184 Embedded user agents are a technically possible method for 3185 authorizing native apps. These embedded user agents are unsafe for 3186 use by third parties to the authorization server by definition, as 3187 the app that hosts the embedded user agent can access the user's full 3188 authentication credentials, not just the OAuth authorization grant 3189 that was intended for the app. 3191 In typical web-view-based implementations of embedded user agents, 3192 the host application can record every keystroke entered in the login 3193 form to capture usernames and passwords, automatically submit forms 3194 to bypass user consent, and copy session cookies and use them to 3195 perform authenticated actions as the user. 3197 Even when used by trusted apps belonging to the same party as the 3198 authorization server, embedded user agents violate the principle of 3199 least privilege by having access to more powerful credentials than 3200 they need, potentially increasing the attack surface. 3202 Encouraging users to enter credentials in an embedded user agent 3203 without the usual address bar and visible certificate validation 3204 features that browsers have makes it impossible for the user to know 3205 if they are signing in to the legitimate site; even when they are, it 3206 trains them that it's OK to enter credentials without validating the 3207 site first. 3209 Aside from the security concerns, embedded user agents do not share 3210 the authentication state with other apps or the browser, requiring 3211 the user to log in for every authorization request, which is often 3212 considered an inferior user experience. 3214 8.5.2. Fake External User-Agents in Native Apps 3216 The native app that is initiating the authorization request has a 3217 large degree of control over the user interface and can potentially 3218 present a fake external user agent, that is, an embedded user agent 3219 made to appear as an external user agent. 3221 When all good actors are using external user agents, the advantage is 3222 that it is possible for security experts to detect bad actors, as 3223 anyone faking an external user agent is provably bad. On the other 3224 hand, if good and bad actors alike are using embedded user agents, 3225 bad actors don't need to fake anything, making them harder to detect. 3226 Once a malicious app is detected, it may be possible to use this 3227 knowledge to blacklist the app's signature in malware scanning 3228 software, take removal action (in the case of apps distributed by app 3229 stores) and other steps to reduce the impact and spread of the 3230 malicious app. 3232 Authorization servers can also directly protect against fake external 3233 user agents by requiring an authentication factor only available to 3234 true external user agents. 3236 Users who are particularly concerned about their security when using 3237 in-app browser tabs may also take the additional step of opening the 3238 request in the full browser from the in-app browser tab and complete 3239 the authorization there, as most implementations of the in-app 3240 browser tab pattern offer such functionality. 3242 8.5.3. Malicious External User-Agents in Native Apps 3244 If a malicious app is able to configure itself as the default handler 3245 for https scheme URIs in the operating system, it will be able to 3246 intercept authorization requests that use the default browser and 3247 abuse this position of trust for malicious ends such as phishing the 3248 user. 3250 This attack is not confined to OAuth; a malicious app configured in 3251 this way would present a general and ongoing risk to the user beyond 3252 OAuth usage by native apps. Many operating systems mitigate this 3253 issue by requiring an explicit user action to change the default 3254 handler for http and https scheme URIs. 3256 9. Browser-Based Apps 3258 Browser-based apps are are clients that run in a web browser, 3259 typically written in JavaScript, also known as "single-page apps". 3260 These types of apps have particular security considerations similar 3261 to native apps. 3263 TODO: Bring in the normative text of the browser-based apps BCP when 3264 it is finalized. 3266 10. Differences from OAuth 2.0 3268 This draft consolidates the functionality in OAuth 2.0 [RFC6749], 3269 OAuth 2.0 for Native Apps ([RFC8252]), Proof Key for Code Exchange 3270 ([RFC7636]), OAuth 2.0 for Browser-Based Apps 3271 ([I-D.ietf-oauth-browser-based-apps]), OAuth Security Best Current 3272 Practice ([I-D.ietf-oauth-security-topics]), and Bearer Token Usage 3273 ([RFC6750]). 3275 Where a later draft updates or obsoletes functionality found in the 3276 original [RFC6749], that functionality in this draft is updated with 3277 the normative changes described in a later draft, or removed 3278 entirely. 3280 A non-normative list of changes from OAuth 2.0 is listed below: 3282 * The authorization code grant is extended with the functionality 3283 from PKCE ([RFC7636]) such that the default method of using the 3284 authorization code grant according to this specification requires 3285 the addition of the PKCE parameters 3287 * Redirect URIs must be compared using exact string matching as per 3288 Section 4.1.3 of [I-D.ietf-oauth-security-topics] 3290 * The Implicit grant (response_type=token) is omitted from this 3291 specification as per Section 2.1.2 of 3292 [I-D.ietf-oauth-security-topics] 3294 * The Resource Owner Password Credentials grant is omitted from this 3295 specification as per Section 2.4 of 3296 [I-D.ietf-oauth-security-topics] 3298 * Bearer token usage omits the use of bearer tokens in the query 3299 string of URIs as per Section 4.3.2 of 3300 [I-D.ietf-oauth-security-topics] 3302 * Refresh tokens for public clients must either be sender- 3303 constrained or one-time use as per Section 4.12.2 of 3304 [I-D.ietf-oauth-security-topics] 3306 10.1. Removal of the OAuth 2.0 Implicit grant 3308 The OAuth 2.0 Implicit grant is omitted from OAuth 2.1 as it was 3309 deprecated in [I-D.ietf-oauth-security-topics]. 3311 The intent of removing the Implicit grant is to no longer issue 3312 access tokens in the authorization response, as such tokens are 3313 vulnerable to leakage and injection, and are unable to be sender- 3314 constrained to a client. This behavior was indicated by clients 3315 using the response_type=token parameter. This value for the 3316 response_type parameter is no longer defined in OAuth 2.1. 3318 Removal of response_type=token does not have an effect on other 3319 extension response types returning other artifacts from the 3320 authorization endpoint, for example, response_type=id_token defined 3321 by [OpenID]. 3323 11. IANA Considerations 3325 This document does not require any IANA actions. 3327 All referenced registries are defined by [RFC6749] and related 3328 documents that this work is based upon. No changes to those 3329 registries are required by this specification. 3331 12. References 3333 12.1. Normative References 3335 [BCP195] Saint-Andre, P., "Recommendations for Secure Use of 3336 Transport Layer Security (TLS)", 2015. 3338 [I-D.ietf-oauth-security-topics] 3339 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3340 "OAuth 2.0 Security Best Current Practice", Work in 3341 Progress, Internet-Draft, draft-ietf-oauth-security- 3342 topics-19, 16 December 2021, 3343 . 3346 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3347 Requirement Levels", BCP 14, RFC 2119, 3348 DOI 10.17487/RFC2119, March 1997, 3349 . 3351 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3352 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3353 Authentication: Basic and Digest Access Authentication", 3354 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3355 . 3357 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3358 DOI 10.17487/RFC2818, May 2000, 3359 . 3361 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3362 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3363 2003, . 3365 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3366 Resource Identifier (URI): Generic Syntax", STD 66, 3367 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3368 . 3370 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3371 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3372 . 3374 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3375 Specifications: ABNF", STD 68, RFC 5234, 3376 DOI 10.17487/RFC5234, January 2008, 3377 . 3379 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3380 Housley, R., and W. Polk, "Internet X.509 Public Key 3381 Infrastructure Certificate and Certificate Revocation List 3382 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3383 . 3385 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3386 Verification of Domain-Based Application Service Identity 3387 within Internet Public Key Infrastructure Using X.509 3388 (PKIX) Certificates in the Context of Transport Layer 3389 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3390 2011, . 3392 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3393 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3394 . 3396 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3397 Framework: Bearer Token Usage", RFC 6750, 3398 DOI 10.17487/RFC6750, October 2012, 3399 . 3401 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3402 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3403 2014, . 3405 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3406 Protocol (HTTP/1.1): Message Syntax and Routing", 3407 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3408 . 3410 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3411 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3412 DOI 10.17487/RFC7231, June 2014, 3413 . 3415 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3416 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3417 RFC 7234, DOI 10.17487/RFC7234, June 2014, 3418 . 3420 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3421 Protocol (HTTP/1.1): Authentication", RFC 7235, 3422 DOI 10.17487/RFC7235, June 2014, 3423 . 3425 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3426 and Registration Procedures for URI Schemes", BCP 35, 3427 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3428 . 3430 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3431 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3432 May 2017, . 3434 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3435 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3436 . 3438 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3439 Interchange Format", STD 90, RFC 8259, 3440 DOI 10.17487/RFC8259, December 2017, 3441 . 3443 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3444 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3445 . 3447 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3448 Standard Code for Information Interchange, ANSI X3.4", 3449 1986. 3451 [W3C.REC-html401-19991224] 3452 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3453 Specification", World Wide Web Consortium Recommendation 3454 REC-html401-19991224, 24 December 1999, 3455 . 3457 [W3C.REC-xml-20081126] 3458 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3459 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3460 Edition)", World Wide Web Consortium Recommendation REC- 3461 xml-20081126, 26 November 2008, 3462 . 3464 12.2. Informative References 3466 [CSP-2] "Content Security Policy Level 2", December 2016, 3467 . 3469 [I-D.bradley-oauth-jwt-encoded-state] 3470 Bradley, J., Lodderstedt, D. T., and H. Zandbelt, 3471 "Encoding claims in the OAuth 2 state parameter using a 3472 JWT", Work in Progress, Internet-Draft, draft-bradley- 3473 oauth-jwt-encoded-state-09, 4 November 2018, 3474 . 3477 [I-D.ietf-oauth-browser-based-apps] 3478 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3479 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3480 browser-based-apps-08, 17 May 2021, 3481 . 3484 [I-D.ietf-oauth-dpop] 3485 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 3486 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 3487 of-Possession at the Application Layer (DPoP)", Work in 3488 Progress, Internet-Draft, draft-ietf-oauth-dpop-06, 1 3489 March 2022, . 3492 [I-D.ietf-oauth-rar] 3493 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3494 Rich Authorization Requests", Work in Progress, Internet- 3495 Draft, draft-ietf-oauth-rar-10, 26 January 2022, 3496 . 3499 [I-D.ietf-oauth-token-binding] 3500 Jones, M. B., Campbell, B., Bradley, J., and W. Denniss, 3501 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3502 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3503 . 3506 [NIST800-63] 3507 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3508 Gupta, S., and E. Nabbus, "NIST Special Publication 3509 800-63-1, INFORMATION SECURITY", December 2011, 3510 . 3512 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3513 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3514 and B. Boyer, "Online Multimedia Authorization Protocol: 3515 An Industry Standard for Authorized Access to Internet 3516 Multimedia Resources", April 2012, 3517 . 3519 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3520 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3521 . 3523 [OpenID.Messages] 3524 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3525 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3526 June 2012, . 3529 [owasp_redir] 3530 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3531 Forwards", 2020, 3532 . 3535 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3536 DOI 10.17487/RFC6265, April 2011, 3537 . 3539 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3540 Threat Model and Security Considerations", RFC 6819, 3541 DOI 10.17487/RFC6819, January 2013, 3542 . 3544 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 3545 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 3546 August 2013, . 3548 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3549 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3550 . 3552 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3553 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3554 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3555 . 3557 [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, 3558 "OAuth 2.0 Dynamic Client Registration Management 3559 Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, 3560 . 3562 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3563 for Code Exchange by OAuth Public Clients", RFC 7636, 3564 DOI 10.17487/RFC7636, September 2015, 3565 . 3567 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 3568 RFC 7662, DOI 10.17487/RFC7662, October 2015, 3569 . 3571 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3572 Authorization Server Metadata", RFC 8414, 3573 DOI 10.17487/RFC8414, June 2018, 3574 . 3576 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 3577 "OAuth 2.0 Device Authorization Grant", RFC 8628, 3578 DOI 10.17487/RFC8628, August 2019, 3579 . 3581 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3582 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3583 and Certificate-Bound Access Tokens", RFC 8705, 3584 DOI 10.17487/RFC8705, February 2020, 3585 . 3587 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3588 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3589 February 2020, . 3591 [RFC9068] Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 3592 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 3593 2021, . 3595 [RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 3596 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 3597 RFC 9126, DOI 10.17487/RFC9126, September 2021, 3598 . 3600 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3602 This section provides Augmented Backus-Naur Form (ABNF) syntax 3603 descriptions for the elements defined in this specification using the 3604 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3605 code points [W3C.REC-xml-20081126]; these characters are typically 3606 encoded in UTF-8. Elements are presented in the order first defined. 3608 Some of the definitions that follow use the "URI-reference" 3609 definition from [RFC3986]. 3611 Some of the definitions that follow use these common definitions: 3613 VSCHAR = %x20-7E 3614 NQCHAR = %x21 / %x23-5B / %x5D-7E 3615 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3616 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3617 %xE000-FFFD / %x10000-10FFFF 3619 (The UNICODECHARNOCRLF definition is based upon the Char definition 3620 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3621 Return and Linefeed characters.) 3623 A.1. "client_id" Syntax 3625 The client_id element is defined in Section 2.4.1: 3627 client-id = *VSCHAR 3629 A.2. "client_secret" Syntax 3631 The client_secret element is defined in Section 2.4.1: 3633 client-secret = *VSCHAR 3635 A.3. "response_type" Syntax 3637 The response_type element is defined in Section 4.1.1 and 3638 Section 6.4: 3640 response-type = response-name *( SP response-name ) 3641 response-name = 1*response-char 3642 response-char = "_" / DIGIT / ALPHA 3644 A.4. "scope" Syntax 3646 The scope element is defined in Section 3.2.2.1: 3648 scope = scope-token *( SP scope-token ) 3649 scope-token = 1*NQCHAR 3651 A.5. "state" Syntax 3653 The state element is defined in Section 4.1.1, Section 4.1.2, and 3654 Section 4.1.2.1: 3656 state = 1*VSCHAR 3658 A.6. "redirect_uri" Syntax 3660 The redirect_uri element is defined in Section 4.1.1, and 3661 Section 4.1.3: 3663 redirect-uri = URI-reference 3665 A.7. "error" Syntax 3667 The error element is defined in Sections Section 4.1.2.1, 3668 Section 3.2.3.1, 7.2, and 8.5: 3670 error = 1*NQSCHAR 3672 A.8. "error_description" Syntax 3674 The error_description element is defined in Sections Section 4.1.2.1, 3675 Section 3.2.3.1, and Section 5.3: 3677 error-description = 1*NQSCHAR 3679 A.9. "error_uri" Syntax 3681 The error_uri element is defined in Sections Section 4.1.2.1, 3682 Section 3.2.3.1, and 7.2: 3684 error-uri = URI-reference 3686 A.10. "grant_type" Syntax 3688 The grant_type element is defined in Section Section 3.2.2: 3690 grant-type = grant-name / URI-reference 3691 grant-name = 1*name-char 3692 name-char = "-" / "." / "_" / DIGIT / ALPHA 3694 A.11. "code" Syntax 3696 The code element is defined in Section 4.1.3: 3698 code = 1*VSCHAR 3700 A.12. "access_token" Syntax 3702 The access_token element is defined in Section 3.2.3: 3704 access-token = 1*VSCHAR 3706 A.13. "token_type" Syntax 3708 The token_type element is defined in Section 3.2.3, and Section 6.1: 3710 token-type = type-name / URI-reference 3711 type-name = 1*name-char 3712 name-char = "-" / "." / "_" / DIGIT / ALPHA 3714 A.14. "expires_in" Syntax 3716 The expires_in element is defined in Section 3.2.3: 3718 expires-in = 1*DIGIT 3720 A.15. "refresh_token" Syntax 3722 The refresh_token element is defined in Section 3.2.3 and 3723 Section 4.3: 3725 refresh-token = 1*VSCHAR 3727 A.16. Endpoint Parameter Syntax 3729 The syntax for new endpoint parameters is defined in Section 6.2: 3731 param-name = 1*name-char 3732 name-char = "-" / "." / "_" / DIGIT / ALPHA 3734 A.17. "code_verifier" Syntax 3736 ABNF for code_verifier is as follows. 3738 code-verifier = 43*128unreserved 3739 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3740 ALPHA = %x41-5A / %x61-7A 3741 DIGIT = %x30-39 3743 A.18. "code_challenge" Syntax 3745 ABNF for code_challenge is as follows. 3747 code-challenge = 43*128unreserved 3748 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3749 ALPHA = %x41-5A / %x61-7A 3750 DIGIT = %x30-39 3752 Appendix B. Use of application/x-www-form-urlencoded Media Type 3754 At the time of publication of this specification, the application/x- 3755 www-form-urlencoded media type was defined in Section 17.13.4 of 3756 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 3757 Types registry (http://www.iana.org/assignments/media-types 3758 (http://www.iana.org/assignments/media-types)). Furthermore, that 3759 definition is incomplete, as it does not consider non-US-ASCII 3760 characters. 3762 To address this shortcoming when generating payloads using this media 3763 type, names and values MUST be encoded using the UTF-8 character 3764 encoding scheme [RFC3629] first; the resulting octet sequence then 3765 needs to be further encoded using the escaping rules defined in 3766 [W3C.REC-html401-19991224]. 3768 When parsing data from a payload using this media type, the names and 3769 values resulting from reversing the name/value encoding consequently 3770 need to be treated as octet sequences, to be decoded using the UTF-8 3771 character encoding scheme. 3773 For example, the value consisting of the six Unicode code points (1) 3774 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3775 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3776 SIGN) would be encoded into the octet sequence below (using 3777 hexadecimal notation): 3779 20 25 26 2B C2 A3 E2 82 AC 3781 and then represented in the payload as: 3783 +%25%26%2B%C2%A3%E2%82%AC 3785 Appendix C. Extensions 3787 Below is a list of well-established extensions at the time of 3788 publication: 3790 * [RFC8628]: OAuth 2.0 Device Authorization Grant 3791 - The Device Authorization Grant (formerly known as the Device 3792 Flow) is an extension that enables devices with no browser or 3793 limited input capability to obtain an access token. This is 3794 commonly used by smart TV apps, or devices like hardware video 3795 encoders that can stream video to a streaming video service. 3797 * [RFC8414]: Authorization Server Metadata 3799 - Authorization Server Metadata (also known as OAuth Discovery) 3800 defines an endpoint clients can use to look up the information 3801 needed to interact with a particular OAuth server, such as the 3802 location of the authorization and token endpoints and the 3803 supported grant types. 3805 * [RFC8707]: Resource Indicators 3807 - Provides a way for the client to explicitly signal to the 3808 authorization server where it intends to use the access token 3809 it is requesting. 3811 * [RFC7591]: Dynamic Client Registration 3813 - Dynamic Client Registration provides a mechanism for 3814 programmatically registering clients with an authorization 3815 server. 3817 * [RFC7592]: Dynamic Client Management 3819 - Dynamic Client Management provides a mechanism for updating 3820 dynamically registered client information. 3822 * [RFC9068]: JSON Web Token (JWT) Profile for OAuth 2.0 Access 3823 Tokens 3825 - This specification defines a profile for issuing OAuth access 3826 tokens in JSON Web Token (JWT) format. 3828 * [RFC8705]: Mutual TLS 3830 - Mutual TLS describes a mechanism of binding access tokens and 3831 refresh tokens to the clients they were issued to, as well as a 3832 client authentication mechanism, via TLS certificate 3833 authentication. 3835 * [RFC7662]: Token Introspection 3837 - The Token Introspection extension defines a mechanism for 3838 resource servers to obtain information about access tokens. 3840 * [RFC7009]: Token Revocation 3842 - The Token Revocation extension defines a mechanism for clients 3843 to indicate to the authorization server that an access token is 3844 no longer needed. 3846 * [RFC9126]: Pushed Authorization Requests 3848 - The Pushed Authorization Requests extension describes a 3849 technique of initiating an OAuth flow from the back channel, 3850 providing better security and more flexibility for building 3851 complex authorization requests. 3853 * [I-D.ietf-oauth-rar]: Rich Authorization Requests 3855 - Rich Authorization Requests specifies a new parameter 3856 authorization_details that is used to carry fine-grained 3857 authorization data in the OAuth authorization request. 3859 Appendix D. Acknowledgements 3861 TBD 3863 Appendix E. Document History 3865 [[ To be removed from the final specification ]] 3867 -05 3869 * Added a section about the removal of the implicit flow 3871 * Moved many normative requirements from security considerations 3872 into the appropriate inline sections 3874 * Reorganized and consolidated TLS language 3876 * Require TLS on redirect URIs except for localhost/custom URL 3877 scheme 3879 * Updated refresh token guidance to match security BCP 3881 -04 3883 * Added explicit mention of not sending access tokens in URI query 3884 strings 3886 * Clarifications on definition of client types 3887 * Consolidated text around loopback vs localhost 3889 * Editorial clarifications throughout the document 3891 -03 3893 * refactoring to collect all the grant types under the same top- 3894 level header in section 4 3896 * Better split normative and security consideration text into the 3897 appropriate places, both moving text that was really security 3898 considerations out of the main part of the document, as well as 3899 pulling normative requirements from the security considerations 3900 sections into the appropriate part of the main document 3902 * Incorporated many of the published errata on RFC6749 3904 * Updated references to various RFCs 3906 * Editorial clarifications throughout the document 3908 -02 3910 -01 3912 -00 3914 * initial revision 3916 Authors' Addresses 3918 Dick Hardt 3919 Hellō 3920 Email: dick.hardt@gmail.com 3922 Aaron Parecki 3923 Okta 3924 Email: aaron@parecki.com 3925 URI: https://aaronparecki.com 3927 Torsten Lodderstedt 3928 yes.com 3929 Email: torsten@lodderstedt.net