SAML Troubleshooting and Checklist
This checklist focuses on Web Browser SSO login failures. Identify whether the failure occurs at the identity provider (IdP), service provider (SP), or transport layer, and follow one login attempt. Diagnose differences between trusted configuration and received data while keeping signature and recipient checks enabled.
Compare clocks and validity
A valid signature does not make an expired assertion usable. Distinguish the actual server clock from the timezone used to display logs.
Check time values
- Check time synchronization at both IdP and SP. SAML time values are UTC with a trailing Z. Matching the OS display timezones does not fix a drifting clock.
- In Conditions, NotBefore starts the interval and NotOnOrAfter ends it. The start is included; the end is excluded. IssueInstant alone is not an expiry time.
- Also check NotOnOrAfter in bearer SubjectConfirmationData. In Web Browser SSO this element must not contain NotBefore; it is separate from Conditions.
- Use a small, bounded clock-skew allowance consistent with the library and policy. Do not disable expiry checking or greatly extend it without diagnosing the cause.
Reading a time boundary
| Example Conditions value | Meaning without clock-skew allowance |
|---|---|
| NotBefore = 2026-01-01T12:00:00Z | Valid from 12:00:00 UTC |
| NotOnOrAfter = 2026-01-01T12:05:00Z | Expired at exactly 12:05:00 UTC |
Check recipient and request correlation
An entityID identifies a party; the ACS URL receives authentication results. They need not be the same. Compare against trusted configuration and metadata.
Values to compare
| Field | Check |
|---|---|
| Audience | The bearer assertion includes this SP entityID as an audience |
| Recipient | Bearer SubjectConfirmationData identifies the ACS that received the response |
| Destination | If present, matches the actual destination; also check binding requirements |
| InResponseTo | For SP-initiated login, Response and bearer SubjectConfirmationData correlate to the saved AuthnRequest ID |
Check environment and replay handling
- Check production versus staging entityIDs, scheme, host, port, and path. Behind a proxy, inspect the configured externally visible URL.
- For SP-initiated login, check whether the saved request ID or session was lost. Treat permitted IdP-initiated login as a separate flow, not a reason to skip correlation for every response.
- Unsolicited IdP-initiated responses omit InResponseTo. Track used POST bearer assertion IDs for their validity interval and reject replay.
Check binding and encoding
A Redirect request and a POST response can be used in one exchange. Each receiving endpoint must support its chosen binding; the two directions do not need the same binding.
Checks by binding
| Binding | Check |
|---|---|
| HTTP Redirect | Default encoding is raw DEFLATE of XML, then Base64, then URL encoding; no gzip or zlib wrapper |
| HTTP POST | Base64-encoded XML in a form field; do not apply Redirect DEFLATE decoding |
| HTTP Artifact | Trace SAMLart separately from the server-to-server artifact resolution |
Separate encoding from signature failures
- DEFLATE is the Redirect default, not an arbitrary compression toggle. For another encoding, check SAMLEncoding and support at both ends.
- Redirect signature verification uses the received URL-encoded values as specified. Decoding and re-encoding can change the signed bytes.
- Reject missing required signatures and invalid signatures. Readable XML does not prove authenticity or a valid login. See bindings and signature validation.
Separate HTTP and SAML outcomes
HTTP 400 or 500 alone does not identify the cause. An HTTP 200 can carry a SAML Response whose Status reports failure.
Identify the failing layer
- Transport/HTTP: check the target URL, which server returned the response, TLS errors, and proxy or application failures.
- SAML: compare StatusCode, any nested code, and IdP/SP validation results. Success does not waive signature, validity, or recipient checks.
- Signature keys: check trusted metadata or configured keys for the Issuer, rollover updates, and allowed algorithms. Do not automatically trust a certificate supplied inside the message.
- Certificates: distinguish HTTPS certificates from SAML signing-key information. Under Metadata IOP, trust is based on accepted metadata keys, not rejection solely for an X.509 expiry date. Check the implemented trust model; see certificates and metadata operations.
Record only necessary diagnostic data
Start with error categories, timestamps, correlation IDs, expected destinations, and validation outcomes.
Protect sensitive data
- Do not paste assertions, cookies, access tokens, or personal attributes into public logs or online decoders. Base64 is not encryption.
- If detailed traffic is necessary, use a controlled environment with restricted access and limited retention. Treat XML content as unverified until validation succeeds.
- After changes, start a new login attempt and also check that expired, misdirected, or replayed messages are still rejected.
Specifications and related reading
SAML Core (§1.3.3, §2.5, §3.2.2) / SAML Profiles (§4.1.4–4.1.5) / SAML Bindings (§3.4–3.6) / Metadata Interoperability Profile (§2)