OAuth 2.0 Authorization Server Issuer IdentificationHackmanitkarsten.meyerzuselhausen@hackmanit.deyes.commail@danielfett.de
Security
Web Authorization Protocolsecurityoauth2This 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
.
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
() 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
. Introduction
. Conventions and Terminology
. Response Parameter iss
. Example Authorization Response
. Example Error Response
. Providing the Issuer Identifier
. Validating the Issuer Identifier
. Authorization Server Metadata
. Security Considerations
. IANA Considerations
. OAuth Authorization Server Metadata
. OAuth Parameters Registration
. References
. Normative References
. Informative References
Acknowledgements
Authors' Addresses
IntroductionThe OAuth 2.0 Authorization Framework 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 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 .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 of "OAuth 2.0 Security Best Current Practice" 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" and "A Comprehensive Formal Security Analysis of OAuth 2.0" .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" .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
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 . The term "issuer identifier" is defined by OAuth 2.0 Authorization Server Metadata .Response Parameter issIn 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 . Its value MUST be a URL that uses the "https" scheme without any query or fragment components.Example Authorization ResponseThe 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
Example Error ResponseThe 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
Providing the Issuer IdentifierAuthorization 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 , the following rules apply:
The issuer identifier included in the server's metadata value issuerMUST 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 , 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.Validating the Issuer IdentifierClients 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 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 . 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 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 ).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 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. already mandates that clients that do not support this specification MUST ignore the unrecognized iss parameter.Authorization Server MetadataThe following parameter for the authorization server metadata 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 . If omitted, the default value is false.
Security ConsiderationsClients MUST validate the iss parameter precisely as described in 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 . 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 ) 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 , 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 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.IANA ConsiderationsOAuth Authorization Server MetadataIANA has registered the following value in the "OAuth Authorization Server Metadata" registry of established by .
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):
of RFC 9207
OAuth Parameters RegistrationIANA has updated the iss entry to appear as follows in the "OAuth Parameters" registry of established by .
Parameter name:
iss
Parameter usage location:
authorization request, authorization response
Change Controller:
IETF
Specification Document(s):
of RFC 9207, , and .
ReferencesNormative ReferencesKey words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Uniform Resource Identifier (URI): Generic SyntaxA Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK]The OAuth 2.0 Authorization FrameworkThe OAuth 2.0 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 1.0 protocol described in RFC 5849. [STANDARDS-TRACK]Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.OAuth 2.0 Authorization Server MetadataThis specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities.Informative ReferencesOn the security of modern Single Sign-On Protocols: Second-Order Vulnerabilities in OpenID ConnectRuhr University BochumRuhr University BochumRuhr University BochumA Comprehensive Formal Security Analysis of OAuth 2.0University of TrierUniversity of TrierUniversity of TrierOAuth ParametersIANAFinancial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)YesPingOAuth 2.0 Security Best Current Practiceyes.comYubicoIndependent Researcheryes.com This document describes best current security practice for OAuth 2.0.
It updates and extends the OAuth 2.0 Security Threat Model to
incorporate practical experiences gathered since OAuth 2.0 was
published and covers new threats relevant due to the broader
application of OAuth 2.0.
Work in ProgressOpenID Connect Core 1.0 incorporating errata set 1NRIPing IdentityMicrosoftGoogleSalesforceJSON Web Token (JWT)JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.OAuth 2.0 Dynamic Client Registration ProtocolThis specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration.The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)The authorization request in OAuth 2.0 described in RFC 6749 utilizes query parameter serialization, which means that authorization request parameters are encoded in the URI of the request and sent through user agents such as web browsers. While it is easy to implement, it means that a) the communication through the user agents is not integrity protected and thus, the parameters can be tainted, b) the source of the communication is not authenticated, and c) the communication through the user agents can be monitored. Because of these weaknesses, several attacks to the protocol have now been put forward.This document introduces the ability to send request parameters in a JSON Web Token (JWT) instead, which allows the request to be signed with JSON Web Signature (JWS) and encrypted with JSON Web Encryption (JWE) so that the integrity, source authentication, and confidentiality properties of the authorization request are attained. The request can be sent by value or by reference.AcknowledgementsWe would like to thank
,
,
,
,
,
,
,
,
,
,
and
for their valuable feedback on this document.Authors' AddressesHackmanitkarsten.meyerzuselhausen@hackmanit.deyes.commail@danielfett.de