idnits 2.17.1 draft-parecki-oauth-v2-1-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 22 instances of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (7 March 2020) is 1510 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 1109, but not defined == Missing Reference: '0-9' is mentioned on line 1109, but not defined == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-14 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-17) exists of draft-ietf-oauth-browser-based-apps-05 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-01 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 8 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track A. Parecki 5 Expires: 8 September 2020 Okta 6 T. Lodderstedt 7 yes.com 8 7 March 2020 10 The OAuth 2.1 Authorization Framework 11 draft-parecki-oauth-v2-1-00 13 Abstract 15 The OAuth 2.1 authorization framework enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and the HTTP service, or by allowing the 19 third-party application to obtain access on its own behalf. This 20 specification replaces and obsoletes the OAuth 2.0 Authorization 21 Framework described in RFC 6749. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 8 September 2020. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 59 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 60 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . 8 61 1.3.2. Client Credentials . . . . . . . . . . . . . . . . . 8 62 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 63 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 64 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 11 65 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 11 66 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 11 67 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 12 68 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 12 69 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13 70 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 14 71 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 14 72 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 73 2.3.2. Other Authorization Methods . . . . . . . . . . . . . 16 74 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 16 75 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 16 76 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 77 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 17 78 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 18 79 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 80 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 20 81 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 21 82 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22 83 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 22 84 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 23 85 4.1.2. Authorization Response . . . . . . . . . . . . . . . 26 86 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 29 87 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 30 88 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 30 89 4.2.1. Authorization Request and Response . . . . . . . . . 31 90 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 31 91 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 32 92 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 32 93 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 33 94 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 33 95 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 34 96 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 36 97 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 38 98 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 39 99 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 39 100 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 39 101 7.2.2. The WWW-Authenticate Response Header Field . . . . . 41 102 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 43 103 7.3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 43 104 7.4. Access Token Security Considerations . . . . . . . . . . 44 105 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 44 106 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 45 107 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 46 108 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 47 109 7.4.5. Access Token Privilege Restriction . . . . . . . . . 48 110 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 48 111 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 48 112 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 49 113 8.3. Defining New Authorization Grant Types . . . . . . . . . 49 114 8.4. Defining New Authorization Endpoint Response Types . . . 49 115 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 50 116 9. Security Considerations . . . . . . . . . . . . . . . . . . . 50 117 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 51 118 9.1.1. Client Authentication of Native Apps . . . . . . . . 52 119 9.2. Registration of Native App Clients . . . . . . . . . . . 52 120 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 53 121 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 53 122 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 54 123 9.4.1. Access Token Privilege Restriction . . . . . . . . . 54 124 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 54 125 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 55 126 9.6. Protecting Redirect-Based Flows . . . . . . . . . . . . . 55 127 9.6.1. Loopback Redirect Considerations in Native Apps . . . 56 128 9.7. Authorization Codes . . . . . . . . . . . . . . . . . . . 57 129 9.8. Request Confidentiality . . . . . . . . . . . . . . . . . 58 130 9.9. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 58 131 9.10. Credentials-Guessing Attacks . . . . . . . . . . . . . . 58 132 9.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 58 133 9.12. Fake External User-Agents in Native Apps . . . . . . . . 59 134 9.13. Malicious External User-Agents in Native Apps . . . . . . 59 135 9.14. Cross-Site Request Forgery . . . . . . . . . . . . . . . 60 136 9.15. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 60 137 9.16. Code Injection and Input Validation . . . . . . . . . . . 61 138 9.17. Open Redirectors . . . . . . . . . . . . . . . . . . . . 61 139 9.17.1. Client as Open Redirector . . . . . . . . . . . . . 62 140 9.17.2. Authorization Server as Open Redirector . . . . . . 62 141 9.18. Authorization Server Mix-Up Mitigation in Native Apps . . 62 142 9.19. Embedded User Agents in Native Apps . . . . . . . . . . . 63 143 9.20. Other Recommendations . . . . . . . . . . . . . . . . . . 64 144 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 64 145 10.1. Using Inter-App URI Communication for OAuth in Native 146 Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 65 147 10.2. Initiating the Authorization Request from a Native 148 App . . . . . . . . . . . . . . . . . . . . . . . . . . 65 149 10.3. Receiving the Authorization Response in a Native App . . 66 150 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 66 151 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 67 152 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 68 153 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 68 154 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 155 12.1. OAuth Access Token Types Registry . . . . . . . . . . . 69 156 12.1.1. Registration Template . . . . . . . . . . . . . . . 69 157 12.1.2. Initial Registry Contents . . . . . . . . . . . . . 70 158 12.2. OAuth Parameters Registry . . . . . . . . . . . . . . . 70 159 12.2.1. Registration Template . . . . . . . . . . . . . . . 71 160 12.2.2. Initial Registry Contents . . . . . . . . . . . . . 71 161 12.3. OAuth Authorization Endpoint Response Types Registry . . 74 162 12.3.1. Registration Template . . . . . . . . . . . . . . . 74 163 12.3.2. Initial Registry Contents . . . . . . . . . . . . . 75 164 12.4. OAuth Extensions Error Registry . . . . . . . . . . . . 75 165 12.4.1. Registration Template . . . . . . . . . . . . . . . 75 166 12.4.2. Initial Registry Contents . . . . . . . . . . . . . 76 167 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 168 13.1. Normative References . . . . . . . . . . . . . . . . . . 76 169 13.2. Informative References . . . . . . . . . . . . . . . . . 79 170 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 81 171 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 82 172 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 82 173 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 82 174 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 82 175 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 82 176 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 83 177 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 83 178 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 83 179 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 83 180 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 83 181 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 83 182 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 84 183 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 84 184 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 84 185 A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 84 186 A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 84 187 A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 84 188 A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 84 189 Appendix B. Use of application/x-www-form-urlencoded Media 190 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 85 191 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 85 192 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 85 194 1. Introduction 196 In the traditional client-server authentication model, the client 197 requests an access-restricted resource (protected resource) on the 198 server by authenticating with the server using the resource owner's 199 credentials. In order to provide third-party applications access to 200 restricted resources, the resource owner shares its credentials with 201 the third party. This creates several problems and limitations: 203 * Third-party applications are required to store the resource 204 owner's credentials for future use, typically a password in clear- 205 text. 207 * Servers are required to support password authentication, despite 208 the security weaknesses inherent in passwords. 210 * Third-party applications gain overly broad access to the resource 211 owner's protected resources, leaving resource owners without any 212 ability to restrict duration or access to a limited subset of 213 resources. 215 * Resource owners cannot revoke access to an individual third party 216 without revoking access to all third parties, and must do so by 217 changing the third party's password. 219 * Compromise of any third-party application results in compromise of 220 the end-user's password and all of the data protected by that 221 password. 223 OAuth addresses these issues by introducing an authorization layer 224 and separating the role of the client from that of the resource 225 owner. In OAuth, the client requests access to resources controlled 226 by the resource owner and hosted by the resource server, and is 227 issued a different set of credentials than those of the resource 228 owner. 230 Instead of using the resource owner's credentials to access protected 231 resources, the client obtains an access token - a string denoting a 232 specific scope, lifetime, and other access attributes. Access tokens 233 are issued to third-party clients by an authorization server with the 234 approval of the resource owner. The client uses the access token to 235 access the protected resources hosted by the resource server. 237 For example, an end-user (resource owner) can grant a printing 238 service (client) access to her protected photos stored at a photo- 239 sharing service (resource server), without sharing her username and 240 password with the printing service. Instead, she authenticates 241 directly with a server trusted by the photo-sharing service 242 (authorization server), which issues the printing service delegation- 243 specific credentials (access token). 245 This specification is designed for use with HTTP ([RFC2616]). The 246 use of OAuth over any protocol other than HTTP is out of scope. 248 Since the publication of the OAuth 2.0 Authorization Framework 249 ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for 250 Native Apps ([RFC8252]), OAuth Security Best Current Practice 251 ([I-D.ietf-oauth-security-topics]), and OAuth 2.0 for Browser-Based 252 Apps ([I-D.ietf-oauth-browser-based-apps]). The OAuth 2.0 253 Authorization Framework: Bearer Token Usage ([RFC6750]) has also been 254 updated with ([I-D.ietf-oauth-security-topics]). This Standards 255 Track specification consolidates the information in all of these 256 documents and removes features that have been found to be insecure in 257 [I-D.ietf-oauth-security-topics]. 259 1.1. Roles 261 OAuth defines four roles: 263 "resource owner": An entity capable of granting access to a 264 protected resource. When the resource owner is a person, it is 265 referred to as an end-user. 267 "resource server": The server hosting the protected resources, 268 capable of accepting and responding to protected resource requests 269 using access tokens. 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. 281 The interaction between the authorization server and resource server 282 is beyond the scope of this specification. The authorization server 283 may be the same server as the resource server or a separate entity. 284 A single authorization server may issue access tokens accepted by 285 multiple resource servers. 287 1.2. Protocol Flow 288 +--------+ +---------------+ 289 | |--(1)- Authorization Request ->| Resource | 290 | | | Owner | 291 | |<-(2)-- Authorization Grant ---| | 292 | | +---------------+ 293 | | 294 | | +---------------+ 295 | |--(3)-- Authorization Grant -->| Authorization | 296 | Client | | Server | 297 | |<-(4)----- Access Token -------| | 298 | | +---------------+ 299 | | 300 | | +---------------+ 301 | |--(5)----- Access Token ------>| Resource | 302 | | | Server | 303 | |<-(6)--- Protected Resource ---| | 304 +--------+ +---------------+ 306 Figure 1: Abstract Protocol Flow 308 The abstract OAuth 2.1 flow illustrated in Figure 1 describes the 309 interaction between the four roles and includes the following steps: 311 1. The client requests authorization from the resource owner. The 312 authorization request can be made directly to the resource owner 313 (as shown), or preferably indirectly via the authorization server 314 as an intermediary. 316 2. The client receives an authorization grant, which is a credential 317 representing the resource owner's authorization, expressed using 318 one of two grant types defined in this specification or using an 319 extension grant type. The authorization grant type depends on 320 the method used by the client to request authorization and the 321 types supported by the authorization server. 323 3. The client requests an access token by authenticating with the 324 authorization server and presenting the authorization grant. 326 4. The authorization server authenticates the client and validates 327 the authorization grant, and if valid, issues an access token. 329 5. The client requests the protected resource from the resource 330 server and authenticates by presenting the access token. 332 6. The resource server validates the access token, and if valid, 333 serves the request. 335 The preferred method for the client to obtain an authorization grant 336 from the resource owner (depicted in steps (1) and (2)) is to use the 337 authorization server as an intermediary, which is illustrated in 338 Figure 3 in Section 4.1. 340 1.3. Authorization Grant 342 An authorization grant is a credential representing the resource 343 owner's authorization (to access its protected resources) used by the 344 client to obtain an access token. This specification defines two 345 grant types - authorization code and client credentials - as well as 346 an extensibility mechanism for defining additional types. 348 1.3.1. Authorization Code 350 The authorization code is obtained by using an authorization server 351 as an intermediary between the client and resource owner. Instead of 352 requesting authorization directly from the resource owner, the client 353 directs the resource owner to an authorization server (via its user- 354 agent as defined in [RFC2616]), which in turn directs the resource 355 owner back to the client with the authorization code. 357 Before directing the resource owner back to the client with the 358 authorization code, the authorization server authenticates the 359 resource owner and obtains authorization. Because the resource owner 360 only authenticates with the authorization server, the resource 361 owner's credentials are never shared with the client. 363 The authorization code provides a few important security benefits, 364 such as the ability to authenticate the client, as well as the 365 transmission of the access token directly to the client without 366 passing it through the resource owner's user-agent and potentially 367 exposing it to others, including the resource owner. 369 1.3.2. Client Credentials 371 The client credentials (or other forms of client authentication) can 372 be used as an authorization grant when the authorization scope is 373 limited to the protected resources under the control of the client, 374 or to protected resources previously arranged with the authorization 375 server. Client credentials are used as an authorization grant 376 typically when the client is acting on its own behalf (the client is 377 also the resource owner) or is requesting access to protected 378 resources based on an authorization previously arranged with the 379 authorization server. 381 1.4. Access Token 383 Access tokens are credentials used to access protected resources. An 384 access token is a string representing an authorization issued to the 385 client. The string is usually opaque to the client. Tokens 386 represent specific scopes and durations of access, granted by the 387 resource owner, and enforced by the resource server and authorization 388 server. 390 The token may denote an identifier used to retrieve the authorization 391 information or may self-contain the authorization information in a 392 verifiable manner (i.e., a token string consisting of some data and a 393 signature). Additional authentication credentials, which are beyond 394 the scope of this specification, may be required in order for the 395 client to use a token. 397 The access token provides an abstraction layer, replacing different 398 authorization constructs (e.g., username and password) with a single 399 token understood by the resource server. This abstraction enables 400 issuing access tokens more restrictive than the authorization grant 401 used to obtain them, as well as removing the resource server's need 402 to understand a wide range of authentication methods. 404 Access tokens can have different formats, structures, and methods of 405 utilization (e.g., cryptographic properties) based on the resource 406 server security requirements. Access token attributes and the 407 methods used to access protected resources may be extended beyond 408 what is described in this specification. 410 1.5. Refresh Token 412 Refresh tokens are credentials used to obtain access tokens. Refresh 413 tokens are issued to the client by the authorization server and are 414 used to obtain a new access token when the current access token 415 becomes invalid or expires, or to obtain additional access tokens 416 with identical or narrower scope (access tokens may have a shorter 417 lifetime and fewer permissions than authorized by the resource 418 owner). Issuing a refresh token is optional at the discretion of the 419 authorization server. If the authorization server issues a refresh 420 token, it is included when issuing an access token (i.e., step (4) in 421 Figure 2). 423 A refresh token is a string representing the authorization granted to 424 the client by the resource owner. The string is usually opaque to 425 the client. The token denotes an identifier used to retrieve the 426 authorization information. Unlike access tokens, refresh tokens are 427 intended for use only with authorization servers and are never sent 428 to resource servers. 430 +--------+ +---------------+ 431 | |--(1)------- Authorization Grant --------->| | 432 | | | | 433 | |<-(2)----------- Access Token -------------| | 434 | | & Refresh Token | | 435 | | | | 436 | | +----------+ | | 437 | |--(3)---- Access Token ---->| | | | 438 | | | | | | 439 | |<-(4)- Protected Resource --| Resource | | Authorization | 440 | Client | | Server | | Server | 441 | |--(5)---- Access Token ---->| | | | 442 | | | | | | 443 | |<-(6)- Invalid Token Error -| | | | 444 | | +----------+ | | 445 | | | | 446 | |--(7)----------- Refresh Token ----------->| | 447 | | | | 448 | |<-(8)----------- Access Token -------------| | 449 +--------+ & Optional Refresh Token +---------------+ 451 Figure 2: Refreshing an Expired Access Token 453 The flow illustrated in Figure 2 includes the following steps: 455 1. The client requests an access token by authenticating with the 456 authorization server and presenting an authorization grant. 458 2. The authorization server authenticates the client and validates 459 the authorization grant, and if valid, issues an access token and 460 a refresh token. 462 3. The client makes a protected resource request to the resource 463 server by presenting the access token. 465 4. The resource server validates the access token, and if valid, 466 serves the request. 468 5. Steps (3) and (4) repeat until the access token expires. If the 469 client knows the access token expired, it skips to step (7); 470 otherwise, it makes another protected resource request. 472 6. Since the access token is invalid, the resource server returns an 473 invalid token error. 475 7. The client requests a new access token by authenticating with the 476 authorization server and presenting the refresh token. The 477 client authentication requirements are based on the client type 478 and on the authorization server policies. 480 8. The authorization server authenticates the client and validates 481 the refresh token, and if valid, issues a new access token (and, 482 optionally, a new refresh token). 484 Steps (3), (4), (5), and (6) are outside the scope of this 485 specification, as described in Section 7. 487 1.6. TLS Version 489 Whenever Transport Layer Security (TLS) is used by this 490 specification, the appropriate version (or versions) of TLS will vary 491 over time, based on the widespread deployment and known security 492 vulnerabilities. At the time of this writing, At the time of this 493 writing, TLS version 1.3 [RFC8446] is the most recent version. 495 Implementations MAY also support additional transport-layer security 496 mechanisms that meet their security requirements. 498 1.7. HTTP Redirections 500 This specification makes extensive use of HTTP redirections, in which 501 the client or the authorization server directs the resource owner's 502 user-agent to another destination. While the examples in this 503 specification show the use of the HTTP 302 status code, any other 504 method available via the user-agent to accomplish this redirection is 505 allowed and is considered to be an implementation detail. 507 1.8. Interoperability 509 OAuth 2.1 provides a rich authorization framework with well-defined 510 security properties. However, as a rich and highly extensible 511 framework with many optional components, on its own, this 512 specification is likely to produce a wide range of non-interoperable 513 implementations. 515 In addition, this specification leaves a few required components 516 partially or fully undefined (e.g., client registration, 517 authorization server capabilities, endpoint discovery). Without 518 these components, clients must be manually and specifically 519 configured against a specific authorization server and resource 520 server in order to interoperate. 522 This framework was designed with the clear expectation that future 523 work will define prescriptive profiles and extensions necessary to 524 achieve full web-scale interoperability. 526 1.9. Notational Conventions 528 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 529 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 530 specification are to be interpreted as described in [RFC2119]. 532 This specification uses the Augmented Backus-Naur Form (ABNF) 533 notation of [RFC5234]. Additionally, the rule URI-reference is 534 included from "Uniform Resource Identifier (URI): Generic Syntax" 535 [RFC3986]. 537 Certain security-related terms are to be understood in the sense 538 defined in [RFC4949]. These terms include, but are not limited to, 539 "attack", "authentication", "authorization", "certificate", 540 "confidentiality", "credential", "encryption", "identity", "sign", 541 "signature", "trust", "validate", and "verify". 543 Unless otherwise noted, all the protocol parameter names and values 544 are case sensitive. 546 2. Client Registration 548 Before initiating the protocol, the client registers with the 549 authorization server. The means through which the client registers 550 with the authorization server are beyond the scope of this 551 specification but typically involve end-user interaction with an HTML 552 registration form. 554 Client registration does not require a direct interaction between the 555 client and the authorization server. When supported by the 556 authorization server, registration can rely on other means for 557 establishing trust and obtaining the required client properties 558 (e.g., redirection URI, client type). For example, registration can 559 be accomplished using a self-issued or third-party-issued assertion, 560 or by the authorization server performing client discovery using a 561 trusted channel. 563 When registering a client, the client developer SHALL: 565 * specify the client type as described in Section 2.1, 567 * provide its client redirection URIs as described in Section 3.1.2, 568 and 570 * include any other information required by the authorization server 571 (e.g., application name, website, description, logo image, the 572 acceptance of legal terms). 574 2.1. Client Types 576 OAuth defines two client types, based on whether they can be issued 577 credentials that they can use to authenticate at the authorization 578 server: 580 "confidential": Clients capable of maintaining the confidentiality 581 of their credentials (e.g., client implemented on a secure server 582 with restricted access to the client credentials), or capable of 583 secure client authentication using other means. 585 "public": Clients incapable of maintaining the confidentiality of 586 their credentials (e.g., clients executing on the device used by 587 the resource owner, such as an installed native application or a 588 web browser-based application), and incapable of secure client 589 authentication via any other means. 591 The client type designation is based on the authorization server's 592 definition of secure authentication and its acceptable exposure 593 levels of client credentials. The authorization server SHOULD NOT 594 make assumptions about the client type. 596 A client may be implemented as a distributed set of components, each 597 with a different client type and security context (e.g., a 598 distributed client with both a confidential server-based component 599 and a public browser-based component). If the authorization server 600 does not provide support for such clients or does not provide 601 guidance with regard to their registration, the client SHOULD 602 register each component as a separate client. 604 This specification has been designed around the following client 605 profiles: 607 "web application": A web application is a confidential client 608 running on a web server. Resource owners access the client via an 609 HTML user interface rendered in a user-agent on the device used by 610 the resource owner. The client credentials as well as any access 611 token issued to the client are stored on the web server and are 612 not exposed to or accessible by the resource owner. 614 "browser-based application": A browser-based application is a public 615 client in which the client code is downloaded from a web server 616 and executes within a user-agent (e.g., web browser) on the device 617 used by the resource owner. Protocol data and credentials are 618 easily accessible (and often visible) to the resource owner. 619 Since such applications reside within the user-agent, they can 620 make seamless use of the user-agent capabilities when requesting 621 authorization. 623 "native application": A native application is a public client 624 installed and executed on the device used by the resource owner. 625 Protocol data and credentials are accessible to the resource 626 owner. It is assumed that any client authentication credentials 627 included in the application can be extracted. On the other hand, 628 dynamically issued credentials such as access tokens or refresh 629 tokens can receive an acceptable level of protection. At a 630 minimum, these credentials are protected from hostile servers with 631 which the application may interact. On some platforms, these 632 credentials might be protected from other applications residing on 633 the same device. 635 2.2. Client Identifier 637 The authorization server issues the registered client a client 638 identifier - a unique string representing the registration 639 information provided by the client. The client identifier is not a 640 secret; it is exposed to the resource owner and MUST NOT be used 641 alone for client authentication. The client identifier is unique to 642 the authorization server. 644 The client identifier string size is left undefined by this 645 specification. The client should avoid making assumptions about the 646 identifier size. The authorization server SHOULD document the size 647 of any identifier it issues. 649 Authorization servers SHOULD NOT allow clients to influence their 650 "client_id" or "sub" value or any other claim if that can cause 651 confusion with a genuine resource owner. 653 2.3. Client Authentication 655 If the client type is confidential, the client and authorization 656 server establish a client authentication method suitable for the 657 security requirements of the authorization server. The authorization 658 server MAY accept any form of client authentication meeting its 659 security requirements. 661 Confidential clients are typically issued (or establish) a set of 662 client credentials used for authenticating with the authorization 663 server (e.g., password, public/private key pair). 665 Authorization servers SHOULD use client authentication if possible. 667 It is RECOMMENDED to use asymmetric (public-key based) methods for 668 client authentication such as mTLS [RFC8705] or "private_key_jwt" 669 [OpenID]. When asymmetric methods for client authentication are 670 used, authorization servers do not need to store sensitive symmetric 671 keys, making these methods more robust against a number of attacks. 673 The authorization server MAY establish a client authentication method 674 with public clients. However, the authorization server MUST NOT rely 675 on public client authentication for the purpose of identifying the 676 client. 678 The client MUST NOT use more than one authentication method in each 679 request. 681 2.3.1. Client Password 683 Clients in possession of a client password MAY use the HTTP Basic 684 authentication scheme as defined in [RFC2617] to authenticate with 685 the authorization server. The client identifier is encoded using the 686 "application/x-www-form-urlencoded" encoding algorithm per 687 Appendix B, and the encoded value is used as the username; the client 688 password is encoded using the same algorithm and used as the 689 password. The authorization server MUST support the HTTP Basic 690 authentication scheme for authenticating clients that were issued a 691 client password. 693 For example (with extra line breaks for display purposes only): 695 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 697 Alternatively, the authorization server MAY support including the 698 client credentials in the request-body using the following 699 parameters: 701 "client_id": REQUIRED. The client identifier issued to the client 702 during the registration process described by Section 2.2. 704 "client_secret": REQUIRED. The client secret. The client MAY omit 705 the parameter if the client secret is an empty string. 707 Including the client credentials in the request-body using the two 708 parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 709 to directly utilize the HTTP Basic authentication scheme (or other 710 password-based HTTP authentication schemes). The parameters can only 711 be transmitted in the request-body and MUST NOT be included in the 712 request URI. 714 For example, a request to refresh an access token (Section 6) using 715 the body parameters (with extra line breaks for display purposes 716 only): 718 POST /token HTTP/1.1 719 Host: server.example.com 720 Content-Type: application/x-www-form-urlencoded 722 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 723 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 725 The authorization server MUST require the use of TLS as described in 726 Section 1.6 when sending requests using password authentication. 728 Since this client authentication method involves a password, the 729 authorization server MUST protect any endpoint utilizing it against 730 brute force attacks. 732 2.3.2. Other Authorization Methods 734 The authorization server MAY support any suitable HTTP authentication 735 scheme matching its security requirements. When using other 736 authentication methods, the authorization server MUST define a 737 mapping between the client identifier (registration record) and 738 authentication scheme. 740 2.4. Unregistered Clients 742 This specification does not exclude the use of unregistered clients. 743 However, the use of such clients is beyond the scope of this 744 specification and requires additional security analysis and review of 745 its interoperability impact. 747 3. Protocol Endpoints 749 The authorization process utilizes two authorization server endpoints 750 (HTTP resources): 752 * Authorization endpoint - used by the client to obtain 753 authorization from the resource owner via user-agent redirection. 755 * Token endpoint - used by the client to exchange an authorization 756 grant for an access token, typically with client authentication. 758 As well as one client endpoint: 760 * Redirection endpoint - used by the authorization server to return 761 responses containing authorization credentials to the client via 762 the resource owner user-agent. 764 Not every authorization grant type utilizes both endpoints. 765 Extension grant types MAY define additional endpoints as needed. 767 3.1. Authorization Endpoint 769 The authorization endpoint is used to interact with the resource 770 owner and obtain an authorization grant. The authorization server 771 MUST first verify the identity of the resource owner. The way in 772 which the authorization server authenticates the resource owner 773 (e.g., username and password login, session cookies) is beyond the 774 scope of this specification. 776 The means through which the client obtains the location of the 777 authorization endpoint are beyond the scope of this specification, 778 but the location is typically provided in the service documentation. 780 The endpoint URI MAY include an "application/x-www-form-urlencoded" 781 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 782 which MUST be retained when adding additional query parameters. The 783 endpoint URI MUST NOT include a fragment component. 785 Since requests to the authorization endpoint result in user 786 authentication and the transmission of clear-text credentials (in the 787 HTTP response), the authorization server MUST require the use of TLS 788 as described in Section 1.6 when sending requests to the 789 authorization endpoint. 791 The authorization server MUST support the use of the HTTP "GET" 792 method [RFC2616] for the authorization endpoint and MAY support the 793 use of the "POST" method as well. 795 Parameters sent without a value MUST be treated as if they were 796 omitted from the request. The authorization server MUST ignore 797 unrecognized request parameters. Request and response parameters 798 MUST NOT be included more than once. 800 3.1.1. Response Type 802 The authorization endpoint is used by the authorization code flow. 803 The client informs the authorization server of the desired grant type 804 using the following parameter: 806 "response_type": REQUIRED. The value MUST be "code" for requesting 807 an authorization code as described by Section 4.1.1, or a 808 registered extension value as described by Section 8.4. 810 Extension response types MAY contain a space-delimited (%x20) list of 811 values, where the order of values does not matter (e.g., response 812 type "a b" is the same as "b a"). The meaning of such composite 813 response types is defined by their respective specifications. 815 For example, OpenID Connect defines "response_type=id_token" as well 816 as a few other combinations which include additional security 817 features for those flows. 819 If an authorization request is missing the "response_type" parameter, 820 or if the response type is not understood, the authorization server 821 MUST return an error response as described in Section 4.1.2.1. 823 3.1.2. Redirection Endpoint 825 After completing its interaction with the resource owner, the 826 authorization server directs the resource owner's user-agent back to 827 the client. The authorization server redirects the user-agent to the 828 client's redirection endpoint previously established with the 829 authorization server during the client registration process. 831 The authorization server MUST compare the two URIs using simple 832 string comparison as defined in [RFC3986], Section 6.2.1. 834 The redirection endpoint URI MUST be an absolute URI as defined by 835 [RFC3986] Section 4.3. The endpoint URI MAY include an "application/ 836 x-www-form-urlencoded" formatted (per Appendix B) query component 837 ([RFC3986] Section 3.4), which MUST be retained when adding 838 additional query parameters. The endpoint URI MUST NOT include a 839 fragment component. 841 3.1.2.1. Endpoint Request Confidentiality 843 The redirection endpoint SHOULD require the use of TLS as described 844 in Section 1.6 when the requested response type is "code", or when 845 the redirection request will result in the transmission of sensitive 846 credentials over an open network. This specification does not 847 mandate the use of TLS because at the time of this writing, requiring 848 clients to deploy TLS is a significant hurdle for many client 849 developers. If TLS is not available, the authorization server SHOULD 850 warn the resource owner about the insecure endpoint prior to 851 redirection (e.g., display a message during the authorization 852 request). 854 Lack of transport-layer security can have a severe impact on the 855 security of the client and the protected resources it is authorized 856 to access. The use of transport-layer security is particularly 857 critical when the authorization process is used as a form of 858 delegated end-user authentication by the client (e.g., third-party 859 sign-in service). 861 3.1.2.2. Registration Requirements 863 The authorization server MUST require all clients to register their 864 redirection endpoint prior to utilizing the authorization endpoint. 866 The authorization server SHOULD require the client to provide the 867 complete redirection URI (the client MAY use the "state" request 868 parameter to achieve per-request customization). 870 The authorization server MAY allow the client to register multiple 871 redirection endpoints. 873 Lack of a redirection URI registration requirement can enable an 874 attacker to use the authorization endpoint as an open redirector as 875 described in Section 9.17. 877 3.1.2.3. Dynamic Configuration 879 If multiple redirection URIs have been registered the client MUST 880 include a redirection URI with the authorization request using the 881 "redirect_uri" request parameter. 883 When a redirection URI is included in an authorization request, the 884 authorization server MUST compare and match the value received 885 against at least one of the registered redirection URIs (or URI 886 components) as defined in [RFC3986] Section 6, if any redirection 887 URIs were registered. If the client registration included the full 888 redirection URI, the authorization server MUST compare the two URIs 889 using simple string comparison as defined in [RFC3986] Section 6.2.1. 891 3.1.2.4. Invalid Endpoint 893 If an authorization request fails validation due to a missing, 894 invalid, or mismatching redirection URI, the authorization server 895 SHOULD inform the resource owner of the error and MUST NOT 896 automatically redirect the user-agent to the invalid redirection URI. 898 3.1.2.5. Endpoint Content 900 The redirection request to the client's endpoint typically results in 901 an HTML document response, processed by the user-agent. If the HTML 902 response is served directly as the result of the redirection request, 903 any script included in the HTML document will execute with full 904 access to the redirection URI and the credentials it contains. 906 The client SHOULD NOT include any third-party scripts (e.g., third- 907 party analytics, social plug-ins, ad networks) in the redirection 908 endpoint response. Instead, it SHOULD extract the credentials from 909 the URI and redirect the user-agent again to another endpoint without 910 exposing the credentials (in the URI or elsewhere). If third-party 911 scripts are included, the client MUST ensure that its own scripts 912 (used to extract and remove the credentials from the URI) will 913 execute first. 915 3.2. Token Endpoint 917 The token endpoint is used by the client to obtain an access token by 918 presenting its authorization grant or refresh token. 920 The means through which the client obtains the location of the token 921 endpoint are beyond the scope of this specification, but the location 922 is typically provided in the service documentation. 924 The endpoint URI MAY include an "application/x-www-form-urlencoded" 925 formatted (per Appendix B) query component ([RFC3986] Section 3.4), 926 which MUST be retained when adding additional query parameters. The 927 endpoint URI MUST NOT include a fragment component. 929 Since requests to the token endpoint result in the transmission of 930 clear-text credentials (in the HTTP request and response), the 931 authorization server MUST require the use of TLS as described in 932 Section 1.6 when sending requests to the token endpoint. 934 The client MUST use the HTTP "POST" method when making access token 935 requests. 937 Parameters sent without a value MUST be treated as if they were 938 omitted from the request. The authorization server MUST ignore 939 unrecognized request parameters. Request and response parameters 940 MUST NOT be included more than once. 942 3.2.1. Client Authentication 944 Confidential clients or other clients issued client credentials MUST 945 authenticate with the authorization server as described in 946 Section 2.3 when making requests to the token endpoint. Client 947 authentication is used for: 949 * Enforcing the binding of refresh tokens and authorization codes to 950 the client they were issued to. Client authentication is critical 951 when an authorization code is transmitted to the redirection 952 endpoint over an insecure channel or when the redirection URI has 953 not been registered in full. 955 * Recovering from a compromised client by disabling the client or 956 changing its credentials, thus preventing an attacker from abusing 957 stolen refresh tokens. Changing a single set of client 958 credentials is significantly faster than revoking an entire set of 959 refresh tokens. 961 * Implementing authentication management best practices, which 962 require periodic credential rotation. Rotation of an entire set 963 of refresh tokens can be challenging, while rotation of a single 964 set of client credentials is significantly easier. 966 A client MAY use the "client_id" request parameter to identify itself 967 when sending requests to the token endpoint. In the 968 "authorization_code" "grant_type" request to the token endpoint, an 969 unauthenticated client MUST send its "client_id" to prevent itself 970 from inadvertently accepting a code intended for a client with a 971 different "client_id". This protects the client from substitution of 972 the authentication code. (It provides no additional security for the 973 protected resource.) 975 3.3. Access Token Scope 977 The authorization and token endpoints allow the client to specify the 978 scope of the access request using the "scope" request parameter. In 979 turn, the authorization server uses the "scope" response parameter to 980 inform the client of the scope of the access token issued. 982 The value of the scope parameter is expressed as a list of space- 983 delimited, case-sensitive strings. The strings are defined by the 984 authorization server. If the value contains multiple space-delimited 985 strings, their order does not matter, and each string adds an 986 additional access range to the requested scope. 988 scope = scope-token *( SP scope-token ) 989 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 991 The authorization server MAY fully or partially ignore the scope 992 requested by the client, based on the authorization server policy or 993 the resource owner's instructions. If the issued access token scope 994 is different from the one requested by the client, the authorization 995 server MUST include the "scope" response parameter to inform the 996 client of the actual scope granted. 998 If the client omits the scope parameter when requesting 999 authorization, the authorization server MUST either process the 1000 request using a pre-defined default value or fail the request 1001 indicating an invalid scope. The authorization server SHOULD 1002 document its scope requirements and default value (if defined). 1004 4. Obtaining Authorization 1006 To request an access token, the client obtains authorization from the 1007 resource owner. The authorization is expressed in the form of an 1008 authorization grant, which the client uses to request the access 1009 token. OAuth defines two grant types: authorization code and client 1010 credentials. It also provides an extension mechanism for defining 1011 additional grant types. 1013 4.1. Authorization Code Grant 1015 The authorization code grant type is used to obtain both access 1016 tokens and refresh tokens. 1018 Since this is a redirection-based flow, the client must be capable of 1019 interacting with the resource owner's user-agent (typically a web 1020 browser) and capable of receiving incoming requests (via redirection) 1021 from the authorization server. 1023 +----------+ 1024 | Resource | 1025 | Owner | 1026 | | 1027 +----------+ 1028 ^ 1029 | 1030 (2) 1031 +----|-----+ Client Identifier +---------------+ 1032 | -+----(1)-- & Redirection URI ---->| | 1033 | User- | | Authorization | 1034 | Agent -+----(2)-- User authenticates --->| Server | 1035 | | | | 1036 | -+----(3)-- Authorization Code ---<| | 1037 +-|----|---+ +---------------+ 1038 | | ^ v 1039 (1) (3) | | 1040 | | | | 1041 ^ v | | 1042 +---------+ | | 1043 | |>---(4)-- Authorization Code ---------' | 1044 | Client | & Redirection URI | 1045 | | | 1046 | |<---(5)----- Access Token -------------------' 1047 +---------+ (w/ Optional Refresh Token) 1049 Note: The lines illustrating steps (1), (2), and (3) are broken into 1050 two parts as they pass through the user-agent. 1052 Figure 3: Authorization Code Flow 1054 The flow illustrated in Figure 3 includes the following steps: 1056 (1) The client initiates the flow by directing the resource owner's 1057 user-agent to the authorization endpoint. The client includes its 1058 client identifier, requested scope, local state, PKCE code challenge, 1059 and a redirection URI to which the authorization server will send the 1060 user-agent back once access is granted (or denied). 1062 (2) The authorization server authenticates the resource owner (via 1063 the user-agent) and establishes whether the resource owner grants or 1064 denies the client's access request. 1066 (3) Assuming the resource owner grants access, the authorization 1067 server redirects the user-agent back to the client using the 1068 redirection URI provided earlier (in the request or during client 1069 registration). The redirection URI includes an authorization code 1070 and any local state provided by the client earlier. 1072 (4) The client requests an access token from the authorization 1073 server's token endpoint by including the authorization code received 1074 in the previous step, and including its code verifier. When making 1075 the request, the client authenticates with the authorization server 1076 if it can. The client includes the redirection URI used to obtain 1077 the authorization code for verification. 1079 (5) The authorization server authenticates the client when possible, 1080 validates the authorization code, validates the code verifier, and 1081 ensures that the redirection URI received matches the URI used to 1082 redirect the client in step (C). If valid, the authorization server 1083 responds back with an access token and, optionally, a refresh token. 1085 4.1.1. Authorization Request 1087 To begin the authorization request, the client builds the 1088 authorization request URI by adding parameters to the authorization 1089 server's authorization endpoint URI. 1091 Without a client secret, public clients would be susceptible to an 1092 authorization code interception attack, where an attacker is able to 1093 intercept the authorization response through various means and use 1094 the authorization code to obtain an access token. To protect against 1095 this attack, as well as to protect against CSRF attacks, the client 1096 first generates a unique secret per authorization request, which it 1097 can later use along with the authorization code to prove that the 1098 application using the authorization code is the same application that 1099 requested it. This practice is known as "Proof-Key for Code 1100 Exchange", or PKCE, after the OAuth 2.0 extension ([RFC7636]) where 1101 it was originally developed. 1103 4.1.1.1. Client Creates a PKCE Code Verifier 1105 The client first creates a PKCE code verifier, "code_verifier", for 1106 each Authorization Request, in the following manner: 1108 code_verifier = high-entropy cryptographic random STRING using the 1109 unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"` 1110 from Section 2.3 of {{RFC3986}}, with a minimum length of 43 characters 1111 and a maximum length of 128 characters. 1113 ABNF for "code_verifier" is as follows. 1115 code-verifier = 43*128unreserved 1116 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1117 ALPHA = %x41-5A / %x61-7A 1118 DIGIT = %x30-39 1120 NOTE: The code verifier SHOULD have enough entropy to make it 1121 impractical to guess the value. It is RECOMMENDED that the output of 1122 a suitable random number generator be used to create a 32-octet 1123 sequence. The octet sequence is then base64url-encoded to produce a 1124 43-octet URL-safe string to use as the code verifier. 1126 4.1.1.2. Client Creates the PKCE Code Challenge 1128 The client then creates a PKCE code challenge derived from the code 1129 verifier by using one of the following transformations on the code 1130 verifier: 1132 plain 1133 code_challenge = code_verifier 1135 S256 1136 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 1138 If the client is capable of using "S256", it MUST use "S256", as 1139 "S256" is Mandatory To Implement (MTI) on the server. Clients are 1140 permitted to use "plain" only if they cannot support "S256" for some 1141 technical reason and know via out-of-band configuration that the 1142 server supports "plain". 1144 The plain transformation is for compatibility with existing 1145 deployments and for constrained environments that can't use the S256 1146 transformation. 1148 ABNF for "code_challenge" is as follows. 1150 code-challenge = 43*128unreserved 1151 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 1152 ALPHA = %x41-5A / %x61-7A 1153 DIGIT = %x30-39 1155 4.1.1.3. Client Initiates the Authorization Request 1157 The client constructs the request URI by adding the following 1158 parameters to the query component of the authorization endpoint URI 1159 using the "application/x-www-form-urlencoded" format, per Appendix B: 1161 "response_type": REQUIRED. Value MUST be set to "code". 1163 "client_id": REQUIRED. The client identifier as described in 1164 Section 2.2. 1166 "code_challenge": REQUIRED. Code challenge. 1168 "code_challenge_method": OPTIONAL, defaults to "plain" if not 1169 present in the request. Code nverifier transformation method is 1170 "S256" or "plain". 1172 "redirect_uri": OPTIONAL. As described in Section 3.1.2. 1174 "scope": OPTIONAL. The scope of the access request as described by 1175 Section 3.3. 1177 "state": OPTIONAL. An opaque value used by the client to maintain 1178 state between the request and callback. The authorization server 1179 includes this value when redirecting the user-agent back to the 1180 client. 1182 The client directs the resource owner to the constructed URI using an 1183 HTTP redirection response, or by other means available to it via the 1184 user-agent. 1186 For example, the client directs the user-agent to make the following 1187 HTTP request using TLS (with extra line breaks for display purposes 1188 only): 1190 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1191 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1192 &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY 1193 &code_challenge_method=S256 HTTP/1.1 1194 Host: server.example.com 1195 The authorization server validates the request to ensure that all 1196 required parameters are present and valid. If the request is valid, 1197 the authorization server authenticates the resource owner and obtains 1198 an authorization decision (by asking the resource owner or by 1199 establishing approval via other means). 1201 When a decision is established, the authorization server directs the 1202 user-agent to the provided client redirection URI using an HTTP 1203 redirection response, or by other means available to it via the user- 1204 agent. 1206 4.1.2. Authorization Response 1208 If the resource owner grants the access request, the authorization 1209 server issues an authorization code and delivers it to the client by 1210 adding the following parameters to the query component of the 1211 redirection URI using the "application/x-www-form-urlencoded" format, 1212 per Appendix B: 1214 "code": REQUIRED. The authorization code generated by the 1215 authorization server. The authorization code MUST expire shortly 1216 after it is issued to mitigate the risk of leaks. A maximum 1217 authorization code lifetime of 10 minutes is RECOMMENDED. The 1218 client MUST NOT use the authorization code more than once. If an 1219 authorization code is used more than once, the authorization 1220 server MUST deny the request and SHOULD revoke (when possible) all 1221 tokens previously issued based on that authorization code. The 1222 authorization code is bound to the client identifier and 1223 redirection URI. 1225 "state": REQUIRED if the "state" parameter was present in the client 1226 authorization request. The exact value received from the client. 1228 For example, the authorization server redirects the user-agent by 1229 sending the following HTTP response: 1231 HTTP/1.1 302 Found 1232 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1233 &state=xyz 1235 The client MUST ignore unrecognized response parameters. The 1236 authorization code string size is left undefined by this 1237 specification. The client should avoid making assumptions about code 1238 value sizes. The authorization server SHOULD document the size of 1239 any value it issues. 1241 When the server issues the authorization code in the authorization 1242 response, it MUST associate the "code_challenge" and 1243 "code_challenge_method" values with the authorization code so it can 1244 be verified later. 1246 Typically, the "code_challenge" and "code_challenge_method" values 1247 are stored in encrypted form in the "code" itself but could 1248 alternatively be stored on the server associated with the code. The 1249 server MUST NOT include the "code_challenge" value in client requests 1250 in a form that other entities can extract. 1252 The exact method that the server uses to associate the 1253 "code_challenge" with the issued "code" is out of scope for this 1254 specification. 1256 4.1.2.1. Error Response 1258 If the request fails due to a missing, invalid, or mismatching 1259 redirection URI, or if the client identifier is missing or invalid, 1260 the authorization server SHOULD inform the resource owner of the 1261 error and MUST NOT automatically redirect the user-agent to the 1262 invalid redirection URI. 1264 If the client does not send the "code_challenge" in the request, the 1265 authorization endpoint MUST return the authorization error response 1266 with the "error" value set to "invalid_request". The 1267 "error_description" or the response of "error_uri" SHOULD explain the 1268 nature of error, e.g., code challenge required. 1270 If the server supporting PKCE does not support the requested 1271 transformation, the authorization endpoint MUST return the 1272 authorization error response with "error" value set to 1273 "invalid_request". The "error_description" or the response of 1274 "error_uri" SHOULD explain the nature of error, e.g., transform 1275 algorithm not supported. 1277 If the resource owner denies the access request or if the request 1278 fails for reasons other than a missing or invalid redirection URI, 1279 the authorization server informs the client by adding the following 1280 parameters to the query component of the redirection URI using the 1281 "application/x-www-form-urlencoded" format, per Appendix B: 1283 "error": REQUIRED. A single ASCII [USASCII] error code from the 1284 following: 1286 "invalid_request": The request is missing a required parameter, 1287 includes an invalid parameter value, includes a parameter more 1288 than once, or is otherwise malformed. 1290 "unauthorized_client": The client is not authorized to request an 1291 authorization code using this method. 1293 "access_denied": The resource owner or authorization server 1294 denied the request. 1296 "unsupported_response_type": The authorization server does not 1297 support obtaining an authorization code using this method. 1299 "invalid_scope": The requested scope is invalid, unknown, or 1300 malformed. 1302 "server_error": The authorization server encountered an 1303 unexpected condition that prevented it from fulfilling the 1304 request. (This error code is needed because a 500 Internal 1305 Server Error HTTP status code cannot be returned to the client 1306 via an HTTP redirect.) 1308 "temporarily_unavailable": The authorization server is currently 1309 unable to handle the request due to a temporary overloading or 1310 maintenance of the server. (This error code is needed because 1311 a 503 Service Unavailable HTTP status code cannot be returned 1312 to the client via an HTTP redirect.) 1314 Values for the "error" parameter MUST NOT include characters 1315 outside the set %x20-21 / %x23-5B / %x5D-7E. 1317 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1318 providing additional information, used to assist the client 1319 developer in understanding the error that occurred. Values for 1320 the "error_description" parameter MUST NOT include characters 1321 outside the set %x20-21 / %x23-5B / %x5D-7E. 1323 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1324 with information about the error, used to provide the client 1325 developer with additional information about the error. Values for 1326 the "error_uri" parameter MUST conform to the URI-reference syntax 1327 and thus MUST NOT include characters outside the set %x21 / 1328 %x23-5B / %x5D-7E. 1330 "state": REQUIRED if a "state" parameter was present in the client 1331 authorization request. The exact value received from the client. 1333 For example, the authorization server redirects the user-agent by 1334 sending the following HTTP response: 1336 HTTP/1.1 302 Found 1337 Location: https://client.example.com/cb?error=access_denied&state=xyz 1339 4.1.3. Access Token Request 1341 The client makes a request to the token endpoint by sending the 1342 following parameters using the "application/x-www-form-urlencoded" 1343 format per Appendix B with a character encoding of UTF-8 in the HTTP 1344 request entity-body: 1346 "grant_type": REQUIRED. Value MUST be set to "authorization_code". 1348 "code": REQUIRED. The authorization code received from the 1349 authorization server. 1351 "redirect_uri": REQUIRED, if the "redirect_uri" parameter was 1352 included in the authorization request as described in 1353 Section 4.1.1, and their values MUST be identical. 1355 "client_id": REQUIRED, if the client is not authenticating with the 1356 authorization server as described in Section 3.2.1. 1358 "code_verifier": REQUIRED. Code verifier 1360 If the client type is confidential or the client was issued client 1361 credentials (or assigned other authentication requirements), the 1362 client MUST authenticate with the authorization server as described 1363 in Section 3.2.1. 1365 For example, the client makes the following HTTP request using TLS 1366 (with extra line breaks for display purposes only): 1368 POST /token HTTP/1.1 1369 Host: server.example.com 1370 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1371 Content-Type: application/x-www-form-urlencoded 1373 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1374 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1375 &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed 1377 The authorization server MUST: 1379 * require client authentication for confidential clients or for any 1380 client that was issued client credentials (or with other 1381 authentication requirements), 1383 * authenticate the client if client authentication is included, 1385 * ensure that the authorization code was issued to the authenticated 1386 confidential client, or if the client is public, ensure that the 1387 code was issued to "client_id" in the request, 1389 * verify that the authorization code is valid, 1391 * verify the "code_verifier" by calculating the code challenge from 1392 the received "code_verifier" and comparing it with the previously 1393 associated "code_challenge", after first transforming it according 1394 to the "code_challenge_method" method specified by the client, and 1396 * ensure that the "redirect_uri" parameter is present if the 1397 "redirect_uri" parameter was included in the initial authorization 1398 request as described in Section 4.1.1, and if included ensure that 1399 their values are identical. 1401 4.1.4. Access Token Response 1403 If the access token request is valid and authorized, the 1404 authorization server issues an access token and optional refresh 1405 token as described in Section 5.1. If the request client 1406 authentication failed or is invalid, the authorization server returns 1407 an error response as described in Section 5.2. 1409 An example successful response: 1411 HTTP/1.1 200 OK 1412 Content-Type: application/json;charset=UTF-8 1413 Cache-Control: no-store 1414 Pragma: no-cache 1416 { 1417 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1418 "token_type": "Bearer", 1419 "expires_in": 3600, 1420 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 1421 "example_parameter": "example_value" 1422 } 1424 4.2. Client Credentials Grant 1426 The client can request an access token using only its client 1427 credentials (or other supported means of authentication) when the 1428 client is requesting access to the protected resources under its 1429 control, or those of another resource owner that have been previously 1430 arranged with the authorization server (the method of which is beyond 1431 the scope of this specification). 1433 The client credentials grant type MUST only be used by confidential 1434 clients. 1436 +---------+ +---------------+ 1437 | | | | 1438 | |>--(A)- Client Authentication --->| Authorization | 1439 | Client | | Server | 1440 | |<--(B)---- Access Token ---------<| | 1441 | | | | 1442 +---------+ +---------------+ 1444 Figure 4: Client Credentials Flow 1446 The flow illustrated in Figure 4 includes the following steps: 1448 (A) The client authenticates with the authorization server and 1449 requests an access token from the token endpoint. 1451 (B) The authorization server authenticates the client, and if valid, 1452 issues an access token. 1454 4.2.1. Authorization Request and Response 1456 Since the client authentication is used as the authorization grant, 1457 no additional authorization request is needed. 1459 4.2.2. Access Token Request 1461 The client makes a request to the token endpoint by adding the 1462 following parameters using the "application/x-www-form-urlencoded" 1463 format per Appendix B with a character encoding of UTF-8 in the HTTP 1464 request entity-body: 1466 "grant_type": REQUIRED. Value MUST be set to "client_credentials". 1468 "scope": OPTIONAL. The scope of the access request as described by 1469 Section 3.3. 1471 The client MUST authenticate with the authorization server as 1472 described in Section 3.2.1. 1474 For example, the client makes the following HTTP request using 1475 transport-layer security (with extra line breaks for display purposes 1476 only): 1478 POST /token HTTP/1.1 1479 Host: server.example.com 1480 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1481 Content-Type: application/x-www-form-urlencoded 1483 grant_type=client_credentials 1485 The authorization server MUST authenticate the client. 1487 4.2.3. Access Token Response 1489 If the access token request is valid and authorized, the 1490 authorization server issues an access token as described in 1491 Section 5.1. A refresh token SHOULD NOT be included. If the request 1492 failed client authentication or is invalid, the authorization server 1493 returns an error response as described in Section 5.2. 1495 An example successful response: 1497 HTTP/1.1 200 OK 1498 Content-Type: application/json;charset=UTF-8 1499 Cache-Control: no-store 1500 Pragma: no-cache 1502 { 1503 "access_token": "2YotnFZFEjr1zCsicMWpAA", 1504 "token_type": "Bearer", 1505 "expires_in": 3600, 1506 "example_parameter": "example_value" 1507 } 1509 4.3. Extension Grants 1511 The client uses an extension grant type by specifying the grant type 1512 using an absolute URI (defined by the authorization server) as the 1513 value of the "grant_type" parameter of the token endpoint, and by 1514 adding any additional parameters necessary. 1516 For example, to request an access token using a Security Assertion 1517 Markup Language (SAML) 2.0 assertion grant type as defined by 1518 [RFC7522], the client could make the following HTTP request using TLS 1519 (with extra line breaks for display purposes only): 1521 POST /token HTTP/1.1 1522 Host: server.example.com 1523 Content-Type: application/x-www-form-urlencoded 1525 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1526 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1527 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1529 If the access token request is valid and authorized, the 1530 authorization server issues an access token and optional refresh 1531 token as described in Section 5.1. If the request failed client 1532 authentication or is invalid, the authorization server returns an 1533 error response as described in Section 5.2. 1535 5. Issuing an Access Token 1537 If the access token request is valid and authorized, the 1538 authorization server issues an access token and optional refresh 1539 token as described in Section 5.1. If the request failed client 1540 authentication or is invalid, the authorization server returns an 1541 error response as described in Section 5.2. 1543 5.1. Successful Response 1545 The authorization server issues an access token and optional refresh 1546 token, and constructs the response by adding the following parameters 1547 to the entity-body of the HTTP response with a 200 (OK) status code: 1549 "access_token": REQUIRED. The access token issued by the 1550 authorization server. 1552 "token_type": REQUIRED. The type of the token issued as described 1553 in Section 7.1. Value is case insensitive. 1555 "expires_in": RECOMMENDED. The lifetime in seconds of the access 1556 token. For example, the value "3600" denotes that the access 1557 token will expire in one hour from the time the response was 1558 generated. If omitted, the authorization server SHOULD provide 1559 the expiration time via other means or document the default value. 1561 "refresh_token": OPTIONAL. The refresh token, which can be used to 1562 obtain new access tokens using the same authorization grant as 1563 described in Section 6. 1565 "scope": OPTIONAL, if identical to the scope requested by the 1566 client; otherwise, REQUIRED. The scope of the access token as 1567 described by Section 3.3. 1569 The parameters are included in the entity-body of the HTTP response 1570 using the "application/json" media type as defined by [RFC4627]. The 1571 parameters are serialized into a JavaScript Object Notation (JSON) 1572 structure by adding each parameter at the highest structure level. 1573 Parameter names and string values are included as JSON strings. 1574 Numerical values are included as JSON numbers. The order of 1575 parameters does not matter and can vary. 1577 The authorization server MUST include the HTTP "Cache-Control" 1578 response header field [RFC2616] with a value of "no-store" in any 1579 response containing tokens, credentials, or other sensitive 1580 information, as well as the "Pragma" response header field [RFC2616] 1581 with a value of "no-cache". 1583 For example: 1585 HTTP/1.1 200 OK 1586 Content-Type: application/json;charset=UTF-8 1587 Cache-Control: no-store 1588 Pragma: no-cache 1590 { 1591 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1592 "token_type":"Bearer", 1593 "expires_in":3600, 1594 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1595 "example_parameter":"example_value" 1596 } 1598 The client MUST ignore unrecognized value names in the response. The 1599 sizes of tokens and other values received from the authorization 1600 server are left undefined. The client should avoid making 1601 assumptions about value sizes. The authorization server SHOULD 1602 document the size of any value it issues. 1604 5.2. Error Response 1606 The authorization server responds with an HTTP 400 (Bad Request) 1607 status code (unless specified otherwise) and includes the following 1608 parameters with the response: 1610 The authorization server responds with an HTTP 400 (Bad Request) 1611 status code (unless specified otherwise) and includes the following 1612 parameters with the response: 1614 "error": REQUIRED. A single ASCII [USASCII] error code from the 1615 following: 1617 "invalid_request": The request is missing a required parameter, 1618 includes an unsupported parameter value (other than grant 1619 type), repeats a parameter, includes multiple credentials, 1620 utilizes more than one mechanism for authenticating the client, 1621 or is otherwise malformed. 1623 "invalid_client": Client authentication failed (e.g., unknown 1624 client, no client authentication included, or unsupported 1625 authentication method). The authorization server MAY return an 1626 HTTP 401 (Unauthorized) status code to indicate which HTTP 1627 authentication schemes are supported. If the client attempted 1628 to authenticate via the "Authorization" request header field, 1629 the authorization server MUST respond with an HTTP 401 1630 (Unauthorized) status code and include the "WWW-Authenticate" 1631 response header field matching the authentication scheme used 1632 by the client. 1634 "invalid_grant": The provided authorization grant (e.g., 1635 authorization code, resource owner credentials) or refresh 1636 token is invalid, expired, revoked, does not match the 1637 redirection URI used in the authorization request, or was 1638 issued to another client. 1640 "unauthorized_client": The authenticated client is not authorized 1641 to use this authorization grant type. 1643 "unsupported_grant_type": The authorization grant type is not 1644 supported by the authorization server. 1646 "invalid_scope": The requested scope is invalid, unknown, 1647 malformed, or exceeds the scope granted by the resource owner. 1649 Values for the "error" parameter MUST NOT include characters 1650 outside the set %x20-21 / %x23-5B / %x5D-7E. 1652 "error_description": OPTIONAL. Human-readable ASCII [USASCII] text 1653 providing additional information, used to assist the client 1654 developer in understanding the error that occurred. Values for 1655 the "error_description" parameter MUST NOT include characters 1656 outside the set %x20-21 / %x23-5B / %x5D-7E. 1658 "error_uri": OPTIONAL. A URI identifying a human-readable web page 1659 with information about the error, used to provide the client 1660 developer with additional information about the error. Values for 1661 the "error_uri" parameter MUST conform to the URI-reference syntax 1662 and thus MUST NOT include characters outside the set %x21 / 1663 %x23-5B / %x5D-7E. 1665 The parameters are included in the entity-body of the HTTP response 1666 using the "application/json" media type as defined by [RFC4627]. The 1667 parameters are serialized into a JSON structure by adding each 1668 parameter at the highest structure level. Parameter names and string 1669 values are included as JSON strings. Numerical values are included 1670 as JSON numbers. The order of parameters does not matter and can 1671 vary. 1673 For example: 1675 HTTP/1.1 400 Bad Request 1676 Content-Type: application/json;charset=UTF-8 1677 Cache-Control: no-store 1678 Pragma: no-cache 1680 { 1681 "error":"invalid_request" 1682 } 1684 6. Refreshing an Access Token 1686 Authorization servers SHOULD determine, based on a risk assessment, 1687 whether to issue refresh tokens to a certain client. If the 1688 authorization server decides not to issue refresh tokens, the client 1689 MAY refresh access tokens by utilizing other grant types, such as the 1690 authorization code grant type. In such a case, the authorization 1691 server may utilize cookies and persistent grants to optimize the user 1692 experience. 1694 If refresh tokens are issued, those refresh tokens MUST be bound to 1695 the scope and resource servers as consented by the resource owner. 1696 This is to prevent privilege escalation by the legitimate client and 1697 reduce the impact of refresh token leakage. 1699 If the authorization server issued a refresh token to the client, the 1700 client makes a refresh request to the token endpoint by adding the 1701 following parameters using the "application/x-www-form-urlencoded" 1702 format per Appendix B with a character encoding of UTF-8 in the HTTP 1703 request entity-body: 1705 "grant_type": REQUIRED. Value MUST be set to "refresh_token". 1707 "refresh_token": REQUIRED. The refresh token issued to the client. 1709 "scope": OPTIONAL. The scope of the access request as described by 1710 Section 3.3. The requested scope MUST NOT include any scope not 1711 originally granted by the resource owner, and if omitted is 1712 treated as equal to the scope originally granted by the resource 1713 owner. 1715 Because refresh tokens are typically long-lasting credentials used to 1716 request additional access tokens, the refresh token is bound to the 1717 client to which it was issued. If the client type is confidential or 1718 the client was issued client credentials (or assigned other 1719 authentication requirements), the client MUST authenticate with the 1720 authorization server as described in Section 3.2.1. 1722 For example, the client makes the following HTTP request using 1723 transport-layer security (with extra line breaks for display purposes 1724 only): 1726 POST /token HTTP/1.1 1727 Host: server.example.com 1728 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1729 Content-Type: application/x-www-form-urlencoded 1731 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1733 The authorization server MUST: 1735 * require client authentication for confidential clients or for any 1736 client that was issued client credentials (or with other 1737 authentication requirements), 1739 * authenticate the client if client authentication is included and 1740 ensure that the refresh token was issued to the authenticated 1741 client, and 1743 * validate the refresh token. 1745 Authorization server MUST utilize one of these methods to detect 1746 refresh token replay by malicious actors for public clients: 1748 * _Sender-constrained refresh tokens:_ the authorization server 1749 cryptographically binds the refresh token to a certain client 1750 instance by utilizing [I-D.ietf-oauth-token-binding] or [RFC8705]. 1752 * _Refresh token rotation:_ the authorization server issues a new 1753 refresh token with every access token refresh response. The 1754 previous refresh token is invalidated but information about the 1755 relationship is retained by the authorization server. If a 1756 refresh token is compromised and subsequently used by both the 1757 attacker and the legitimate client, one of them will present an 1758 invalidated refresh token, which will inform the authorization 1759 server of the breach. The authorization server cannot determine 1760 which party submitted the invalid refresh token, but it will 1761 revoke the active refresh token. This stops the attack at the 1762 cost of forcing the legitimate client to obtain a fresh 1763 authorization grant. 1765 Implementation note: the grant to which a refresh token belongs 1766 may be encoded into the refresh token itself. This can enable an 1767 authorization server to efficiently determine the grant to which a 1768 refresh token belongs, and by extension, all refresh tokens that 1769 need to be revoked. Authorization servers MUST ensure the 1770 integrity of the refresh token value in this case, for example, 1771 using signatures. 1773 If valid and authorized, the authorization server issues an access 1774 token as described in Section 5.1. If the request failed 1775 verification or is invalid, the authorization server returns an error 1776 response as described in Section 5.2. 1778 The authorization server MAY issue a new refresh token, in which case 1779 the client MUST discard the old refresh token and replace it with the 1780 new refresh token. The authorization server MAY revoke the old 1781 refresh token after issuing a new refresh token to the client. If a 1782 new refresh token is issued, the refresh token scope MUST be 1783 identical to that of the refresh token included by the client in the 1784 request. 1786 Authorization servers MAY revoke refresh tokens automatically in case 1787 of a security event, such as: 1789 * password change 1791 * logout at the authorization server 1793 Refresh tokens SHOULD expire if the client has been inactive for some 1794 time, i.e., the refresh token has not been used to obtain fresh 1795 access tokens for some time. The expiration time is at the 1796 discretion of the authorization server. It might be a global value 1797 or determined based on the client policy or the grant associated with 1798 the refresh token (and its sensitivity). 1800 7. Accessing Protected Resources 1802 The client accesses protected resources by presenting the access 1803 token to the resource server. The resource server MUST validate the 1804 access token and ensure that it has not expired and that its scope 1805 covers the requested resource. The methods used by the resource 1806 server to validate the access token (as well as any error responses) 1807 are beyond the scope of this specification but generally involve an 1808 interaction or coordination between the resource server and the 1809 authorization server. 1811 The method in which the client utilizes the access token to 1812 authenticate with the resource server depends on the type of access 1813 token issued by the authorization server. Typically, it involves 1814 using the HTTP "Authorization" request header field [RFC2617] with an 1815 authentication scheme defined by the specification of the access 1816 token type used, such as "Bearer", defined below. 1818 7.1. Access Token Types 1820 The access token type provides the client with the information 1821 required to successfully utilize the access token to make a protected 1822 resource request (along with type-specific attributes). The client 1823 MUST NOT use an access token if it does not understand the token 1824 type. 1826 For example, the "Bearer" token type defined in this specification is 1827 utilized by simply including the access token string in the request: 1829 GET /resource/1 HTTP/1.1 1830 Host: example.com 1831 Authorization: Bearer mF_9.B5f-4.1JqM 1833 The above example is provided for illustration purposes only. 1835 Each access token type definition specifies the additional attributes 1836 (if any) sent to the client together with the "access_token" response 1837 parameter. It also defines the HTTP authentication method used to 1838 include the access token when making a protected resource request. 1840 7.2. Bearer Tokens 1842 A Bearer Token is a security token with the property that any party 1843 in possession of the token (a "bearer") can use the token in any way 1844 that any other party in possession of it can. Using a bearer token 1845 does not require a bearer to prove possession of cryptographic key 1846 material (proof-of-possession). 1848 Bearer tokens may be extended to include proof-of-possession 1849 techniques by other specifications. 1851 7.2.1. Authenticated Requests 1853 This section defines two methods of sending Bearer tokens in resource 1854 requetss to resource servers. Clients MUST NOT use more than one 1855 method to transmit the token in each request. 1857 7.2.1.1. Authorization Request Header Field 1859 When sending the access token in the "Authorization" request header 1860 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 1861 authentication scheme to transmit the access token. 1863 For example: 1865 GET /resource HTTP/1.1 1866 Host: server.example.com 1867 Authorization: Bearer mF_9.B5f-4.1JqM 1869 The syntax of the "Authorization" header field for this scheme 1870 follows the usage of the Basic scheme defined in Section 2 of 1871 [RFC2617]. Note that, as with Basic, it does not conform to the 1872 generic syntax defined in Section 1.2 of [RFC2617] but is compatible 1873 with the general authentication framework in HTTP 1.1 Authentication 1874 [RFC7235], although it does not follow the preferred practice 1875 outlined therein in order to reflect existing deployments. The 1876 syntax for Bearer credentials is as follows: 1878 b64token = 1*( ALPHA / DIGIT / 1879 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 1880 credentials = "Bearer" 1*SP b64token 1882 Clients SHOULD make authenticated requests with a bearer token using 1883 the "Authorization" request header field with the "Bearer" HTTP 1884 authorization scheme. Resource servers MUST support this method. 1886 7.2.1.2. Form-Encoded Body Parameter 1888 When sending the access token in the HTTP request entity-body, the 1889 client adds the access token to the request-body using the 1890 "access_token" parameter. The client MUST NOT use this method unless 1891 all of the following conditions are met: 1893 * The HTTP request entity-header includes the "Content-Type" header 1894 field set to "application/x-www-form-urlencoded". 1896 * The entity-body follows the encoding requirements of the 1897 "application/x-www-form-urlencoded" content-type as defined by 1898 HTML 4.01 [W3C.REC-html401-19991224]. 1900 * The HTTP request entity-body is single-part. 1902 * The content to be encoded in the entity-body MUST consist entirely 1903 of ASCII [USASCII] characters. 1905 * The HTTP request method is one for which the request-body has 1906 defined semantics. In particular, this means that the "GET" 1907 method MUST NOT be used. 1909 The entity-body MAY include other request-specific parameters, in 1910 which case the "access_token" parameter MUST be properly separated 1911 from the request-specific parameters using "&" character(s) (ASCII 1912 code 38). 1914 For example, the client makes the following HTTP request using 1915 transport-layer security: 1917 POST /resource HTTP/1.1 1918 Host: server.example.com 1919 Content-Type: application/x-www-form-urlencoded 1921 access_token=mF_9.B5f-4.1JqM 1923 The "application/x-www-form-urlencoded" method SHOULD NOT be used 1924 except in application contexts where participating clients do not 1925 have access to the "Authorization" request header field. Resource 1926 servers MAY support this method. 1928 7.2.2. The WWW-Authenticate Response Header Field 1930 If the protected resource request does not include authentication 1931 credentials or does not contain an access token that enables access 1932 to the protected resource, the resource server MUST include the HTTP 1933 "WWW-Authenticate" response header field; it MAY include it in 1934 response to other conditions as well. The "WWW-Authenticate" header 1935 field uses the framework defined by HTTP/1.1 [RFC2617]. 1937 All challenges defined by this specification MUST use the auth-scheme 1938 value "Bearer". This scheme MUST be followed by one or more auth- 1939 param values. The auth-param attributes used or defined by this 1940 specification are as follows. Other auth-param attributes MAY be 1941 used as well. 1943 A "realm" attribute MAY be included to indicate the scope of 1944 protection in the manner described in HTTP/1.1 [RFC2617]. The 1945 "realm" attribute MUST NOT appear more than once. 1947 The "scope" attribute is defined in Section 3.3. The "scope" 1948 attribute is a space-delimited list of case-sensitive scope values 1949 indicating the required scope of the access token for accessing the 1950 requested resource. "scope" values are implementation defined; there 1951 is no centralized registry for them; allowed values are defined by 1952 the authorization server. The order of "scope" values is not 1953 significant. In some cases, the "scope" value will be used when 1954 requesting a new access token with sufficient scope of access to 1955 utilize the protected resource. Use of the "scope" attribute is 1956 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 1957 "scope" value is intended for programmatic use and is not meant to be 1958 displayed to end-users. 1960 Two example scope values follow; these are taken from the OpenID 1961 Connect [OpenID.Messages] and the Open Authentication Technology 1962 Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 1963 OAuth 2.0 use cases, respectively: 1965 scope="openid profile email" 1966 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 1968 If the protected resource request included an access token and failed 1969 authentication, the resource server SHOULD include the "error" 1970 attribute to provide the client with the reason why the access 1971 request was declined. The parameter value is described in 1972 Section 7.3.1. In addition, the resource server MAY include the 1973 "error_description" attribute to provide developers a human-readable 1974 explanation that is not meant to be displayed to end-users. It also 1975 MAY include the "error_uri" attribute with an absolute URI 1976 identifying a human-readable web page explaining the error. The 1977 "error", "error_description", and "error_uri" attributes MUST NOT 1978 appear more than once. 1980 Values for the "scope" attribute (specified in Appendix A.4) MUST NOT 1981 include characters outside the set %x21 / %x23-5B / %x5D-7E for 1982 representing scope values and %x20 for delimiters between scope 1983 values. Values for the "error" and "error_description" attributes 1984 (specified in Appendixes A.7 and A.8) MUST NOT include characters 1985 outside the set %x20-21 / %x23-5B / %x5D-7E. Values for the 1986 "error_uri" attribute (specified in Appendix A.9 of) MUST conform to 1987 the URI-reference syntax and thus MUST NOT include characters outside 1988 the set %x21 / %x23-5B / %x5D-7E. 1990 For example, in response to a protected resource request without 1991 authentication: 1993 HTTP/1.1 401 Unauthorized 1994 WWW-Authenticate: Bearer realm="example" 1996 And in response to a protected resource request with an 1997 authentication attempt using an expired access token: 1999 HTTP/1.1 401 Unauthorized 2000 WWW-Authenticate: Bearer realm="example", 2001 error="invalid_token", 2002 error_description="The access token expired" 2004 7.3. Error Response 2006 If a resource access request fails, the resource server SHOULD inform 2007 the client of the error. While the specifics of such error responses 2008 are beyond the scope of this specification, this document establishes 2009 a common registry in Section 12.4 for error values to be shared among 2010 OAuth token authentication schemes. 2012 New authentication schemes designed primarily for OAuth token 2013 authentication SHOULD define a mechanism for providing an error 2014 status code to the client, in which the error values allowed are 2015 registered in the error registry established by this specification. 2017 Such schemes MAY limit the set of valid error codes to a subset of 2018 the registered values. If the error code is returned using a named 2019 parameter, the parameter name SHOULD be "error". 2021 Other schemes capable of being used for OAuth token authentication, 2022 but not primarily designed for that purpose, MAY bind their error 2023 values to the registry in the same manner. 2025 New authentication schemes MAY choose to also specify the use of the 2026 "error_description" and "error_uri" parameters to return error 2027 information in a manner parallel to their usage in this 2028 specification. 2030 7.3.1. Error Codes 2032 When a request fails, the resource server responds using the 2033 appropriate HTTP status code (typically, 400, 401, 403, or 405) and 2034 includes one of the following error codes in the response: 2036 "invalid_request": The request is missing a required parameter, 2037 includes an unsupported parameter or parameter value, repeats the 2038 same parameter, uses more than one method for including an access 2039 token, or is otherwise malformed. The resource server SHOULD 2040 respond with the HTTP 400 (Bad Request) status code. 2042 "invalid_token": The access token provided is expired, revoked, 2043 malformed, or invalid for other reasons. The resource SHOULD 2044 respond with the HTTP 401 (Unauthorized) status code. The client 2045 MAY request a new access token and retry the protected resource 2046 request. 2048 "insufficient_scope": The request requires higher privileges than 2049 provided by the access token. The resource server SHOULD respond 2050 with the HTTP 403 (Forbidden) status code and MAY include the 2051 "scope" attribute with the scope necessary to access the protected 2052 resource. 2054 If the request lacks any authentication information (e.g., the client 2055 was unaware that authentication is necessary or attempted using an 2056 unsupported authentication method), the resource server SHOULD NOT 2057 include an error code or other error information. 2059 For example: 2061 HTTP/1.1 401 Unauthorized 2062 WWW-Authenticate: Bearer realm="example" 2064 7.4. Access Token Security Considerations 2066 7.4.1. Security Threats 2068 The following list presents several common threats against protocols 2069 utilizing some form of tokens. This list of threats is based on NIST 2070 Special Publication 800-63 [NIST800-63]. 2072 7.4.1.1. Token manufacture/modification 2074 An attacker may generate a bogus token or modify the token contents 2075 (such as the authentication or attribute statements) of an existing 2076 token, causing the resource server to grant inappropriate access to 2077 the client. For example, an attacker may modify the token to extend 2078 the validity period; a malicious client may modify the assertion to 2079 gain access to information that they should not be able to view. 2081 7.4.1.2. Token disclosure 2083 Tokens may contain authentication and attribute statements that 2084 include sensitive information. 2086 7.4.1.3. Token redirect 2088 An attacker uses a token generated for consumption by one resource 2089 server to gain access to a different resource server that mistakenly 2090 believes the token to be for it. 2092 7.4.1.4. Token replay 2094 An attacker attempts to use a token that has already been used with 2095 that resource server in the past. 2097 7.4.2. Threat Mitigation 2099 A large range of threats can be mitigated by protecting the contents 2100 of the token by using a digital signature. Alternatively, a bearer 2101 token can contain a reference to authorization information, rather 2102 than encoding the information directly. Such references MUST be 2103 infeasible for an attacker to guess; using a reference may require an 2104 extra interaction between a server and the token issuer to resolve 2105 the reference to the authorization information. The mechanics of 2106 such an interaction are not defined by this specification. 2108 This document does not specify the encoding or the contents of the 2109 token; hence, detailed recommendations about the means of 2110 guaranteeing token integrity protection are outside the scope of this 2111 document. The token integrity protection MUST be sufficient to 2112 prevent the token from being modified. 2114 To deal with token redirect, it is important for the authorization 2115 server to include the identity of the intended recipients (the 2116 audience), typically a single resource server (or a list of resource 2117 servers), in the token. Restricting the use of the token to a 2118 specific scope is also RECOMMENDED. 2120 The authorization server MUST implement TLS. Which version(s) ought 2121 to be implemented will vary over time and will depend on the 2122 widespread deployment and known security vulnerabilities at the time 2123 of implementation. 2125 To protect against token disclosure, confidentiality protection MUST 2126 be applied using TLS with a ciphersuite that provides confidentiality 2127 and integrity protection. This requires that the communication 2128 interaction between the client and the authorization server, as well 2129 as the interaction between the client and the resource server, 2130 utilize confidentiality and integrity protection. Since TLS is 2131 mandatory to implement and to use with this specification, it is the 2132 preferred approach for preventing token disclosure via the 2133 communication channel. For those cases where the client is prevented 2134 from observing the contents of the token, token encryption MUST be 2135 applied in addition to the usage of TLS protection. As a further 2136 defense against token disclosure, the client MUST validate the TLS 2137 certificate chain when making requests to protected resources, 2138 including checking the Certificate Revocation List (CRL) [RFC5280]. 2140 Cookies are typically transmitted in the clear. Thus, any 2141 information contained in them is at risk of disclosure. Therefore, 2142 Bearer tokens MUST NOT be stored in cookies that can be sent in the 2143 clear, as any information in them is at risk of disclosure. See 2144 "HTTP State Management Mechanism" [RFC6265] for security 2145 considerations about cookies. 2147 In some deployments, including those utilizing load balancers, the 2148 TLS connection to the resource server terminates prior to the actual 2149 server that provides the resource. This could leave the token 2150 unprotected between the front-end server where the TLS connection 2151 terminates and the back-end server that provides the resource. In 2152 such deployments, sufficient measures MUST be employed to ensure 2153 confidentiality of the token between the front-end and back-end 2154 servers; encryption of the token is one such possible measure. 2156 To deal with token capture and replay, the following recommendations 2157 are made: First, the lifetime of the token MUST be limited; one means 2158 of achieving this is by putting a validity time field inside the 2159 protected part of the token. Note that using short-lived (one hour 2160 or less) tokens reduces the impact of them being leaked. Second, 2161 confidentiality protection of the exchanges between the client and 2162 the authorization server and between the client and the resource 2163 server MUST be applied. As a consequence, no eavesdropper along the 2164 communication path is able to observe the token exchange. 2165 Consequently, such an on-path adversary cannot replay the token. 2166 Furthermore, when presenting the token to a resource server, the 2167 client MUST verify the identity of that resource server, as per 2168 Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST 2169 validate the TLS certificate chain when making these requests to 2170 protected resources. Presenting the token to an unauthenticated and 2171 unauthorized resource server or failing to validate the certificate 2172 chain will allow adversaries to steal the token and gain unauthorized 2173 access to protected resources. 2175 7.4.3. Summary of Recommendations 2177 7.4.3.1. Safeguard bearer tokens 2179 Client implementations MUST ensure that bearer tokens are not leaked 2180 to unintended parties, as they will be able to use them to gain 2181 access to protected resources. This is the primary security 2182 consideration when using bearer tokens and underlies all the more 2183 specific recommendations that follow. 2185 7.4.3.2. Validate TLS certificate chains 2187 The client MUST validate the TLS certificate chain when making 2188 requests to protected resources. Failing to do so may enable DNS 2189 hijacking attacks to steal the token and gain unintended access. 2191 7.4.3.3. Always use TLS (https) 2193 Clients MUST always use TLS (https) or equivalent transport security 2194 when making requests with bearer tokens. Failing to do so exposes 2195 the token to numerous attacks that could give attackers unintended 2196 access. 2198 7.4.3.4. Don't store bearer tokens in HTTP cookies 2200 Implementations MUST NOT store bearer tokens within cookies that can 2201 be sent in the clear (which is the default transmission mode for 2202 cookies). Implementations that do store bearer tokens in cookies 2203 MUST take precautions against cross-site request forgery. 2205 7.4.3.5. Issue short-lived bearer tokens 2207 Token servers SHOULD issue short-lived (one hour or less) bearer 2208 tokens, particularly when issuing tokens to clients that run within a 2209 web browser or other environments where information leakage may 2210 occur. Using short-lived bearer tokens can reduce the impact of them 2211 being leaked. 2213 7.4.3.6. Issue scoped bearer tokens 2215 Token servers SHOULD issue bearer tokens that contain an audience 2216 restriction, scoping their use to the intended relying party or set 2217 of relying parties. 2219 7.4.3.7. Don't pass bearer tokens in page URLs 2221 Bearer tokens MUST NOT be passed in page URLs (for example, as query 2222 string parameters). Instead, bearer tokens SHOULD be passed in HTTP 2223 message headers or message bodies for which confidentiality measures 2224 are taken. Browsers, web servers, and other software may not 2225 adequately secure URLs in the browser history, web server logs, and 2226 other data structures. If bearer tokens are passed in page URLs, 2227 attackers might be able to steal them from the history data, logs, or 2228 other unsecured locations. 2230 7.4.4. Token Replay Prevention 2232 A sender-constrained access token scopes the applicability of an 2233 access token to a certain sender. This sender is obliged to 2234 demonstrate knowledge of a certain secret as prerequisite for the 2235 acceptance of that token at the recipient (e.g., a resource server). 2237 Authorization and resource servers SHOULD use mechanisms for sender- 2238 constrained access tokens to prevent token replay as described in 2239 Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of 2240 Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 2242 It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be 2243 terminated at an intermediary, refer to Section 4.11 of 2244 [I-D.ietf-oauth-security-topics] for further security advice. 2246 7.4.5. Access Token Privilege Restriction 2248 The privileges associated with an access token SHOULD be restricted 2249 to the minimum required for the particular application or use case. 2250 This prevents clients from exceeding the privileges authorized by the 2251 resource owner. It also prevents users from exceeding their 2252 privileges authorized by the respective security policy. Privilege 2253 restrictions also help to reduce the impact of access token leakage. 2255 In particular, access tokens SHOULD be restricted to certain resource 2256 servers (audience restriction), preferably to a single resource 2257 server. To put this into effect, the authorization server associates 2258 the access token with certain resource servers and every resource 2259 server is obliged to verify, for every request, whether the access 2260 token sent with that request was meant to be used for that particular 2261 resource server. If not, the resource server MUST refuse to serve 2262 the respective request. Clients and authorization servers MAY 2263 utilize the parameters "scope" or "resource" as specified in this 2264 document and [I-D.ietf-oauth-resource-indicators], respectively, to 2265 determine the resource server they want to access. 2267 Additionally, access tokens SHOULD be restricted to certain resources 2268 and actions on resource servers or resources. To put this into 2269 effect, the authorization server associates the access token with the 2270 respective resource and actions and every resource server is obliged 2271 to verify, for every request, whether the access token sent with that 2272 request was meant to be used for that particular action on the 2273 particular resource. If not, the resource server must refuse to 2274 serve the respective request. Clients and authorization servers MAY 2275 utilize the parameter "scope" and "authorization_details" as 2276 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2277 actions. 2279 8. Extensibility 2281 8.1. Defining Access Token Types 2283 Access token types can be defined in one of two ways: registered in 2284 the Access Token Types registry (following the procedures in 2285 Section 12.1), or by using a unique absolute URI as its name. 2287 Types utilizing a URI name SHOULD be limited to vendor-specific 2288 implementations that are not commonly applicable, and are specific to 2289 the implementation details of the resource server where they are 2290 used. 2292 All other types MUST be registered. Type names MUST conform to the 2293 type-name ABNF. If the type definition includes a new HTTP 2294 authentication scheme, the type name SHOULD be identical to the HTTP 2295 authentication scheme name (as defined by [RFC2617]). The token type 2296 "example" is reserved for use in examples. 2298 type-name = 1*name-char 2299 name-char = "-" / "." / "_" / DIGIT / ALPHA 2301 8.2. Defining New Endpoint Parameters 2303 New request or response parameters for use with the authorization 2304 endpoint or the token endpoint are defined and registered in the 2305 OAuth Parameters registry following the procedure in Section 12.2. 2307 Parameter names MUST conform to the param-name ABNF, and parameter 2308 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2309 to the syntax of an existing parameter). 2311 param-name = 1*name-char 2312 name-char = "-" / "." / "_" / DIGIT / ALPHA 2314 Unregistered vendor-specific parameter extensions that are not 2315 commonly applicable and that are specific to the implementation 2316 details of the authorization server where they are used SHOULD 2317 utilize a vendor-specific prefix that is not likely to conflict with 2318 other registered values (e.g., begin with 'companyname_'). 2320 8.3. Defining New Authorization Grant Types 2322 New authorization grant types can be defined by assigning them a 2323 unique absolute URI for use with the "grant_type" parameter. If the 2324 extension grant type requires additional token endpoint parameters, 2325 they MUST be registered in the OAuth Parameters registry as described 2326 by Section 12.2. 2328 8.4. Defining New Authorization Endpoint Response Types 2330 New response types for use with the authorization endpoint are 2331 defined and registered in the Authorization Endpoint Response Types 2332 registry following the procedure in Section 12.3. Response type 2333 names MUST conform to the response-type ABNF. 2335 response-type = response-name *( SP response-name ) 2336 response-name = 1*response-char 2337 response-char = "_" / DIGIT / ALPHA 2339 If a response type contains one or more space characters (%x20), it 2340 is compared as a space-delimited list of values in which the order of 2341 values does not matter. Only one order of values can be registered, 2342 which covers all other arrangements of the same set of values. 2344 For example, the response type "token code" is left undefined by this 2345 specification. However, an extension can define and register the 2346 "token code" response type. Once registered, the same combination 2347 cannot be registered as "code token", but both values can be used to 2348 denote the same response type. 2350 8.5. Defining Additional Error Codes 2352 In cases where protocol extensions (i.e., access token types, 2353 extension parameters, or extension grant types) require additional 2354 error codes to be used with the authorization code grant error 2355 response (Section 4.1.2.1), the token error response (Section 5.2), 2356 or the resource access error response (Section 7.3), such error codes 2357 MAY be defined. 2359 Extension error codes MUST be registered (following the procedures in 2360 Section 12.4) if the extension they are used in conjunction with is a 2361 registered access token type, a registered endpoint parameter, or an 2362 extension grant type. Error codes used with unregistered extensions 2363 MAY be registered. 2365 Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2366 an identifying name when possible. For example, an error identifying 2367 an invalid value set to the extension parameter "example" SHOULD be 2368 named "example_invalid". 2370 error = 1*error-char 2371 error-char = %x20-21 / %x23-5B / %x5D-7E 2373 9. Security Considerations 2375 As a flexible and extensible framework, OAuth's security 2376 considerations depend on many factors. The following sections 2377 provide implementers with security guidelines focused on the three 2378 client profiles described in Section 2.1: web application, browser- 2379 based application, and native application. 2381 A comprehensive OAuth security model and analysis, as well as 2382 background for the protocol design, is provided by [RFC6819] and 2383 [I-D.ietf-oauth-security-topics]. 2385 9.1. Client Authentication 2387 Authorization servers SHOULD use client authentication if possible. 2389 It is RECOMMENDED to use asymmetric (public-key based) methods for 2390 client authentication such as mTLS [RFC8705] or "private_key_jwt" 2391 [OpenID]. When asymmetric methods for client authentication are 2392 used, authorization servers do not need to store sensitive symmetric 2393 keys, making these methods more robust against a number of attacks. 2395 Authorization server MUST only rely on client authentication if the 2396 process of issuance/registration and distribution of the underlying 2397 credentials ensures their confidentiality. 2399 When client authentication is not possible, the authorization server 2400 SHOULD employ other means to validate the client's identity - for 2401 example, by requiring the registration of the client redirection URI 2402 or enlisting the resource owner to confirm identity. A valid 2403 redirection URI is not sufficient to verify the client's identity 2404 when asking for resource owner authorization but can be used to 2405 prevent delivering credentials to a counterfeit client after 2406 obtaining resource owner authorization. 2408 The authorization server must consider the security implications of 2409 interacting with unauthenticated clients and take measures to limit 2410 the potential exposure of other credentials (e.g., refresh tokens) 2411 issued to such clients. 2413 The privileges an authorization server associates with a certain 2414 client identity MUST depend on the assessment of the overall process 2415 for client identification and client credential lifecycle management. 2416 For example, authentication of a dynamically registered client just 2417 ensures the authorization server it is talking to the same client 2418 again. In contrast, if there is a web application whose developer's 2419 identity was verified, who signed a contract and is issued a client 2420 secret that is only used in a secure backend service, the 2421 authorization server might allow this client to access more sensible 2422 services or to use the client credential grant type. 2424 9.1.1. Client Authentication of Native Apps 2426 Secrets that are statically included as part of an app distributed to 2427 multiple users should not be treated as confidential secrets, as one 2428 user may inspect their copy and learn the shared secret. For this 2429 reason, it is NOT RECOMMENDED for authorization servers to require 2430 client authentication of public native apps clients using a shared 2431 secret, as this serves little value beyond client identification 2432 which is already provided by the "client_id" request parameter. 2434 Authorization servers that still require a statically included shared 2435 secret for native app clients MUST treat the client as a public 2436 client (as defined in Section 2.1), and not accept the secret as 2437 proof of the client's identity. Without additional measures, such 2438 clients are subject to client impersonation (see Section 9.3.1). 2440 9.2. Registration of Native App Clients 2442 Except when using a mechanism like Dynamic Client Registration 2443 [RFC7591] to provision per-instance secrets, native apps are 2444 classified as public clients, as defined in Section 2.1; they MUST be 2445 registered with the authorization server as such. Authorization 2446 servers MUST record the client type in the client registration 2447 details in order to identify and process requests accordingly. 2449 Authorization servers MUST require clients to register their complete 2450 redirect URI (including the path component) and reject authorization 2451 requests that specify a redirect URI that doesn't exactly match the 2452 one that was registered; the exception is loopback redirects, where 2453 an exact match is required except for the port URI component. 2455 For private-use URI scheme-based redirects, authorization servers 2456 SHOULD enforce the requirement in Section 10.3.1 that clients use 2457 schemes that are reverse domain name based. At a minimum, any 2458 private-use URI scheme that doesn't contain a period character (".") 2459 SHOULD be rejected. 2461 In addition to the collision-resistant properties, requiring a URI 2462 scheme based on a domain name that is under the control of the app 2463 can help to prove ownership in the event of a dispute where two apps 2464 claim the same private-use URI scheme (where one app is acting 2465 maliciously). For example, if two apps claimed "com.example.app", 2466 the owner of "example.com" could petition the app store operator to 2467 remove the counterfeit app. Such a petition is harder to prove if a 2468 generic URI scheme was used. 2470 Authorization servers MAY request the inclusion of other platform- 2471 specific information, such as the app package or bundle name, or 2472 other information that may be useful for verifying the calling app's 2473 identity on operating systems that support such functions. 2475 9.3. Client Impersonation 2477 A malicious client can impersonate another client and obtain access 2478 to protected resources if the impersonated client fails to, or is 2479 unable to, keep its client credentials confidential. 2481 The authorization server MUST authenticate the client whenever 2482 possible. If the authorization server cannot authenticate the client 2483 due to the client's nature, the authorization server MUST require the 2484 registration of any redirection URI used for receiving authorization 2485 responses and SHOULD utilize other means to protect resource owners 2486 from such potentially malicious clients. For example, the 2487 authorization server can engage the resource owner to assist in 2488 identifying the client and its origin. 2490 The authorization server SHOULD enforce explicit resource owner 2491 authentication and provide the resource owner with information about 2492 the client and the requested authorization scope and lifetime. It is 2493 up to the resource owner to review the information in the context of 2494 the current client and to authorize or deny the request. 2496 The authorization server SHOULD NOT process repeated authorization 2497 requests automatically (without active resource owner interaction) 2498 without authenticating the client or relying on other measures to 2499 ensure that the repeated request comes from the original client and 2500 not an impersonator. 2502 9.3.1. Impersonation of Native Apps 2504 As stated above, the authorization server SHOULD NOT process 2505 authorization requests automatically without user consent or 2506 interaction, except when the identity of the client can be assured. 2507 This includes the case where the user has previously approved an 2508 authorization request for a given client id - unless the identity of 2509 the client can be proven, the request SHOULD be processed as if no 2510 previous request had been approved. 2512 Measures such as claimed "https" scheme redirects MAY be accepted by 2513 authorization servers as identity proof. Some operating systems may 2514 offer alternative platform-specific identity features that MAY be 2515 accepted, as appropriate. 2517 9.4. Access Tokens 2519 Access token credentials (as well as any confidential access token 2520 attributes) MUST be kept confidential in transit and storage, and 2521 only shared among the authorization server, the resource servers the 2522 access token is valid for, and the client to whom the access token is 2523 issued. Access token credentials MUST only be transmitted using TLS 2524 as described in Section 1.6 with server authentication as defined by 2525 [RFC2818]. 2527 The authorization server MUST ensure that access tokens cannot be 2528 generated, modified, or guessed to produce valid access tokens by 2529 unauthorized parties. 2531 9.4.1. Access Token Privilege Restriction 2533 The client SHOULD request access tokens with the minimal scope 2534 necessary. The authorization server SHOULD take the client identity 2535 into account when choosing how to honor the requested scope and MAY 2536 issue an access token with less rights than requested. 2538 The privileges associated with an access token SHOULD be restricted 2539 to the minimum required for the particular application or use case. 2540 This prevents clients from exceeding the privileges authorized by the 2541 resource owner. It also prevents users from exceeding their 2542 privileges authorized by the respective security policy. Privilege 2543 restrictions also help to reduce the impact of access token leakage. 2545 In particular, access tokens SHOULD be restricted to certain resource 2546 servers (audience restriction), preferably to a single resource 2547 server. To put this into effect, the authorization server associates 2548 the access token with certain resource servers and every resource 2549 server is obliged to verify, for every request, whether the access 2550 token sent with that request was meant to be used for that particular 2551 resource server. If not, the resource server MUST refuse to serve 2552 the respective request. Clients and authorization servers MAY 2553 utilize the parameters "scope" or "resource" as specified in 2554 [RFC8707], respectively, to determine the resource server they want 2555 to access. 2557 9.4.2. Access Token Replay Prevention 2559 Additionally, access tokens SHOULD be restricted to certain resources 2560 and actions on resource servers or resources. To put this into 2561 effect, the authorization server associates the access token with the 2562 respective resource and actions and every resource server is obliged 2563 to verify, for every request, whether the access token sent with that 2564 request was meant to be used for that particular action on the 2565 particular resource. If not, the resource server must refuse to 2566 serve the respective request. Clients and authorization servers MAY 2567 utilize the parameter "scope" and "authorization_details" as 2568 specified in [I-D.ietf-oauth-rar] to determine those resources and/or 2569 actions. 2571 Authorization and resource servers SHOULD use mechanisms for sender- 2572 constrained access tokens to prevent token replay as described in 2573 (#pop_tokens). A sender-constrained access token scopes the 2574 applicability of an access token to a certain sender. This sender is 2575 obliged to demonstrate knowledge of a certain secret as prerequisite 2576 for the acceptance of that token at the recipient (e.g., a resource 2577 server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is 2578 RECOMMENDED. 2580 9.5. Refresh Tokens 2582 Authorization servers MAY issue refresh tokens to clients. 2584 Refresh tokens MUST be kept confidential in transit and storage, and 2585 shared only among the authorization server and the client to whom the 2586 refresh tokens were issued. The authorization server MUST maintain 2587 the binding between a refresh token and the client to whom it was 2588 issued. Refresh tokens MUST only be transmitted using TLS as 2589 described in Section 1.6 with server authentication as defined by 2590 [RFC2818]. 2592 The authorization server MUST verify the binding between the refresh 2593 token and client identity whenever the client identity can be 2594 authenticated. When client authentication is not possible, the 2595 authorization server MUST issue sender-constrained refresh tokens or 2596 use refresh token rotation as described in 2597 (#refresh_token_protection). 2599 The authorization server MUST ensure that refresh tokens cannot be 2600 generated, modified, or guessed to produce valid refresh tokens by 2601 unauthorized parties. 2603 9.6. Protecting Redirect-Based Flows 2605 When comparing client redirect URIs against pre-registered URIs, 2606 authorization servers MUST utilize exact string matching. This 2607 measure contributes to the prevention of leakage of authorization 2608 codes and access tokens (see (#insufficient_uri_validation)). It can 2609 also help to detect mix-up attacks (see (#mix_up)). 2611 Clients MUST NOT expose URLs that forward the user's browser to 2612 arbitrary URIs obtained from a query parameter ("open redirector"). 2614 Open redirectors can enable exfiltration of authorization codes and 2615 access tokens, see (#open_redirector_on_client). 2617 Clients MUST prevent Cross-Site Request Forgery (CSRF). In this 2618 context, CSRF refers to requests to the redirection endpoint that do 2619 not originate at the authorization server, but a malicious third 2620 party (see Section 4.4.1.8. of [RFC6819] for details). Clients that 2621 have ensured that the authorization server supports PKCE MAY rely the 2622 CSRF protection provided by PKCE. In OpenID Connect flows, the 2623 "nonce" parameter provides CSRF protection. Otherwise, one-time use 2624 CSRF tokens carried in the "state" parameter that are securely bound 2625 to the user agent MUST be used for CSRF protection (see 2626 (#csrf_countermeasures)). 2628 In order to prevent mix-up attacks (see (#mix_up)), clients MUST only 2629 process redirect responses of the authorization server they sent the 2630 respective request to and from the same user agent this authorization 2631 request was initiated with. Clients MUST store the authorization 2632 server they sent an authorization request to and bind this 2633 information to the user agent and check that the authorization 2634 request was received from the correct authorization server. Clients 2635 MUST ensure that the subsequent token request, if applicable, is sent 2636 to the same authorization server. Clients SHOULD use distinct 2637 redirect URIs for each authorization server as a means to identify 2638 the authorization server a particular response came from. 2640 An AS that redirects a request potentially containing user 2641 credentials MUST avoid forwarding these user credentials accidentally 2642 (see (#redirect_307) for details). 2644 9.6.1. Loopback Redirect Considerations in Native Apps 2646 Loopback interface redirect URIs use the "http" scheme (i.e., without 2647 Transport Layer Security (TLS)). This is acceptable for loopback 2648 interface redirect URIs as the HTTP request never leaves the device. 2650 Clients should open the network port only when starting the 2651 authorization request and close it once the response is returned. 2653 Clients should listen on the loopback network interface only, in 2654 order to avoid interference by other network actors. 2656 While redirect URIs using localhost (i.e., 2657 "http://localhost:{port}/{path}") function similarly to loopback IP 2658 redirects described in Section 10.3.3, the use of "localhost" is NOT 2659 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 2660 rather than "localhost" avoids inadvertently listening on network 2661 interfaces other than the loopback interface. It is also less 2662 susceptible to client-side firewalls and misconfigured host name 2663 resolution on the user's device. 2665 9.7. Authorization Codes 2667 The transmission of authorization codes MUST be made over a secure 2668 channel, and the client MUST require the use of TLS with its 2669 redirection URI if the URI identifies a network resource. Since 2670 authorization codes are transmitted via user-agent redirections, they 2671 could potentially be disclosed through user-agent history and HTTP 2672 referrer headers. 2674 Authorization codes MUST be short lived and single-use. If the 2675 authorization server observes multiple attempts to exchange an 2676 authorization code for an access token, the authorization server 2677 SHOULD attempt to revoke all refresh and access tokens already 2678 granted based on the compromised authorization code. 2680 If the client can be authenticated, the authorization servers MUST 2681 authenticate the client and ensure that the authorization code was 2682 issued to the same client. 2684 Clients MUST prevent injection (replay) of authorization codes into 2685 the authorization response by attackers. The use of PKCE is 2686 RECOMMENDED to this end. The OpenID Connect "nonce" parameter and ID 2687 Token Claim [OpenID] MAY be used as well. The PKCE challenge or 2688 OpenID Connect "nonce" MUST be transaction-specific and securely 2689 bound to the client and the user agent in which the transaction was 2690 started. 2692 Note: although PKCE so far was designed as a mechanism to protect 2693 native apps, this advice applies to all kinds of OAuth clients, 2694 including web applications. 2696 When using PKCE, clients SHOULD use PKCE code challenge methods that 2697 do not expose the PKCE verifier in the authorization request. 2698 Otherwise, attackers that can read the authorization request (cf. 2699 Attacker A4 in (#secmodel)) can break the security provided by PKCE. 2700 Currently, "S256" is the only such method. 2702 Authorization servers MUST support PKCE. 2704 Authorization servers MUST provide a way to detect their support for 2705 PKCE. To this end, they MUST either (a) publish the element 2706 "code_challenge_methods_supported" in their AS metadata ([RFC8418]) 2707 containing the supported PKCE challenge methods (which can be used by 2708 the client to detect PKCE support) or (b) provide a deployment- 2709 specific way to ensure or determine PKCE support by the AS. 2711 9.8. Request Confidentiality 2713 Access tokens, refresh tokens, authorization codes, and client 2714 credentials MUST NOT be transmitted in the clear. 2716 The "state" and "scope" parameters SHOULD NOT include sensitive 2717 client or resource owner information in plain text, as they can be 2718 transmitted over insecure channels or stored insecurely. 2720 9.9. Ensuring Endpoint Authenticity 2722 In order to prevent man-in-the-middle attacks, the authorization 2723 server MUST require the use of TLS with server authentication as 2724 defined by [RFC2818] for any request sent to the authorization and 2725 token endpoints. The client MUST validate the authorization server's 2726 TLS certificate as defined by [RFC6125] and in accordance with its 2727 requirements for server identity authentication. 2729 9.10. Credentials-Guessing Attacks 2731 The authorization server MUST prevent attackers from guessing access 2732 tokens, authorization codes, refresh tokens, resource owner 2733 passwords, and client credentials. 2735 The probability of an attacker guessing generated tokens (and other 2736 credentials not intended for handling by end-users) MUST be less than 2737 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2739 The authorization server MUST utilize other means to protect 2740 credentials intended for end-user usage. 2742 9.11. Phishing Attacks 2744 Wide deployment of this and similar protocols may cause end-users to 2745 become inured to the practice of being redirected to websites where 2746 they are asked to enter their passwords. If end-users are not 2747 careful to verify the authenticity of these websites before entering 2748 their credentials, it will be possible for attackers to exploit this 2749 practice to steal resource owners' passwords. 2751 Service providers should attempt to educate end-users about the risks 2752 phishing attacks pose and should provide mechanisms that make it easy 2753 for end-users to confirm the authenticity of their sites. Client 2754 developers should consider the security implications of how they 2755 interact with the user-agent (e.g., external, embedded), and the 2756 ability of the end-user to verify the authenticity of the 2757 authorization server. 2759 To reduce the risk of phishing attacks, the authorization servers 2760 MUST require the use of TLS on every endpoint used for end-user 2761 interaction. 2763 9.12. Fake External User-Agents in Native Apps 2765 The native app that is initiating the authorization request has a 2766 large degree of control over the user interface and can potentially 2767 present a fake external user-agent, that is, an embedded user-agent 2768 made to appear as an external user-agent. 2770 When all good actors are using external user-agents, the advantage is 2771 that it is possible for security experts to detect bad actors, as 2772 anyone faking an external user-agent is provably bad. On the other 2773 hand, if good and bad actors alike are using embedded user-agents, 2774 bad actors don't need to fake anything, making them harder to detect. 2775 Once a malicious app is detected, it may be possible to use this 2776 knowledge to blacklist the app's signature in malware scanning 2777 software, take removal action (in the case of apps distributed by app 2778 stores) and other steps to reduce the impact and spread of the 2779 malicious app. 2781 Authorization servers can also directly protect against fake external 2782 user-agents by requiring an authentication factor only available to 2783 true external user-agents. 2785 Users who are particularly concerned about their security when using 2786 in-app browser tabs may also take the additional step of opening the 2787 request in the full browser from the in-app browser tab and complete 2788 the authorization there, as most implementations of the in-app 2789 browser tab pattern offer such functionality. 2791 9.13. Malicious External User-Agents in Native Apps 2793 If a malicious app is able to configure itself as the default handler 2794 for "https" scheme URIs in the operating system, it will be able to 2795 intercept authorization requests that use the default browser and 2796 abuse this position of trust for malicious ends such as phishing the 2797 user. 2799 This attack is not confined to OAuth; a malicious app configured in 2800 this way would present a general and ongoing risk to the user beyond 2801 OAuth usage by native apps. Many operating systems mitigate this 2802 issue by requiring an explicit user action to change the default 2803 handler for "http" and "https" scheme URIs. 2805 9.14. Cross-Site Request Forgery 2807 An attacker might attempt to inject a request to the redirect URI of 2808 the legitimate client on the victim's device, e.g., to cause the 2809 client to access resources under the attacker's control. This is a 2810 variant of an attack known as Cross-Site Request Forgery (CSRF). 2812 The traditional countermeasure are CSRF tokens that are bound to the 2813 user agent and passed in the "state" parameter to the authorization 2814 server as described in [RFC6819]. The same protection is provided by 2815 PKCE or the OpenID Connect "nonce" value. 2817 When using PKCE instead of "state" or "nonce" for CSRF protection, it 2818 is important to note that: 2820 * Clients MUST ensure that the AS supports PKCE before using PKCE 2821 for CSRF protection. If an authorization server does not support 2822 PKCE, "state" or "nonce" MUST be used for CSRF protection. 2824 * If "state" is used for carrying application state, and integrity 2825 of its contents is a concern, clients MUST protect "state" against 2826 tampering and swapping. This can be achieved by binding the 2827 contents of state to the browser session and/or signed/encrypted 2828 state values [I-D.bradley-oauth-jwt-encoded-state]. 2830 AS therefore MUST provide a way to detect their support for PKCE 2831 either via AS metadata according to [RFC8414] or provide a 2832 deployment-specific way to ensure or determine PKCE support. 2834 9.15. Clickjacking 2836 As described in Section 4.4.1.9 of [RFC6819], the authorization 2837 request is susceptible to clickjacking. An attacker can use this 2838 vector to obtain the user's authentication credentials, change the 2839 scope of access granted to the client, and potentially access the 2840 user's resources. 2842 Authorization servers MUST prevent clickjacking attacks. Multiple 2843 countermeasures are described in [RFC6819], including the use of the 2844 X-Frame-Options HTTP response header field and frame-busting 2845 JavaScript. In addition to those, authorization servers SHOULD also 2846 use Content Security Policy (CSP) level 2 [CSP-2] or greater. 2848 To be effective, CSP must be used on the authorization endpoint and, 2849 if applicable, other endpoints used to authenticate the user and 2850 authorize the client (e.g., the device authorization endpoint, login 2851 pages, error pages, etc.). This prevents framing by unauthorized 2852 origins in user agents that support CSP. The client MAY permit being 2853 framed by some other origin than the one used in its redirection 2854 endpoint. For this reason, authorization servers SHOULD allow 2855 administrators to configure allowed origins for particular clients 2856 and/or for clients to register these dynamically. 2858 Using CSP allows authorization servers to specify multiple origins in 2859 a single response header field and to constrain these using flexible 2860 patterns (see [CSP-2] for details). Level 2 of this standard 2861 provides a robust mechanism for protecting against clickjacking by 2862 using policies that restrict the origin of frames (using "frame- 2863 ancestors") together with those that restrict the sources of scripts 2864 allowed to execute on an HTML page (by using "script-src"). A non- 2865 normative example of such a policy is shown in the following listing: 2867 "HTTP/1.1 200 OK Content-Security-Policy: frame-ancestors 2868 https://ext.example.org:8000 Content-Security-Policy: script-src 2869 'self' X-Frame-Options: ALLOW-FROM https://ext.example.org:8000 ..." 2871 Because some user agents do not support [CSP-2], this technique 2872 SHOULD be combined with others, including those described in 2873 [RFC6819], unless such legacy user agents are explicitly unsupported 2874 by the authorization server. Even in such cases, additional 2875 countermeasures SHOULD still be employed. 2877 9.16. Code Injection and Input Validation 2879 A code injection attack occurs when an input or otherwise external 2880 variable is used by an application unsanitized and causes 2881 modification to the application logic. This may allow an attacker to 2882 gain access to the application device or its data, cause denial of 2883 service, or introduce a wide range of malicious side-effects. 2885 The authorization server and client MUST sanitize (and validate when 2886 possible) any value received - in particular, the value of the 2887 "state" and "redirect_uri" parameters. 2889 9.17. Open Redirectors 2891 The following attacks can occur when an AS or client has an open 2892 redirector. An open redirector is an endpoint that forwards a user's 2893 browser to an arbitrary URI obtained from a query parameter. 2895 9.17.1. Client as Open Redirector 2897 Clients MUST NOT expose open redirectors. Attackers may use open 2898 redirectors to produce URLs pointing to the client and utilize them 2899 to exfiltrate authorization codes and access tokens, as described in 2900 (#redir_uri_open_redir). Another abuse case is to produce URLs that 2901 appear to point to the client. This might trick users into trusting 2902 the URL and follow it in their browser. This can be abused for 2903 phishing. 2905 In order to prevent open redirection, clients should only redirect if 2906 the target URLs are whitelisted or if the origin and integrity of a 2907 request can be authenticated. Countermeasures against open 2908 redirection are described by OWASP [owasp_redir]. 2910 9.17.2. Authorization Server as Open Redirector 2912 Just as with clients, attackers could try to utilize a user's trust 2913 in the authorization server (and its URL in particular) for 2914 performing phishing attacks. OAuth authorization servers regularly 2915 redirect users to other web sites (the clients), but must do so in a 2916 safe way. 2918 Section 4.1.2.1 already prevents open redirects by stating that the 2919 AS MUST NOT automatically redirect the user agent in case of an 2920 invalid combination of "client_id" and "redirect_uri". 2922 However, an attacker could also utilize a correctly registered 2923 redirect URI to perform phishing attacks. The attacker could, for 2924 example, register a client via dynamic client registration [RFC7591] 2925 and intentionally send an erroneous authorization request, e.g., by 2926 using an invalid scope value, thus instructing the AS to redirect the 2927 user agent to its phishing site. 2929 The AS MUST take precautions to prevent this threat. Based on its 2930 risk assessment, the AS needs to decide whether it can trust the 2931 redirect URI and SHOULD only automatically redirect the user agent if 2932 it trusts the redirect URI. If the URI is not trusted, the AS MAY 2933 inform the user and rely on the user to make the correct decision. 2935 9.18. Authorization Server Mix-Up Mitigation in Native Apps 2937 (TODO: merge this with the regular mix-up section when it is brought 2938 in) 2940 To protect against a compromised or malicious authorization server 2941 attacking another authorization server used by the same app, it is 2942 REQUIRED that a unique redirect URI is used for each authorization 2943 server used by the app (for example, by varying the path component), 2944 and that authorization responses are rejected if the redirect URI 2945 they were received on doesn't match the redirect URI in an outgoing 2946 authorization request. 2948 The native app MUST store the redirect URI used in the authorization 2949 request with the authorization session data (i.e., along with "state" 2950 and other related data) and MUST verify that the URI on which the 2951 authorization response was received exactly matches it. 2953 The requirement of Section 9.2, specifically that authorization 2954 servers reject requests with URIs that don't match what was 2955 registered, is also required to prevent such attacks. 2957 9.19. Embedded User Agents in Native Apps 2959 Embedded user-agents are a technically possible method for 2960 authorizing native apps. These embedded user-agents are unsafe for 2961 use by third parties to the authorization server by definition, as 2962 the app that hosts the embedded user-agent can access the user's full 2963 authentication credential, not just the OAuth authorization grant 2964 that was intended for the app. 2966 In typical web-view-based implementations of embedded user-agents, 2967 the host application can record every keystroke entered in the login 2968 form to capture usernames and passwords, automatically submit forms 2969 to bypass user consent, and copy session cookies and use them to 2970 perform authenticated actions as the user. 2972 Even when used by trusted apps belonging to the same party as the 2973 authorization server, embedded user-agents violate the principle of 2974 least privilege by having access to more powerful credentials than 2975 they need, potentially increasing the attack surface. 2977 Encouraging users to enter credentials in an embedded user-agent 2978 without the usual address bar and visible certificate validation 2979 features that browsers have makes it impossible for the user to know 2980 if they are signing in to the legitimate site; even when they are, it 2981 trains them that it's OK to enter credentials without validating the 2982 site first. 2984 Aside from the security concerns, embedded user-agents do not share 2985 the authentication state with other apps or the browser, requiring 2986 the user to log in for every authorization request, which is often 2987 considered an inferior user experience. 2989 9.20. Other Recommendations 2991 Authorization servers SHOULD NOT allow clients to influence their 2992 "client_id" or "sub" value or any other claim if that can cause 2993 confusion with a genuine resource owner (see 2994 (#client_impersonating)). 2996 10. Native Applications 2998 Native applications are clients installed and executed on the device 2999 used by the resource owner (i.e., desktop application, native mobile 3000 application). Native applications require special consideration 3001 related to security, platform capabilities, and overall end-user 3002 experience. 3004 The authorization endpoint requires interaction between the client 3005 and the resource owner's user-agent. The best current practice is to 3006 perform the OAuth authorization request in an external user-agent 3007 (typically the browser) rather than an embedded user-agent (such as 3008 one implemented with web-views). 3010 The native application can capture the response from the 3011 authorization server using a redirection URI with a scheme registered 3012 with the operating system to invoke the client as the handler, manual 3013 copy-and-paste of the credentials, running a local web server, 3014 installing a user-agent extension, or by providing a redirection URI 3015 identifying a server-hosted resource under the client's control, 3016 which in turn makes the response available to the native application. 3018 Previously, it was common for native apps to use embedded user-agents 3019 (commonly implemented with web-views) for OAuth authorization 3020 requests. That approach has many drawbacks, including the host app 3021 being able to copy user credentials and cookies as well as the user 3022 needing to authenticate from scratch in each app. See Section 9.19 3023 for a deeper analysis of the drawbacks of using embedded user-agents 3024 for OAuth. 3026 Native app authorization requests that use the browser are more 3027 secure and can take advantage of the user's authentication state. 3028 Being able to use the existing authentication session in the browser 3029 enables single sign-on, as users don't need to authenticate to the 3030 authorization server each time they use a new app (unless required by 3031 the authorization server policy). 3033 Supporting authorization flows between a native app and the browser 3034 is possible without changing the OAuth protocol itself, as the OAuth 3035 authorization request and response are already defined in terms of 3036 URIs. This encompasses URIs that can be used for inter-app 3037 communication. Some OAuth server implementations that assume all 3038 clients are confidential web clients will need to add an 3039 understanding of public native app clients and the types of redirect 3040 URIs they use to support this best practice. 3042 10.1. Using Inter-App URI Communication for OAuth in Native Apps 3044 Just as URIs are used for OAuth on the web to initiate the 3045 authorization request and return the authorization response to the 3046 requesting website, URIs can be used by native apps to initiate the 3047 authorization request in the device's browser and return the response 3048 to the requesting native app. 3050 By adopting the same methods used on the web for OAuth, benefits seen 3051 in the web context like the usability of a single sign-on session and 3052 the security of a separate authentication context are likewise gained 3053 in the native app context. Reusing the same approach also reduces 3054 the implementation complexity and increases interoperability by 3055 relying on standards-based web flows that are not specific to a 3056 particular platform. 3058 Native apps MUST use an external user-agent to perform OAuth 3059 authorization requests. This is achieved by opening the 3060 authorization request in the browser (detailed in Section 10.2) and 3061 using a redirect URI that will return the authorization response back 3062 to the native app (defined in Section 10.3). 3064 10.2. Initiating the Authorization Request from a Native App 3066 Native apps needing user authorization create an authorization 3067 request URI with the authorization code grant type per Section 4.1 3068 using a redirect URI capable of being received by the native app. 3070 The function of the redirect URI for a native app authorization 3071 request is similar to that of a web-based authorization request. 3072 Rather than returning the authorization response to the OAuth 3073 client's server, the redirect URI used by a native app returns the 3074 response to the app. Several options for a redirect URI that will 3075 return the authorization response to the native app in different 3076 platforms are documented in Section 10.3. Any redirect URI that 3077 allows the app to receive the URI and inspect its parameters is 3078 viable. 3080 After constructing the authorization request URI, the app uses 3081 platform-specific APIs to open the URI in an external user-agent. 3082 Typically, the external user-agent used is the default browser, that 3083 is, the application configured for handling "http" and "https" scheme 3084 URIs on the system; however, different browser selection criteria and 3085 other categories of external user-agents MAY be used. 3087 This best practice focuses on the browser as the RECOMMENDED external 3088 user-agent for native apps. An external user-agent designed 3089 specifically for user authorization and capable of processing 3090 authorization requests and responses like a browser MAY also be used. 3091 Other external user-agents, such as a native app provided by the 3092 authorization server may meet the criteria set out in this best 3093 practice, including using the same redirection URI properties, but 3094 their use is out of scope for this specification. 3096 Some platforms support a browser feature known as "in-app browser 3097 tabs", where an app can present a tab of the browser within the app 3098 context without switching apps, but still retain key benefits of the 3099 browser such as a shared authentication state and security context. 3100 On platforms where they are supported, it is RECOMMENDED, for 3101 usability reasons, that apps use in-app browser tabs for the 3102 authorization request. 3104 10.3. Receiving the Authorization Response in a Native App 3106 There are several redirect URI options available to native apps for 3107 receiving the authorization response from the browser, the 3108 availability and user experience of which varies by platform. 3110 To fully support native apps, authorization servers MUST offer at 3111 least the three redirect URI options described in the following 3112 subsections to native apps. Native apps MAY use whichever redirect 3113 option suits their needs best, taking into account platform-specific 3114 implementation details. 3116 10.3.1. Private-Use URI Scheme Redirection 3118 Many mobile and desktop computing platforms support inter-app 3119 communication via URIs by allowing apps to register private-use URI 3120 schemes (sometimes colloquially referred to as "custom URL schemes") 3121 like "com.example.app". When the browser or another app attempts to 3122 load a URI with a private-use URI scheme, the app that registered it 3123 is launched to handle the request. 3125 To perform an authorization request with a private-use URI scheme 3126 redirect, the native app launches the browser with a standard 3127 authorization request, but one where the redirection URI utilizes a 3128 private-use URI scheme it registered with the operating system. 3130 When choosing a URI scheme to associate with the app, apps MUST use a 3131 URI scheme based on a domain name under their control, expressed in 3132 reverse order, as recommended by Section 3.8 of [RFC7595] for 3133 private-use URI schemes. 3135 For example, an app that controls the domain name "app.example.com" 3136 can use "com.example.app" as their scheme. Some authorization 3137 servers assign client identifiers based on domain names, for example, 3138 "client1234.usercontent.example.net", which can also be used as the 3139 domain name for the scheme when reversed in the same manner. A 3140 scheme such as "myapp", however, would not meet this requirement, as 3141 it is not based on a domain name. 3143 When there are multiple apps by the same publisher, care must be 3144 taken so that each scheme is unique within that group. On platforms 3145 that use app identifiers based on reverse-order domain names, those 3146 identifiers can be reused as the private-use URI scheme for the OAuth 3147 redirect to help avoid this problem. 3149 Following the requirements of Section 3.2 of [RFC3986], as there is 3150 no naming authority for private-use URI scheme redirects, only a 3151 single slash ("/") appears after the scheme component. A complete 3152 example of a redirect URI utilizing a private-use URI scheme is: 3154 com.example.app:/oauth2redirect/example-provider 3156 When the authorization server completes the request, it redirects to 3157 the client's redirection URI as it would normally. As the 3158 redirection URI uses a private-use URI scheme, it results in the 3159 operating system launching the native app, passing in the URI as a 3160 launch parameter. Then, the native app uses normal processing for 3161 the authorization response. 3163 10.3.2. Claimed "https" Scheme URI Redirection 3165 Some operating systems allow apps to claim "https" scheme [RFC7230] 3166 URIs in the domains they control. When the browser encounters a 3167 claimed URI, instead of the page being loaded in the browser, the 3168 native app is launched with the URI supplied as a launch parameter. 3170 Such URIs can be used as redirect URIs by native apps. They are 3171 indistinguishable to the authorization server from a regular web- 3172 based client redirect URI. An example is: 3174 https://app.example.com/oauth2redirect/example-provider 3176 As the redirect URI alone is not enough to distinguish public native 3177 app clients from confidential web clients, it is REQUIRED in 3178 Section 9.2 that the client type be recorded during client 3179 registration to enable the server to determine the client type and 3180 act accordingly. 3182 App-claimed "https" scheme redirect URIs have some advantages 3183 compared to other native app redirect options in that the identity of 3184 the destination app is guaranteed to the authorization server by the 3185 operating system. For this reason, native apps SHOULD use them over 3186 the other options where possible. 3188 10.3.3. Loopback Interface Redirection 3190 Native apps that are able to open a port on the loopback network 3191 interface without needing special permissions (typically, those on 3192 desktop operating systems) can use the loopback interface to receive 3193 the OAuth redirect. 3195 Loopback redirect URIs use the "http" scheme and are constructed with 3196 the loopback IP literal and whatever port the client is listening on. 3198 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 3199 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 3200 IPv4 loopback interface with a randomly assigned port: 3202 http://127.0.0.1:51004/oauth2redirect/example-provider 3204 An example redirect using the IPv6 loopback interface with a randomly 3205 assigned port: 3207 http://[::1]:61023/oauth2redirect/example-provider 3209 The authorization server MUST allow any port to be specified at the 3210 time of the request for loopback IP redirect URIs, to accommodate 3211 clients that obtain an available ephemeral port from the operating 3212 system at the time of the request. 3214 Clients SHOULD NOT assume that the device supports a particular 3215 version of the Internet Protocol. It is RECOMMENDED that clients 3216 attempt to bind to the loopback interface using both IPv4 and IPv6 3217 and use whichever is available. 3219 11. Browser-Based Apps 3221 Browser-based apps are are clients that run in a web browser, 3222 typically written in JavaScript, also known as "single-page apps". 3223 These types of apps have particular security considerations similar 3224 to native apps. 3226 TODO: Bring in the normative text of the browser-based apps BCP when 3227 it is finalized. 3229 12. IANA Considerations 3231 12.1. OAuth Access Token Types Registry 3233 This specification establishes the OAuth Access Token Types registry. 3235 Access token types are registered with a Specification Required 3236 ([RFC5226]) after a two-week review period on the oauth-ext- 3237 review@ietf.org mailing list, on the advice of one or more Designated 3238 Experts. However, to allow for the allocation of values prior to 3239 publication, the Designated Expert(s) may approve registration once 3240 they are satisfied that such a specification will be published. 3242 Registration requests must be sent to the oauth-ext-review@ietf.org 3243 mailing list for review and comment, with an appropriate subject 3244 (e.g., "Request for access token type: example"). 3246 Within the review period, the Designated Expert(s) will either 3247 approve or deny the registration request, communicating this decision 3248 to the review list and IANA. Denials should include an explanation 3249 and, if applicable, suggestions as to how to make the request 3250 successful. 3252 IANA must only accept registry updates from the Designated Expert(s) 3253 and should direct all requests for registration to the review mailing 3254 list. 3256 12.1.1. Registration Template 3258 Type name: The name requested (e.g., "example"). 3260 Additional Token Endpoint Response Parameters: Additional response 3261 parameters returned together with the "access_token" parameter. 3262 New parameters MUST be separately registered in the OAuth 3263 Parameters registry as described by Section 12.2. 3265 HTTP Authentication Scheme(s): The HTTP authentication scheme 3266 name(s), if any, used to authenticate protected resource requests 3267 using access tokens of this type. 3269 Change controller: For Standards Track RFCs, state "IETF". For 3270 others, give the name of the responsible party. Other details 3271 (e.g., postal address, email address, home page URI) may also be 3272 included. 3274 Specification document(s): Reference to the document(s) that specify 3275 the parameter, preferably including a URI that can be used to 3276 retrieve a copy of the document(s). An indication of the relevant 3277 sections may also be included but is not required. 3279 12.1.2. Initial Registry Contents 3281 The OAuth Access Token Types registry's initial contents are: 3283 * Type name: Bearer 3285 * Additional Token Endpoint Response Parameters: (none) 3287 * HTTP Authentication Scheme(s): Bearer 3289 * Change controller: IETF 3291 * Specification document(s): OAuth 2.1 3293 12.2. OAuth Parameters Registry 3295 This specification establishes the OAuth Parameters registry. 3297 Additional parameters for inclusion in the authorization endpoint 3298 request, the authorization endpoint response, the token endpoint 3299 request, or the token endpoint response are registered with a 3300 Specification Required ([RFC5226]) after a two-week review period on 3301 the oauth-ext-review@ietf.org mailing list, on the advice of one or 3302 more Designated Experts. However, to allow for the allocation of 3303 values prior to publication, the Designated Expert(s) may approve 3304 registration once they are satisfied that such a specification will 3305 be published. 3307 Registration requests must be sent to the oauth-ext-review@ietf.org 3308 mailing list for review and comment, with an appropriate subject 3309 (e.g., "Request for parameter: example"). 3311 Within the review period, the Designated Expert(s) will either 3312 approve or deny the registration request, communicating this decision 3313 to the review list and IANA. Denials should include an explanation 3314 and, if applicable, suggestions as to how to make the request 3315 successful. 3317 IANA must only accept registry updates from the Designated Expert(s) 3318 and should direct all requests for registration to the review mailing 3319 list. 3321 12.2.1. Registration Template 3323 Parameter name: The name requested (e.g., "example"). 3325 Parameter usage location: The location(s) where parameter can be 3326 used. The possible locations are authorization request, 3327 authorization response, token request, or token response. 3329 Change controller: For Standards Track RFCs, state "IETF". For 3330 others, give the name of the responsible party. Other details 3331 (e.g., postal address, email address, home page URI) may also be 3332 included. 3334 Specification document(s): Reference to the document(s) that specify 3335 the parameter, preferably including a URI that can be used to 3336 retrieve a copy of the document(s). An indication of the relevant 3337 sections may also be included but is not required. 3339 12.2.2. Initial Registry Contents 3341 The OAuth Parameters registry's initial contents are: 3343 * Parameter name: client_id 3345 * Parameter usage location: authorization request, token request 3347 * Change controller: IETF 3349 * Specification document(s): RFC 6749 3351 * Parameter name: client_secret 3353 * Parameter usage location: token request 3355 * Change controller: IETF 3357 * Specification document(s): RFC 6749 3359 * Parameter name: response_type 3361 * Parameter usage location: authorization request 3363 * Change controller: IETF 3365 * Specification document(s): RFC 6749 3367 * Parameter name: redirect_uri 3368 * Parameter usage location: authorization request, token request 3370 * Change controller: IETF 3372 * Specification document(s): RFC 6749 3374 * Parameter name: scope 3376 * Parameter usage location: authorization request, authorization 3377 response, token request, token response 3379 * Change controller: IETF 3381 * Specification document(s): RFC 6749 3383 * Parameter name: state 3385 * Parameter usage location: authorization request, authorization 3386 response 3388 * Change controller: IETF 3390 * Specification document(s): RFC 6749 3392 * Parameter name: code 3394 * Parameter usage location: authorization response, token request 3396 * Change controller: IETF 3398 * Specification document(s): RFC 6749 3400 * Parameter name: error_description 3402 * Parameter usage location: authorization response, token response 3404 * Change controller: IETF 3406 * Specification document(s): RFC 6749 3408 * Parameter name: error_uri 3410 * Parameter usage location: authorization response, token response 3412 * Change controller: IETF 3414 * Specification document(s): RFC 6749 3415 * Parameter name: grant_type 3417 * Parameter usage location: token request 3419 * Change controller: IETF 3421 * Specification document(s): RFC 6749 3423 * Parameter name: access_token 3425 * Parameter usage location: authorization response, token response 3427 * Change controller: IETF 3429 * Specification document(s): RFC 6749 3431 * Parameter name: token_type 3433 * Parameter usage location: authorization response, token response 3435 * Change controller: IETF 3437 * Specification document(s): RFC 6749 3439 * Parameter name: expires_in 3441 * Parameter usage location: authorization response, token response 3443 * Change controller: IETF 3445 * Specification document(s): RFC 6749 3447 * Parameter name: username 3449 * Parameter usage location: token request 3451 * Change controller: IETF 3453 * Specification document(s): RFC 6749 3455 * Parameter name: password 3457 * Parameter usage location: token request 3459 * Change controller: IETF 3461 * Specification document(s): RFC 6749 3462 * Parameter name: refresh_token 3464 * Parameter usage location: token request, token response 3466 * Change controller: IETF 3468 * Specification document(s): RFC 6749 3470 12.3. OAuth Authorization Endpoint Response Types Registry 3472 This specification establishes the OAuth Authorization Endpoint 3473 Response Types registry. 3475 Additional response types for use with the authorization endpoint are 3476 registered with a Specification Required ([RFC5226]) after a two-week 3477 review period on the oauth-ext-review@ietf.org mailing list, on the 3478 advice of one or more Designated Experts. However, to allow for the 3479 allocation of values prior to publication, the Designated Expert(s) 3480 may approve registration once they are satisfied that such a 3481 specification will be published. 3483 Registration requests must be sent to the oauth-ext-review@ietf.org 3484 mailing list for review and comment, with an appropriate subject 3485 (e.g., "Request for response type: example"). 3487 Within the review period, the Designated Expert(s) will either 3488 approve or deny the registration request, communicating this decision 3489 to the review list and IANA. Denials should include an explanation 3490 and, if applicable, suggestions as to how to make the request 3491 successful. 3493 IANA must only accept registry updates from the Designated Expert(s) 3494 and should direct all requests for registration to the review mailing 3495 list. 3497 12.3.1. Registration Template 3499 Response type name: The name requested (e.g., "example"). 3501 Change controller: For Standards Track RFCs, state "IETF". For 3502 others, give the name of the responsible party. Other details 3503 (e.g., postal address, email address, home page URI) may also be 3504 included. 3506 Specification document(s): Reference to the document(s) that specify 3507 the type, preferably including a URI that can be used to retrieve 3508 a copy of the document(s). An indication of the relevant sections 3509 may also be included but is not required. 3511 12.3.2. Initial Registry Contents 3513 The OAuth Authorization Endpoint Response Types registry's initial 3514 contents are: 3516 * Response type name: code 3518 * Change controller: IETF 3520 * Specification document(s): RFC 6749 3522 12.4. OAuth Extensions Error Registry 3524 This specification establishes the OAuth Extensions Error registry. 3526 Additional error codes used together with other protocol extensions 3527 (i.e., extension grant types, access token types, or extension 3528 parameters) are registered with a Specification Required ([RFC5226]) 3529 after a two-week review period on the oauth-ext-review@ietf.org 3530 mailing list, on the advice of one or more Designated Experts. 3531 However, to allow for the allocation of values prior to publication, 3532 the Designated Expert(s) may approve registration once they are 3533 satisfied that such a specification will be published. 3535 Registration requests must be sent to the oauth-ext-review@ietf.org 3536 mailing list for review and comment, with an appropriate subject 3537 (e.g., "Request for error code: example"). 3539 Within the review period, the Designated Expert(s) will either 3540 approve or deny the registration request, communicating this decision 3541 to the review list and IANA. Denials should include an explanation 3542 and, if applicable, suggestions as to how to make the request 3543 successful. 3545 IANA must only accept registry updates from the Designated Expert(s) 3546 and should direct all requests for registration to the review mailing 3547 list. 3549 12.4.1. Registration Template 3551 Error name: The name requested (e.g., "example"). Values for the 3552 error name MUST NOT include characters outside the set %x20-21 / 3553 %x23-5B / %x5D-7E. 3555 Error usage location: The location(s) where the error can be used. 3556 The possible locations are authorization code grant error response 3557 (Section 4.1.2.1), token error response (Section 5.2), or resource 3558 access error response (Section 7.3). 3560 Related protocol extension: The name of the extension grant type, 3561 access token type, or extension parameter that the error code is 3562 used in conjunction with. 3564 Change controller: For Standards Track RFCs, state "IETF". For 3565 others, give the name of the responsible party. Other details 3566 (e.g., postal address, email address, home page URI) may also be 3567 included. 3569 Specification document(s): Reference to the document(s) that specify 3570 the error code, preferably including a URI that can be used to 3571 retrieve a copy of the document(s). An indication of the relevant 3572 sections may also be included but is not required. 3574 12.4.2. Initial Registry Contents 3576 The OAuth Error registry's initial contents are: 3578 * Error name: invalid_request 3580 * Error usage location: Resource access error response 3582 * Change controller: IETF 3584 * Specification document(s): OAuth 2.1 3586 * Error name: invalid_token 3588 * Error usage location: Resource access error response 3590 * Change controller: IETF 3592 * Specification document(s): OAuth 2.1 3594 * Error name: insufficient_scope 3596 * Error usage location: Resource access error response 3598 * Change controller: IETF 3600 * Specification document(s): OAuth 2.1 3602 13. References 3604 13.1. Normative References 3606 [I-D.ietf-oauth-security-topics] 3607 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 3608 "OAuth 2.0 Security Best Current Practice", Work in 3609 Progress, Internet-Draft, draft-ietf-oauth-security- 3610 topics-14, 10 February 2020, . 3613 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3614 Requirement Levels", BCP 14, RFC 2119, 3615 DOI 10.17487/RFC2119, March 1997, 3616 . 3618 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3619 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3620 Transfer Protocol -- HTTP/1.1", RFC 2616, 3621 DOI 10.17487/RFC2616, June 1999, 3622 . 3624 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3625 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3626 Authentication: Basic and Digest Access Authentication", 3627 RFC 2617, DOI 10.17487/RFC2617, June 1999, 3628 . 3630 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3631 DOI 10.17487/RFC2818, May 2000, 3632 . 3634 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3635 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3636 2003, . 3638 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3639 Resource Identifier (URI): Generic Syntax", STD 66, 3640 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3641 . 3643 [RFC4627] Crockford, D., "The application/json Media Type for 3644 JavaScript Object Notation (JSON)", RFC 4627, 3645 DOI 10.17487/RFC4627, July 2006, 3646 . 3648 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3649 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3650 . 3652 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3653 IANA Considerations Section in RFCs", RFC 5226, 3654 DOI 10.17487/RFC5226, May 2008, 3655 . 3657 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3658 Specifications: ABNF", STD 68, RFC 5234, 3659 DOI 10.17487/RFC5234, January 2008, 3660 . 3662 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3663 Housley, R., and W. Polk, "Internet X.509 Public Key 3664 Infrastructure Certificate and Certificate Revocation List 3665 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3666 . 3668 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3669 Verification of Domain-Based Application Service Identity 3670 within Internet Public Key Infrastructure Using X.509 3671 (PKIX) Certificates in the Context of Transport Layer 3672 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3673 2011, . 3675 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3676 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3677 . 3679 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3680 Framework: Bearer Token Usage", RFC 6750, 3681 DOI 10.17487/RFC6750, October 2012, 3682 . 3684 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 3685 and Registration Procedures for URI Schemes", BCP 35, 3686 RFC 7595, DOI 10.17487/RFC7595, June 2015, 3687 . 3689 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 3690 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 3691 . 3693 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3694 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3695 . 3697 [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American 3698 Standard Code for Information Interchange, ANSI X3.4", 3699 1986. 3701 [W3C.REC-html401-19991224] 3702 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 3703 Specification", World Wide Web Consortium Recommendation 3704 REC-html401-19991224, 24 December 1999, 3705 . 3707 [W3C.REC-xml-20081126] 3708 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 3709 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3710 Edition)", World Wide Web Consortium Recommendation REC- 3711 xml-20081126, 26 November 2008, 3712 . 3714 13.2. Informative References 3716 [CSP-2] "Content Security Policy Level 2", December 2016, 3717 . 3719 [I-D.bradley-oauth-jwt-encoded-state] 3720 Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding 3721 claims in the OAuth 2 state parameter using a JWT", Work 3722 in Progress, Internet-Draft, draft-bradley-oauth-jwt- 3723 encoded-state-09, 4 November 2018, . 3727 [I-D.ietf-oauth-browser-based-apps] 3728 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 3729 Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- 3730 browser-based-apps-05, 28 February 2020, 3731 . 3734 [I-D.ietf-oauth-rar] 3735 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 3736 Rich Authorization Requests", Work in Progress, Internet- 3737 Draft, draft-ietf-oauth-rar-01, 19 February 2020, 3738 . 3741 [I-D.ietf-oauth-resource-indicators] 3742 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3743 Indicators for OAuth 2.0", Work in Progress, Internet- 3744 Draft, draft-ietf-oauth-resource-indicators-08, 11 3745 September 2019, . 3748 [I-D.ietf-oauth-token-binding] 3749 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 3750 "OAuth 2.0 Token Binding", Work in Progress, Internet- 3751 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 3752 . 3755 [NIST800-63] 3756 Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., 3757 Gupta, S., and E. Nabbus, "NIST Special Publication 3758 800-63-1, INFORMATION SECURITY", December 2011, 3759 . 3761 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 3762 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 3763 and B. Boyer, "Online Multimedia Authorization Protocol: 3764 An Industry Standard for Authorized Access to Internet 3765 Multimedia Resources", April 2012, 3766 . 3768 [OpenID] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 3769 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 3770 . 3772 [OpenID.Messages] 3773 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 3774 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 3775 June 2012, . 3778 [owasp_redir] 3779 "OWASP Cheat Sheet Series - Unvalidated Redirects and 3780 Forwards", 2020, 3781 . 3784 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3785 DOI 10.17487/RFC6265, April 2011, 3786 . 3788 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 3789 Threat Model and Security Considerations", RFC 6819, 3790 DOI 10.17487/RFC6819, January 2013, 3791 . 3793 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3794 Protocol (HTTP/1.1): Message Syntax and Routing", 3795 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3796 . 3798 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3799 Protocol (HTTP/1.1): Authentication", RFC 7235, 3800 DOI 10.17487/RFC7235, June 2014, 3801 . 3803 [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security 3804 Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 3805 Client Authentication and Authorization Grants", RFC 7522, 3806 DOI 10.17487/RFC7522, May 2015, 3807 . 3809 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 3810 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 3811 RFC 7591, DOI 10.17487/RFC7591, July 2015, 3812 . 3814 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 3815 for Code Exchange by OAuth Public Clients", RFC 7636, 3816 DOI 10.17487/RFC7636, September 2015, 3817 . 3819 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 3820 Authorization Server Metadata", RFC 8414, 3821 DOI 10.17487/RFC8414, June 2018, 3822 . 3824 [RFC8418] Housley, R., "Use of the Elliptic Curve Diffie-Hellman Key 3825 Agreement Algorithm with X25519 and X448 in the 3826 Cryptographic Message Syntax (CMS)", RFC 8418, 3827 DOI 10.17487/RFC8418, August 2018, 3828 . 3830 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 3831 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 3832 and Certificate-Bound Access Tokens", RFC 8705, 3833 DOI 10.17487/RFC8705, February 2020, 3834 . 3836 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 3837 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 3838 February 2020, . 3840 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3842 This section provides Augmented Backus-Naur Form (ABNF) syntax 3843 descriptions for the elements defined in this specification using the 3844 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3845 code points [W3C.REC-xml-20081126]; these characters are typically 3846 encoded in UTF-8. Elements are presented in the order first defined. 3848 Some of the definitions that follow use the "URI-reference" 3849 definition from [RFC3986]. 3851 Some of the definitions that follow use these common definitions: 3853 VSCHAR = %x20-7E 3854 NQCHAR = %x21 / %x23-5B / %x5D-7E 3855 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3856 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3857 %xE000-FFFD / %x10000-10FFFF 3859 (The UNICODECHARNOCRLF definition is based upon the Char definition 3860 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3861 Return and Linefeed characters.) 3863 A.1. "client_id" Syntax 3865 The "client_id" element is defined in Section 2.3.1: 3867 client-id = *VSCHAR 3869 A.2. "client_secret" Syntax 3871 The "client_secret" element is defined in Section 2.3.1: 3873 client-secret = *VSCHAR 3875 A.3. "response_type" Syntax 3877 The "response_type" element is defined in Section 3.1.1 and 3878 Section 8.4: 3880 response-type = response-name *( SP response-name ) 3881 response-name = 1*response-char 3882 response-char = "_" / DIGIT / ALPHA 3884 A.4. "scope" Syntax 3886 The "scope" element is defined in Section 3.3: 3888 scope = scope-token *( SP scope-token ) 3889 scope-token = 1*NQCHAR 3891 A.5. "state" Syntax 3893 The "state" element is defined in Section 4.1.1, Section 4.1.2, and 3894 Section 4.1.2.1: 3896 state = 1*VSCHAR 3898 A.6. "redirect_uri" Syntax 3900 The "redirect_uri" element is defined in Section 4.1.1, and 3901 Section 4.1.3: 3903 redirect-uri = URI-reference 3905 A.7. "error" Syntax 3907 The "error" element is defined in Sections Section 4.1.2.1, 3908 Section 5.2, 7.2, and 8.5: 3910 error = 1*NQSCHAR 3912 A.8. "error_description" Syntax 3914 The "error_description" element is defined in Sections 3915 Section 4.1.2.1, Section 5.2, and Section 7.3: 3917 error-description = 1*NQSCHAR 3919 A.9. "error_uri" Syntax 3921 The "error_uri" element is defined in Sections Section 4.1.2.1, 3922 Section 5.2, and 7.2: 3924 error-uri = URI-reference 3926 A.10. "grant_type" Syntax 3928 The "grant_type" element is defined in Sections Section 4.1.3, 3929 Section 4.2.3, Section 4.2.2, Section 4.3, and Section 6: 3931 grant-type = grant-name / URI-reference 3932 grant-name = 1*name-char 3933 name-char = "-" / "." / "_" / DIGIT / ALPHA 3935 A.11. "code" Syntax 3937 The "code" element is defined in Section 4.1.3: 3939 code = 1*VSCHAR 3941 A.12. "access_token" Syntax 3943 The "access_token" element is defined in Section 4.2.3 and 3944 Section 5.1: 3946 access-token = 1*VSCHAR 3948 A.13. "token_type" Syntax 3950 The "token_type" element is defined in Section 5.1, and Section 8.1: 3952 token-type = type-name / URI-reference 3953 type-name = 1*name-char 3954 name-char = "-" / "." / "_" / DIGIT / ALPHA 3956 A.14. "expires_in" Syntax 3958 The "expires_in" element is defined in Section 5.1: 3960 expires-in = 1*DIGIT 3962 A.15. "refresh_token" Syntax 3964 The "refresh_token" element is defined in Section 5.1 and Section 6: 3966 refresh-token = 1*VSCHAR 3968 A.16. Endpoint Parameter Syntax 3970 The syntax for new endpoint parameters is defined in Section 8.2: 3972 param-name = 1*name-char 3973 name-char = "-" / "." / "_" / DIGIT / ALPHA 3975 A.17. "code_verifier" Syntax 3977 ABNF for "code_verifier" is as follows. 3979 code-verifier = 43*128unreserved 3980 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3981 ALPHA = %x41-5A / %x61-7A 3982 DIGIT = %x30-39 3984 A.18. "code_challenge" Syntax 3986 ABNF for "code_challenge" is as follows. 3988 code-challenge = 43*128unreserved 3989 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 3990 ALPHA = %x41-5A / %x61-7A 3991 DIGIT = %x30-39 3993 Appendix B. Use of application/x-www-form-urlencoded Media Type 3995 At the time of publication of this specification, the "application/x- 3996 www-form-urlencoded" media type was defined in Section 17.13.4 of 3997 [W3C.REC-html401-19991224] but not registered in the IANA MIME Media 3998 Types registry (http://www.iana.org/assignments/media-types 3999 (http://www.iana.org/assignments/media-types)). Furthermore, that 4000 definition is incomplete, as it does not consider non-US-ASCII 4001 characters. 4003 To address this shortcoming when generating payloads using this media 4004 type, names and values MUST be encoded using the UTF-8 character 4005 encoding scheme [RFC3629] first; the resulting octet sequence then 4006 needs to be further encoded using the escaping rules defined in 4007 [W3C.REC-html401-19991224]. 4009 When parsing data from a payload using this media type, the names and 4010 values resulting from reversing the name/value encoding consequently 4011 need to be treated as octet sequences, to be decoded using the UTF-8 4012 character encoding scheme. 4014 For example, the value consisting of the six Unicode code points (1) 4015 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 4016 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 4017 SIGN) would be encoded into the octet sequence below (using 4018 hexadecimal notation): 4020 20 25 26 2B C2 A3 E2 82 AC 4022 and then represented in the payload as: 4024 +%25%26%2B%C2%A3%E2%82%AC 4026 Appendix C. Acknowledgements 4028 TBD 4030 Authors' Addresses 4032 Dick Hardt 4033 SignIn.Org 4034 United States 4035 Email: dick.hardt@gmail.com 4037 Aaron Parecki 4038 Okta 4039 United States 4041 Email: aaron@parecki.com 4042 URI: https://aaronparecki.com 4044 Torsten Lodderstedt 4045 yes.com 4047 Email: torsten@lodderstedt.net