AuthServer
AuthServer Overview
Identity, sessions, organizations, and SSO in one embedded module.
AuthServer is SqlOS's identity piece. Users, orgs, sessions, tokens, OIDC, and SAML run inside your app. Data lives in your database.
Recommended reading order
- Dashboard → Organizations → Hosted vs headless
- Password login or Email OTP → OIDC / SAML
- 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
Email/password, email OTP, 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.
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 enters email. Home realm discovery picks password, Email OTP, or SSO.
- User signs in (password, Email OTP, 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 OTP, 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 |
Signing keys and protected secrets#
SqlOS stores JWT signing keys in your application database. Private signing key PEMs are protected with SqlOSCryptoService.ProtectSecret when ASP.NET Data Protection is available, and legacy plaintext rows are upgraded the next time the active key is loaded.
Production deployments should configure a durable Data Protection key ring outside the application database. If Data Protection keys are lost, existing protected signing keys and other protected secrets cannot be unprotected.
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/OIDC, sessions, and token issuance. 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 · MFA and TOTP · Email Invitations · CLI OAuth · Hosted vs Headless