# passport-saml: Invalid signature on document: debugging

## TL;DR

The SAML response's signature does not verify: wrong IdP cert, the response was modified in transit (often by parsing), or the canonicalization differs. Verify against the raw XML with the correct cert before blaming the IdP. Most causes are local.

```text
passport-saml: Invalid signature on document
```

## Steps

1. Verify the IdP cert configured in passport-saml matches the IdP's current signing cert.
   Expected: The certs match.

2. Check for XML mangling: log the raw response before parsing; whitespace or encoding changes break signatures.
   Expected: The raw XML is intact.

3. Confirm the signature covers what you validate: response-level vs assertion-level signatures need the right settings.
   Expected: The validation target is correct.

4. Test with the IdP's published test harness or a known-good response.
   Expected: The local setup is isolated from IdP issues.

5. Fix the local cause found above (cert, mangling, or settings) and retest the full login.
   Expected: Validation passes.

## When to use

- passport-saml reports invalid signature
- SSO broke after a change
- the IdP insists its side is fine

## When not to use

- the error is about decryption, not signature (different key)
- the cert is known-stale (update it; no debugging needed)
- using a different SAML library (the settings differ)

## Tool compatibility

- passport-saml
- Node.js

## Variant phrasings

- "passport-saml invalid signature document"
- "passport saml signature validation failed"
- "saml invalid signature debugging"

## Why it happens

XML signatures are brittle: they sign the exact bytes, so any parse-reserialize, encoding change, or whitespace normalization invalidates them. Combined with cert management, most 'invalid signature' errors are the SP's environment, not the IdP's response. Debugging from the raw bytes inward finds it fast.

## Edge cases

- never disable signature validation to 'test'; you will forget to re-enable it
- clock skew can masquerade as signature issues via condition checks; verify times too
- the IdP's metadata is the cert source of truth; compare against it

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_lKhAt3waso6C6HnZTJK7eA