RFC 9207

OAuth 2.0 Authorization Server Issuer Identification

📅 published March 2022, from ietf

OAuth 2.0 Authorization Server Issuer Identification 🎀

Okay bestie, this is RFC 9207 💖 It's a Standards Track document from the IETF, dated March 2022. The authors are K. Meyer zu Selhausen (Hackmanit) and D. Fett (yes.com), and the ISSN is 2070-1721. The header doesn't list any RFC that this one obsoletes or updates ✨

Abstract

This document specifies a new parameter called iss 🦋 It explicitly includes the issuer identifier of the authorization server in the authorization response of an OAuth authorization flow. The iss parameter is an effective countermeasure to "mix-up attacks" 🔥

Status of This Memo

Okay, the status is that this is an Internet Standards Track document 💅

It's a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, received public review, and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841 🌸

Info about the current status, any errata, and how to give feedback lives at https://www.rfc-editor.org/info/rfc9207 🧚

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. Please review these documents carefully, because they describe your rights and restrictions for 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 they're 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 ✨

Okay, so the OAuth 2.0 Authorization Framework [RFC6749] lets clients talk to multiple independent authorization servers that are controlled by separate entities 🌈 Some OAuth grant types use the resource owner's user agent to deliver the authorization server's response to the OAuth client. The authorization response of the authorization code grant is one example of this pattern 💖

Here's the tea 🫖 The authorization response in Section 4.1.2 of [RFC6749] doesn't say anything about which authorization server issued it. So a client that gets a response from the resource owner's user agent can't be sure who originally issued the response, or the secrets inside it. That lack of certainty about where the response came from is what enables a class of attacks called "mix-up attacks" 😭

Mix-up attacks are a potential threat to every OAuth client that works with multiple authorization servers. If at least one of those servers is under an attacker's control, the attacker can launch a mix-up attack to grab authorization codes or access tokens issued by any of the other authorization servers. There are several ways an attacker could gain control over an authorization server the client supports. For example, an authorization server could get compromised, or the attacker could register their own authorization server, say through dynamic client registration [RFC7591] 👀

OAuth clients that only interact with one authorization server aren't vulnerable to mix-up attacks. BUT, if those clients decide to add support for a second authorization server later, they become vulnerable and need to apply countermeasures to mix-up attacks 🚨

The goal of a mix-up attack is to steal an authorization code or access token by tricking the client into sending it to the attacker instead of the honest authorization or resource server. This is a severe threat to the confidentiality and integrity of resources whose access is managed with OAuth 💀 A detailed description and the 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]. You can also check the original research that first highlighted 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 🦋 It lets the authorization server include its identity in the response explicitly. The client can compare the value of iss to the issuer identifier of the authorization server it believes it's talking to (for example, the one retrieved from its metadata). That gives the client certainty about the authorization server's identity, so it can send credentials like 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 spec uses the terms "access token", "authorization code", "authorization code grant", "authorization server", "resource server", "authorization response", "grant type", and "client", all 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. No skipping this one, bestie 🚫

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 and has no 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 just for display 🙈)

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

Here's an error response from that same authorization server. (Extra line breaks and indentation are again just for display 💜)

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 so clients can validate the iss parameter effectively. Non-negotiable 💅

For authorization servers that publish 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. That's outside the scope of this specification ✨

2.4. Validating the Issuer Identifier 🔍✨

Okay so, bestie, this is the part where clients have to be super careful about the iss value 💅. Clients that support this spec MUST pull out the iss value from authorization responses they get, if it's there 🎀. Then they MUST decode it from its "application/x-www-form-urlencoded" form using Appendix B of [RFC6749] 🦋, and compare the result to the issuer identifier of the authorization server the request was sent to. That comparison MUST use simple string comparison from Section 6.2.1 of [RFC3986] 🌸. If the value doesn't match, clients MUST reject the authorization response and MUST NOT go on with the authorization grant 🙈. And for error responses? Clients MUST NOT assume the error came from the server they meant to talk to 😭.

More precisely, clients that work with authorization servers supporting OAuth metadata [RFC8414] MUST compare the iss value to the issuer value in the server's metadata document 🧚. If OAuth metadata isn't used, clients MUST use deployment-specific stuff (like a static configuration) to decide if the returned iss value is the expected one in the current flow (see also Section 4) 💜.

If clients talk to both authorization servers that support this spec and ones that don't, clients MUST keep state about whether each authorization server supports the iss parameter 👑. Clients MUST reject authorization responses without the iss parameter from servers that do support it, according to the client's configuration 💀. Clients SHOULD discard authorization responses that have the iss parameter from servers that don't indicate support for it 🫶. Still, there might be legit servers that send iss without saying so in their metadata ✨. Local policy or configuration can decide whether to accept those responses, and specific guidance is out of scope for this spec 🌈.

In general, clients that support this spec MAY accept authorization responses without the iss parameter, or they can reject them and only support servers that include iss in the authorization response 🍓. Local policy or configuration can decide when to accept such responses, and specific guidance is out of scope for this spec 🔥.

In OpenID Connect [OIDC.Core] flows where an ID Token comes back 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 says that clients that don't support this spec MUST ignore the unrecognized iss parameter 🦋.

📝 Note: The "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)" [JARM] defines a mechanism that carries all authorization response parameters in a JSON Web Token (JWT) 🎀. This JWT has an iss claim that gives the same protection if it's validated as described in Section 2.4 💖. So an extra iss parameter outside the JWT isn't 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 spec 🧚:

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 🔐💀

Okay this section is SERIOUS, bestie 😭. 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 lets a client decide if an authorization server "expects" to be used in an OAuth flow together with a certain token endpoint and maybe other endpoints, like the userinfo endpoint [OIDC.Core] 🦋. When OAuth metadata is used, the iss parameter identifies the issuer, and therefore the OAuth metadata document that points to the other endpoints 🧚. When OAuth metadata isn't used, the client can use, for example, a statically configured expected iss value for each configured authorization server 🌸.

The issuer identifier in the authorization response is NOT cryptographically protected against tampering. Hmm, wait, let me be precise: it is not cryptographically protected against tampering 🙈. In general, mechanisms like 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 the client receives it, the attacker would also have direct access to the authorization code 😱. The attacker doesn't need to run a mix-up attack to steal the authorization code 💀. So 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 gets an authorization response that contains multiple issuer identifiers, the client MUST reject the response if these issuer identifiers don't match 🔥. The details of alternative countermeasures are outside the scope of this spec 🦋.

Mix-up attacks only matter for clients that talk to multiple authorization servers 🧚. But clients that only talk to one authorization server might add support for a second one later 👀. Once they support 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

📦 where this page comes from

ietf: rfc9207 2022-03
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms