Troubleshooting: An SP-initiated SAML response was received unexpectedly

[ComponentSpace]

SAML Session State

A SAML session cookie is used to maintain session state in support of the SAML protocol.

By default, the SAML session cookie value is a key into SAML session state stored in the web server’s memory.

The SAML session cookie and associated SAML session state store are implementation details of the SAML library and the application shouldn’t attempt to access or manipulate either.

Unexpected SAML Responses

Often if an “SP-initiated SAML response was received unexpectedly” exception occurs, this is the result of the SAML session state not being present or accessible.

When a SAML authn request is sent, related state information is saved to correctly process the received SAML response.

If this state information isn’t present when a SAML response is received, it cannot be processed correctly and an exception is thrown.

Missing Cookie

The first step to identify the issue is to determine whether the SAML session cookie is included in the HTTP Post of the SAML response.

The default cookie name in SAML for ASP.NET is SAML_SessionId. The default cookie name in SAML for ASP.NET Core is saml-session.

The following examples refer to the saml-session cookie but apply equally to the SAML_SessionId cookie.

Browser Developer Tools

Use the browser developer tools (F12) to capture the network traffic to determine whether the cookie is present and, if not, why the browser didn’t send the cookie.

The following instructions apply to Chrome.

1. Close all instances of the browser to ensure all session cookies are cleared.
2. Open the browser including the browser developer tools (F12).
3. Ensure the Preserve log checkbox is checked.
4. Initiate the SAML SSO sequence.

Network traffic and associated settings are under the Network tab.

HTTP headers are displayed under the Headers tab and cookies are displayed under the Cookies tab.

HTTP Response Cookie

Locate the HTTP response containing the SAML authn request. By default, SAML authn requests are sent using an HTTP 302 redirect to the identity provider’s SSO service endpoint.

Check whether the HTTP response includes a set-cookie header for the SAML session cookie.

For example:

set-cookie: saml-session=2UsHd29ZaXnqpcyYDscw6WheUJ7FQ9vd; path=/; secure; samesite=none; httponly

If this response cookie isn’t present:

1. Ensure the cookie isn’t included as a request cookie. If it is, close all browser instances to clear all session cookies and try again.
2. Ensure there’s no application code or configuration, middleware or network infrastructure preventing the setting of this cookie.

If this response cookie is present:

1. Ensure the domain, if specified, is correct.
2. Ensure the path is correct. The default path is “/”.
3. Ensure the secure flag is specified. This is a requirement of the samesite property and mandates the use of HTTPS.
4. Ensure the samesite property is set to none. This is required as SAML protocol exchanges are cross-site.
5. Ensure the httponly flag is specified.

If any of the set-cookie properties are incorrect, check whether any application code or configuration, middleware or network infrastructure is overriding these properties.

HTTP Request Cookie

Locate the HTTP request containing the SAML response. By default, SAML responses are sent using an HTTP Post to the service provider’s assertion consumer service endpoint.

Check whether the HTTP request includes a cookie header for the SAML session cookie.

For example:

cookie: saml-session=2UsHd29ZaXnqpcyYDscw6WheUJ7FQ9vd

If the cookie is present with the show filtered out request cookies checkbox unchecked, the cookie is working correctly.

If the cookie is present only with the show filtered out request cookies checkbox checked, the browser isn’t sending the cookie.

If this is the case, locate the information icon in the SAML session cookie row.

In the following example, this icon is in the SameSite column.

Hover over this icon to display the reason for the browser not sending the cookie.

In this example, the cookie was set with samesite set to strict rather than the required none.

If the cookie has been filtered out:

1. Update the set-cookie properties as required.

If the cookie is not present, even if the show filtered out request cookies checkbox is checked:

1. Update the set-cookie properties as required. In some cases, the browser developer tools won’t show the cookie even when the show filtered out request cookies checkbox is checked.
2. Ensure the application code or configuration, middleware or network infrastructure isn’t expiring the cookie.

Common Issues

1. Attempting SSO over HTTP rather than HTTPS.
2. Cookie policy that prevents SameSite=None being specified.
3. Different host names for the same application (e.g. sp.com vs www.sp.com).

Exporting HAR Files

If the cause of a missing cookie cannot be determined, we may ask you to email the exported HAR file as an email attachment.

Make sure to Export HAR (with sensitive data). The sensitive data includes the cookies.

The HAR will be treated as confidential information.

Missing Session State

If the SAML session cookie is present but the SAML response is unexpected, it’s possible the SAML session state is not present. By default, SAML session state is stored in the web server’s memory.

The most common scenario is a multi-server environment where SSO is initiated on one web server but the SAML response is processed on another web server.

If this is the case, either sticky sessions must be configured in the load balancer or the SAML session state must be stored in a central repository, such as a database, that’s accessible to all the web servers.

Although less likely, another possibility is that the web application restarted which caused the SAML session state memory to be cleared.