SAML 2.0 SSO

Atomic Reactor supports SAML 2.0 Single Sign-On (SSO), letting organizations authenticate users with their existing Identity Provider (IdP) — Okta, Azure AD, Google Workspace, Shibboleth, and others.

How it works

Atomic Reactor acts as the Service Provider (SP); your organization’s IdP authenticates users. The flow is SP-initiated:

1. A user visits /saml/{tenant_id}/login.
2. Atomic Reactor generates a SAML AuthnRequest and redirects to your IdP.
3. The user authenticates with the IdP.
4. The IdP posts a signed assertion back to Atomic Reactor’s Assertion Consumer Service (ACS).
5. Atomic Reactor validates the assertion, provisions the user (JIT), and signs them in.

Key capabilities

• Just-in-time provisioning — users are created automatically on first login.
• Attribute mapping — map SAML attributes to user fields (email, first/last name, display name).
• Role mapping — map SAML groups or affiliations to Atomic Reactor roles.
• Multi-tenant — each tenant can use a different IdP, with isolated configuration.
• Auto-generated SP certificates — 2048-bit RSA keys, encrypted at rest (AES-256-GCM).

Security

SAML validation follows the OWASP SAML Security Cheat Sheet, including XML signature verification, timestamp and audience checks, recipient validation, and Redis-backed replay-attack prevention. IdP-initiated SSO is disabled by default. All SAML traffic must use HTTPS in production.

Note

Redis is required for SAML because assertion IDs are tracked to prevent replay attacks. See Configuration.

Getting started

1. Create a SAML configuration for your tenant via the admin API:

   POST /api/admin/saml/config
   Content-Type: application/json
   
   {
     "idp_entity_id": "http://idp.example.com/metadata",
     "idp_sso_url": "https://idp.example.com/sso",
     "idp_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
     "attribute_mappings": {
       "email": "email",
       "first_name": "firstName",
       "last_name": "lastName"
     },
     "enabled": true
   }

   SP entity ID and certificates are auto-generated if not supplied.

2. Download SP metadata to configure in your IdP:

   GET /saml/{tenant_id}/metadata

3. Configure the IdP — upload the SP metadata, set attribute mappings, enable signed assertions, and copy the IdP entity ID, SSO URL, and X.509 certificate back into the SAML configuration.

4. Test the flow by visiting https://your-domain.com/saml/{tenant_id}/login.

Public endpoints

Method	Endpoint	Description
GET	/saml/{tenant_id}/metadata	SP metadata XML
GET	/saml/{tenant_id}/login	Initiate SSO login
POST	/saml/{tenant_id}/acs	Assertion Consumer Service
POST	/saml/{tenant_id}/slo	Single Logout Service

Admin configuration endpoints live under /api/admin/saml/* and require admin.saml.* permissions. For full schemas, see the API Reference.