📄️ Upgrading to 4.0 from 3.x
4.0.0 replaces every optional parameter on the send/handle methods — relayState, sessionIndex, nameIdPolicyFormat, nameId, validate/issuer, and the attribute array — with a single variadic ContextList parameter. It also adds first-class NameID Format support, which changes nameId from a plain string to a value object. Both changes are breaking; this guide covers everything you need to update.
📄️ Upgrading to 3.0 from 2.x
3.0.0 fixes an XML Signature Wrapping (XSW) vulnerability in signature validation and removes the API that made it possible to get it wrong. If your code validates signatures at all, you need to make the change below before upgrading.
📄️ Upgrade from lightsaml
litesaml/saml is a high-level rewrite of litesaml/lightsaml. The API is not backwards-compatible — this guide covers every breaking change and shows before/after examples for the most common patterns.