--- 1/draft-ietf-oauth-v2-1-00.txt 2021-02-01 18:13:09.091324625 -0800 +++ 2/draft-ietf-oauth-v2-1-01.txt 2021-02-01 18:13:09.179325776 -0800 @@ -1,197 +1,198 @@ OAuth Working Group D. Hardt Internet-Draft SignIn.Org Intended status: Standards Track A. Parecki -Expires: 31 January 2021 Okta +Expires: 5 August 2021 Okta T. Lodderstedt yes.com - 30 July 2020 + 1 February 2021 The OAuth 2.1 Authorization Framework - draft-ietf-oauth-v2-1-00 + draft-ietf-oauth-v2-1-01 Abstract The OAuth 2.1 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction - between the resource owner and the HTTP service, or by allowing the - third-party application to obtain access on its own behalf. This - specification replaces and obsoletes the OAuth 2.0 Authorization - Framework described in RFC 6749. + between the resource owner and an authorization service, or by + allowing the third-party application to obtain access on its own + behalf. This specification replaces and obsoletes the OAuth 2.0 + Authorization Framework described in RFC 6749. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 31 January 2021. + This Internet-Draft will expire on 5 August 2021. Copyright Notice - Copyright (c) 2020 IETF Trust and the persons identified as the + Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 7 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . 8 - 1.3.2. Client Credentials . . . . . . . . . . . . . . . . . 8 + 1.3.2. Client Credentials . . . . . . . . . . . . . . . . . 9 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 - 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 - 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 11 - 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 11 - 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 11 - 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 12 - 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 12 - 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13 - 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 14 - 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 15 - 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 - 2.3.2. Other Authentication Methods . . . . . . . . . . . . 16 - 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 17 - 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 17 - 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 - 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18 - 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 18 - 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 - 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21 - 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 21 - 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22 - 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 22 - 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 24 - 4.1.2. Authorization Response . . . . . . . . . . . . . . . 27 - 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 30 - 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 31 - 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 31 - 4.2.1. Authorization Request and Response . . . . . . . . . 32 - 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 32 - 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 33 - 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 33 - 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 34 - 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 34 - 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 35 - 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 37 - 6.1. Refresh Token Protection . . . . . . . . . . . . . . . . 38 - 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 40 - 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 40 - 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 41 - 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 41 - 7.2.2. The WWW-Authenticate Response Header Field . . . . . 43 - 7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 44 - 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 45 - 7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 45 - 7.4. Access Token Security Considerations . . . . . . . . . . 45 - 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 46 - 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 46 - 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 48 - 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 49 - 7.4.5. Access Token Privilege Restriction . . . . . . . . . 50 - 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 50 - 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 50 - 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 51 - 8.3. Defining New Authorization Grant Types . . . . . . . . . 51 - 8.4. Defining New Authorization Endpoint Response Types . . . 51 - 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 52 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 52 - 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 53 - 9.1.1. Client Authentication of Native Apps . . . . . . . . 53 - 9.2. Registration of Native App Clients . . . . . . . . . . . 54 - 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 54 - 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 55 - 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 55 - 9.4.1. Access Token Privilege Restriction . . . . . . . . . 56 - 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 56 - 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 57 - 9.6. Client Impersonating Resource Owner . . . . . . . . . . . 57 - 9.7. Protecting Redirect-Based Flows . . . . . . . . . . . . . 58 - 9.7.1. Loopback Redirect Considerations in Native Apps . . . 58 - 9.7.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 59 - 9.8. Authorization Codes . . . . . . . . . . . . . . . . . . . 60 - 9.9. Request Confidentiality . . . . . . . . . . . . . . . . . 61 - 9.10. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 61 - 9.11. Credentials-Guessing Attacks . . . . . . . . . . . . . . 62 - 9.12. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 62 - 9.13. Fake External User-Agents in Native Apps . . . . . . . . 62 - 9.14. Malicious External User-Agents in Native Apps . . . . . . 63 - 9.15. Cross-Site Request Forgery . . . . . . . . . . . . . . . 63 - 9.16. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 64 - 9.17. Code Injection and Input Validation . . . . . . . . . . . 65 - 9.18. Open Redirectors . . . . . . . . . . . . . . . . . . . . 65 - 9.18.1. Client as Open Redirector . . . . . . . . . . . . . 65 - 9.18.2. Authorization Server as Open Redirector . . . . . . 65 + 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10 + 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 + 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 + 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12 + 1.9. Compatibility with OAuth 2.0 . . . . . . . . . . . . . . 13 + 1.10. Notational Conventions . . . . . . . . . . . . . . . . . 13 + 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 14 + 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14 + 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 16 + 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 16 + 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 17 + 2.3.2. Other Authentication Methods . . . . . . . . . . . . 18 + 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 18 + 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 18 + 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 19 + 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 19 + 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 20 + 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 22 + 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 22 + 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 23 + 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 23 + 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23 + 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 25 + 4.1.2. Authorization Response . . . . . . . . . . . . . . . 28 + 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 31 + 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 32 + 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 33 + 4.2.1. Authorization Request and Response . . . . . . . . . 33 + 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 33 + 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 34 + 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 34 + 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 35 + 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 35 + 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 36 - 9.19. Authorization Server Mix-Up Mitigation in Native Apps . . 66 - 9.20. Embedded User Agents in Native Apps . . . . . . . . . . . 66 - 9.21. Other Recommendations . . . . . . . . . . . . . . . . . . 67 - 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 67 + 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 38 + 6.1. Refresh Token Protection . . . . . . . . . . . . . . . . 39 + 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 + 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 + 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42 + 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 42 + 7.2.2. The WWW-Authenticate Response Header Field . . . . . 44 + 7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 45 + 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 46 + 7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 46 + 7.4. Access Token Security Considerations . . . . . . . . . . 46 + 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 47 + 7.4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . 47 + 7.4.3. Summary of Recommendations . . . . . . . . . . . . . 49 + 7.4.4. Token Replay Prevention . . . . . . . . . . . . . . . 50 + 7.4.5. Access Token Privilege Restriction . . . . . . . . . 51 + 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 51 + 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 51 + 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 52 + 8.3. Defining New Authorization Grant Types . . . . . . . . . 52 + 8.4. Defining New Authorization Endpoint Response Types . . . 52 + 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 53 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 53 + 9.1. Client Authentication . . . . . . . . . . . . . . . . . . 54 + 9.1.1. Client Authentication of Native Apps . . . . . . . . 54 + 9.2. Registration of Native App Clients . . . . . . . . . . . 55 + 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 55 + 9.3.1. Impersonation of Native Apps . . . . . . . . . . . . 56 + 9.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 56 + 9.4.1. Access Token Privilege Restriction . . . . . . . . . 57 + 9.4.2. Access Token Replay Prevention . . . . . . . . . . . 57 + 9.5. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 58 + 9.6. Client Impersonating Resource Owner . . . . . . . . . . . 58 + 9.7. Protecting Redirect-Based Flows . . . . . . . . . . . . . 59 + 9.7.1. Loopback Redirect Considerations in Native Apps . . . 59 + 9.7.2. HTTP 307 Redirect . . . . . . . . . . . . . . . . . . 60 + 9.8. Authorization Codes . . . . . . . . . . . . . . . . . . . 61 + 9.9. Request Confidentiality . . . . . . . . . . . . . . . . . 62 + 9.10. Ensuring Endpoint Authenticity . . . . . . . . . . . . . 62 + 9.11. Credentials-Guessing Attacks . . . . . . . . . . . . . . 63 + 9.12. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 63 + 9.13. Fake External User-Agents in Native Apps . . . . . . . . 63 + 9.14. Malicious External User-Agents in Native Apps . . . . . . 64 + 9.15. Cross-Site Request Forgery . . . . . . . . . . . . . . . 64 + 9.16. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 65 + 9.17. Code Injection and Input Validation . . . . . . . . . . . 66 + 9.18. Open Redirectors . . . . . . . . . . . . . . . . . . . . 66 + 9.18.1. Client as Open Redirector . . . . . . . . . . . . . 66 + 9.18.2. Authorization Server as Open Redirector . . . . . . 66 + 9.19. Authorization Server Mix-Up Mitigation in Native Apps . . 67 + 9.20. Embedded User Agents in Native Apps . . . . . . . . . . . 67 + 9.21. Other Recommendations . . . . . . . . . . . . . . . . . . 68 + 10. Native Applications . . . . . . . . . . . . . . . . . . . . . 68 10.1. Using Inter-App URI Communication for OAuth in Native - Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 68 + Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 69 10.2. Initiating the Authorization Request from a Native - App . . . . . . . . . . . . . . . . . . . . . . . . . . 69 - 10.3. Receiving the Authorization Response in a Native App . . 70 - 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 70 - 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 71 - 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 71 - 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 72 - 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 72 - 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 - 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 - 14.1. Normative References . . . . . . . . . . . . . . . . . . 73 - 14.2. Informative References . . . . . . . . . . . . . . . . . 76 - Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 79 - A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 79 - A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 79 - A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 80 - A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 80 - A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 80 - A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 80 - A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 80 - A.8. "error_description" Syntax . . . . . . . . . . . . . . . 80 - A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 81 - A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 81 - A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 81 - A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 81 - A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 81 - A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 81 - A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 81 - A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 82 - A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 82 - A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 82 + App . . . . . . . . . . . . . . . . . . . . . . . . . . 70 + 10.3. Receiving the Authorization Response in a Native App . . 71 + 10.3.1. Private-Use URI Scheme Redirection . . . . . . . . . 71 + 10.3.2. Claimed "https" Scheme URI Redirection . . . . . . . 72 + 10.3.3. Loopback Interface Redirection . . . . . . . . . . . 72 + 11. Browser-Based Apps . . . . . . . . . . . . . . . . . . . . . 73 + 12. Differences from OAuth 2.0 . . . . . . . . . . . . . . . . . 73 + 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 74 + 14.2. Informative References . . . . . . . . . . . . . . . . . 77 + Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 80 + A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 81 + A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 81 + A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 81 + A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 81 + A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 81 + A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 81 + A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 81 + A.8. "error_description" Syntax . . . . . . . . . . . . . . . 82 + A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 82 + A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 82 + A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 82 + A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 82 + A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 82 + A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 82 + A.15. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 83 + A.16. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 83 + A.17. "code_verifier" Syntax . . . . . . . . . . . . . . . . . 83 + A.18. "code_challenge" Syntax . . . . . . . . . . . . . . . . . 83 Appendix B. Use of application/x-www-form-urlencoded Media - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 82 - Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 83 - Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 84 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 83 + Appendix C. Extensions . . . . . . . . . . . . . . . . . . . . . 84 + Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 86 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 1. Introduction In the traditional client-server authentication model, the client requests an access-restricted resource (protected resource) on the server by authenticating with the server using the resource owner's credentials. In order to provide third-party applications access to restricted resources, the resource owner shares its credentials with the third party. This creates several problems and limitations: @@ -200,46 +201,48 @@ text. * Servers are required to support password authentication, despite the security weaknesses inherent in passwords. * Third-party applications gain overly broad access to the resource owner's protected resources, leaving resource owners without any ability to restrict duration or access to a limited subset of resources. + * Resource owners often reuse passwords with other unrelated + services, despite best security practices. This password reuse + means a vulnerability or exposure in one service may have security + implications in completely unrelated services. + * Resource owners cannot revoke access to an individual third party without revoking access to all third parties, and must do so by changing the third party's password. * Compromise of any third-party application results in compromise of the end-user's password and all of the data protected by that password. OAuth addresses these issues by introducing an authorization layer and separating the role of the client from that of the resource owner. In OAuth, the client requests access to resources controlled - by the resource owner and hosted by the resource server, and is - issued a different set of credentials than those of the resource - owner. - - Instead of using the resource owner's credentials to access protected - resources, the client obtains an access token - a string denoting a - specific scope, lifetime, and other access attributes. Access tokens - are issued to third-party clients by an authorization server with the + by the resource owner and hosted by the resource server. Instead of + using the resource owner's credentials to access protected resources, + the client obtains an access token - a credential representing a + specific set of access attributes such as scope and lifetime. Access + tokens are issued to clients by an authorization server with the approval of the resource owner. The client uses the access token to access the protected resources hosted by the resource server. For example, an end-user (resource owner) can grant a printing - service (client) access to her protected photos stored at a photo- - sharing service (resource server), without sharing her username and - password with the printing service. Instead, she authenticates + service (client) access to their protected photos stored at a photo- + sharing service (resource server), without sharing their username and + password with the printing service. Instead, they authenticates directly with a server trusted by the photo-sharing service (authorization server), which issues the printing service delegation- specific credentials (access token). This specification is designed for use with HTTP ([RFC7230]). The use of OAuth over any protocol other than HTTP is out of scope. Since the publication of the OAuth 2.0 Authorization Framework ([RFC6749]) in October 2012, it has been updated by OAuth 2.0 for Native Apps ([RFC8252]), OAuth Security Best Current Practice @@ -255,21 +258,22 @@ OAuth defines four roles: "resource owner": An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user. This is sometimes abbreviated as "RO". "resource server": The server hosting the protected resources, capable of accepting and responding to protected resource requests - using access tokens. This is sometimes abbreviated as "RS". + using access tokens. The resource server is often accessible via + an API. This is sometimes abbreviated as "RS". "client": An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices). "authorization server": The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. This is sometimes abbreviated as "AS". @@ -307,24 +311,25 @@ The abstract OAuth 2.1 flow illustrated in Figure 1 describes the interaction between the four roles and includes the following steps: 1. The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner (as shown), or preferably indirectly via the authorization server as an intermediary. 2. The client receives an authorization grant, which is a credential representing the resource owner's authorization, expressed using - one of two grant types defined in this specification or using an - extension grant type. The authorization grant type depends on - the method used by the client to request authorization and the - types supported by the authorization server. + one of two authorization grant types defined in this + specification or using an extension grant type. The + authorization grant type depends on the method used by the client + to request authorization and the types supported by the + authorization server. 3. The client requests an access token by authenticating with the authorization server and presenting the authorization grant. 4. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token. 5. The client requests the protected resource from the resource server and authenticates by presenting the access token. @@ -339,73 +344,81 @@ 1.3. Authorization Grant An authorization grant is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token. This specification defines two grant types - authorization code and client credentials - as well as an extensibility mechanism for defining additional types. 1.3.1. Authorization Code - The authorization code is obtained by using an authorization server - as an intermediary between the client and resource owner. Instead of - requesting authorization directly from the resource owner, the client - directs the resource owner to an authorization server (via its user- - agent as defined in [RFC7231]), which in turn directs the resource - owner back to the client with the authorization code. + An authorization code is a temporary credential used to obtain an + access token. Instead of the client requesting authorization + directly from the resource owner, the client directs the resource + owner to an authorization server (via its user-agent as defined in + [RFC7231]), which in turn directs the resource owner back to the + client with the authorization code. The client can then exchange the + authorization code for an access token. Before directing the resource owner back to the client with the authorization code, the authorization server authenticates the - resource owner and obtains authorization. Because the resource owner - only authenticates with the authorization server, the resource - owner's credentials are never shared with the client. + resource owner, and may request the resource owner's consent or + otherwise inform them of the client's request. Because the resource + owner only authenticates with the authorization server, the resource + owner's credentials are never shared with the client, and the client + does not need to have knowledge of any additional authentication + steps such as multi-factor authentication or delegated accounts. The authorization code provides a few important security benefits, such as the ability to authenticate the client, as well as the transmission of the access token directly to the client without passing it through the resource owner's user-agent and potentially exposing it to others, including the resource owner. 1.3.2. Client Credentials - The client credentials (or other forms of client authentication) can - be used as an authorization grant when the authorization scope is - limited to the protected resources under the control of the client, - or to protected resources previously arranged with the authorization - server. Client credentials are used as an authorization grant - typically when the client is acting on its own behalf (the client is - also the resource owner) or is requesting access to protected - resources based on an authorization previously arranged with the - authorization server. + The client credentials or other forms of client authentication (e.g. + a "client_secret" or a private key used to sign a JWT) can be used as + an authorization grant when the authorization scope is limited to the + protected resources under the control of the client, or to protected + resources previously arranged with the authorization server. Client + credentials are used as an authorization grant typically when the + client is acting on its own behalf (the client is also the resource + owner) or is requesting access to protected resources based on an + authorization previously arranged with the authorization server. 1.4. Access Token Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the - client. The string is opaque to the client, but depending on the - authorization server, may be parseable by the resource server. + client. The string is considered opaque to the client, even if it + has a structure. Depending on the authorization server, the access + token string may be parseable by the resource server. - Tokens represent specific scopes and durations of access, granted by - the resource owner, and enforced by the resource server and - authorization server. + Access tokens represent specific scopes and durations of access, + granted by the resource owner, and enforced by the resource server + and authorization server. - The token may denote an identifier used to retrieve the authorization - information or may self-contain the authorization information in a - verifiable manner (i.e., a token string consisting of some data and a - signature). One example of a structured token format is + The token may be used by the RS to retrieve the authorization + information, or the token may self-contain the authorization + information in a verifiable manner (i.e., a token string consisting + of a signed data payload). One example of a token retrieval + mechanism is Token Introspection [RFC7662], in which the RS calls an + endpoint on the AS to validate the token presented by the client. + One example of a structured token format is [I-D.ietf-oauth-access-token-jwt], a method of encoding access token data as a JSON Web Token [RFC7519]. Additional authentication credentials, which are beyond the scope of - this specification, may be required in order for the client to use a - token. This is typically referred to as a sender-constrained access - token, such as Mutual TLS Access Tokens [RFC8705]. + this specification, may be required in order for the client to use an + access token. This is typically referred to as a sender-constrained + access token, such as Mutual TLS Access Tokens [RFC8705]. The access token provides an abstraction layer, replacing different authorization constructs (e.g., username and password) with a single token understood by the resource server. This abstraction enables issuing access tokens more restrictive than the authorization grant used to obtain them, as well as removing the resource server's need to understand a wide range of authentication methods. Access tokens can have different formats, structures, and methods of utilization (e.g., cryptographic properties) based on the resource @@ -415,30 +428,33 @@ 1.5. Refresh Token Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner). Issuing a refresh token is optional at the discretion of the - authorization server. If the authorization server issues a refresh - token, it is included when issuing an access token (i.e., step (4) in - Figure 2). + authorization server, and may be issued based on properties of the + client, properties of the request, policies within the authorization + server, or any other criteria. If the authorization server issues a + refresh token, it is included when issuing an access token (i.e., + step (2) in Figure 2). A refresh token is a string representing the authorization granted to - the client by the resource owner. The string is usually opaque to - the client. The token denotes an identifier used to retrieve the - authorization information. Unlike access tokens, refresh tokens are - intended for use only with authorization servers and are never sent - to resource servers. + the client by the resource owner. The string is considered opaque to + the client. The refresh token may be an identifier used to retrieve + the authorization information or may encode this information into the + string itself. Unlike access tokens, refresh tokens are intended for + use only with authorization servers and are never sent to resource + servers. +--------+ +---------------+ | |--(1)------- Authorization Grant --------->| | | | | | | |<-(2)----------- Access Token -------------| | | | & Refresh Token | | | | | | | | +----------+ | | | |--(3)---- Access Token ---->| | | | | | | | | | @@ -485,22 +501,22 @@ 8. The authorization server authenticates the client and validates the refresh token, and if valid, issues a new access token (and, optionally, a new refresh token). 1.6. TLS Version Whenever Transport Layer Security (TLS) is used by this specification, the appropriate version (or versions) of TLS will vary over time, based on the widespread deployment and known security - vulnerabilities. At the time of this writing, TLS version 1.3 - [RFC8446] is the most recent version. + vulnerabilities. Refer to [BCP195] for up to date recommendations on + transport layer security. Implementations MAY also support additional transport-layer security mechanisms that meet their security requirements. 1.7. HTTP Redirections This specification makes extensive use of HTTP redirections, in which the client or the authorization server directs the resource owner's user-agent to another destination. While the examples in this specification show the use of the HTTP 302 status code, any other @@ -510,54 +526,85 @@ 1.8. Interoperability OAuth 2.1 provides a rich authorization framework with well-defined security properties. This specification leaves a few required components partially or fully undefined (e.g., client registration, authorization server capabilities, endpoint discovery). Some of these behaviors are defined in optional extensions which implementations can choose to - use. + use, such as: + + * [RFC8414]: Authorization Server Metadata, defining an endpoint + clients can use to look up the information needed to interact with + a particular OAuth server + + * [RFC7591]: Dynamic Client Registration, providing a mechanism for + programmatically registering clients with an authorization server + + * [RFC7592]: Dynamic Client Management, providing a mechanism for + updating dynamically registered client information + + * [RFC7662]: Token Introspection, defining a mechanism for resource + servers to obtain information about access tokens Please refer to Appendix C for a list of current known extensions at the time of this publication. -1.9. Notational Conventions +1.9. Compatibility with OAuth 2.0 + + OAuth 2.1 is compatible with OAuth 2.0 with the extensions and + restrictions from known best current practices applied. + Specifically, features not specified in OAuth 2.0 core, such as PKCE, + are required in OAuth 2.1. Additionally, some features available in + OAuth 2.0, such as the Implicit or Resource Owner Credentials grant + types, are not specified in OAuth 2.1. Furthermore, some behaviors + allowed in OAuth 2.0 are restricted in OAuth 2.1, such as the strict + string matching of redirect URIs required by OAuth 2.1. + + See Section 12 for more details on the differences from OAuth 2.0. + +1.10. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234]. Additionally, the rule URI-reference is included from "Uniform Resource Identifier (URI): Generic Syntax" [RFC3986]. Certain security-related terms are to be understood in the sense defined in [RFC4949]. These terms include, but are not limited to, "attack", "authentication", "authorization", "certificate", "confidentiality", "credential", "encryption", "identity", "sign", "signature", "trust", "validate", and "verify". + The term "payload" is to be interpreted as described in Section 3.3 + of [RFC7231]. + Unless otherwise noted, all the protocol parameter names and values are case sensitive. 2. Client Registration - Before initiating the protocol, the client registers with the - authorization server. The means through which the client registers - with the authorization server are beyond the scope of this - specification but typically involve end-user interaction with an HTML - registration form, or by using Dynamic Client Registration + Before initiating the protocol, the client must establish its + registration with the authorization server. The means through which + the client registers with the authorization server are beyond the + scope of this specification but typically involve the client + developer manually registering the client at the authorization + server's website after creating an account and agreeing to the + service's Terms of Service, or by using Dynamic Client Registration ([RFC7591]). Client registration does not require a direct interaction between the client and the authorization server. When supported by the authorization server, registration can rely on other means for establishing trust and obtaining the required client properties (e.g., redirect URI, client type). For example, registration can be accomplished using a self-issued or third-party-issued assertion, or by the authorization server performing client discovery using a trusted channel. @@ -654,29 +701,29 @@ The client identifier string size is left undefined by this specification. The client should avoid making assumptions about the identifier size. The authorization server SHOULD document the size of any identifier it issues. Authorization servers SHOULD NOT allow clients to choose or influence their "client_id" value. See Section 9.6 for details. 2.3. Client Authentication - If the client has credentials, (is a confidential or credentialed - client), the client and authorization server establish a client - authentication method suitable for the security requirements of the - authorization server. The authorization server MAY accept any form - of client authentication meeting its security requirements. + If the client type is confidential, the client and authorization + server establish a client authentication method suitable for the + security requirements of the authorization server. The authorization + server MAY accept any form of client authentication meeting its + security requirements. - Confidential and credentialed clients are typically issued (or - establish) a set of client credentials used for authenticating with - the authorization server (e.g., password, public/private key pair). + Confidential clients are typically issued (or establish) a set of + client credentials used for authenticating with the authorization + server (e.g., password, public/private key pair). Authorization servers SHOULD use client authentication if possible. It is RECOMMENDED to use asymmetric (public-key based) methods for client authentication such as mTLS [RFC8705] or "private_key_jwt" [OpenID]. When asymmetric methods for client authentication are used, authorization servers do not need to store sensitive symmetric keys, making these methods more robust against a number of attacks. The authorization server MAY establish a client authentication method @@ -935,23 +982,24 @@ The client MUST use the HTTP "POST" method when making access token requests. Parameters sent without a value MUST be treated as if they were omitted from the request. The authorization server MUST ignore unrecognized request parameters. Request and response parameters defined by this specification MUST NOT be included more than once. 3.2.1. Client Authentication - Confidential or credentialed clients client MUST authenticate with - the authorization server as described in Section 2.3 when making - requests to the token endpoint. Client authentication is used for: + Confidential clients or other clients issued client credentials MUST + authenticate with the authorization server as described in + Section 2.3 when making requests to the token endpoint. Client + authentication is used for: * Enforcing the binding of refresh tokens and authorization codes to the client they were issued to. Client authentication is critical when an authorization code is transmitted to the redirection endpoint over an insecure channel. * Recovering from a compromised client by disabling the client or changing its credentials, thus preventing an attacker from abusing stolen refresh tokens. Changing a single set of client credentials is significantly faster than revoking an entire set of @@ -989,23 +1037,23 @@ authorization, the authorization server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope. The authorization server SHOULD document its scope requirements and default value (if defined). 4. Obtaining Authorization To request an access token, the client obtains authorization from the resource owner. The authorization is expressed in the form of an authorization grant, which the client uses to request the access - token. OAuth defines two grant types: authorization code and client - credentials. It also provides an extension mechanism for defining - additional grant types. + token. OAuth defines two authorization grant types: authorization + code and client credentials. It also provides an extension mechanism + for defining additional grant types. 4.1. Authorization Code Grant The authorization code grant type is used to obtain both access tokens and refresh tokens. Since this is a redirect-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server. @@ -1208,23 +1256,23 @@ redirect URI using the "application/x-www-form-urlencoded" format, per Appendix B: "code": REQUIRED. The authorization code generated by the authorization server. The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all - tokens previously issued based on that authorization code. The - authorization code is bound to the client identifier and redirect - URI. + access tokens and refresh tokens previously issued based on that + authorization code. The authorization code is bound to the client + identifier and redirect URI. "state": REQUIRED if the "state" parameter was present in the client authorization request. The exact value received from the client. For example, the authorization server redirects the user-agent by sending the following HTTP response: HTTP/1.1 302 Found Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA &state=xyz @@ -1330,63 +1378,65 @@ sending the following HTTP response: HTTP/1.1 302 Found Location: https://client.example.com/cb?error=access_denied&state=xyz 4.1.3. Access Token Request The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP - request entity-body: + request payload: "grant_type": REQUIRED. Value MUST be set to "authorization_code". "code": REQUIRED. The authorization code received from the authorization server. "redirect_uri": REQUIRED, if the "redirect_uri" parameter was included in the authorization request as described in Section 4.1.1, and their values MUST be identical. "client_id": REQUIRED, if the client is not authenticating with the authorization server as described in Section 3.2.1. "code_verifier": REQUIRED, if the "code_challenge" parameter was included in the authorization request. MUST NOT be used otherwise. The original code verifier string. - Confidential or credentialed clients MUST authenticate with the - authorization server as described in Section 3.2.1. + If the client type is confidential or the client was issued client + credentials (or assigned other authentication requirements), the + client MUST authenticate with the authorization server as described + in Section 3.2.1. For example, the client makes the following HTTP request using TLS (with extra line breaks for display purposes only): POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed The authorization server MUST: - * require client authentication for confidential and credentialed - clients (or clients with other authentication requirements), + * require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), * authenticate the client if client authentication is included, - * ensure that the authorization code was issued to the authenticated - confidential or credentialed client, or if the client is public, - ensure that the code was issued to "client_id" in the request, + confidential client, or if the client is public, ensure that the + code was issued to "client_id" in the request, * verify that the authorization code is valid, * verify that the "code_verifier" parameter is present if and only if a "code_challenge" parameter was present in the authorization request, * if a "code_verifier" is present, verify the "code_verifier" by calculating the code challenge from the received "code_verifier" and comparing it with the previously associated "code_challenge", @@ -1424,21 +1474,21 @@ 4.2. Client Credentials Grant The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server (the method of which is beyond the scope of this specification). The client credentials grant type MUST only be used by confidential - or credentialed clients. + clients. +---------+ +---------------+ | | | | | |>--(1)- Client Authentication --->| Authorization | | Client | | Server | | |<--(2)---- Access Token ---------<| | | | | | +---------+ +---------------+ Figure 4: Client Credentials Flow @@ -1454,21 +1504,21 @@ 4.2.1. Authorization Request and Response Since the client authentication is used as the authorization grant, no additional authorization request is needed. 4.2.2. Access Token Request The client makes a request to the token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP - request entity-body: + request payload: "grant_type": REQUIRED. Value MUST be set to "client_credentials". "scope": OPTIONAL. The scope of the access request as described by Section 3.3. The client MUST authenticate with the authorization server as described in Section 3.2.1. For example, the client makes the following HTTP request using @@ -1538,44 +1588,44 @@ If the access token request is valid and authorized, the authorization server issues an access token and optional refresh token as described in Section 5.1. If the request failed client authentication or is invalid, the authorization server returns an error response as described in Section 5.2. 5.1. Successful Response The authorization server issues an access token and optional refresh token, and constructs the response by adding the following parameters - to the entity-body of the HTTP response with a 200 (OK) status code: + to the payload of the HTTP response with a 200 (OK) status code: "access_token": REQUIRED. The access token issued by the authorization server. - "token_type": REQUIRED. The type of the token issued as described - in Section 7.1. Value is case insensitive. + "token_type": REQUIRED. The type of the access token issued as + described in Section 7.1. Value is case insensitive. "expires_in": RECOMMENDED. The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value. "refresh_token": OPTIONAL. The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in Section 6. "scope": OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED. The scope of the access token as described by Section 3.3. - The parameters are included in the entity-body of the HTTP response - using the "application/json" media type as defined by [RFC7159]. The + The parameters are included in the payload of the HTTP response using + the "application/json" media type as defined by [RFC7159]. The parameters are serialized into a JavaScript Object Notation (JSON) structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary. The authorization server MUST include the HTTP "Cache-Control" response header field [RFC7234] with a value of "no-store" in any response containing tokens, credentials, or other sensitive information, as well as the "Pragma" response header field [RFC7234] @@ -1653,22 +1703,22 @@ the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. "error_uri": OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. - The parameters are included in the entity-body of the HTTP response - using the "application/json" media type as defined by [RFC7159]. The + The parameters are included in the payload of the HTTP response using + the "application/json" media type as defined by [RFC7159]. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary. For example: HTTP/1.1 400 Bad Request Content-Type: application/json @@ -1691,53 +1741,55 @@ If refresh tokens are issued, those refresh tokens MUST be bound to the scope and resource servers as consented by the resource owner. This is to prevent privilege escalation by the legitimate client and reduce the impact of refresh token leakage. If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP - request entity-body: + request payload: "grant_type": REQUIRED. Value MUST be set to "refresh_token". "refresh_token": REQUIRED. The refresh token issued to the client. "scope": OPTIONAL. The scope of the access request as described by Section 3.3. The requested scope MUST NOT include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner. Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the - client to which it was issued. Confidential or credentialed clients - MUST authenticate with the authorization server as described in - Section 3.2.1. + client to which it was issued. If the client type is confidential or + the client was issued client credentials (or assigned other + authentication requirements), the client MUST authenticate with the + authorization server as described in Section 3.2.1. For example, the client makes the following HTTP request using transport-layer security (with extra line breaks for display purposes only): POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA The authorization server MUST: - * require client authentication for confidential or credentialed - clients + * require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), * authenticate the client if client authentication is included and ensure that the refresh token was issued to the authenticated client, and * validate the refresh token. 6.1. Refresh Token Protection Authorization servers SHOULD utilize one of these methods to detect @@ -1878,45 +1930,44 @@ b64token = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"=" credentials = "Bearer" 1*SP b64token Clients SHOULD make authenticated requests with a bearer token using the "Authorization" request header field with the "Bearer" HTTP authorization scheme. Resource servers MUST support this method. 7.2.1.2. Form-Encoded Body Parameter - When sending the access token in the HTTP request entity-body, the - client adds the access token to the request-body using the - "access_token" parameter. The client MUST NOT use this method unless - all of the following conditions are met: + When sending the access token in the HTTP request payload, the client + adds the access token to the request-body using the "access_token" + parameter. The client MUST NOT use this method unless all of the + following conditions are met: * The HTTP request entity-header includes the "Content-Type" header field set to "application/x-www-form-urlencoded". - * The entity-body follows the encoding requirements of the - "application/x-www-form-urlencoded" content-type as defined by - HTML 4.01 [W3C.REC-html401-19991224]. + * The payload follows the encoding requirements of the "application/ + x-www-form-urlencoded" content-type as defined by HTML 4.01 + [W3C.REC-html401-19991224]. - * The HTTP request entity-body is single-part. + * The HTTP request payload is single-part. - * The content to be encoded in the entity-body MUST consist entirely - of ASCII [USASCII] characters. + * The content to be encoded in the payload MUST consist entirely of + ASCII [USASCII] characters. * The HTTP request method is one for which the request-body has defined semantics. In particular, this means that the "GET" method MUST NOT be used. - The entity-body MAY include other request-specific parameters, in - which case the "access_token" parameter MUST be properly separated - from the request-specific parameters using "&" character(s) (ASCII - code 38). + The payload MAY include other request-specific parameters, in which + case the "access_token" parameter MUST be properly separated from the + request-specific parameters using "&" character(s) (ASCII code 38). For example, the client makes the following HTTP request using transport-layer security: POST /resource HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded access_token=mF_9.B5f-4.1JqM @@ -2201,49 +2252,50 @@ 7.4.3.4. Don't store bearer tokens in HTTP cookies Implementations MUST NOT store bearer tokens within cookies that can be sent in the clear (which is the default transmission mode for cookies). Implementations that do store bearer tokens in cookies MUST take precautions against cross-site request forgery. 7.4.3.5. Issue short-lived bearer tokens - Token servers SHOULD issue short-lived (one hour or less) bearer - tokens, particularly when issuing tokens to clients that run within a - web browser or other environments where information leakage may - occur. Using short-lived bearer tokens can reduce the impact of them - being leaked. + Authorization servers SHOULD issue short-lived (one hour or less) + bearer tokens, particularly when issuing tokens to clients that run + within a web browser or other environments where information leakage + may occur. Using short-lived bearer tokens can reduce the impact of + them being leaked. 7.4.3.6. Issue scoped bearer tokens - Token servers SHOULD issue bearer tokens that contain an audience - restriction, scoping their use to the intended relying party or set - of relying parties. + Authorization servers SHOULD issue bearer tokens that contain an + audience restriction, scoping their use to the intended relying party + or set of relying parties. 7.4.3.7. Don't pass bearer tokens in page URLs Bearer tokens MUST NOT be passed in page URLs (for example, as query string parameters). Instead, bearer tokens SHOULD be passed in HTTP message headers or message bodies for which confidentiality measures are taken. Browsers, web servers, and other software may not adequately secure URLs in the browser history, web server logs, and other data structures. If bearer tokens are passed in page URLs, attackers might be able to steal them from the history data, logs, or other unsecured locations. 7.4.4. Token Replay Prevention A sender-constrained access token scopes the applicability of an access token to a certain sender. This sender is obliged to demonstrate knowledge of a certain secret as prerequisite for the - acceptance of that token at the recipient (e.g., a resource server). + acceptance of that access token at the recipient (e.g., a resource + server). Authorization and resource servers SHOULD use mechanisms for sender- constrained access tokens to prevent token replay as described in Section 4.8.1.1.2 of [I-D.ietf-oauth-security-topics]. The use of Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. It is RECOMMENDED to use end-to-end TLS. If TLS traffic needs to be terminated at an intermediary, refer to Section 4.11 of [I-D.ietf-oauth-security-topics] for further security advice. @@ -2570,22 +2622,22 @@ serve the respective request. Clients and authorization servers MAY utilize the parameter "scope" and "authorization_details" as specified in [I-D.ietf-oauth-rar] to determine those resources and/or actions. Authorization and resource servers SHOULD use mechanisms for sender- constrained access tokens to prevent token replay as described in (#pop_tokens). A sender-constrained access token scopes the applicability of an access token to a certain sender. This sender is obliged to demonstrate knowledge of a certain secret as prerequisite - for the acceptance of that token at the recipient (e.g., a resource - server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is + for the acceptance of that access token at the recipient (e.g., a + resource server). The use of Mutual TLS for OAuth 2.0 [RFC8705] is RECOMMENDED. 9.5. Refresh Tokens Authorization servers MAY issue refresh tokens to clients. Refresh tokens MUST be kept confidential in transit and storage, and shared only among the authorization server and the client to whom the refresh tokens were issued. The authorization server MUST maintain the binding between a refresh token and the client to whom it was @@ -2648,24 +2700,24 @@ carried in the "state" parameter that are securely bound to the user agent MUST be used for CSRF protection (see (#csrf_countermeasures)). In order to prevent mix-up attacks (see (#mix_up)), clients MUST only process redirect responses of the authorization server they sent the respective request to and from the same user agent this authorization request was initiated with. Clients MUST store the authorization server they sent an authorization request to and bind this information to the user agent and check that the authorization request was received from the correct authorization server. Clients - MUST ensure that the subsequent token request, if applicable, is sent - to the same authorization server. Clients SHOULD use distinct - redirect URIs for each authorization server as a means to identify - the authorization server a particular response came from. + MUST ensure that the subsequent access token request, if applicable, + is sent to the same authorization server. Clients SHOULD use + distinct redirect URIs for each authorization server as a means to + identify the authorization server a particular response came from. An AS that redirects a request potentially containing user credentials MUST avoid forwarding these user credentials accidentally (see Section 9.7.2 for details). 9.7.1. Loopback Redirect Considerations in Native Apps Loopback interface redirect URIs use the "http" scheme (i.e., without Transport Layer Security (TLS)). This is acceptable for loopback interface redirect URIs as the HTTP request never leaves the device. @@ -2686,21 +2738,21 @@ resolution on the user's device. 9.7.2. HTTP 307 Redirect An AS which redirects a request that potentially contains user credentials MUST NOT use the HTTP 307 status code for redirection. If an HTTP redirection (and not, for example, JavaScript) is used for such a request, AS SHOULD use HTTP status code 303 "See Other". At the authorization endpoint, a typical protocol flow is that the AS - prompts the user to enter her credentials in a form that is then + prompts the user to enter their credentials in a form that is then submitted (using the HTTP POST method) back to the authorization server. The AS checks the credentials and, if successful, redirects the user agent to the client's redirect URI. If the status code 307 were used for redirection, the user agent would send the user credentials via HTTP POST to the client. This discloses the sensitive credentials to the client. If the relying party is malicious, it can use the credentials to impersonate the user at the AS. @@ -2737,21 +2789,21 @@ If the client can be authenticated, the authorization servers MUST authenticate the client and ensure that the authorization code was issued to the same client. Clients MUST prevent injection (replay) of authorization codes into the authorization response by attackers. To this end, using "code_challenge" and "code_verifier" is REQUIRED for clients and authorization servers MUST enforce their use, unless both of the following criteria are met: - * The client is a confidential or credentialed client. + * The client is a confidential client. * In the specific deployment and the specific request, there is reasonable assurance for authorization server that the client implements the OpenID Connect "nonce" mechanism properly. In this case, using and enforcing "code_challenge" and "code_verifier" is still RECOMMENDED. The "code_challenge" or OpenID Connect "nonce" value MUST be transaction-specific and securely bound to the client and the user @@ -3356,26 +3408,30 @@ This document does not require any IANA actions. All referenced registries are defined by RFC6749 and related documents that this work is based upon. No changes to those registries are required by this specification. 14. References 14.1. Normative References + [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, + "Recommendations for Secure Use of Transport Layer + Security (TLS)", n.d.. + [I-D.ietf-oauth-security-topics] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "OAuth 2.0 Security Best Current Practice", Work in Progress, Internet-Draft, draft-ietf-oauth-security- - topics-15, 5 April 2020, . + topics-16, 5 October 2020, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, DOI 10.17487/RFC2617, June 1999, @@ -3457,77 +3513,77 @@ . [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American Standard Code for Information Interchange, ANSI X3.4", 1986. [W3C.REC-html401-19991224] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 Specification", World Wide Web Consortium Recommendation REC-html401-19991224, 24 December 1999, - . + . [W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- xml-20081126, 26 November 2008, - . + . 14.2. Informative References [CSP-2] "Content Security Policy Level 2", December 2016, . [I-D.bradley-oauth-jwt-encoded-state] Bradley, J., Lodderstedt, T., and H. Zandbelt, "Encoding claims in the OAuth 2 state parameter using a JWT", Work in Progress, Internet-Draft, draft-bradley-oauth-jwt- encoded-state-09, 4 November 2018, . [I-D.ietf-oauth-access-token-jwt] Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", Work in Progress, Internet-Draft, draft- - ietf-oauth-access-token-jwt-07, 27 April 2020, + ietf-oauth-access-token-jwt-11, 22 January 2021, . + access-token-jwt-11.txt>. [I-D.ietf-oauth-browser-based-apps] Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based Apps", Work in Progress, Internet-Draft, draft-ietf-oauth- - browser-based-apps-06, 5 April 2020, . + browser-based-apps-07, 2 October 2020, + . [I-D.ietf-oauth-dpop] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., - Jones, M., and D. Waite, "OAuth 2.0 Demonstration of - Proof-of-Possession at the Application Layer (DPoP)", Work - in Progress, Internet-Draft, draft-ietf-oauth-dpop-01, 1 - May 2020, . + Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- + of-Possession at the Application Layer (DPoP)", Work in + Progress, Internet-Draft, draft-ietf-oauth-dpop-02, 18 + November 2020, . [I-D.ietf-oauth-par] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", - Work in Progress, Internet-Draft, draft-ietf-oauth-par-02, - 10 July 2020, . + Work in Progress, Internet-Draft, draft-ietf-oauth-par-05, + 14 December 2020, . [I-D.ietf-oauth-rar] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", Work in Progress, Internet- - Draft, draft-ietf-oauth-rar-01, 19 February 2020, + Draft, draft-ietf-oauth-rar-03, 18 October 2020, . + 03.txt>. [I-D.ietf-oauth-token-binding] Jones, M., Campbell, B., Bradley, J., and W. Denniss, "OAuth 2.0 Token Binding", Work in Progress, Internet- Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, . [NIST800-63] Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., @@ -3831,34 +3887,34 @@ location of the authorization and token endpoints and the supported grant types. * [RFC8707]: Resource Indicators - Provides a way for the client to explicitly signal to the authorization server where it intends to use the access token it is requesting. * [RFC7591]: Dynamic Client Registration - - Dynamic Client Registration provides a mechanism for programmatically registering clients with an authorization server. * [RFC7592]: Dynamic Client Management + - Dynamic Client Management provides a mechanism for updating dynamically registered client information. * [I-D.ietf-oauth-access-token-jwt]: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens - This specification defines a profile for issuing OAuth access - tokens in JSON web token (JWT) format. + tokens in JSON Web Token (JWT) format. * [RFC8705]: Mutual TLS - Mutual TLS describes a mechanism of binding access tokens and refresh tokens to the clients they were issued to, as well as a client authentication mechanism, via TLS certificate authentication. * [RFC7662]: Token Introspection