SAML Signature Basics
SAML Responses are protected with XML Signatures. This page covers how signatures are structured, what to check when verifying them, and how to run certificate operations safely.
🔏 Signature Structure
Signatures live under ds:Signature and may target the Assertion or the entire Response. Verification uses a previously trusted IdP public key, not a certificate trusted solely because it appears in the received XML.
Core elements
- 📌 The target can be the Assertion or the full Response (sometimes both).
- 📌 Signature is stored in ds:Signature and verified with an X.509 certificate.
- 📌 Use the exact signed element that passed validation for authentication. Reading a different unsigned assertion can enable XML signature wrapping.
🛡️ Verification Tips
Check not only the signature itself but also the conditions and certificate state.
Common checks
- ✅ Time drift causes NotBefore / NotOnOrAfter failures.
- ✅ Audience must match the expected EntityID.
- ✅ Ensure the signature covers the expected element (Assertion/Response).
- ✅ Check configured keys, certificate format, and the expiry policy of the selected trust model.
Certificate operations
- 🔁 Track rotation schedules and update metadata in advance.
- 🔁 Follow the certificate trust model for key revocation and expiry.
- 🔁 If key pinning is used, deploy new keys in the right order to avoid lockouts.
- 🔁 Keep test and production certificates separate to avoid mix-ups.
🧯 Common Errors and Fixes
Signature failures have recurring patterns; knowing them speeds up troubleshooting.
Typical cases
- ⚠️ Signature verification errors: wrong certificate, wrong reference, possible tampering.
- ⚠️ XML parsing errors: Deflate/Base64 decoding failures.
- ⚠️ Condition mismatch: time drift or audience mismatch.
How to troubleshoot
- 🧭 Check the Reference URI and certificate fingerprint shown in logs.
- 🧭 Check clock synchronization and UTC parsing; a different display timezone alone is not clock skew.
- 🧭 Compare metadata from a trusted source and review changes before updating it.
SubjectConfirmation / Conditions checks
SubjectConfirmation (especially Bearer) and Conditions must be validated; mismatches mean the assertion is not intended for the recipient.
- SubjectConfirmationData Recipient matches the ACS URL.
- Validate Conditions time bounds and the bearer SubjectConfirmationData expiry. For SP-initiated login, match InResponseTo to an unused request ID and reject assertion ID reuse.
- Conditions > AudienceRestriction matches the expected EntityID.
Specifications and related guides
OASIS SAML profiles / OASIS Metadata Interoperability Profile / OWASP SAML Security Cheat Sheet
Related SAML guide