twobotechnologies

Federation · Identity & access management · 6 min read

SAML Response Errors: How to Debug and Fix SSO Failures

Short answer

Most SAML SSO failures come from a handful of mismatches between what the identity provider sends and what the service provider expects: a non-success status, a signature made with a rotated certificate, an Audience or Recipient URL that differs by a character, a stale InResponseTo, clock skew on NotBefore and NotOnOrAfter, or a NameID in the wrong format; decode the response and compare each field against the service provider's configuration.

Key takeaways

  • Start by decoding the SAMLResponse and reading the StatusCode; a non-success status means the IdP refused, and the SP settings are not the problem.
  • Certificate rollovers are the most common cause of sudden, total SSO outages; check which certificate signed the response.
  • Audience must match the SP entity ID exactly, and Recipient and Destination must match the ACS URL exactly, including scheme, host, path and trailing slash.
  • InResponseTo errors usually mean a lost session, an IdP-initiated login the SP doesn't allow, or a reused response.
  • Allow only a small clock skew, and fix server time with NTP rather than widening the window.

A SAML login fails and the service provider shows a one-line error, or just sends the user back to the login page. The identity provider's logs say it issued a response. Somewhere between the two, a value didn't match. The good news is that SAML failures fall into a short list of causes, and almost all of them can be found by reading the response the browser carried. This article goes through them in the order worth checking.

How do you capture and read a SAML response?

Open the browser's network tools, find the POST to the service provider's ACS URL, copy the SAMLResponse field and base64-decode it.

With the usual HTTP-POST binding, the identity provider returns an HTML form that the browser posts to the service provider's Assertion Consumer Service (ACS) URL. The SAMLResponse field is base64-encoded XML. Messages sent with the HTTP-Redirect binding, which is common for requests, are also DEFLATE-compressed before encoding.

The Twobo SAML decoder does the decoding in your browser and lays out the fields this article refers to. Use a test account where you can, since real responses contain personal data.

What does the status code tell you?

If the StatusCode is not Success, the identity provider refused the login, and the fix is on the IdP side.

Look at <samlp:Status> first. A value ending in :Success means the IdP authenticated the user and issued an assertion. Anything else, such as Requester, Responder, AuthnFailed or NoPassive, tells you the IdP declined. Common reasons are a user not assigned to the application, a policy blocking the login, or a request asking for an authentication context the IdP can't satisfy. Changing SP settings won't help until the IdP returns Success.

Is the signature valid, and with which certificate?

Check which certificate signed the response or assertion and whether the service provider trusts it, because certificate rollovers cause most sudden, total outages.

When SSO breaks for every user at the same moment, suspect the signing certificate. Identity providers rotate signing certificates on a schedule or after an incident, and a service provider that pinned the old one rejects every response.

Compare the certificate in the response's <ds:X509Certificate> element (if included) or the IdP's current metadata with what the SP has configured. The long-term fix is to have the SP consume the IdP's metadata URL so new certificates arrive automatically, and to publish the next certificate in metadata before switching to it.

Also check what is signed. Some SPs require a signed assertion, some a signed response, some both. A mismatch here shows up as "signature missing" even though one signature is present.

Do Audience, Recipient and Destination match exactly?

The Audience must equal the SP's entity ID, and Recipient and Destination must equal the ACS URL, character for character.

These three fields cause more support tickets than anything else, because they are configured by hand on two systems.

Field Where Must match
Audience <saml:AudienceRestriction> in the assertion SP entity ID
Recipient <saml:SubjectConfirmationData> SP ACS URL
Destination <samlp:Response> attribute SP ACS URL

Differences that break login include http versus https, a www prefix, a trailing slash, a different port behind a load balancer, or an entity ID copied with surrounding spaces. If the SP sits behind a proxy, make sure it builds its own URLs from the external host name, not the internal one.

What does an InResponseTo error mean?

An InResponseTo mismatch means the service provider can't find the request this response answers, usually because the session was lost, the login was IdP-initiated, or the response was reused.

In an SP-initiated flow, the SP sends an AuthnRequest with an ID and remembers it. The response's InResponseTo must match. Typical causes of a mismatch:

  • The SP stores the request ID in a session cookie that was lost, often because of SameSite cookie settings on the cross-site POST back.
  • The user started at the IdP portal, so there was no request, and the SP doesn't accept IdP-initiated logins.
  • The user pressed Back and resubmitted an old response.
  • Several SP instances behind a load balancer don't share session state.

Fix the session handling rather than turning the check off. The check is part of what stops replayed and injected responses.

Why do time conditions fail?

NotBefore and NotOnOrAfter failures almost always mean a clock is wrong on one of the servers, and the fix is time synchronization, not a wider window.

Assertions are valid for a short window, often a few minutes. If the SP's clock runs ahead, a fresh assertion looks expired; if it runs behind, the assertion looks not yet valid. Allow a small skew of a minute or two and make sure both sides sync time with NTP.

Is the NameID what the service provider expects?

The NameID format and value must match what the SP uses to look up accounts, such as an email address, a persistent identifier or a username.

If login "succeeds" but the user lands in the wrong account or gets "user not found," compare the <saml:NameID> value and its Format attribute with the SP's account key. Email-based NameIDs break when users change addresses, which is one reason many deployments prefer a persistent, opaque identifier.

What about attacks hidden in malformed responses?

Use a maintained SAML library that validates the signature over exactly the elements it then reads, because XML signature wrapping attacks exploit gaps between the two.

In a signature wrapping attack, an attacker moves the signed assertion and inserts an unsigned one that the application reads instead. The signature still verifies, but over the wrong element. The OWASP SAML cheat sheet covers the defenses. If you are debugging a custom SAML integration rather than a mature library, that alone is worth a security review.

For how federation fits into the wider identity picture, see the federation guide.

Questions

How do I see what is inside a SAML response?

Capture the SAMLResponse form field from the browser's network tools, base64-decode it and read the XML. For the HTTP-Redirect binding, messages are also DEFLATE-compressed. A browser-based decoder does both steps for you.

What does 'Invalid audience' mean in SAML?

The Audience value in the assertion's AudienceRestriction doesn't match the entity ID the service provider expects. Fix the value on the IdP side for that SP, or correct the SP's entity ID, so they are identical strings.

Why did SSO stop working for everyone at once?

The most common cause is a signing certificate change on the identity provider that the service provider hasn't picked up. Update the SP's trusted certificate or metadata, ideally by consuming the IdP's metadata URL.

Should the response or the assertion be signed?

Either can be signed, and many deployments sign both. The SP must verify the signature that covers the assertion it uses and must reject unsigned assertions it wasn't configured to accept.

Is it safe to paste a SAML response into an online tool?

A response can contain personal data and, until it expires, can sometimes be replayed. Use a tool that runs locally in your browser, or a test account, and don't share real responses in tickets or chat.

Sources

Tagged: SAML, SAML 2.0, Single sign-on, Federation

The Twobo Technologies editors write practical explainers on identity and API security and maintain the free tools on this site. Spotted an error or an outdated detail? Email contact@twobotechnologies.com.

Related articles