SAML 2.0 (Security Assertion Markup Language) is an OASIS standard for XML-based single sign-on. An Identity Provider (IdP) authenticates a user and issues a signed assertion; a Service Provider (SP) trusts the IdP and grants the user access. Messages are carried over HTTP using bindings — most commonly HTTP-POST (form POST) and HTTP-Redirect (query string with signature).
LumoAuth can act as either side of a SAML trust. Use this API to accept logins from a corporate IdP or to issue assertions to a SAML-enabled application.
Dual Mode Architecture
LumoAuth supports two SAML modes:
| Mode | LumoAuth Role | Use Case |
|---|
| Service Provider (SP) | Consumes SAML assertions from external IdPs | Let users log in via corporate IdPs (Okta, Azure AD, ADFS) |
| Identity Provider (IdP) | Issues SAML assertions to SP applications | Enable SSO to SAML apps (Salesforce, Box, Slack, custom apps) |
SAML Endpoints Reference
Service Provider Endpoints
Use these when LumoAuth acts as the SP, accepting logins from external IdPs:
| Endpoint | Method | Description |
|---|
/orgs/\{orgId\}/saml/sp/metadata | GET | SP Metadata XML document |
/orgs/\{orgId\}/saml/sp/login | GET | Initiate SSO (redirects to IdP) |
/orgs/\{orgId\}/saml/sp/login/\{idpId\} | GET | Initiate SSO with specific IdP |
/orgs/\{orgId\}/saml/sp/acs | POST | Assertion Consumer Service (receives SAML Response) |
/orgs/\{orgId\}/saml/sp/slo | GET/POST | Single Logout Service |
Identity Provider Endpoints
Use these when LumoAuth acts as the IdP, issuing assertions to SP applications:
| Endpoint | Method | Description |
|---|
/orgs/\{orgId\}/saml/idp/metadata | GET | IdP Metadata XML document |
/orgs/\{orgId\}/saml/idp/sso | GET/POST | Single Sign-On Service (receives AuthnRequest) |
/orgs/\{orgId\}/saml/idp/slo | GET/POST | Single Logout Service |
Key Concepts
| Term | Description |
|---|
| Entity ID | Unique identifier for an SP or IdP, typically a URL |
| Metadata | XML document describing endpoints, certificates, and capabilities |
| AuthnRequest | SAML authentication request sent from SP to IdP |
| SAML Response | Signed XML containing one or more assertions |
| Assertion | Signed statement containing user identity and attributes |
| NameID | User identifier in SAML (email, persistent ID, transient) |
| ACS URL | Assertion Consumer Service — where responses are sent |
| SLO | Single Logout — terminates sessions across all parties |
Security Features
| Feature | Description | Default |
|---|
| Response Signing | Entire SAML Response is cryptographically signed | Enabled |
| Assertion Signing | Individual assertions are signed | Enabled |
| Assertion Encryption | Assertions encrypted with SP's certificate | Optional |
| Signature Verification | Verify signatures from IdP/SP | Required |
| Audience Restriction | Assertions only valid for intended SP | Enforced |
| Replay Protection | Assertions cannot be reused | Enforced |
Getting Started
The simplest setup uses metadata URL exchange: provide your SP's metadata URL to LumoAuth and LumoAuth's metadata URL to your SP. This keeps endpoints and certificates synchronized on both sides.
| Format | URN | Typical Use |
|---|
| Email Address | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress | Most common, matches on email |
| Persistent | urn:oasis:names:tc:SAML:2.0:nameid-format:persistent | Stable identifier, survives email changes |
| Transient | urn:oasis:names:tc:SAML:2.0:nameid-format:transient | Session-specific, privacy-focused |
| Unspecified | urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified | SP determines interpretation |
Glossary
| Term | Definition |
|---|
| SAML | Security Assertion Markup Language — XML-based SSO standard |
| SSO | Single Sign-On — one login for multiple applications |
| IdP | Identity Provider — authenticates users and issues assertions |
| SP | Service Provider — application that accepts SAML assertions |
| JIT Provisioning | Just-in-Time user creation on first SAML login |
| X.509 | Standard for digital certificates used in SAML signing |
Reference Specifications