What Is SAML

Enterprise customers expect SSO

When a company with 500 employees buys your product, they do not want each employee to create a separate password. They want their employees to log in with their company credentials — the same ones they use for email, Slack, and every other tool.

This is single sign-on (SSO): one login for all services. The company manages employee accounts in a central system (Okta, Azure AD, Google Workspace), and your app trusts that system to authenticate users.

SAML (Security Assertion Markup Language) is the protocol that makes this work. It has been the enterprise SSO standard for over 20 years.

The actors

Identity Provider (IdP): The company’s authentication system. Okta, Azure AD, Google Workspace, OneLogin. The IdP knows who the employees are and authenticates them.

Service Provider (SP): Your app. The SP trusts the IdP to authenticate users and accepts the IdP’s assertions about who the user is.

The flow

1. User visits yourapp.com
2. Your app redirects to the company's IdP (e.g., Okta)
3. The user logs in at the IdP (if not already logged in)
4. The IdP creates a SAML assertion (signed XML) with user info
5. The IdP redirects back to your app with the assertion
6. Your app validates the assertion (checks the signature)
7. Your app creates a session for the user

This is similar to OAuth’s authorization code flow, but the data format is XML instead of JSON, the “token” is a signed assertion instead of a JWT, and the protocol predates OAuth by about a decade.

How SAML differs from OAuth

Both achieve the same goal (federated authentication), but SAML is the enterprise standard and OAuth/OIDC is the modern web standard. Many apps support both.

SAML assertions

A SAML assertion is a signed XML document that contains:

• Who: The user’s identity (email, name, employee ID)
• From: Which IdP issued the assertion
• For: Which SP the assertion is intended for
• When: When the assertion was issued and when it expires
• Signature: A cryptographic signature from the IdP

Your app validates the signature using the IdP’s public certificate (which you configure when setting up the integration). If the signature is valid, you trust the assertion.

Per-customer configuration

Unlike OAuth (where you configure one GitHub app and one Google app for all users), SAML is configured per-customer. Each enterprise customer has their own IdP with their own configuration: entity ID, login URL, certificate.

Your app stores this configuration in the saml_providers table (from the project setup). When a user from acmecorp.com tries to log in, you look up Acme Corp’s SAML configuration and redirect to their IdP.

Exercises

Exercise 1: If you have access to an Okta or Azure AD tenant, look at the SAML app configuration. What fields does it ask for? (Answer: SP entity ID, Assertion Consumer Service URL, and sometimes the SP’s certificate.)

Exercise 2: Compare the SAML flow to the OAuth flow from the OAuth course. Both redirect to an external provider and receive user info. How are they similar? How do they differ?