SAML SSO Authentication
Enterprise single sign-on for AI Security Gateway — configure Okta, Azure AD, Google Workspace, or any SAML 2.0 IdP.
When to use SSO
- Your compliance framework requires centralized identity management (SOC 2, HIPAA, ISO 27001)
- You need to enforce single sign-on across all AI governance tools
- Employee lifecycle management — onboarding and offboarding should be handled by your IdP
- You want domain-based access control so only corporate email addresses can access AISG
- Audit requirements demand a single authentication source of truth
Architecture
SSO is powered by BoxyHQ's SAML Jackson, running as a dedicated isolated service. Jackson handles all SAML protocol complexity and integrates with NextAuth for session management.
SAML Jackson (BoxyHQ)
Isolated ContainerOpen-source SAML 2.0 service provider. Handles SP-initiated SSO flows, assertion parsing, signature validation, and IdP metadata management. Runs as an isolated container with TLS termination.
NextAuth Integration
Web AppThe AISG web application uses NextAuth with a custom SAML provider. On successful assertion, NextAuth creates a session and auto-provisions the user into the correct organization with the configured default role.
SSO Request Routing
Edge LayerSSO requests are routed through a path-rewrite layer to the Jackson service. All SAML traffic is encrypted in transit end-to-end.
Supported Identity Providers
Okta
Full SAML 2.0 app integration with attribute mapping. Most common enterprise IdP — tested extensively.
Setup: Create a SAML app in Okta Admin → paste ACS URL and Entity ID → download metadata XML or copy metadata URL.
Azure AD (Entra ID)
Enterprise Application registration with SAML SSO. Supports group-based assignment and conditional access policies.
Setup: Register an Enterprise Application → configure SAML SSO → set ACS URL and Entity ID → download Federation Metadata XML.
Google Workspace
Custom SAML app in Google Admin console. Supports organizational unit scoping for granular rollout.
Setup: Add a custom SAML app in Google Admin → enter ACS URL and Entity ID → download IdP metadata → assign to users/OUs.
Any SAML 2.0 IdP
Standard SAML 2.0 SP-initiated flow. Works with JumpCloud, OneLogin, PingIdentity, Auth0, Keycloak, and others.
Setup: Configure your IdP with the ACS URL and Entity ID below → provide the metadata URL or upload metadata XML.
How It Works
User enters email
User navigates to the login page and enters their email address
Domain check
AISG checks if the email domain has an SSO connection configured for any org
SSO redirect
If SSO is configured, the user sees an SSO banner and is redirected to their IdP via SAML Jackson
IdP authentication
User authenticates with their identity provider (password, MFA, etc.)
SAML assertion
IdP sends a signed SAML assertion back to Jackson with user attributes
Session created
Jackson validates the assertion → NextAuth creates a session → user is auto-provisioned into the org with the configured default role
Configuration
Configure SSO from the dashboard at Settings → SSO. The setup wizard guides you through three steps.
- 1
Choose your identity provider
Select Okta, Azure AD, Google Workspace, or "Other SAML 2.0" from the provider dropdown.
- 2
Provide IdP metadata
Paste a metadata URL (recommended — auto-refreshes certificates) or upload a metadata XML file from your IdP.
- 3
Configure domains & options
Add your corporate email domains, set the default role for new users, and choose whether to enforce SSO or allow password fallback.
Per-Organization Settings
| Field | Type | Description |
|---|---|---|
| enforceSso | boolean | When enabled, users with a matching email domain must authenticate via SSO. Password login is blocked for those domains. |
| allowedDomains | string[] | Email domains linked to this SSO connection (e.g. acme.com, acme.co.uk). Users with these domains are routed to the org's IdP. |
| defaultRole | enum | Role assigned to auto-provisioned users: MEMBER (recommended default) or ADMIN. Existing users keep their current role on re-login. Warning: if autoProvision is enabled, setting defaultRole to ADMIN means anyone with a matching email domain gets admin rights on first login — use MEMBER and promote individually. |
| autoProvision | boolean | Automatically create user accounts on first SSO login. When disabled, only pre-invited users can authenticate. |
IdP Setup Reference
Use these values when configuring the SAML application in your identity provider.
| Parameter | Value |
|---|---|
| ACS URL (Reply URL) | https://api.aisecuritygateway.ai/sso/api/oauth/saml |
| Entity ID (Audience URI) | https://aisecuritygateway.ai |
| NameID Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Binding | HTTP-POST |
Attribute Mapping
| Attribute | Required | Notes |
|---|---|---|
| Required | Used as the unique identifier. Can be sent as NameID or as an attribute. | |
| firstName | Optional | Populates the user's first name in their AISG profile. |
| lastName | Optional | Populates the user's last name in their AISG profile. |
Security Guarantees
Isolated Jackson Service
SAML Jackson runs as a dedicated isolated service. It handles all SAML protocol complexity — assertion parsing, signature validation, and response generation — fully isolated from the main application.
No Assertion Storage
SAML assertions are validated and consumed in real-time. Raw XML assertions are never persisted. Only the extracted user attributes (email, name) are used to create or update the session.
Encrypted Connection Storage
SSO connection metadata (IdP endpoints, certificates, configuration) is encrypted at rest. No connection data is stored in application memory or local filesystems.
Role-Based Auto-Provisioning
New users are assigned the org's configured default role. Auto-provisioning can be disabled entirely, requiring admins to pre-invite users before they can authenticate via SSO.
Domain-Based Enforcement
SSO enforcement is scoped to specific email domains. Users outside the allowed domains are unaffected and can continue using standard authentication methods.
Multi-Tenant Routing
Each organization has its own SSO connection. Jackson routes SAML requests to the correct IdP based on the user's email domain, supporting multiple orgs with different IdPs on a single deployment.
Frequently Asked Questions
Can I use SSO alongside password login?
Yes. SSO enforcement is optional and domain-scoped. If enforceSso is disabled, users with SSO-linked domains can choose either SSO or password login. If enforced, only SSO is allowed for those domains — other users in the org can still use passwords.
What happens when an employee leaves the company?
When you deactivate a user in your IdP, they can no longer authenticate via SSO. Their AISG session expires naturally (or you can revoke it manually). No action is needed in the AISG dashboard — the IdP is the source of truth.
Can different organizations use different IdPs?
Yes. Each organization configures its own SSO connection independently. One org can use Okta while another uses Azure AD. Jackson routes to the correct IdP based on the email domain.
Does SSO support multi-factor authentication?
MFA is handled by your identity provider. If your IdP requires MFA (e.g. Okta Verify, Microsoft Authenticator), users must complete MFA during the IdP authentication step before being redirected back.
What SAML attributes are required?
Only email is required (sent as the NameID or an email attribute). firstName and lastName are optional — if provided, they populate the user profile. Group or role attributes are not currently mapped.
Ready to configure SSO?
Set up SAML SSO for your organization in minutes. Enterprise plan required.
Join the Community
Want to self-host this?
AI Security Gateway is open source. Deploy the core AI security proxy on your own infrastructure — PII redaction, prompt injection blocking, and secret detection included. No account required.