SAML has a reputation for being enormous. The specification is enormous. The part you have to implement is not, and confusing the two is why the first integration feels so much worse than it should.
There are three parties. The person signing in. Your application, which the specification calls the service provider. And the identity provider, which the customer's IT department already runs and will not change for you.
The handshake, in four moves
Someone arrives at your sign-in page. You do not know who they are, but you know which organisation they belong to, usually from their email domain. You redirect them to that organisation's identity provider with a request that says: tell me who this is, and send the answer here.
The identity provider does whatever it does — a password, a badge, a push notification, none of your business — and posts back an assertion: a signed XML document saying this person is who they say they are, here is their email, here are their groups, and this is valid for the next few minutes.
- You verify the signature against the certificate you were given at setup
- You check the audience, so an assertion minted for someone else is refused
- You check the timestamps, so a captured assertion cannot be replayed tomorrow
- Only then do you create a session
Where it actually goes wrong
Not in the cryptography. In the configuration. The certificate expires in eighteen months and nobody diarises it. The assertion consumer URL has a trailing slash in one system and not the other. The customer maps their group attribute to a name you do not read, so everyone signs in successfully with no permissions at all.
Every one of those produces a ticket that reads 'SSO is broken', and every one is a different problem. This is the real cost of SAML: not writing the parser, but running the support conversation with someone else's IT department, in their vocabulary, on their schedule.
The real cost of SAML is not the parser. It is the support conversation with someone else's IT department.
What good looks like
A good integration hides the protocol entirely from your application code. Your code receives a normalised profile — an identifier, an email, a name, a set of groups — and does not know or care whether SAML or OIDC produced it.
The other half is giving the customer's administrator a place to do the setup themselves, with screenshots for the provider they actually run, and validation that catches the trailing slash before they leave the page.
Everything here, already built
Sign-in, enterprise SSO, directory provisioning, roles and an audit trail behind one API. Start with the quickstart and have a working sign-in this afternoon.