Home Realm Discovery

Home realm discovery inspects an email address and returns the appropriate login method. It determines whether a user may use local credentials such as password or Email OTP, or must be redirected to their organization's SSO identity provider.

How it works#

1. Extract the email domain
2. Check active verified organization-domain claims with active SSO connections
3. If no verified claim matches, check the legacy operator-managed organization PrimaryDomain
4. If a match has enabled SSO metadata, check the connection enrollment policy
5. Return sso when either the email belongs to an existing verified organization member and existing-member SSO is required, or no existing member matches and JIT provisioning is enabled
6. Otherwise return password, meaning local credentials are allowed

Verified domains are created by delegated SSO setup. The customer admin publishes a TXT record such as _sqlos-verify.acme.com with a sqlos-domain-verification=... value. SqlOS verifies that record before the domain participates in home realm discovery. Existing dashboard-managed PrimaryDomain values continue to work as a fallback.

Portal-created SSO connections default to requiring SSO for existing verified members and leaving JIT provisioning off. That means unknown users at a verified SSO domain continue to get the default local credential flow until an admin enables JIT provisioning or creates the membership another way.

SDK#

var discovery = await discoveryService.DiscoverAsync(
    new SqlOSHomeRealmDiscoveryRequest("user@acme.com"), ct);
 
switch (discovery.Mode)
{
    case "sso":
        // Redirect to IdP via SqlOSSsoAuthorizationService
        break;
    case "password":
        // Show the configured local credential method:
        // password, Email OTP, or provider buttons
        break;
}

API#

curl -X POST http://localhost:5062/api/v1/auth/discover \
  -H "Content-Type: application/json" \
  -d '{"email": "user@acme.com"}'

Response:

{
  "mode": "password",
  "organizations": []
}

Or for an SSO user:

{
  "mode": "sso",
  "organizationId": "org_...",
  "ssoConnectionId": "sso_..."
}

Usage in the login UI#

The example apps use discovery as the first step of login. The user enters their email, the app calls discover, and then shows the configured local credential method or redirects to SSO. If the mode is password, the UI can show password, Email OTP, and configured OIDC providers, depending on AuthPage settings.