SAML SSO

SqlOS supports SAML 2.0 enterprise SSO. Each organization can have its own connection. Home realm discovery routes a matching email domain only when that connection is complete, enabled, and its enrollment policy applies to the user.

For a complete customer IT administrator journey, use Let customer admins set up enterprise SSO. For the platform-team workflow, use Set up SAML SSO.

Setup#

You can configure SAML in three ways:

• Code-first setup: your application declares a stable-keyed connection that SqlOS reconciles on startup.
• 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.

Code-first connection#

Use a seed when the organization and IdP configuration are deployment topology that should be reproducible in source control. Keep the public signing certificate or metadata in host configuration; SqlOS does not call a cloud key service or fetch a remote metadata URL.

var metadataXml = builder.Configuration["SqlOS:Saml:Acme:MetadataXml"]
    ?? throw new InvalidOperationException("Acme SAML metadata is not configured.");
 
options.AuthServer.SeedSamlConnection("acme-workforce", saml =>
{
    saml.OrganizationSlug = "acme";
    saml.DisplayName = "Acme workforce SSO";
    saml.MetadataXml = metadataXml;
    saml.PrimaryDomain = "acme.com";
    saml.AutoProvisionUsers = false;
    saml.AutoLinkByEmail = true;
});

You can provide IdentityProviderEntityId, SingleSignOnUrl, and X509CertificatePem instead of MetadataXml. Do not provide both modes. The certificate is public verification material, but treating deployment-specific metadata as configuration keeps customer topology out of a shared source tree.

The stable key—not the display name—owns reconciliation. Code-owned fields update on restart, renames preserve the same record, and unrelated dashboard-owned connections are never adopted. Removing a seed marks the record orphaned without deleting or silently disabling a live enterprise connection. A dashboard emergency disable survives restart; setting IsEnabled = false in code can disable an existing connection, while true only controls initial creation and does not undo an operator disable.

The dashboard labels code-owned connections and makes their metadata editor read-only. Operators can still emergency-disable or re-enable the connection. Metadata changes are normalized through the same parser used by the dashboard/API, must contain an absolute HTTPS SSO URL and a currently valid X.509 certificate, and are written to the audit log without certificate contents.

1. Create an SSO draft#

SDK:

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

Admin API:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-connections/draft \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_...",
    "displayName": "Acme Entra SSO",
    "primaryDomain": "acme.com",
    "autoProvisionUsers": false,
    "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 \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H "Content-Type: application/json" \
  -d '{"metadataXml": "<?xml version=\"1.0\" ...>"}'

The connection is now active. With the conservative examples above, existing organization members with verified @acme.com email addresses are routed to Entra on their next sign-in, while unknown users are not JIT-provisioned. Set AutoProvisionUsers/autoProvisionUsers to true only when you intentionally want a valid SAML assertion to create the missing user or membership.

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 \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -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 \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H "Content-Type: application/json" \
  -d '{"reason": "customer_cancelled"}'

These platform-admin endpoints require an operator session; see Authenticate operator API calls. Portal-scoped endpoints use the separate organization setup-session cookie described below.

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.

An active SCIM-provisioned member can also complete that first subject link when AutoLinkByEmail is false. This narrow path requires an enabled SCIM connection, an active and non-deleted SCIM user record, and an active membership in the same organization, plus an exact normalized match between the signed SAML assertion's email attribute and the SCIM record's current primary email. A login hint is not sufficient. A disabled connection, a SCIM record from another organization, a stale email alias, or any deactivated/deleted SCIM state is not accepted. This does not enable general email auto-linking.

Home realm discovery still follows RequireSsoForExistingMembers: when it is disabled, email-first discovery does not force an existing member into SSO. The SCIM-provenance exception applies after a client explicitly starts that organization's SAML connection. Enable RequireSsoForExistingMembers when existing members should be routed to SSO automatically.

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.

Every first-time email link and every JIT provision requires the configured email attribute in the signed SAML assertion. The login hint used for discovery and routing is never accepted as an authenticated email claim. An already-linked IdP subject can continue to resolve its existing user without an email attribute.

JIT provisioning never reactivates an existing inactive membership, and SAML callbacks reject inactive users and inactive organizations. This preserves offboarding even when the IdP still sends a valid assertion for a previously linked subject. Re-enable the user or membership through an explicit trusted workflow before allowing another SAML login.

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. That action invalidates matching-domain OAuth and hosted AuthPage sessions for the organization.

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:

When /test includes clientId and redirectUri, it must also include a fresh state, an S256 codeChallenge, and codeChallengeMethod: "S256". The bundled portal generates these values with Web Crypto. A host-owned portal should do the same; first-factor or portal-session state is never a substitute for PKCE.

Options#

Upstream MFA trust#

SqlOS extracts AuthnContextClassRef only from the signature-covered assertion. A SAML connection does not satisfy local MFA merely because the primary method is saml.

Platform-admin connection creation can opt in explicitly:

{
  "organizationId": "org_example",
  "displayName": "Workforce SSO",
  "identityProviderEntityId": "https://idp.example.com",
  "singleSignOnUrl": "https://idp.example.com/sso",
  "x509CertificatePem": "-----BEGIN CERTIFICATE-----...",
  "autoProvisionUsers": true,
  "autoLinkByEmail": false,
  "trustUpstreamMfa": true,
  "acceptedAuthnContextClassRefs": [
    "urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken"
  ]
}

Comparisons are exact per connection. Missing or unrecognized context leaves MFA unsatisfied, so the normal local step-up policy runs. Accepted evidence adds upstream_mfa alongside the saml primary method and records the assertion issuer, accepted class reference, and decision in the audit event.

Only allowlist class references whose meaning you have verified for that IdP tenant. A URI name alone is not a guarantee that the upstream policy actually required a second factor.

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. The client generates a high-entropy PKCE verifier, its S256 challenge, and a state value. The verifier must be 43–128 RFC 7636 unreserved characters; generating 32 random bytes and base64url-encoding them produces the recommended 43-character verifier. The S256 challenge is exactly 43 base64url characters.
2. User enters email on the login page.
3. Home realm discovery detects the @acme.com domain and checks the connection enrollment policy.
4. AuthServer binds the client, exact registered redirect URI (including path case), state, and validated S256 challenge to the SAML authorization request, then redirects to the IdP.
5. User authenticates at the IdP.
6. IdP POSTs a SAML Response to the ACS URL.
7. AuthServer validates the assertion, requires an explicitly bounded bearer SubjectConfirmationData, and atomically records the signed Response ID and Assertion ID before returning an authorization code. Reuse of either identifier on the same connection is rejected, including concurrent replay.
8. The client posts the code, client ID, exact redirect URI, and verifier to /sqlos/auth/token. Missing, wrong, downgraded, or plain PKCE is rejected.

Use canonical /sqlos/auth/authorize and /sqlos/auth/token for hosted clients. The explicit /sqlos/auth/sso/authorization-url helper is retained for connection-directed flows, but it requires state, codeChallenge, and codeChallengeMethod: "S256" and produces the same PKCE-bound authorization-code record. The old /sqlos/auth/token/exchange and /sqlos/auth/saml/login/{connectionId} routes are retired.

Replay protection uses SqlOS's existing SQL database and expires records after the assertion validity window plus clock skew. It is automatic: applications do not configure a cache or external coordination service.