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#

You can configure SAML in two ways:

• Platform-admin setup: your operator creates the draft and imports metadata from the dashboard or admin API.
• Delegated org-admin setup: your operator or host app creates a one-organization portal session, sends the setup link to the customer IT admin, and lets that admin complete the same SAML setup without access to the global dashboard.

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:

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. By default, existing organization members with verified @acme.com email addresses will be routed to Entra on their next sign-in. New users are not JIT-provisioned unless you explicitly enable that policy.

Delegated org-admin portal#

Create a portal session from the dashboard organization SSO tab or through the admin API:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-portal/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_...",
    "provider": "microsoft-entra"
  }'

The response includes a setupUrl. Send that URL with your own mailer or admin workflow. The first browser open consumes the URL token and stores an HttpOnly server-side portal session cookie. Reuse requires a new setup link.

The portal is scoped to one organization and supports:

• provider guides for Microsoft Entra, Okta, Google Workspace, and generic SAML
• copy-ready SP Entity ID and ACS URL values
• DNS TXT verification for self-serve organization email domains
• access-policy controls for existing-member SSO enrollment and optional JIT provisioning
• metadata XML paste or file upload
• validation before activation
• activation, disable, metadata replacement, and retest
• an explicit, confirm-gated action to sign out existing sessions after activation

Hosts can expose the same launch behavior from their own admin surfaces by wrapping SqlOSSsoPortalService.CreateSessionAsync, as the example app does with POST /api/sso-portal-links.

Revoke a setup link or portal session:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-portal/sessions/{sessionId}/revoke \
  -H "Content-Type: application/json" \
  -d '{"reason": "customer_cancelled"}'

Portal-scoped APIs live under /sqlos/admin/auth/sso-portal/api and require the portal session cookie. They cannot list users, clients, other organizations, or global dashboard pages.

Verified organization domains#

Self-serve SSO setup can claim an organization's email domain before home realm discovery trusts it. The portal asks the org admin for a domain such as acme.com, creates a pending claim, and returns a DNS TXT record:

When the TXT record is visible, the portal marks the domain active. Home realm discovery checks active verified domains first, then falls back to the legacy operator-managed PrimaryDomain field. This keeps existing platform-admin setups working while making self-serve domain claims authoritative.

SqlOS has no Azure dependency for this. The default verifier uses public DNS-over-HTTPS and is registered behind ISqlOSDomainDnsVerifier, so hosts can replace it with internal DNS, provider-specific DNS APIs, or a test fake.

Activation requires a verified self-serve domain by default when the organization does not already have an operator-managed primary domain. Disable that gate only when your own host app enforces equivalent ownership outside SqlOS.

options.AuthServer.ConfigureSsoPortal(portal =>
{
    portal.ReservedDomainRoots.Add("yourapp.com");
    portal.RequireVerifiedDomainForActivation = true;
});

Enrollment policy#

Portal-created connections default to:

• RequireSsoForExistingMembers = true
• AllowJitProvisioning = false

Internally these map to the existing connection flags:

• RequireSsoForExistingMembers maps to AutoLinkByEmail
• AllowJitProvisioning maps to AutoProvisionUsers

When RequireSsoForExistingMembers is enabled, a user who already belongs to the organization and has a verified email on the SSO domain is sent to SSO. The first successful SAML sign-in links the IdP subject to that existing user. SqlOS does not create a user or membership on this path.

When AllowJitProvisioning is enabled, a successful SAML sign-in may create the missing user or organization membership when no existing organization member matches the SAML email. Keep this disabled when access should be invitation- or admin-managed.

Activation only enables the SSO connection and HRD behavior. It does not revoke active sessions. Use the separate session revocation action when an admin intentionally wants existing matching-domain sessions to sign in again through SSO.

Headless setup state machine#

The hosted portal is optional. Configure BuildUiUrl to hand the opened portal session to your own admin UI, and call the setup API for state transitions.

options.AuthServer.ConfigureSsoPortal(portal =>
{
    portal.UseHostedPortal = false;
    portal.BuildUiUrl = ctx =>
        $"https://admin.example.com/sso/setup?session_id={ctx.SessionId}&view={ctx.View}";
});

Default setup API base path:

/sqlos/admin/auth/sso-portal/api/setup

Override it with SsoPortal.HeadlessApiBasePath. Keep it on the SqlOS origin or configure your host for credentialed browser requests, because the portal session is stored in an HttpOnly cookie.

The setup API returns SqlOSSsoSetupActionResult:

State-machine endpoints:

Options#

Provider notes#

For metadata rotation, open the delegated portal again or use the dashboard, paste or upload the new XML, review the parsed IdP values, and activate. New metadata is validated before it replaces the active configuration.

SSO login flow#

1. User enters email on the login page
2. Home realm discovery detects the @acme.com domain and checks the connection enrollment policy
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, links the existing user or provisions access only when policy allows it, and creates a session