01 · Definition
What is SAML?
Security Assertion Markup Language (SAML) is an open XML standard for exchanging authentication data between two parties: an identity provider (IdP), such as a company's directory, which signs the user in, and a service provider (SP), such as a messaging dashboard, which trusts the IdP's word. The version in use everywhere is SAML 2.0, approved as an OASIS standard in 2005, and it is the protocol behind most enterprise single sign-on (SSO).
The IdP's statement is an assertion: an XML document that names the user in <saml:Subject> (the NameID, often an email address), says when and how they authenticated, lists attributes such as department or role, and restricts who may accept it (<saml:AudienceRestriction>) and until when (NotOnOrAfter). The assertion, the response that carries it, or both are signed with XML Signature using the IdP's private key. The SP verifies them with the IdP's X.509 certificate, exchanged once in metadata XML together with each side's entity ID and the SP's Assertion Consumer Service (ACS) URL.
Login can start at either end. In SP-initiated login the application redirects the browser to the IdP with an AuthnRequest and later checks that the response's InResponseTo matches it. In IdP-initiated login the user clicks a tile in the IdP's portal and an unsolicited response is POSTed to the ACS URL — convenient, but with no request to match, so replay protection rests on short validity and one-time assertion IDs. OpenID Connect does the same job with JSON and JSON Web Tokens and suits mobile and API clients better; SAML remains the default in large enterprises.
Key takeaways
- SAML 2.0 is an XML standard in which an identity provider sends a signed assertion telling an application who the user is.
- The service provider must verify the XML signature against the IdP's certificate, plus audience, recipient and time limits, before creating a session.
- SP-initiated login carries an InResponseTo value you can check; IdP-initiated login does not, so it relies on short validity to resist replay.
- IdP signing certificates expire: trust the new certificate before the IdP switches to it, or every SSO login fails at once.
- SAML and OpenID Connect solve the same SSO problem; OIDC uses JSON and JWTs, SAML uses XML carried through the browser.
02 · Specifications
SAML: key facts and limits
| Standard | SAML 2.0 (OASIS, 2005) |
|---|---|
| Format | XML, signed with XML Signature (RSA-SHA256 typical) |
| Request binding | HTTP-Redirect (AuthnRequest) |
| Response binding | HTTP-POST to the ACS URL |
| Assertion lifetime | Usually a few minutes (NotOnOrAfter) |
| Subject | NameID: email or persistent opaque ID |
| Trust anchor | IdP's X.509 signing certificate from metadata |
03 · Operation
How does SAML work?
Exchange metadata
The SP publishes its entity ID, ACS URL and preferred
NameIDformat; the IdP publishes its entity ID, SSO URL and X.509 signing certificate. Each side imports the other's metadata XML once, and again whenever certificates change.Send the user to the IdP
In SP-initiated login the application builds an
AuthnRequestwith a unique ID, stores that ID in the user's session and redirects the browser to the IdP's SSO URL (HTTP-Redirect binding), withRelayStateto return the user to the page they wanted.The user authenticates at the IdP
The IdP applies its own policy — password, multi-factor authentication, device checks — then builds a
<samlp:Response>containing the signed assertion.The browser POSTs the response
An auto-submitting form POSTs the base64-encoded
SAMLResponseto the ACS URL (HTTP-POST binding). The browser is only the courier: it can read the assertion but cannot change it without breaking the signature.The SP validates, then creates a session
Verify the signature with the IdP certificate, then check
Issuer,Audience,DestinationandRecipient,NotBefore/NotOnOrAfter,InResponseTo, and that the assertion ID has not been used before. Only then map theNameIDand attributes to a user and a role.
04 · Code samples
SAML in code
<samlp:Response ID="_r8f2c1" InResponseTo="_a91c77" Version="2.0"Destination="https://app.example.com/sso/acs" IssueInstant="2026-10-19T04:30:02Z"><saml:Issuer>https://idp.example.com/</saml:Issuer><saml:Assertion ID="_as7d40" Version="2.0" IssueInstant="2026-10-19T04:30:02Z"><saml:Issuer>https://idp.example.com/</saml:Issuer><ds:Signature><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/><ds:Reference URI="#_as7d40"><ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><ds:DigestValue>q3Jz…base64…</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>Mb8w…base64…</ds:SignatureValue></ds:Signature><saml:Subject><saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">priya@example.in</saml:NameID><saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml:SubjectConfirmationData InResponseTo="_a91c77"Recipient="https://app.example.com/sso/acs" NotOnOrAfter="2026-10-19T04:35:02Z"/></saml:SubjectConfirmation></saml:Subject><saml:Conditions NotBefore="2026-10-19T04:29:32Z" NotOnOrAfter="2026-10-19T04:35:02Z"><saml:AudienceRestriction><saml:Audience>https://app.example.com/saml/metadata</saml:Audience></saml:AudienceRestriction></saml:Conditions><saml:AttributeStatement><saml:Attribute Name="department"><saml:AttributeValue>Support</saml:AttributeValue></saml:Attribute></saml:AttributeStatement></saml:Assertion></samlp:Response>
The Reference URI points at the assertion's ID: only data inside that signed element may be trusted.
05Playground
A working model of SAML. Use its controls to replay it step by step.
Tamper with an assertion and watch the digest break
Incoming request
As signedPOST /webhook HTTP/1.1
DigestValue: 93db18a6704351decf7197eadf59225026f24d54bbb790fad87c3a1aa19e2820
505 bytes, exactly as the sender signed them.
Your server verifies
- Read the raw body and the headerUse the exact bytes received — 505 bytes, before any JSON parsing.
- Hash what arrivedSHA-256(raw body)
- Compare the two digestsEqual digests mean equal bytes.
DigestValue (received) vs SHA-256(raw body) (computed)
93db18a6704351decf7197eadf59225026f24d54bbb790fad87c3a1aa19e282093db18a6704351decf7197eadf59225026f24d54bbb790fad87c3a1aa19e2820Match — bytes arrived intact. The digest proves nothing changed in transit (but not who sent it).
06 · Cautions
Common mistakes with SAML
Checking that a signature exists, not what it covers
In XML signature wrapping attacks, a signed element is moved and an unsigned assertion inserted where the code reads it. Use a maintained library, require signed assertions, and read user data only from the element the signature's
Referencepoints to.Skipping audience, recipient and time checks
An assertion issued for another application, or captured last week, still carries a valid signature. Enforce
Audience,Destination/RecipientandNotOnOrAfterwith small clock skew, and reject assertion IDs you have already accepted.Letting the IdP certificate catch you out
When the IdP rolls to a new signing certificate and the SP trusts only the old one, everyone is locked out at the same moment. Trust both during rollover and alert 30 days before the current certificate expires.
Treating SSO login as deprovisioning
SAML runs only at login. A session created yesterday keeps working after the directory account is disabled. Keep application sessions short and use SCIM or an admin API to deactivate leavers immediately.
07 · Rationale
Why does SAML matter?
A WhatsApp operations dashboard holds customer conversations, approved templates and the power to message customers in the brand's name. SAML lets the company's IT team control that access from the directory it already runs: a new agent gets in by joining a group, and a leaver loses access when their directory account is disabled, with no separate password to forget to remove. For the developer building the service-provider side, SAML is also unforgiving — real-world SAML breaches almost always come from verification shortcuts in the application, not from broken cryptography.
08 · Worked example: Rolling out SSO for a 120-agent support team
Example: Rolling out SSO for a 120-agent support team
A Hyderabad insurance company moves its WhatsApp support team onto SSO through its corporate identity provider. IT registers the dashboard with its entity ID and ACS URL, maps a department attribute to the inbox role and assigns two directory groups: agents and supervisors. On day one, agents click the dashboard tile and arrive signed in. Three weeks later an agent leaves; HR disables her directory account and her next login attempt stops at the IdP. Six months on, the IdP's signing certificate is due to expire: the team adds the new certificate to the SP's trusted list a week before the switch, so logins keep working the morning the IdP starts signing with it.
09 · Recommended practice
Best practices for SAML
- Prefer SP-initiated login and validate
InResponseTo; allow IdP-initiated login only when portal tiles are a real requirement. - Reject SHA-1 signatures and digests and require SHA-256.
- Map roles from a group or attribute claim, never from the email domain.
- Keep one break-glass admin account outside SSO, protected by a security key, for IdP outages.
10 · Questions and answers
SAML FAQs
- What is the difference between SAML and SSO?
- SSO is the capability; SAML is one protocol that delivers it. Single sign-on means one login for many applications, and SAML 2.0, OpenID Connect and older protocols are ways of passing that login from the identity provider to each application.
- Is SAML more secure than OpenID Connect?
- Neither is more secure by design; they suit different clients. SAML is entrenched in enterprise identity providers and browser-based apps, while OpenID Connect, built on OAuth 2.0 and JWTs, is simpler to implement and works for mobile apps and APIs. Many products support both.
- Why did SAML login suddenly fail after working for months?
- The usual cause is a rotated or expired IdP signing certificate. Check whether the IdP started signing with a certificate the service provider does not trust yet; clock skew and a changed ACS URL or entity ID are the next suspects.
- Does SAML encrypt the user's data?
- Not by default. Assertions are signed, which stops tampering, but anyone holding the browser can read them unless the IdP also encrypts them with the SP's certificate as an
EncryptedAssertion. TLS protects them on the wire.