diff options
Diffstat (limited to 'doc/rfc/rfc9207.txt')
| -rw-r--r-- | doc/rfc/rfc9207.txt | 447 |
1 files changed, 447 insertions, 0 deletions
diff --git a/doc/rfc/rfc9207.txt b/doc/rfc/rfc9207.txt new file mode 100644 index 0000000..c33cec4 --- /dev/null +++ b/doc/rfc/rfc9207.txt @@ -0,0 +1,447 @@ + + + + +Internet Engineering Task Force (IETF) K. Meyer zu Selhausen +Request for Comments: 9207 Hackmanit +Category: Standards Track D. Fett +ISSN: 2070-1721 yes.com + March 2022 + + + OAuth 2.0 Authorization Server Issuer Identification + +Abstract + + This document specifies a new parameter called iss. This parameter + is used to explicitly include the issuer identifier of the + authorization server in the authorization response of an OAuth + authorization flow. The iss parameter serves as an effective + countermeasure to "mix-up attacks". + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9207. + +Copyright Notice + + Copyright (c) 2022 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 Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Conventions and Terminology + 2. Response Parameter iss + 2.1. Example Authorization Response + 2.2. Example Error Response + 2.3. Providing the Issuer Identifier + 2.4. Validating the Issuer Identifier + 3. Authorization Server Metadata + 4. Security Considerations + 5. IANA Considerations + 5.1. OAuth Authorization Server Metadata + 5.2. OAuth Parameters Registration + 6. References + 6.1. Normative References + 6.2. Informative References + Acknowledgements + Authors' Addresses + +1. Introduction + + The OAuth 2.0 Authorization Framework [RFC6749] allows clients to + interact with multiple independent authorization servers under the + control of separate entities. Some OAuth grant types utilize the + resource owner's user agent to deliver the authorization server's + response to the OAuth client. One example of this pattern is the + authorization response of the authorization code grant. + + The authorization response as specified in Section 4.1.2 of [RFC6749] + does not contain any information about the identity of the + authorization server that issued the response. Therefore, clients + receiving a response from the resource owner's user agent cannot be + sure who initially issued the response and the secrets contained + therein. The lack of certainty about the origin of the response + enables a class of attacks called "mix-up attacks". + + Mix-up attacks are a potential threat to all OAuth clients that + interact with multiple authorization servers. When at least one of + these authorization servers is under an attacker's control, the + attacker can launch a mix-up attack to acquire authorization codes or + access tokens issued by any one of the other authorization servers. + There are multiple ways in which an attacker can gain control over an + authorization server supported by the client; for instance, an + authorization server could become compromised, or the attacker could + register their own authorization server, for example, using dynamic + client registration [RFC7591]. + + OAuth clients that interact with only one authorization server are + not vulnerable to mix-up attacks. However, when such clients decide + to add support for a second authorization server in the future, they + become vulnerable and need to apply countermeasures to mix-up + attacks. + + Mix-up attacks aim to steal an authorization code or access token by + tricking the client into sending the authorization code or access + token to the attacker instead of the honest authorization or resource + server. This marks a severe threat to the confidentiality and + integrity of resources whose access is managed with OAuth. A + detailed description and different variants of the mix-up attack + class can be found in Section 4.4 of "OAuth 2.0 Security Best Current + Practice" [OAUTH-SECURITY-TOPICS] as well as in the original research + first highlighting this attack class, "On the security of modern + Single Sign-On Protocols: Second-Order Vulnerabilities in OpenID + Connect" [arXiv.1508.04324] and "A Comprehensive Formal Security + Analysis of OAuth 2.0" [arXiv.1601.01229]. + + This document defines a new parameter in the authorization response + called iss. The iss parameter allows the authorization server to + include its identity in the authorization response explicitly. The + client can compare the value of the iss parameter to the issuer + identifier of the authorization server (e.g., retrieved from its + metadata) it believes it is interacting with. The iss parameter + gives the client certainty about the authorization server's identity + and enables it to send credentials such as authorization codes and + access tokens only to the intended recipients. + + The effectiveness of the iss parameter against mix-up attacks was + analyzed and formally proven in "A Comprehensive Formal Security + Analysis of OAuth 2.0" [arXiv.1601.01229]. + +1.1. Conventions and Terminology + + 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 terms "access token", "authorization + code", "authorization code grant", "authorization server", "resource + server", "authorization response", "grant type", and "client" defined + by the OAuth 2.0 Authorization Framework [RFC6749]. The term "issuer + identifier" is defined by OAuth 2.0 Authorization Server Metadata + [RFC8414]. + +2. Response Parameter iss + + In authorization responses to the client, including error responses, + an authorization server supporting this specification MUST indicate + its identity by including the iss parameter in the response. + + The iss parameter value is the issuer identifier of the authorization + server that created the authorization response, as defined in + [RFC8414]. Its value MUST be a URL that uses the "https" scheme + without any query or fragment components. + +2.1. Example Authorization Response + + The following example shows an authorization response from the + authorization server whose issuer identifier is + https://honest.as.example (extra line breaks and indentation are for + display purposes only): + + HTTP/1.1 302 Found + Location: https://client.example/cb? + code=x1848ZT64p4IirMPT0R-X3141MFPTuBX-VFL_cvaplMH58 + &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI + &iss=https%3A%2F%2Fhonest.as.example + +2.2. Example Error Response + + The following example shows an error response from the same + authorization server (extra line breaks and indentation are for + display purposes only): + + HTTP/1.1 302 Found + Location: https://client.example/cb? + error=access_denied + &state=N2JjNGJhY2JiZjRhYzA3MGJkMzNmMDE5OWJhZmJhZjA + &iss=https%3A%2F%2Fhonest.as.example + +2.3. Providing the Issuer Identifier + + Authorization servers supporting this specification MUST provide + their issuer identifier to enable clients to validate the iss + parameter effectively. + + For authorization servers publishing metadata according to [RFC8414], + the following rules apply: + + * The issuer identifier included in the server's metadata value + issuer MUST be identical to the iss parameter's value. + + * The server MUST indicate its support for the iss parameter by + setting the metadata parameter + authorization_response_iss_parameter_supported, defined in + Section 3, to true. + + Authorization servers MAY additionally provide the issuer identifier + to clients by any other mechanism, which is outside of the scope of + this specification. + +2.4. Validating the Issuer Identifier + + Clients that support this specification MUST extract the value of the + iss parameter from authorization responses they receive if the + parameter is present. Clients MUST then decode the value from its + "application/x-www-form-urlencoded" form according to Appendix B of + [RFC6749] and compare the result to the issuer identifier of the + authorization server where the authorization request was sent to. + This comparison MUST use simple string comparison as defined in + Section 6.2.1 of [RFC3986]. If the value does not match the expected + issuer identifier, clients MUST reject the authorization response and + MUST NOT proceed with the authorization grant. For error responses, + clients MUST NOT assume that the error originates from the intended + authorization server. + + More precisely, clients that interact with authorization servers + supporting OAuth metadata [RFC8414] MUST compare the iss parameter + value to the issuer value in the server's metadata document. If + OAuth metadata is not used, clients MUST use deployment-specific ways + (for example, a static configuration) to decide if the returned iss + value is the expected value in the current flow (see also Section 4). + + If clients interact with both authorization servers supporting this + specification and authorization servers not supporting this + specification, clients MUST retain state about whether each + authorization server supports the iss parameter. Clients MUST reject + authorization responses without the iss parameter from authorization + servers that do support the parameter according to the client's + configuration. Clients SHOULD discard authorization responses with + the iss parameter from authorization servers that do not indicate + their support for the parameter. However, there might be legitimate + authorization servers that provide the iss parameter without + indicating their support in their metadata. Local policy or + configuration can determine whether to accept such responses, and + specific guidance is out of scope for this specification. + + In general, clients that support this specification MAY accept + authorization responses that do not contain the iss parameter or + reject them and exclusively support authorization servers that + provide the iss parameter in the authorization response. Local + policy or configuration can determine when to accept such responses, + and specific guidance is out of scope for this specification. + + In OpenID Connect [OIDC.Core] flows where an ID Token is returned + from the authorization endpoint, the value in the iss parameter MUST + always be identical to the iss claim in the ID Token. + + Section 4.1.2 of [RFC6749] already mandates that clients that do not + support this specification MUST ignore the unrecognized iss + parameter. + + | Note: The "JWT Secured Authorization Response Mode for OAuth + | 2.0 (JARM)" [JARM] defines a mechanism that conveys all + | authorization response parameters in a JSON Web Token (JWT). + | This JWT contains an iss claim that provides the same + | protection if it is validated as described in Section 2.4. + | Therefore, an additional iss parameter outside the JWT is not + | necessary when JARM is used. + +3. Authorization Server Metadata + + The following parameter for the authorization server metadata + [RFC8414] is introduced to signal the authorization server's support + for this specification: + + authorization_response_iss_parameter_supported: Boolean parameter + indicating whether the authorization server provides the iss + parameter in the authorization response as defined in Section 2. + If omitted, the default value is false. + +4. Security Considerations + + Clients MUST validate the iss parameter precisely as described in + Section 2.4 and MUST NOT allow multiple authorization servers to use + the same issuer identifier. In particular, when authorization server + details can be manually configured in the client, the client MUST + ensure that the accepted iss values are unique for each authorization + server. + + The iss parameter enables a client to decide if an authorization + server "expects" to be used in an OAuth flow together with a certain + token endpoint and potentially other endpoints, like the userinfo + endpoint [OIDC.Core]. When OAuth metadata is used, the iss parameter + identifies the issuer and therefore the respective OAuth metadata + document that points to the other endpoints. When OAuth metadata is + not used, the client can use, for example, a statically configured + expected iss value for each configured authorization server. + + The issuer identifier contained in the authorization response is not + cryptographically protected against tampering. In general, + mechanisms such as JWTs (as specified in [JARM]) could be used to + protect the integrity of the authorization response. However, in + mix-up attacks, the client generally receives the authorization + response from an uncompromised authorization server. If an attacker + can tamper with this authorization response before it is received by + the client, the attacker would also have direct access to the + authorization code. The attacker does not need to execute a mix-up + attack to steal the authorization code. Therefore, integrity + protection for the authorization response is not necessary to defend + against mix-up attacks. + + There are also alternative countermeasures to mix-up attacks. When + an authorization response already includes an authorization server's + issuer identifier by other means and this identifier is checked as + laid out in Section 2.4, the use and verification of the iss + parameter is not necessary and MAY be omitted. For example, this is + the case when OpenID Connect response types that return an ID Token + from the authorization endpoint (e.g., response_type=code id_token) + or [JARM] are used. However, if a client receives an authorization + response that contains multiple issuer identifiers, the client MUST + reject the response if these issuer identifiers do not match. The + details of alternative countermeasures are outside of the scope of + this specification. + + Mix-up attacks are only relevant to clients that interact with + multiple authorization servers. However, clients interacting with + only one authorization server might add support for a second + authorization server in the future. By supporting multiple + authorization servers, they become vulnerable to mix-up attacks and + need to apply countermeasures. + +5. IANA Considerations + +5.1. OAuth Authorization Server Metadata + + IANA has registered the following value in the "OAuth Authorization + Server Metadata" registry of [IANA.OAuth.Parameters] established by + [RFC8414]. + + Metadata Name: authorization_response_iss_parameter_supported + Metadata Description: Boolean value indicating whether the + authorization server provides the iss parameter in the + authorization response. + Change Controller: IETF + Specification Document(s): Section 3 of RFC 9207 + +5.2. OAuth Parameters Registration + + IANA has updated the iss entry to appear as follows in the "OAuth + Parameters" registry of [IANA.OAuth.Parameters] established by + [RFC6749]. + + Parameter name: iss + Parameter usage location: authorization request, authorization + response + Change Controller: IETF + Specification Document(s): Section 2 of RFC 9207, [RFC9101], and + Section 4.1.1 of [RFC7519]. + +6. References + +6.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + <https://www.rfc-editor.org/info/rfc3986>. + + [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", + RFC 6749, DOI 10.17487/RFC6749, October 2012, + <https://www.rfc-editor.org/info/rfc6749>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + + [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 + Authorization Server Metadata", RFC 8414, + DOI 10.17487/RFC8414, June 2018, + <https://www.rfc-editor.org/info/rfc8414>. + +6.2. Informative References + + [arXiv.1508.04324] + Mainka, C., Mladenov, V., and J. Schwenk, "On the security + of modern Single Sign-On Protocols: Second-Order + Vulnerabilities in OpenID Connect", August 2015, + <https://arxiv.org/abs/1508.04324>. + + [arXiv.1601.01229] + Fett, D., Kuesters, R., and G. Schmitz, "A Comprehensive + Formal Security Analysis of OAuth 2.0", + DOI 10.1145/2976749.2978385, January 2016, + <https://arxiv.org/abs/1601.01229>. + + [IANA.OAuth.Parameters] + IANA, "OAuth Parameters", + <https://www.iana.org/assignments/oauth-parameters>. + + [JARM] Lodderstedt, T. and B. Campbell, "Financial-grade API: JWT + Secured Authorization Response Mode for OAuth 2.0 (JARM)", + October 2018, + <https://openid.net/specs/openid-financial-api-jarm.html>. + + [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-19, 16 December 2021, + <https://datatracker.ietf.org/doc/html/draft-ietf-oauth- + security-topics-19>. + + [OIDC.Core] + Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and + C. Mortimore, "OpenID Connect Core 1.0 incorporating + errata set 1", November 2014, + <https://openid.net/specs/openid-connect-core-1_0.html>. + + [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token + (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, + <https://www.rfc-editor.org/info/rfc7519>. + + [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and + P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", + RFC 7591, DOI 10.17487/RFC7591, July 2015, + <https://www.rfc-editor.org/info/rfc7591>. + + [RFC9101] Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 + Authorization Framework: JWT-Secured Authorization Request + (JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021, + <https://www.rfc-editor.org/info/rfc9101>. + +Acknowledgements + + We would like to thank Brian Campbell, Roman Danyliw, Vladimir + Dzhuvinov, Joseph Heenan, Takahiko Kawasaki, Torsten Lodderstedt, + Christian Mainka, Vladislav Mladenov, Warren Parad, Aaron Parecki, + and Rifaat Shekh-Yusef for their valuable feedback on this document. + +Authors' Addresses + + Karsten Meyer zu Selhausen + Hackmanit + Email: karsten.meyerzuselhausen@hackmanit.de + + + Daniel Fett + yes.com + Email: mail@danielfett.de |