OAuth 2.0 Mix-Up Mitigation
draft-jones-oauth-mix-up-mitigation-00

Abstract

This specification defines an extension to The OAuth 2.0 Authorization Framework that enables an authorization server to provide a client using it with a consistent set of metadata about itself. This information is returned in the authorization response. It can be used by the client 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.

Status of This Memo

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 http://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 July 13, 2016.

Copyright Notice

Copyright (c) 2016 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 (http://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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 1.1. Requirements Notation and Conventions
• 1.2. Terminology
• 2. The OAuth Issuer
• 3. Methods of Returning Mitigation Data
• 3.1. Mitigation Data Returned in JWT
• 3.2. Mitigation Data Returned in Authorization Response Parameters
• 4. Validating the Response
• 5. JWT Contents
• 6. JWT Validation
• 7. Compatibility Notes
• 8. Security Considerations
• 8.1. IdP Mix-Up and Malicious Endpoint Attacks
• 8.2. Cut-and-Paste Attacks
• 8.3. Duplicate Information Attacks
• 9. IANA Considerations
• 9.1. OAuth Parameters Registration
• 9.1.1. Registry Contents
• 10. References
• 10.1. Normative References
• 10.2. Informative References
• Appendix A. Acknowledgements
• Appendix B. Open Issues
• Appendix C. Document History
• Author's Address

1. Introduction

OAuth 2.0 [RFC6749] clients use multiple authorization server endpoints when using some response types. For instance, when using the code response type, a 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 attacks described in Section 8. Recent research publications refer to these as "IdP Mix-Up" [arXiv.1601.01229v2] and "Malicious Endpoint" [arXiv.1508.04324v2] 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 provides a means for the authorization server to provide information to the client that enables it to verify that all endpoints being used belong to the same authorization server, and to abort interactions in which endpoints from multiple authorization servers would otherwise be used.

The mitigation data provided is an issuer URL, which is used to obtain a consistent set of metadata describing the authorization server configuration, and a client ID, which is used to verify that the response is from the correct authorization server and is intended for this client. Both the issuer URL and the discovery metadata are defined in Section 3 of [OAuth.Discovery]. Means of returning the mitigation data from the authorization server and of the client using the mitigation data to validate the OAuth interaction are defined by this specification.

1.1. Requirements Notation and Conventions

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 [RFC2119].

1.2. Terminology

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 [RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [JWT].

2. The OAuth Issuer

As defined in [OAuth.Discovery], the OAuth issuer is the URL of the authorization server's configuration information location, which uses the https scheme and has no query or fragment components. Also as specified there, when discovery is supported, the authorization server's metadata is retrieved as a JSON document [RFC7159] from the path formed by concatenating the string /.well-known/openid-configuration to the configuration information location. An authorization server supporting this specification MUST supply a metadata document at this location. This metadata document contains a consistent set of metadata describing the authorization server configuration. As described in Section 7, despite the identifier /.well-known/openid-configuration, appearing to be OpenID-specific, its usage in this specification is actually referring to a general OAuth 2.0 feature that is not specific to OpenID Connect [OpenID.Core].

3. Methods of Returning Mitigation Data

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 URL. There are two ways that this data can be returned in the authorization response: as claims in a JWT [JWT] signed by the authorization server or as additional authorization response parameters. These alternatives are discussed below.

3.1. Mitigation Data Returned in JWT

One method of returning the mitigation data is as claims in a JWT [JWT] signed by the authorization server. The issuer is returned as the iss (issuer) claim value. The client ID is returned as an aud (audience) claim value. The JWT is signed using a key contained in the authorization server's JWK Set [JWK] document, which is referenced using the authorization server's jwks_uri metadata value. The JWT is returned using the id_token response parameter registered in the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters] by OpenID Connect [OpenID.Core]. The required claims in this JWT are described in Section 5. Section 6 describes how to validate the contents of the JWT.

The advantage of this method is that the mitigation data values are cryptographically tied to the authorization server by the JWT signature, preventing "cut-and-paste" attacks, which are described in Section 8.2. However, this does require both the authorization server and the client to support JWTs and their underlying cryptographic functions, which may not be workable in all deployments.

Note that like its usage in OpenID Connect, this JWT identifies the authorization server using the iss (issuer) claim and the client using the aud (audience) claim. However, while returning these values in this manner is intentionally compatible with OpenID Connect, and specifically, OpenID Connect ID Tokens, OpenID Connect adds additional required claims to the JWT so that it also identifies a subject. These additional claims are not required for the use defined by this specification. The good news is that for OAuth implementations that also implement OpenID Connect, this JWT is already being returned as the ID Token for flows that return an ID Token in the authorization response.

3.2. Mitigation Data Returned in Authorization Response Parameters

Another method of returning the mitigation data is as additional OAuth response parameters. These new response parameters are defined for this purpose:

client_id

Client that this response is intended for. It MUST contain the OAuth 2.0 client ID of the client as its value.

iss

Issuer URL 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.

The advantage of this method is that it requires no JWT or cryptographic support from the participants. The disadvantage of this method is that it is subject to "cut-and-paste" attacks, which are described in Section 8.2. This method is to be used only if returning the mitigation data in a signed JWT is not feasible.

4. Validating the Response

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 configuration information that it obtained at client registration time is consistent with the authorization server configuration information contained in the metadata referenced by the issuer URL.

The client MUST validate the authorization server configuration as follows:

1. Verify that the response is intended for this client by confirming that the client's client identifier is an audience value of the JWT or that the client's client identifier matches the value of the client_id response parameter. If not, the client MUST NOT proceed with the authorization.
2. Compare the issuer URL for the authorization server that the client used when it was registered with the issuer value returned in the iss claim or the iss response parameter. If they match, retrieving the authorization server metadata and using it, as described in steps 3-6, can be skipped.
3. Retrieve the authorization server metadata as a JSON document from the path formed by concatenating the string /.well-known/openid-configuration to the issuer URL.
4. Confirm that the issuer metadata value exactly matches the issuer URL returned by the authorization server. If not, the client MUST NOT proceed with the authorization.
5. If the response type being used uses a token endpoint, confirm that the token_endpoint metadata value exactly matches the token endpoint value obtained at registration time. If not, the client MUST either use the token endpoint specified in the retrieved metadata or not proceed with the authorization.
6. If the authorization flow will use other endpoints or information obtained at registration time, confirm that the corresponding metadata values exactly match the values obtained at registration time. If not, the client MUST either use the values specified in the retrieved metadata or not proceed with the authorization.
7. Verify that the client ID is associated with the authorization server identified by the issuer. If not, the client MUST NOT proceed with the authorization.
8. If the issuer URL was returned in a JWT, as described in Section 3.1 and Section 5, then validate the contents of the JWT as described in Section 6.

Note that if the issuer URLs in step 2 do not match, this could either be because an attacker is attempting to confuse the client into using the wrong endpoints or because the authorization server is multi-tenant and the issuer URL refers to tenant-specific authorization server information. In either case, in the event of a mismatch, the client should use the authorization server metadata values retrieved using the issuer URL rather than the values obtained at registration time to ensure that endpoints from multiple authorization servers aren't being used in the same interaction.

5. JWT Contents

When the mitigation data is returned in a JWT, as described in Section 3.1, the JWT includes the following claims:

iss

REQUIRED. Issuer URL 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.

aud

REQUIRED. Audience(s) that this response is intended for. It MUST contain the OAuth 2.0 client ID of the client as an audience value. It MAY also contain identifiers for other audiences.

at_hash

Access token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the JWT's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url-encode them. The at_hash value is a case-sensitive string.

If the JWT is issued from the authorization endpoint with an access_token value, which is the case for the response_type value token, this is REQUIRED; otherwise, it should not be included.

c_hash

Code hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the JWT's JOSE Header. For instance, if the alg is HS512, hash the code value with SHA-512, then take the left-most 256 bits and base64url-encode them. The c_hash value is a case-sensitive string.

If the JWT is issued from the authorization endpoint with a code value, which is the case for the response_type value code, this is REQUIRED; otherwise, it should not be included.

The JWT MAY contain other claims. Any claims used that are not understood MUST be ignored.

The JWT MUST be signed and optionally both signed and then encrypted, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality. If the JWT is encrypted, it MUST be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The JWT MUST NOT use none [JWA] as the alg value.

The JWT SHOULD NOT use the JWS [JWS] or JWE [JWE] x5u, x5c, jku, or jwk Header Parameter fields. Instead, references to keys used are communicated using the OAuth Discovery [OAuth.Discovery] jwks_uri metadata value.

The following is a non-normative example of the set of claims (the JWT Claims Set) in the JWT:

  {
   "iss": "https://server.example.com",
   "aud": "s6BhdRkqt3",
   "c_hash": "LDktKdoQak3Pk0cnXxCltA"
  }

6. JWT Validation

When the issuer URL is returned in a JWT, as described in Section 3.1, the client MUST perform the following validation steps:

1. If the JWT is encrypted, decrypt it using the keys and algorithms that the client specified during registration that the authorization server was to use to encrypt the JWT. If encryption was negotiated with the authorization server at registration time and the JWT is not encrypted, the RP SHOULD reject it.
2. The issuer URL for the authorization server MUST exactly match the value of the iss (issuer) claim.
3. The client MUST validate that the aud (audience) claim contains its client ID value registered at the issuer identified by the iss (issuer) claim as an audience. The JWT MUST be rejected if the JWT does not list the client as a valid audience, or if it contains additional audiences not trusted by the client.
4. The alg value SHOULD be the default of RS256 or the algorithm registered by the client as the id_token_signed_response_alg registration metadata value, which was registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591] by the "OpenID Connect Dynamic Client Registration 1.0" [OpenID.Registration] specification.
5. Validate the JWT signature. If the JWT alg Header Parameter uses a MAC based algorithm such as HS256, HS384, or HS512, the octets of the UTF-8 [RFC3629] representation of the client_secret corresponding to the client_id contained in the aud (audience) claim are used as the key to validate the signature. For MAC based algorithms, the behavior is unspecified if the aud is multi-valued. Otherwise, use a key obtained via the jwks_uri metadata value.
6. If the response type being used returns an access token in the authorization response, hash the octets of the ASCII representation of the access_token with the hash algorithm specified for the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, the hash algorithm used is SHA-256. Take the left-most half of the hash and base64url-encode it. The value of at_hash in the ID Token MUST match the value produced in the previous step.
7. If the response type being used returns an authorization code in the authorization response, hash the octets of the ASCII representation of the code with the hash algorithm specified for the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, the hash algorithm used is SHA-256. Take the left-most half of the hash and base64url-encode it. The value of c_hash in the ID Token MUST match the value produced in the previous step.

7. Compatibility Notes

The identifiers /.well-known/openid-configuration and id_token contain strings referring to the OpenID Connect family of specifications that were originally defined by "OpenID Connect Core 1.0" [OpenID.Core] and "OpenID Connect Discovery 1.0" [OpenID.Discovery]. Despite the reuse of these identifiers that appear to be OpenID-specific, their usage in this specification is actually referring to general OAuth 2.0 features that are not specific to OpenID Connect.

By design, OpenID Connect ID Tokens are compatible with the JWTs defined by this specification that are returned from the authorization server containing the mitigation data. OpenID Connect already returns a JWT compatible with the one specified in Section 3.1 when using the response type [OAuth.Responses] values id_token, code id_token, id_token token, or code id_token token.

8. Security Considerations

8.1. IdP Mix-Up and Malicious Endpoint Attacks

The attacks mitigated by this extension are described in detail in "A Comprehensive Formal Security Analysis of OAuth 2.0" [arXiv.1601.01229v2] and "On the security of modern Single Sign-On Protocols: Second-Order Vulnerabilities in OpenID Connect" [arXiv.1508.04324v2]. 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.

8.2. Cut-and-Paste Attacks

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 [RFC6819] is one example of the use of a cut-and-paste attack.

Cut-and-paste attacks can be detected and prevented if the values of the parameters are cryptographically bound together because modifications to the values caused by the "pasting" can then be detected. For example, the c_hash and at_hash claims described in Section 5 respectively enable detection of attempts to substitute different authorization code and access token values into an authorization response.

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. Until such an analysis has been done and unless it reaches the conclusion that no bad effects can result, it would seem significantly safer to use the signed JWT method, since it is immune to this attack.

8.3. Duplicate Information Attacks

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.

9. IANA Considerations

9.1. OAuth Parameters Registration

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

9.1.1. Registry Contents

• Parameter name: client_id
• Parameter usage location: Authorization Response
• Change controller: IESG
• Specification document(s): Section 3.2 of [[ this specification ]]
• Related information: None

• Parameter name: iss
• Parameter usage location: Authorization Response
• Change controller: IESG
• Specification document(s): Section 3.2 of [[ this specification ]]
• Related information: None

10. References

10.1. Normative References

10.2. Informative References

Appendix A. Acknowledgements

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.

Appendix B. Open Issues

• Should we also describe mechanisms for binding the session of the authorization request to the authorization response here? Possible mechanisms include the use of nonce request parameter and claim, as defined by OpenID Connect, and/or the use of a state hash value. Adding this would enable implementers to have a comprehensive description of all the mitigation mechanisms and validation procedures in one place.
• For response types that do not return an ID Token in the authorization response, how should the mitigation information be returned, by default?
• We need to do a security analysis of cut-and-paste attacks involving the use of the mitigation information to determine whether there are situations in which it is acceptably safe to return it as individual authorization response parameters whose values are not cryptographically bound together or whether the signed JWT return method needs to always be used to return the mitigation data.

Appendix C. Document History

[[ to be removed by the RFC Editor before publication as an RFC ]]

-00

• Created the initial version.

Author's Address