ObjectStackAuth Config
Auth Config protocol schemas
Better-Auth Configuration Protocol
Defines the configuration required to initialize the Better-Auth kernel.
Used in server-side configuration injection.
Source: packages/spec/src/system/auth-config.zod.ts
TypeScript Usage
import { AdvancedAuthConfig, AuthConfig, AuthPluginConfig, AuthProviderConfig, EmailAndPasswordConfig, EmailVerificationConfig, MutualTLSConfig, OidcProviderConfig, OidcProvidersConfig, SocialProviderConfig } from '@objectstack/spec/system';
import type { AdvancedAuthConfig, AuthConfig, AuthPluginConfig, AuthProviderConfig, EmailAndPasswordConfig, EmailVerificationConfig, MutualTLSConfig, OidcProviderConfig, OidcProvidersConfig, SocialProviderConfig } from '@objectstack/spec/system';
// Validate data
const result = AdvancedAuthConfig.parse(data);AdvancedAuthConfig
Advanced / low-level Better-Auth options
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| crossSubDomainCookies | Object | optional | Share auth cookies across subdomains (critical for *.example.com multi-tenant) |
| useSecureCookies | boolean | optional | Force Secure flag on cookies |
| disableCSRFCheck | boolean | optional | ⚠ Disable CSRF check — security risk, use with caution |
| cookiePrefix | string | optional | Prefix for auth cookie names |
AuthConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| secret | string | optional | Encryption secret |
| baseUrl | string | optional | Base URL for auth routes |
| uiBasePath | string | ✅ | Basename where the auth UI (Console) is mounted (default /_console) |
| databaseUrl | string | optional | Database connection string |
| providers | Object[] | optional | |
| plugins | Object | optional | |
| session | Object | optional | |
| trustedOrigins | string[] | optional | Trusted origins for CSRF protection. Supports wildcards (e.g. "https://*.example.com"). The baseUrl origin is always trusted implicitly. |
| socialProviders | Record<string, Record<string, any>> | optional | Social/OAuth provider map forwarded to better-auth socialProviders. Keys are provider ids (google, github, apple, …). |
| oidcProviders | Object[] | optional | List of OIDC/OAuth2 providers for enterprise SSO. Can also be provided via OIDC_PROVIDERS env var as a JSON array. |
| emailAndPassword | Object | optional | Email and password authentication options forwarded to better-auth |
| emailVerification | Object | optional | Email verification options forwarded to better-auth |
| advanced | Object | optional | Advanced / low-level Better-Auth options |
| mutualTls | Object | optional | Mutual TLS (mTLS) configuration |
AuthPluginConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| organization | boolean | ✅ | Enable Organization/Teams support (frontend AuthProvider expects this enabled) |
| twoFactor | boolean | ✅ | Enable 2FA |
| passkeys | boolean | ✅ | Enable Passkey support |
| magicLink | boolean | ✅ | Enable Magic Link login |
| oidcProvider | boolean | ✅ | Enable the OpenID Connect provider plugin (acts as an OIDC IdP) |
| deviceAuthorization | boolean | ✅ | Enable RFC 8628 Device Authorization Grant (CLI / TV-style login) |
| admin | boolean | ✅ | Enable platform admin operations (ban/unban, set-password, impersonate, set-role) |
AuthProviderConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | Provider ID (github, google) |
| clientId | string | ✅ | OAuth Client ID |
| clientSecret | string | ✅ | OAuth Client Secret |
| scope | string[] | optional | Requested permissions |
EmailAndPasswordConfig
Email and password authentication options forwarded to better-auth
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| enabled | boolean | ✅ | Enable email/password auth |
| disableSignUp | boolean | optional | Disable new user registration via email/password |
| requireEmailVerification | boolean | optional | Require email verification before creating a session |
| minPasswordLength | number | optional | Minimum password length (default 8) |
| maxPasswordLength | number | optional | Maximum password length (default 128) |
| resetPasswordTokenExpiresIn | number | optional | Reset-password token TTL in seconds (default 3600) |
| autoSignIn | boolean | optional | Auto sign-in after sign-up (default true) |
| revokeSessionsOnPasswordReset | boolean | optional | Revoke all other sessions on password reset |
EmailVerificationConfig
Email verification options forwarded to better-auth
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| sendOnSignUp | boolean | optional | Automatically send verification email after sign-up |
| sendOnSignIn | boolean | optional | Send verification email on sign-in when not yet verified |
| autoSignInAfterVerification | boolean | optional | Auto sign-in the user after email verification |
| expiresIn | number | optional | Verification token TTL in seconds (default 3600) |
MutualTLSConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| enabled | boolean | ✅ | Enable mutual TLS authentication |
| clientCertRequired | boolean | ✅ | Require client certificates for all connections |
| trustedCAs | string[] | ✅ | PEM-encoded CA certificates or file paths |
| crlUrl | string | optional | Certificate Revocation List (CRL) URL |
| ocspUrl | string | optional | Online Certificate Status Protocol (OCSP) URL |
| certificateValidation | Enum<'strict' | 'relaxed' | 'none'> | ✅ | Certificate validation strictness level |
| allowedCNs | string[] | optional | Allowed Common Names (CN) on client certificates |
| allowedOUs | string[] | optional | Allowed Organizational Units (OU) on client certificates |
| pinning | Object | optional | Certificate pinning configuration |
OidcProviderConfig
OIDC / Generic OAuth2 provider configuration for enterprise SSO
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| providerId | string | ✅ | Unique identifier for this provider (e.g., okta, azure-ad) |
| name | string | optional | Display name shown in the UI (defaults to providerId) |
| discoveryUrl | string | optional | OIDC discovery URL (.well-known/openid-configuration). When provided, authorizationUrl/tokenUrl/userInfoUrl are fetched automatically. |
| issuer | string | optional | Expected issuer identifier for token validation |
| authorizationUrl | string | optional | OAuth2 authorization endpoint (optional if discoveryUrl is set) |
| tokenUrl | string | optional | OAuth2 token endpoint (optional if discoveryUrl is set) |
| userInfoUrl | string | optional | OAuth2 userinfo endpoint (optional if discoveryUrl is set) |
| clientId | string | ✅ | OAuth2 client ID |
| clientSecret | string | ✅ | OAuth2 client secret |
| scopes | string[] | optional | Requested scopes (default: openid email profile) |
| pkce | boolean | optional | Enable PKCE (recommended for public clients) |