SAML SSO

SqlOS supports SAML 2.0 enterprise SSO. Each organization can have its own SSO connection, and users with matching email domains are automatically routed to their organization's identity provider.

Setup

1. Create an SSO draft

SDK:

var draft = await adminService.CreateSsoConnectionDraftAsync(new CreateSsoConnectionDraftRequest
{
    OrganizationId = org.Id,
    DisplayName = "Acme Entra SSO",
    PrimaryDomain = "acme.com",
    AutoProvisionUsers = true,
    AutoLinkByEmail = true
});

Admin API:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-connections/draft \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_...",
    "displayName": "Acme Entra SSO",
    "primaryDomain": "acme.com",
    "autoProvisionUsers": true,
    "autoLinkByEmail": true
  }'

After creation, SqlOS generates two values you need for your IdP:

Value	IdP field (Entra)
SP Entity ID	Identifier (Entity ID)
ACS URL	Reply URL (Assertion Consumer Service URL)

2. Configure your IdP

In Microsoft Entra ID (or any SAML IdP):

1. Create a new Enterprise Application > SAML
2. Set Identifier (Entity ID) to the SP Entity ID from the draft
3. Set Reply URL to the ACS URL from the draft
4. Download the Federation Metadata XML

3. Import metadata

curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-connections/{connectionId}/metadata \
  -H "Content-Type: application/json" \
  -d '{"metadataXml": "<?xml version=\"1.0\" ...>"}'

The connection is now active. Users with @acme.com emails will be routed to Entra for authentication.

Options

Option	Default	Description
autoProvisionUsers	false	Create SqlOS users from SAML assertions on first login
autoLinkByEmail	false	Link SAML logins to existing users by email match

SSO login flow

1. User enters email on the login page
2. Home realm discovery detects the @acme.com domain matches an SSO connection
3. AuthServer generates a SAML AuthnRequest and redirects to the IdP
4. User authenticates at the IdP
5. IdP POSTs a SAML Response to the ACS URL
6. AuthServer validates the assertion, provisions/links the user, and creates a session