AuthServer
AuthServer Overview
Identity, sessions, organizations, and SSO in one embedded module.
AuthServer is SqlOS's identity piece. Users, orgs, sessions, OAuth tokens, social OIDC, and SAML run inside your app. Data lives in your database. For applications, SqlOS is an OAuth authorization server; for Google, Microsoft, Apple, and custom social login, it acts as an OIDC relying party.
Recommended reading order
- Dashboard → Organizations → Hosted vs headless
- Password login, Email OTP, Magic Link, or Phone OTP → OIDC / SAML / SCIM
- Security policy: MFA and TOTP and Security Settings
- One app: Single-Application Setup
- Advanced: Clients, Application Access, CIMD, DCR -- only when you need them
What you get#
Organizations
Multi-tenant orgs, memberships, and roles.
Users
Password, email code, magic link, phone code, SSO-provisioned, or OIDC-linked identities.
Sessions
JWT access tokens, refresh token rotation, and replay detection.
MFA and recovery codes
Optional self-enrollment, tenant-required TOTP, and recovery-code challenges.
OIDC
Google, Microsoft, GitHub, Apple, and custom providers.
SAML SSO
Enterprise SSO with provisioning and hosted flows.
SCIM
Directory provisioning, deprovisioning, and FGA group sync.
Invitations
Email-bound organization invites with hosted, headless, and SDK acceptance.
CLI OAuth
Device Authorization Grant for terminal apps and remote sessions.
Hosted or headless
Use the built-in pages or render your own UI on top of the same runtime.
Setup#
builder.AddSqlOS<AppDbContext>();
var app = builder.Build();
app.MapSqlOS();Auth flow#
Typical browser login:
- App sends the user to
/sqlos/auth/authorizewith PKCE. - User chooses an enabled credential. Email-first flows use home realm discovery to pick password, Email OTP, a magic link, or SSO.
- User signs in (password, email or phone OTP, magic link, OIDC, or SAML).
- Multiple orgs? User picks one.
- MFA required? SqlOS renders or returns a TOTP challenge or forced enrollment step.
- SqlOS returns an auth code.
- App trades the code for access and refresh tokens.
Start with owned clients first
For most teams, the first production flow should use a seeded or dashboard-created owned client. Add CIMD, DCR, and resource indicators only when you actually need portable or compatibility clients.
Dashboard#
Open /sqlos/admin/auth/. Manage orgs, users, memberships, clients, OIDC, SSO, security, and sessions there.
SDK services#
| Service | Purpose |
|---|---|
SqlOSAuthService | Login, email and phone OTP, magic links, invitations, refresh, logout, token validation |
SqlOSAdminService | Create orgs, users, memberships, clients, SSO |
SqlOSCryptoService | Token generation, PKCE, password hashing, JWKS |
SqlOSHomeRealmDiscoveryService | Route users to password or SSO by email domain |
SqlOSSsoAuthorizationService | SAML SSO authorization and code exchange |
SqlOSOidcAuthService | Google, Microsoft, GitHub, Apple, and custom social login |
SqlOSSettingsService | Session lifetimes and security configuration |
Hosted and headless#
Hosted auth
SqlOS renders the login, signup, invitation, OTP, and recovery pages for you. This is the fastest path for internal tools and most first-party apps.
Headless auth
SqlOS still runs OAuth authorization, sessions, token issuance, and its social OIDC relying-party flows. Your application takes ownership of the login UI and interaction flow.
Client onboarding modes
Use seeded or dashboard-created owned clients for the normal path. Reach for CLI device flow, CIMD, and optional DCR when you need terminal, portable, or compatibility-oriented clients.
Headless Auth · Email OTP · Magic Link · Phone OTP · MFA and TOTP · Email Invitations · SAML SSO · SCIM Directory Sync · CLI OAuth · Hosted vs Headless