Internet-Draft oauth-iss-auth-resp October 2020
Meyer zu Selhausen & Fett Expires 29 April 2021 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-meyerzuselhausen-oauth-iss-auth-resp-00
Published:
Intended Status:
Standards Track
Expires:
Authors:
K. Meyer zu Selhausen
Hackmanit
D. Fett
yes.com

OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response

Abstract

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 grant. If implemented correctly, the iss parameter serves as an effective countermeasure to "mix-up" 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 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 29 April 2021.

Table of Contents

1. Introduction

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 [RFC6479] 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. The lack of certainty about the origin of the response benefits a class of attacks called "mix-up attacks".

This type of attack is a 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. There are multiple ways in which an attacker can gain control over an authorization server supported by the client: For example, an authorization server could become compromised, or the attacker could register their own authorization server if the client supports multiple authorization servers and dynamic client registration ([RFC7591]).

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 Practices [I-D.ietf-oauth-security-topics].

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. Therefore, the implementation of the iss parameter serves as an effective countermeasure to mix-up attacks.

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

2. Response Parameter iss

In authorization responses to the client, 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 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. If the authorization server provides metadata as defined in [RFC8414], the value of the parameter iss MUST be identical to the authorization server metadata value issuer.

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 for display purposes only):

HTTP/1.1 302 Found
Location: https://client.example/cb?
  code=x1848ZT64p4IirMPT0R-X3141MFPTuBX-VFL_cvaplMH58
  &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI
  &iss=https://honest.as.example

2.2. Providing the Issuer Identifier iss

Authorization 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 [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 iss_parameter_supported, defined in Section 3, 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.

2.3. Validation of the Issuer Identifier iss

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 compare the extracted and URL-decoded value 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.

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 SHOULD store the information which 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.

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. This decision is individual for every scenario and it is not in the scope of this specification.

Section 4.1.2. of [RFC6479] already mandates that clients that do not support this specification MUST ignore the unrecognized iss parameter.

3. Authorization Server Metadata

The following parameter for the authorization server metadata [RFC8414] is introduced to signal the authorization server's support for this specification:

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

The authorization response parameter iss defined in this specification serves as a countermeasure for "mix-up" attacks described in Section 4.4. of the OAuth Security Best Current Practices [I-D.ietf-oauth-security-topics] and in detail in "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]. The latter provides a formal proof of the effectiveness of the countermeasure.

Clients MUST validate the iss parameter precisely as described in Section Section 2.3 and MUST NOT allow multiple authorization servers to return the same issuer identifier during registration.

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 ([OIDC.Core]). When OAuth metadata is used, the iss parameter identifes 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 "JWT Secured Authorization Response Mode for OAuth 2.0 (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 for "mix-up" attacks. For example, the authorization server's issuer identifier is included in ID Tokens in OpenID Connect [OIDC.Core]. This inclusion enables clients to use an ID Token in the same way as the iss parameter when an ID Token is returned in the authorization response. These alternative countermeasures are outside of the scope of this specification.

5. IANA Considerations

5.1. OAuth Authorization Server Metadata

This specification requests registration of the following values in the IANA "OAuth Authorization Server Metadata" registry of [IANA.OAuth.Parameters] established by [RFC8414].

Metadata Name:

iss_parameter_supported

Metadata Description:

Boolean value indicating whether the authorization server provides the iss parameter in the authorization response.

Change Controller:

IESG

Specification Document(s):

Section 3 of [[ this document ]]

5.2. OAuth Parameters Registration

This specification requests registration of the following values in the IANA "OAuth Parameters" registry of [IANA.OAuth.Parameters] established by [RFC6749].

Parameter name:

iss

Parameter usage location:

authorization response

Change Controller:

IESG

Specification Document(s):

Section 2 of [[ this document ]]

6. Acknowledgements

TBD

7. Normative References

[IANA.OAuth.Parameters]
IANA, "OAuth Parameters", <http://www.iana.org/assignments/oauth-parameters>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC2119]
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>.
[RFC8414]
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>.
[RFC3986]
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>.
[RFC6479]
Zhang, X. and T. Tsou, "IPsec Anti-Replay Algorithm without Bit Shifting", RFC 6479, DOI 10.17487/RFC6479, , <https://www.rfc-editor.org/info/rfc6479>.
[I-D.ietf-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-16, , <https://tools.ietf.org/html/draft-ietf-oauth-security-topics-16>.
[RFC8174]
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>.

8. Informative References

[arXiv.1601.01229]
Fett, D., Kuesters, R., and G. Schmitz, "A Comprehensive Formal Security Analysis of OAuth 2.0", , <https://arxiv.org/abs/1601.01229>.
[JARM]
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>.
[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, , <https://www.rfc-editor.org/info/rfc7591>.
[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", , <http://arxiv.org/abs/1508.04324>.
[OIDC.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", , <http://openid.net/specs/openid-connect-core-1_0.html>.

Appendix A. Document History

[[ To be removed from the final specification ]]

-00

*  initial draft

Authors' Addresses

Karsten Meyer zu Selhausen
Hackmanit
Daniel Fett
yes.com