SAML SSO Errors Troubleshooting Guide: find which side broke and fix it

A broken SAML single sign-on integration usually shows the user a generic error page, while the real reason sits in an XML message that neither the identity provider nor the application displays. The fastest route to a fix is to decide which side rejected the exchange, capture the SAML request and response, and compare a small set of values: entity IDs, URLs, the NameID, timestamps and the signing certificate. This guide gives a symptom-led method for doing that, with the SAML 2.0 status codes, the Microsoft Entra ID AADSTS codes seen most often with SAML apps, and typical service provider library messages. It is for identity engineers, application owners and support teams who run SAML federations; for the security model and hardening see the SAML Security Guide.

Key takeaways

• First decide which side failed. An error on the identity provider's sign-in page means the AuthnRequest or the user's assignment was rejected; an error on the application after a successful sign-in means the service provider rejected the assertion.
• Capture before you change anything. A browser capture of the SAMLRequest and SAMLResponse, plus the IdP's correlation ID and timestamp, resolves most cases in minutes and stops trial and error edits.
• Five values cause most failures. Issuer or entity ID, Assertion Consumer Service URL, audience, NameID format and value, and the signing certificate account for the bulk of real SAML errors.
• Certificates expire on a schedule you already know. Signing certificate rollover is the most predictable SAML outage; the IdP tells you the date months ahead.
• Never fix by weakening validation. Turning off signature checks, accepting any audience or widening clock tolerance to hours makes the error go away by removing the controls that stop forged assertions.

Locate the failure: which side rejected the exchange

In service provider (SP) initiated SSO, the application sends an AuthnRequest to the identity provider (IdP), the user authenticates, and the IdP posts a signed Response containing an Assertion to the SP's Assertion Consumer Service (ACS) URL. In IdP-initiated SSO there is no AuthnRequest, so the Response has no InResponseTo value. Each stage fails in a characteristic way.

Capture the evidence

1. Record the error identifiers: in Microsoft Entra ID copy the message from the error page including the CorrelationID and Timestamp; other IdPs show an equivalent request or trace ID. These locate the sign-in event in the IdP logs.
2. Capture the messages: use the IdP's own tooling where it exists (Entra's Test single sign-on page with the My Apps Secure Sign-in Extension downloads the SAML request and response) or a browser developer tools network capture. The HTTP-POST binding carries a base64 encoded SAMLResponse form field; the HTTP-Redirect binding carries a deflated, base64 and URL encoded SAMLRequest query parameter.
3. Decode and read: decode locally rather than in an online tool, because a captured assertion is a live bearer credential until it expires.
4. Check the SP log: most SP libraries log the precise validation failure even when the user sees a generic page.
5. Compare against configuration: lay the decoded values next to the IdP application settings and the SP metadata, field by field, using the table in the next section.

The values to compare

Microsoft notes that Entra error texts can change; check the current wording at login.microsoftonline.com/error?code= followed by the number.

SAML 2.0 status codes

When the IdP returns a Response that is not a success, the Status element carries a top-level code and often a second-level code. These are defined in the OASIS SAML 2.0 core specification, section 3.2.2.2.

Symptom guide: common errors, causes and fixes

Application not found or reply URL mismatch

• Symptom: the IdP shows an error before or straight after the user enters credentials (Entra AADSTS700016 or AADSTS50011).
• Likely causes, most common first: the SP sends an entity ID that differs from the Identifier at the IdP (trailing slash, http versus https, tenant specific suffix); the app was moved to a new hostname and the ACS URL was not added; the request went to the wrong tenant or IdP.
• Diagnose: read Issuer and AssertionConsumerServiceURL in the decoded AuthnRequest and compare character by character with the IdP configuration.
• Fix: correct the value at whichever side is wrong; add new reply URLs rather than replacing old ones during a migration.
• Prevent: exchange metadata rather than typing values, and include SAML settings in the application's change checklist.

Signature validation failed

• Symptom: sign-in succeeds at the IdP, the application rejects the response, and the SP log reports a signature failure or "No Signature found".
• Likely causes: the IdP signing certificate was rolled over and the SP still trusts the old one; the SP expects a signed assertion but the IdP signs only the response, or the reverse; a proxy or load balancer re-encoded the POST body; the SP rejects SHA-1 or the IdP is set to SHA-1 for a legacy app.
• Diagnose: compare the certificate in the Response KeyInfo (or the IdP metadata) with the one configured at the SP by thumbprint; check whether the Signature element sits on Response, Assertion or both.
• Fix: upload the current IdP certificate to the SP, or align the signing option. In Entra the Signing Option values are Sign SAML response, Sign SAML response and assertion, and Sign SAML assertion; Signing Algorithm should only be changed to SHA-1 when the application cannot accept anything else.
• Prevent: see the certificate rollover section below.

Audience, recipient or destination rejected

• Symptom: the SP log names the audience, recipient or destination as invalid.
• Likely causes: the SP sits behind a reverse proxy or TLS terminator and computes its own URL as http or with an internal host name; the IdP Identifier was changed to make the request side work and now no longer equals the SP's entity ID; several environments (test, production) share one IdP application.
• Diagnose: compare Audience with the SP entity ID and Recipient with the external ACS URL; check the SP's base URL or forwarded header settings.
• Fix: configure the SP with its external URL and keep one IdP application per environment.

Assertion not yet valid or expired

• Symptom: intermittent failures with "not yet valid" or "expired", often on one server in a pool.
• Likely causes: SP host clock drift; the user took too long on a step-up prompt and the assertion window passed; a saved bookmark replays an old POST.
• Diagnose: compare IssueInstant, NotBefore and NotOnOrAfter with the SP server time in the log entry. The python3-saml library, for example, allows 300 seconds of drift.
• Fix: repair time synchronisation on the SP host. Do not raise allowed drift beyond a few minutes.

InResponseTo mismatch or unsolicited response

• Symptom: failures after the user opened several tabs, used the back button, or started sign-in from an IdP portal tile.
• Likely causes: the SP keeps the AuthnRequest ID in a session cookie that was lost (SameSite rules, cookie on a different host, load balancer without session affinity); the SP does not accept IdP-initiated responses.
• Diagnose: check whether InResponseTo is present and whether the SP session still holds the request ID.
• Fix: store request state in a way that survives the cross-site POST, or enable IdP-initiated SSO deliberately with its replay protections, not by disabling InResponseTo checks.

User signs in but is not recognised or has no rights

• Symptom: "user not found", a new empty account, or missing roles in the application.
• Likely causes: NameID set to an attribute the SP does not use (object ID instead of email or UPN), a NameID Format mismatch, a UPN change after rename or marriage, the user not provisioned in the app, or a role or group claim not configured.
• Diagnose: read NameID and the AttributeStatement in the decoded assertion and compare with the SP account record.
• Fix: choose a stable, unique identifier for NameID, add the missing claims, and provision users before first sign-in. See the SCIM Provisioning Errors Troubleshooting Guide.

Authentication context not met

• Symptom: NoAuthnContext from the IdP, or Entra AADSTS75011: "The authentication method by which the user authenticated with the service doesn't match requested authentication method."
• Cause and fix: the SP hard-codes a RequestedAuthnContext such as password protected transport while the user signed in with a passkey, certificate or federated method. Remove or broaden the requested context at the SP and enforce strength through IdP policy instead.

Signing certificate rollover without an outage

Microsoft Entra ID creates SAML signing certificates valid for three years and emails up to five notification addresses 60, 30 and 7 days before expiry. Other IdPs follow similar patterns. A safe rollover:

1. Add owned group mailboxes, not individuals, as notification addresses for every SAML application.
2. Create the new certificate at the IdP; it stays inactive.
3. Check whether the SP supports two trusted certificates or a metadata URL. Microsoft advises application vendors to support multiple certificates and refresh metadata at least every 24 hours.
4. If it does, add the new certificate at the SP first, then make it active at the IdP. If it holds only one, agree a short change window and switch both sides together.
5. Test sign-in immediately, keep the old certificate available for rollback until the test passes, then remove it from the SP.

Note Microsoft's warning: if an SP does not validate certificate expiry, an expired certificate matching on both sides keeps working, so an apparently healthy app can fail the moment a new certificate is activated.

Decision guidance

A small organisation with a few dozen SAML apps can track certificates and owners in a spreadsheet. A large one needs an inventory of every federated application with owner, entity ID, certificate expiry and metadata method, fed from the IdP's API, and alerts at 60 days.

Detection and measurement

• IdP sign-in logs: failure codes per application, especially sudden spikes after a change or on certificate expiry dates.
• SP validation logs: forward them centrally. Repeated signature or audience failures from one source can indicate tampering attempts, not only misconfiguration.
• Federation changes: alert on new or modified signing certificates and federation trusts at the IdP; an unexpected certificate is the core of Golden SAML (MITRE ATT&CK T1606.002). See the Golden SAML and Federation Trust Abuse Defence Guide.

Metrics:

1. SAML sign-in failure rate per application, weekly.
2. Number of signing certificates expiring within 60 days without a scheduled change.
3. Share of SAML apps using metadata URLs rather than manual configuration.
4. Share of SAML apps with a named owner and group notification address.
5. Count of apps with SHA-1 or validation exceptions (target: falling to zero).
6. Mean time to resolve SAML incidents.

Framework mapping

Common failure patterns

• Disabling signature validation to "get it working": the SP then accepts any assertion, including a forged one.
• Personal mailbox as the only certificate contact: the person leaves and the 60, 30 and 7 day notices go nowhere.
• Treating the signing key as configuration rather than a credential: the token signing key is a machine credential of the highest value; its theft enabled forged SAML tokens in the SolarWinds supply chain compromise.
• Editing the IdP Identifier to match a broken SP request: the request side starts working and the audience check on the response fails.
• Email as NameID with no plan for renames: a changed address creates a duplicate account or locks the user out.
• Pasting assertions into public decoders: a valid assertion is a bearer credential until NotOnOrAfter.

Practitioner checklist

• Establish which side rejected the exchange before changing any setting.
• Capture the SAMLRequest, SAMLResponse, correlation ID and timestamp for every incident.
• Decode locally and compare Issuer, ACS URL, Destination, Audience, Recipient, NameID and certificate with configuration.
• Read the SP library log for the exact validation message.
• Check SP host time before touching clock tolerance.
• Use metadata URLs where supported and keep one IdP application per environment.
• Give every SAML app an owner and a group notification address; review expiries monthly.
• Record exceptions (SHA-1, IdP-initiated) with an owner and an end date.

Standards and references

• OASIS: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0
• Microsoft Learn: Microsoft Entra authentication and authorization error codes
• Microsoft Learn: Debug SAML-based single sign-on to applications
• Microsoft Learn: An app page shows an error message after the user signs in
• Microsoft Learn: Manage certificates for federated single sign-on
• SAML-Toolkits: python3-saml library

Related NHI Mgmt Group resources: SAML Security Guide · Golden SAML and Federation Trust Abuse Defence Guide · SAML to OIDC Migration · Federation and Trust Relationships Guide · Kerberos Error Codes Troubleshooting Guide