|Meyer zu Selhausen & Fett||Expires 5 June 2022||[Page]|
- Web Authorization Protocol
- Intended Status:
- Standards Track
OAuth 2.0 Authorization Server Issuer Identification
This document specifies a new parameter
iss that 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".¶
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 5 June 2022.¶
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 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.¶
The OAuth 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 which 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 the OAuth Security Best Current Practice [I-D.ietf-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 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 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] and the term "issuer identifier" defined by OAuth 2.0 Authorization Server Metadata [RFC8414].¶
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.¶
iss parameter value is the issuer identifier of the authorization server which 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.¶
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¶
Authorization servers supporting this specification MUST provide their issuer identifier to enable clients to validate the
iss parameter effectively.¶
The issuer identifier included in the server's metadata value
issuerMUST be identical to the
Authorization servers MAY additionally provide the issuer identifier to clients by any other mechanism which is outside of the scope of this specification.¶
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 [RFC6749], Appendix B, 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 which do support the parameter according to the client's configuration. Clients SHOULD discard authorization responses with the
iss parameter from authorization servers which 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 which 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.¶
Note: The "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)" [JARM] defines a mechanism that conveys all authorization response parameters in a 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.¶
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.¶
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 which 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 [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 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. 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 response mode are used, for example. 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.¶
- Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.
- Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
- Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
- Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
- 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-18, , <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-18>.
- Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
- Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
- Mainka, C., Mladenov, V., and J. Schwenk, "On the security of modern Single Sign-On Protocols: Second-Order Vulnerabilities in OpenID Connect", , <https://arxiv.org/abs/1508.04324>.
- Fett, D., Kuesters, R., and G. Schmitz, "A Comprehensive Formal Security Analysis of OAuth 2.0", , <https://arxiv.org/abs/1601.01229>.
- Lodderstedt, T. and B. Campbell, "Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)", , <https://openid.net/specs/openid-financial-api-jarm.html>.
- 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, , <https://www.rfc-editor.org/info/rfc7591>.
- IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
- Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", , <https://openid.net/specs/openid-connect-core-1_0.html>.
- Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)", RFC 9101, DOI 10.17487/RFC9101, , <https://www.rfc-editor.org/info/rfc9101>.
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.¶
[[ To be removed from the final specification ]] -04 [[ Working Group Draft ]] * Incorporated feedback from Lars Eggert * Incorporated feedback from Francesca Palombini (IANA registrations) * Incorporated feedback from Benjamin Kaduk -03 [[ Working Group Draft ]] * Incorporated feedback from AD review * Incorporated feedback from artart and secdir reviews -02 [[ Working Group Draft ]] * Incorporated feedback from shepherd review * Changed SHOULD to MUST (clients MUST store which AS support `iss` parameter) * Added note for clients receiving unexpected `iss` parameter * Editorial changes -01 [[ Working Group Draft ]] * Incorporated WG feedback * Changed title of the draft to make it shorter * Clarified mix-up attacks in introduction * Improved note on JARM in validation section -00 [[ Working Group Draft ]] * Working group draft -02 * Incorporated WG feedback * Clarifications for unique issuer identifier * Clarifications when multiple issuer identifier could be present * Added note that iss parameter MUST NOT be used with JARM * Added note on error responses and example for error response * Editorial changes -01 * Incorporated first WG feedback * Clarifications for use with OIDC * Added note that clients supporting just one AS are not vulnerable * Renamed metadata parameter * Various editorial changes -00 * initial draft¶