Enterprise SSO (SAML)

Codapult includes enterprise-grade SSO via BoxyHQ Jackson, supporting SAML 2.0 identity providers (Okta, Azure AD, Google Workspace, OneLogin, etc.).

When to Use SSO

SSO is typically required by enterprise customers who need:

• Centralized user management through their identity provider
• Automatic provisioning/deprovisioning via SCIM (see Teams)
• Compliance with corporate security policies

Environment Variables

SSO_PROVIDER="jackson"
SSO_PRODUCT="your-product-name"

# Production: use Postgres for durable storage
SSO_DB_ENGINE="sql"
SSO_DB_TYPE="postgres"
SSO_DB_URL="postgres://user:password@host:5432/jackson"

For development, Jackson defaults to in-memory storage — no database configuration needed.

In server code, access the product identifier via env.sso.product from src/config/env.ts instead of reading process.env.SSO_PRODUCT directly.

Admin Setup

1. Go to Admin → Enterprise SSO
2. Click Add Connection
3. Enter the tenant slug (matches the organization) and paste the IdP metadata XML or URL
4. Share these values with the customer's IT team:

Sign-In Flow

1. User enters their email on the sign-in page
2. Codapult detects the SSO connection by email domain
3. User is redirected to their company's identity provider
4. After IdP authentication, the user is redirected back and signed in

Testing SSO Locally

Use a free SAML IdP for testing:

1. Create a test IdP at mocksaml.com or use samltest.id
2. Register your local ACS URL: http://localhost:3000/api/auth/sso/callback
3. Add the connection in the admin panel using the test IdP's metadata

For more details on Jackson configuration and supported IdPs, see the BoxyHQ Jackson docs.