Microsoft

mbj@microsoft.com http://self-issued.info/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

Nomura Research Institute, Ltd.

n-sakimura@nri.co.jp http://nat.sakimura.org/

Security OAuth Working Group OAuth Issuer Client ID Audience Discovery State Authorization Server Configuration Information Metadata JavaScript Object Notation JSON JSON Web Token JWT This specification defines an extension to The OAuth 2.0 Authorization Framework that enables the authorization server to dynamically provide the client using it with additional information about the current protocol interaction that can be validated by the client and that enables the client to dynamically provide the authorization server with additional information about the current protocol interaction that can be validated by the authorization server. This additional information can be used by the client and the authorization server to prevent classes of attacks in which the client might otherwise be tricked into using inconsistent sets of metadata from multiple authorization servers, including potentially using a token endpoint that does not belong to the same authorization server as the authorization endpoint used. Recent research publications refer to these as "IdP Mix-Up" and "Malicious Endpoint" attacks.

OAuth 2.0 clients use multiple authorization server endpoints when using some OAuth response types. For instance, when using the code response type, the client uses both the authorization endpoint and the token endpoint. It is important that endpoints belonging to the same authorization server always be used together. Otherwise, information produced by one authorization server could mistakenly be sent by the client to different authorization server, resulting in some of the attacks described in . Recent research publications refer to these specific attacks as "IdP Mix-Up" and "Malicious Endpoint" attacks. The client obviously cannot be confused into using endpoints from multiple authorization servers in an authorization flow if the client is configured to use only a single authorization server. However, the client can potentially be tricked into mixing endpoints if it is configured to use more than one authorization server, whether the configuration is dynamic or static. The client may be confused if it has no way to determine whether the set of endpoints belongs to the same authorization server. Or, a client may be confused simply because it is receiving authorization responses from more than one authorization server at the same redirection endpoint and the client is insufficiently able to determine that the response received is associated with the correct authorization server. This specification enables the authorization server to dynamically provide the client using it with additional information about the current protocol interaction that can be validated by the client and that enables the client to dynamically provide the authorization server with additional information about the current protocol interaction that can be validated by the authorization server. This enables them to abort interactions in which endpoints from multiple authorization servers would otherwise be used. The mitigation data provided by the authorization server to the client is an issuer identifier, which is used to identify the authorization server, and a client ID, which is used to verify that the response is from the correct authorization server and is intended for this client. The issuer identifier is defined in Section 2 of . If supported by the authorization server, the issuer identifier can also be used to obtain a consistent set of metadata describing the authorization server configuration, as also described in . This mitigation data is returned to the client in the authorization response. The syntax for returning the mitigation data from the authorization server is dependent upon the OAuth response type being used. The syntax used with the existing response types registered in the IANA "OAuth Authorization Endpoint Response Types" registry as of the time of this writing is defined by this specification. Two of these response types are defined by RFC 6749; the rest are defined by . The mitigation data provided by the client to the authorization server is the existing state value defined by RFC 6749, but adding also sending it from the client to the token endpoint. This is used by the authorization server to verify that the authorization code and state both belong to the same protocol interaction.

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 RFC 2119.

This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0, the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT).

The OAuth issuer identifier serves as a concrete identifier for the authorization server. As defined in , the issuer identifier is a URL that uses the https scheme and has no query or fragment components. Also as specified there, this is the location where .well-known RFC 5785 resources containing information about the authorization server are published. In particular, when discovery is supported, the authorization server's metadata is retrieved as a JSON document from a path derived from this URL. This metadata document contains a consistent set of metadata describing the authorization server configuration. Implementations supporting this specification MAY also support discovery or they MAY simply use the issuer identifier as a concrete identifier for the authorization server. This specification does not rely upon the authorization server publishing or the client retrieving a discovery metadata document.

Mitigating the attacks relies on the authorization server returning additional data about the interaction and the client checking that data. The mitigation data returned is the client ID and the issuer identifier. The syntax for returning the mitigation data from the authorization server is dependent upon the OAuth response type being used.

Some OAuth response types do not already return the issuer identifier and client ID in the authorization response. When this is the case, the mitigation data is returned as additional OAuth response parameters. These new response parameters are defined for this purpose: Client that this response is intended for. It MUST contain the OAuth 2.0 client ID of the client as its value. Issuer identifier for the authorization server issuing the response. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. As of the time of this writing, these are the existing response types that are registered in the IANA "OAuth Authorization Endpoint Response Types" registry that do not already return the issuer identifier and client ID in the authorization response: code, code token, none, and token. Therefore, the client ID and issuer are returned using the new authorization response parameters when using these response types. To avoid duplication, as discussed in , it is NOT RECOMMENDED to also return them in this manner when the response type already returns these values in the authorization response.

The following example authorization response is to a request that used the code response type. It uses the iss and client_id response parameters to return the mitigation information to the client.

The example successful authorization response follows (with line breaks within lines for display purposes only):

As of the time of this writing, these are the existing response types that are registered in the IANA "OAuth Authorization Endpoint Response Types" registry that already return the issuer identifier and client ID in the authorization response: code id_token, code id_token token, id_token, and id_token token. All of these return these values as the iss (issuer) claim value and as an aud (audience) claim value in a signed ID Token, which is a JSON Web Token , as specified in "OpenID Connect Core 1.0". When using these response types, the client MUST use the client ID and issuer values returned in the ID Token for validating the mitigation data.

The following example authorization response is to a request that used the id_token token response type. It uses the iss and aud claims in the ID Token to return the mitigation information to the client.

The example successful authorization response follows (with line breaks within lines for display purposes only):

Decoding the ID Token in the response will yield the following claims, which includes the mitigation information in the iss and aud claims:

Upon receiving the mitigation data in an authorization response, the client MUST validate that the response was intended for it and that the authorization server metadata that it obtained at client registration time is consistent with the authorization server metadata contained in the metadata referenced by the issuer identifier. The client MUST validate the authorization server configuration as follows: Compare the issuer identifier for the authorization server that the client received when it registered at the authorization server that it made the request to with the issuer value returned in the iss response parameter or the iss claim in the ID Token, depending upon the response type being used. If they do not exactly match, the client MUST NOT proceed with the authorization. Verify that the response is intended for this client by confirming that the client's client identifier for the authorization server the request was made to matches the value of the client_id response parameter or that the client's client identifier is an audience value of the ID Token, depending upon the response type being used. If not, the client MUST NOT proceed with the authorization.

Mitigating the attacks also relies on the client sending additional data about the interaction to the token endpoint, for response types that use it, and the authorization server checking that data. The mitigation data sent is the same state value that is sent in the authorization request and returned in the authorization response. This specification defines the new state token request parameter for passing this additional information. As of the time of this writing, these are the existing response types that are registered in the IANA "OAuth Authorization Endpoint Response Types" registry that use the token endpoint: code, code id_token, code id_token token, and code token. The state value is to be sent in the state token request parameter when using these response types, and any new response types registered that use the token endpoint.

The following example token request is part of a protocol interaction that used the code response type. It uses the state request parameter to send mitigation information to the authorization server.

The example of token request follows (with line breaks within lines for display purposes only):

When the authorization server receives a token request at the token endpoint that contains a value in the state parameter, it MUST validate that the state value received exactly matches the state value previously received in the corresponding authorization request. If the recorded state value and the state value received do not exactly match, the authorization server MUST NOT proceed with the authorization.

The attacks mitigated by this extension are described in detail in "A Comprehensive Formal Security Analysis of OAuth 2.0" and "On the security of modern Single Sign-On Protocols: Second-Order Vulnerabilities in OpenID Connect" . To mitigate these attacks, clients configured to use more than one authorization server should use authorization servers that return issuer and client ID information and should validate that a consistent set of authorization server endpoints are being used when using response types that utilize multiple endpoints. When registering, clients SHOULD NOT allow multiple authorization servers to return the same issuer value, and MUST NOT allow multiple authorization servers to return the same issuer and client ID value pair.

If a protocol is defined to return the same information in multiple locations, this can create an additional attack surface. Knowing that the information is supposed to be the same, recipients will often be lazy and use the information from only one of the locations, not validating that all the supposedly duplicate instances are the same. This can enable attackers to create illegal protocol messages that have different values in the multiple locations and those illegal messages will not be detected or rejected by these lazy recipients. For this reason, if an OAuth profile is being used that returns the mitigation information defined by this specification in one location, it SHOULD NOT also be returned in another. In particular, if a JWT containing the client ID and issuer values is being returned in the authorization response, they SHOULD NOT also be returned as individual authorization response parameters.

OAuth authorization responses are sent as redirects to redirection URIs, with the response parameters typically passed as URI query parameters or fragment values. A "cut-and-paste" attack is performed by the attacker creating what appears to be a legitimate authorization response, but that substitutes some of the response parameter values with values of the attacker's choosing. Sometimes this is done by copying or "cutting" some values out of a legitimate response and replacing or "pasting" some of these values into a different response, the original version of which may have also been legitimate, creating a combination of response values that are not legitimate and that may cause behaviors sought by the attacker. The Code Substitution threat described in Section 4.4.1.13 of is one example of the use of a cut-and-paste attack. A concern with returning the mitigation information as new individual authorization response parameters whose values are not cryptographically bound together is that cut-and-paste attacks against their values will not be detected. A security analysis has not been done of the effects of the new attacks that the use of cut-and-paste against these new values will enable. To prevent replay of the state in another browser instance by an attacker, the state value MUST be tied to the browser instance in a way that cannot be forged by an attacker. Section 4 of provides several examples of how a client can accomplish this. In the replay attack, the attacker can set cookies in the browser. Using an unsigned cookie to bind state to the browser is not sufficient.

This specification registers the following parameters in the IANA "OAuth Parameters" registry established by RFC 6749.

Parameter name: client_id Parameter usage location: Authorization Response Change controller: IESG Specification document(s): of [[ this specification ]] Related information: None Parameter name: iss Parameter usage location: Authorization Response Change controller: IESG Specification document(s): of [[ this specification ]] Related information: None Parameter name: state Parameter usage location: Token Request Change controller: IESG Specification document(s): of [[ this specification ]] Related information: None

Microsoft

mbj@microsoft.com http://self-issued.info/

Nomura Research Institute, Ltd.

n-sakimura@nri.co.jp http://nat.sakimura.org/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

Microsoft Ping Identity Nomura Research Institute, Ltd. Google Google Facebook Microsoft IANA Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce

The authorization server can compare the two state values either by recording the complete state value between the authorization request and the token request, possibly in the same data structure in which the authorization code issued was recorded, or by recording only a cryptographic hash of the state value, possibly resulting in substantial size savings.

Alfred Albrecht, John Bradley, Brian Campbell, Joerg Connotte, William Denniss, Sebastian Ebling, Florian Feldmann, Daniel Fett, Roland Hedberg, Phil Hunt, Ralf Kuesters, Torsten Lodderstedt, Christian Mainka, Vladislav Mladenov, Anthony Nadalin, Justin Richer, Nat Sakimura, Antonio Sanso, Guido Schmitz, Joerg Schwenk, Hannes Tschofenig, and Hans Zandbelt all contributed to the discussions that led to the creation of this specification. This specification is partially based on the OpenID Connect Core 1.0 specification, which was produced by the OpenID Connect working group of the OpenID Foundation.

We need to do a security analysis of the cut-and-paste attacks that may be enabled when mitigation information is returned to the client using individual authorization response parameters.

[[ to be removed by the RFC Editor before publication as an RFC ]] -01 Changed terms "issuer URL" and "configuration information location" to "issuer identifier" so that consistent terminology is used for this. -00 Created the initial working group draft from draft-jones-oauth-mix-up-mitigation-01 with no normative changes and adding Nat Sakimura as an editor.