Enterprise SSO

Atlas supports enterprise SSO via SAML 2.0 and OpenID Connect (OIDC). Admins register identity providers through the admin API, map email domains to providers, and users are auto-provisioned on first login.

How It Works

1. An admin registers an SSO provider (SAML or OIDC) via the admin API
2. The provider is linked to an email domain (e.g., acme.com)
3. When a user with that email domain signs in, Atlas routes them to the configured IdP
4. On successful IdP authentication, the user is auto-provisioned into the workspace

Each organization can have multiple SSO providers, each mapped to a different email domain. Domain uniqueness is enforced globally — no two providers across any organization can claim the same domain.

SAML Configuration

SAML providers require three pieces of information from your identity provider:

Optional fields for service provider (SP) configuration:

Register a SAML Provider

curl -X POST https://your-atlas.example.com/api/v1/admin/sso/providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "type": "saml",
    "issuer": "https://idp.acme.com",
    "domain": "acme.com",
    "enabled": true,
    "config": {
      "idpEntityId": "https://idp.acme.com/entity",
      "idpSsoUrl": "https://idp.acme.com/sso",
      "idpCertificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
    }
  }'

OIDC Configuration

OIDC providers require:

Register an OIDC Provider

curl -X POST https://your-atlas.example.com/api/v1/admin/sso/providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "type": "oidc",
    "issuer": "https://accounts.google.com",
    "domain": "acme.com",
    "enabled": true,
    "config": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "discoveryUrl": "https://accounts.google.com/.well-known/openid-configuration"
    }
  }'

Admin API Endpoints

All SSO endpoints require the admin role and an active enterprise license. They are mounted at /api/v1/admin/sso.

Error Responses

Domain Auto-Provisioning

When a user signs in with an email matching a configured SSO domain:

1. Atlas calls findProviderByDomain() to locate the matching, enabled SSO provider
2. The user is redirected to the IdP for authentication
3. On successful authentication, Atlas creates or updates the user account
4. The user is added to the organization that owns the SSO provider

Domain format requirements:

• Lowercase letters, numbers, hyphens, and dots
• Must be a valid DNS domain (e.g., acme.com, engineering.acme.com)
• Validated against the pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$

SSO Enforcement

By default, SSO is an optional login method — users with a matching email domain are routed to the IdP, but password login remains available. SSO enforcement changes this: when enabled, password and email-based login is blocked for all users whose email domain matches a configured SSO provider. They must sign in through the identity provider.

Enforcement is an organization-level setting. When toggled, it updates the sso_enforced flag on all SSO providers belonging to that organization.

What Happens When Enforcement Is On

1. A user attempts to sign in with email alice@acme.com
2. Atlas detects that acme.com has an SSO provider with enforcement enabled
3. The password/session auth is blocked with a 403 response:

   {
     "error": "SSO is required for this workspace. Please sign in via your identity provider.",
     "ssoRedirectUrl": "https://idp.acme.com/sso"
   }

4. The response includes ssoRedirectUrl so the client can redirect the user to the IdP

Check Enforcement Status

curl https://your-atlas.example.com/api/v1/admin/sso/enforcement \
  -H "Authorization: Bearer <admin-token>"

Response (200):

{
  "enforced": false,
  "orgId": "org_abc123"
}

Enable Enforcement

curl -X PUT https://your-atlas.example.com/api/v1/admin/sso/enforcement \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{ "enforced": true }'

Response (200):

{
  "enforced": true,
  "orgId": "org_abc123"
}

Disable Enforcement

curl -X PUT https://your-atlas.example.com/api/v1/admin/sso/enforcement \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{ "enforced": false }'

{
  "error": "no_provider",
  "message": "Cannot enforce SSO without at least one active SSO provider. Create and enable a SAML or OIDC provider first."
}

Enforcement and Existing Users

When you enable SSO enforcement:

• Active sessions are not terminated. Users already signed in continue to have access until their session expires
• New sign-in attempts via password are blocked. Users must use the SSO flow on their next login
• API key access is unaffected. The simple-key auth mode bypasses SSO enforcement, providing a break-glass path for administrators

When you disable SSO enforcement:

• Password login is immediately available again for all users
• SSO login continues to work — disabling enforcement does not remove SSO providers

SAML vs OIDC

Choose SAML when your IdP mandates it or for compliance requirements. Choose OIDC for simpler setup with modern identity providers.

See Also

• IP Allowlisting — Restrict access by IP range
• Authentication — Auth mode setup and configuration
• Admin Console — Manage users and sessions
• Environment Variables — Full variable reference