What SAML actually is, for devs building SaaS

SAML is the protocol nobody wants to learn, that every enterprise buyer requires, and that will eventually land on your roadmap the week before a deal closes. Here’s what you actually need to know.

The basic flow

SAML has three parties: the user, the Service Provider (that’s you), and the Identity Provider (the customer’s SSO — Okta, Azure AD, etc.). The flow:

1. User visits your app
2. You redirect them to the IdP with a SAML AuthnRequest (an XML blob, often compressed and base64-encoded, passed via a browser redirect)
3. User authenticates with the IdP
4. IdP sends an XML SAML Response to your Assertion Consumer Service (ACS) endpoint — a POST containing a signed XML blob
5. You verify the signature against the IdP’s certificate and extract the user’s identity from the XML

That’s it, conceptually. The ugly parts are all in the XML and the signature validation.

Why it’s hard

• XML signatures are fragile. The XML DSig spec has several canonicalization algorithms, and a mismatch between IdP and SP produces cryptic errors.
• Every IdP implements slightly differently. Attribute names vary (email vs emailAddress vs http://schemas.xmlsoap.org/.../emailaddress), group memberships come as repeated attributes or comma-separated strings, and NameID formats differ.
• Configuration is a metadata dance. The IdP publishes XML metadata, you publish XML metadata, and if either side updates their signing certificate, the integration breaks.

What to do

1. Don’t hand-roll SAML. Use passport-saml, python3-saml, ruby-saml, or a managed provider. The canonicalization bugs alone will consume weeks.
2. Test against multiple IdPs. Okta, Azure AD, OneLogin, Ping, and Google Workspace all behave slightly differently. If you only test Okta, the first Azure AD customer will find the bugs.
3. Never skip signature validation. “It worked in dev without it” is how you ship CVEs.
4. Log the raw XML on failure. Debugging SAML without the raw assertion is hopeless.

The honest take

SAML is 20 years old, XML-based, and a protocol you support because your customers require it. Most new integrations happen over OIDC; SAML shows up when the buyer is a Fortune-X company with an IT team that likes XML. Ship it when you have to, use a library, and don’t let it touch your elegant OIDC code path.