SAML Debugging for SSO: A Practical Checklist

Quick answer: Decode the response (/saml-decoder), then validate time conditions, destination/audience, NameID, attributes, and signature. Most SAML failures are configuration mismatches, not code bugs.

Look at NotBefore and NotOnOrAfter. Clock skew between IdP and SP is a frequent issue.

Key takeaways

• Definition: Check time conditions explains what you are looking at and why it matters in practice.
• Context: this section helps you interpret inputs and outputs correctly, not just run a tool.
• Verification: confirm assumptions (format, encoding, units, or environment) before changing anything.
• Consistency: apply one approach end-to-end so results are repeatable and easy to debug.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see from Check time conditions.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, and expected markers).
4. If the result still looks encoded, repeat step-by-step and stop as soon as it becomes clear.

Destination must match your ACS URL. Audience must match your entity id.

Also check:

• Recipient and InResponseTo (if your SP validates them)
• RelayState handling (incorrect relay state can break redirects)

Key takeaways

• Definition: Verify destination and audience explains what you are looking at and why it matters in practice.
• Context: this section helps you interpret inputs and outputs correctly, not just run a tool.
• Verification: confirm assumptions (format, encoding, units, or environment) before changing anything.
• Consistency: apply one approach end-to-end so results are repeatable and easy to debug.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see from Verify destination and audience.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, and expected markers).
4. If the result still looks encoded, repeat step-by-step and stop as soon as it becomes clear.

Make sure the format and value are what your app expects.

Key takeaways

• Definition: Inspect the NameID explains what you are looking at and why it matters in practice.
• Context: this section helps you interpret inputs and outputs correctly, not just run a tool.
• Verification: confirm assumptions (format, encoding, units, or environment) before changing anything.
• Consistency: apply one approach end-to-end so results are repeatable and easy to debug.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see from Inspect the NameID.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, and expected markers).
4. If the result still looks encoded, repeat step-by-step and stop as soon as it becomes clear.

A mismatch certificate or algorithm will cause failures. Confirm you are using the IdP public certificate.

Key takeaways

• Definition: Validate the signature explains what you are looking at and why it matters in practice.
• Context: this section helps you interpret inputs and outputs correctly, not just run a tool.
• Verification: confirm assumptions (format, encoding, units, or environment) before changing anything.
• Consistency: apply one approach end-to-end so results are repeatable and easy to debug.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see from Validate the signature.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, and expected markers).
4. If the result still looks encoded, repeat step-by-step and stop as soon as it becomes clear.

If user profile data is missing, check attribute mappings on the IdP.

Also confirm whether attributes are in:

• the Assertion directly, or
• an EncryptedAssertion you cannot inspect without decryption

Key takeaways

• Definition: Look for missing attributes explains what you are looking at and why it matters in practice.
• Context: this section helps you interpret inputs and outputs correctly, not just run a tool.
• Verification: confirm assumptions (format, encoding, units, or environment) before changing anything.
• Consistency: apply one approach end-to-end so results are repeatable and easy to debug.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see from Look for missing attributes.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, and expected markers).
4. If the result still looks encoded, repeat step-by-step and stop as soon as it becomes clear.

Make sure your IdP is posting to the correct ACS endpoint and using the expected binding (POST vs Redirect). A wrong endpoint often looks like a generic login failure.

Key takeaways

• Definition: Confirm the binding and endpoint explains what you are looking at and why it matters in practice.
• Context: this section helps you interpret inputs and outputs correctly, not just run a tool.
• Verification: confirm assumptions (format, encoding, units, or environment) before changing anything.
• Consistency: apply one approach end-to-end so results are repeatable and easy to debug.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see from Confirm the binding and endpoint.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, and expected markers).
4. If the result still looks encoded, repeat step-by-step and stop as soon as it becomes clear.

Decode the response, inspect the XML, and compare it to your service provider configuration line by line.

Why this workflow works

• Final step reduces guesswork by separating inspection (readability) from verification (correctness).
• It encourages small, reversible steps so you can pinpoint where things go wrong.
• It keeps the original input intact so you can always restart from a known-good baseline.

Detailed steps

1. Copy the raw input exactly as received (avoid trimming or reformatting).
2. Inspect for obvious markers (delimiters, prefixes, or repeated escape patterns).
3. Decode/convert once and re-check whether the output is now readable.
4. If it is still encoded, decode again only if you can explain why (nested encoding is common).
5. Validate the final output (JSON parse, XML parse, expected timestamps, etc.).

What to record

• Save the working sample input and the successful settings as a reusable checklist.

Why does it work for some users but not others?

Often it is attribute mapping or group-based policy differences. Compare the successful and failing assertions side by side.

What should I do if the output still looks encoded?

Decode step-by-step. If you still see obvious markers (percent codes, escape sequences, or Base64-like text), the data is likely nested.

What is the safest way to avoid bugs?

Keep the original input, change one thing at a time, and validate after each step so you know exactly what fixed the issue.

Should I use the decoded value in production requests?

Usually no. Decode for inspection and debugging, but send the original encoded form unless your protocol explicitly expects decoded text.

Why does it work in one environment but not another?

Different environments often have different settings (time zones, keys, encoders, or parsing rules). Compare a known-good sample side-by-side.

• Reminder: verify inputs and outputs for "FAQ" with a known-good sample.
• Reminder: verify inputs and outputs for "FAQ" with a known-good sample.

• OASIS SAML 2.0 Core - Core SAML spec.
• OASIS SAML 2.0 Bindings - HTTP bindings.
• OASIS SAML 2.0 Profiles - Profile definitions.
• OASIS SAML 2.0 Metadata - Metadata spec.
• OASIS SAML V2.0 Errata - Errata updates.
• W3C XML Signature - XML signature spec.
• W3C XML Canonicalization 1.1 - Canonicalization rules.
• RFC 7522: SAML 2.0 Bearer Assertion Grant - OAuth profile.
• OASIS SAML Technical Committee - SAML committee home.
• IANA XML Media Types - XML media types.

Key takeaways

• Definition: References clarifies what the input represents and what the output should mean.
• Why it matters: correct interpretation prevents downstream bugs and incorrect conclusions.
• Validation: confirm assumptions before changing formats, units, or encodings.
• Repeatability: use the same steps each time so results are consistent across environments.

Common pitfalls

• Mistake: skipping validation and trusting the first output you see in References.
• Mistake: mixing formats or layers (for example, decoding the wrong field or using the wrong unit).
• Mistake: losing the original input, making it impossible to reproduce the issue.

Quick checklist

1. Identify the exact input format and whether it is nested or transformed multiple times.
2. Apply the minimal transformation needed to make it readable.
3. Validate the result (structure, encoding, expected markers) before acting on it.
4. Stop as soon as the result is clear; avoid over-decoding or over-normalizing.