Auth Config Auth Config protocol schemas
Source: packages/spec/src/system/auth-config.zod.ts
import { AdvancedAuthConfigSchema, AudienceConfigSchema, AuthConfigSchema, AuthPluginConfigSchema, AuthProviderConfigSchema, EmailAndPasswordConfigSchema, EmailVerificationConfigSchema, MutualTLSConfigSchema, OidcProviderConfigSchema, OidcProvidersConfigSchema, SocialProviderConfigSchema } from '@objectstack/spec/system' ; import type { AdvancedAuthConfig, AudienceConfig, AuthConfig, AuthPluginConfig, AuthProviderConfig, EmailAndPasswordConfig, EmailVerificationConfig, MutualTLSConfig, OidcProviderConfig, OidcProvidersConfig, SocialProviderConfig } from '@objectstack/spec/system' ; // Validate data const result = AdvancedAuthConfigSchema. parse (data); Advanced / low-level Better-Auth options
Property Type Required Description crossSubDomainCookies { enabled: boolean; additionalCookies?: string[]; domain?: string }optional Share auth cookies across subdomains (critical for *.example.com multi-tenant) useSecureCookies booleanoptional Force Secure flag on cookies disableCSRFCheck booleanoptional ⚠ Disable CSRF check — security risk, use with caution cookiePrefix stringoptional Prefix for auth cookie names
Property Type Required Description enabled boolean✅ Enable cross-subdomain cookies additionalCookies string[]optional Extra cookies shared across subdomains domain stringoptional Cookie domain override — defaults to root domain derived from baseUrl
Property Type Required Description posture Enum<'invite_only' | 'email_domain' | 'open'>optional (default: "invite_only") Who may self-register into this environment: invite_only (default — operator acts only), email_domain (allowlisted email domains), or open (anyone). Any posture other than invite_only forces email verification on. allowedEmailDomains string[]optional Email domains admitted to self-register under posture email_domain (exact, case-insensitive match; subdomains need their own entries). Required non-empty for email_domain; refused under other postures. selfRegistrationPermissionSet stringoptional sys_permission_set name granted to each self-registrant. Required when posture is email_domain or open; refused for invite_only. admin_full_access is refused.
Property Type Required Description secret stringoptional Encryption secret baseUrl stringoptional Base URL for auth routes uiBasePath stringoptional (default: "/_console") Basename where the auth UI (Console) is mounted (default /_console) databaseUrl stringoptional Database connection string providers { id: string; clientId: string; clientSecret: string; scope?: string[] }[]optional plugins { organization: boolean; twoFactor: boolean; passkeys: boolean; passwordRejectBreached: boolean; … }optional session { expiresIn: number; updateAge: number }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, { clientId: string; clientSecret: string; enabled: boolean; scope?: string[] } & Record<string, any>>optional Social/OAuth provider map forwarded to better-auth socialProviders. Keys are provider ids (google, github, apple, …). oidcProviders { providerId: string; name?: string; discoveryUrl?: string; issuer?: string; … }[]optional List of OIDC/OAuth2 providers for enterprise SSO. Product or enterprise packages can pass this directly or contribute it through auth:configure. emailAndPassword { enabled: boolean; disableSignUp?: boolean; requireEmailVerification?: boolean; minPasswordLength?: number; … }optional Email and password authentication options forwarded to better-auth emailVerification { sendOnSignUp?: boolean; sendOnSignIn?: boolean; autoSignInAfterVerification?: boolean; expiresIn?: number }optional Email verification options forwarded to better-auth audience { posture: Enum<'invite_only' | 'email_domain' | 'open'>; allowedEmailDomains?: string[]; selfRegistrationPermissionSet?: string }optional Audience posture: who may self-register into this environment (invite_only — the default — | email_domain | open). See AudienceConfigSchema. advanced { crossSubDomainCookies?: object; useSecureCookies?: boolean; disableCSRFCheck?: boolean; cookiePrefix?: string }optional Advanced / low-level Better-Auth options ssoOnlyMode booleanoptional SSO-only login: hide the local password form + self-registration (the break-glass password endpoint stays enabled) mutualTls { enabled: boolean; clientCertRequired: boolean; trustedCAs: string[]; crlUrl?: string; … }optional Mutual TLS (mTLS) configuration
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
Property Type Required Description organization booleanoptional (default: true) Enable Organization/Teams support (frontend AuthProvider expects this enabled) twoFactor booleanoptional (default: false) Enable 2FA passkeys booleanoptional (default: false) Enable Passkey support passwordRejectBreached booleanoptional (default: false) Reject passwords found in the Have I Been Pwned breach corpus (enables better-auth's haveibeenpwned plugin) magicLink booleanoptional (default: false) Enable Magic Link login oidcProvider booleanoptional (default: false) Enable the OpenID Connect provider plugin (acts as an OIDC IdP) dynamicClientRegistration booleanoptional Allow unauthenticated RFC 7591 Dynamic Client Registration (default: follows OS_MCP_SERVER_ENABLED) deviceAuthorization booleanoptional (default: false) Enable RFC 8628 Device Authorization Grant (CLI / TV-style login) admin booleanoptional (default: false) Enable platform admin operations (ban/unban, set-password, impersonate, set-role) phoneNumber booleanoptional (default: false) Enable phone-number sign-in (phone + password; OTP sign-in/reset when an SMS service is configured)
Property Type Required Description expiresIn numberoptional (default: 604800) Session duration in seconds updateAge numberoptional (default: 86400) Session update frequency
Property Type Required Description clientId string✅ OAuth Client ID clientSecret string✅ OAuth Client Secret enabled booleanoptional (default: true) Enable this provider (default: true) scope string[]optional Additional OAuth scopes
OIDC / Generic OAuth2 provider configuration for enterprise SSO
Property Type Required Description providerId string✅ Unique identifier for this provider (e.g., okta, azure-ad) name stringoptional Display name shown in the UI (defaults to providerId) discoveryUrl stringoptional OIDC discovery URL (.well-known/openid-configuration). When provided, authorizationUrl/tokenUrl/userInfoUrl are fetched automatically. issuer stringoptional Expected issuer identifier for token validation authorizationUrl stringoptional OAuth2 authorization endpoint (optional if discoveryUrl is set) tokenUrl stringoptional OAuth2 token endpoint (optional if discoveryUrl is set) userInfoUrl stringoptional 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 booleanoptional Enable PKCE (recommended for public clients)
Property Type Required Description enabled booleanoptional (default: true) Enable email/password auth disableSignUp booleanoptional Disable new user registration via email/password requireEmailVerification booleanoptional Require email verification before creating a session minPasswordLength numberoptional Minimum password length (default 8) maxPasswordLength numberoptional Maximum password length (default 128) resetPasswordTokenExpiresIn numberoptional Reset-password token TTL in seconds (default 3600) autoSignIn booleanoptional Auto sign-in after sign-up (default true) revokeSessionsOnPasswordReset booleanoptional Revoke all other sessions on password reset
Property Type Required Description sendOnSignUp booleanoptional Automatically send verification email after sign-up sendOnSignIn booleanoptional Send verification email on sign-in when not yet verified autoSignInAfterVerification booleanoptional Auto sign-in the user after email verification expiresIn numberoptional Verification token TTL in seconds (default 3600)
Property Type Required Description posture Enum<'invite_only' | 'email_domain' | 'open'>optional (default: "invite_only") Who may self-register into this environment: invite_only (default — operator acts only), email_domain (allowlisted email domains), or open (anyone). Any posture other than invite_only forces email verification on. allowedEmailDomains string[]optional Email domains admitted to self-register under posture email_domain (exact, case-insensitive match; subdomains need their own entries). Required non-empty for email_domain; refused under other postures. selfRegistrationPermissionSet stringoptional sys_permission_set name granted to each self-registrant. Required when posture is email_domain or open; refused for invite_only. admin_full_access is refused.
Property Type Required Description crossSubDomainCookies { enabled: boolean; additionalCookies?: string[]; domain?: string }optional Share auth cookies across subdomains (critical for *.example.com multi-tenant) useSecureCookies booleanoptional Force Secure flag on cookies disableCSRFCheck booleanoptional ⚠ Disable CSRF check — security risk, use with caution cookiePrefix stringoptional Prefix for auth cookie names
Property Type Required Description enabled booleanoptional (default: false) Enable mutual TLS authentication clientCertRequired booleanoptional (default: false) Require client certificates for all connections trustedCAs string[]✅ PEM-encoded CA certificates or file paths crlUrl stringoptional Certificate Revocation List (CRL) URL ocspUrl stringoptional 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 { enabled: boolean; pins: string[] }optional Certificate pinning configuration
Property Type Required Description organization booleanoptional (default: true) Enable Organization/Teams support (frontend AuthProvider expects this enabled) twoFactor booleanoptional (default: false) Enable 2FA passkeys booleanoptional (default: false) Enable Passkey support passwordRejectBreached booleanoptional (default: false) Reject passwords found in the Have I Been Pwned breach corpus (enables better-auth's haveibeenpwned plugin) magicLink booleanoptional (default: false) Enable Magic Link login oidcProvider booleanoptional (default: false) Enable the OpenID Connect provider plugin (acts as an OIDC IdP) dynamicClientRegistration booleanoptional Allow unauthenticated RFC 7591 Dynamic Client Registration (default: follows OS_MCP_SERVER_ENABLED) deviceAuthorization booleanoptional (default: false) Enable RFC 8628 Device Authorization Grant (CLI / TV-style login) admin booleanoptional (default: false) Enable platform admin operations (ban/unban, set-password, impersonate, set-role) phoneNumber booleanoptional (default: false) Enable phone-number sign-in (phone + password; OTP sign-in/reset when an SMS service is configured)
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
Email and password authentication options forwarded to better-auth
Property Type Required Description enabled booleanoptional (default: true) Enable email/password auth disableSignUp booleanoptional Disable new user registration via email/password requireEmailVerification booleanoptional Require email verification before creating a session minPasswordLength numberoptional Minimum password length (default 8) maxPasswordLength numberoptional Maximum password length (default 128) resetPasswordTokenExpiresIn numberoptional Reset-password token TTL in seconds (default 3600) autoSignIn booleanoptional Auto sign-in after sign-up (default true) revokeSessionsOnPasswordReset booleanoptional Revoke all other sessions on password reset
Email verification options forwarded to better-auth
Property Type Required Description sendOnSignUp booleanoptional Automatically send verification email after sign-up sendOnSignIn booleanoptional Send verification email on sign-in when not yet verified autoSignInAfterVerification booleanoptional Auto sign-in the user after email verification expiresIn numberoptional Verification token TTL in seconds (default 3600)
Property Type Required Description enabled booleanoptional (default: false) Enable mutual TLS authentication clientCertRequired booleanoptional (default: false) Require client certificates for all connections trustedCAs string[]✅ PEM-encoded CA certificates or file paths crlUrl stringoptional Certificate Revocation List (CRL) URL ocspUrl stringoptional 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 { enabled: boolean; pins: string[] }optional Certificate pinning configuration
Property Type Required Description enabled boolean✅ Enable certificate pinning pins string[]✅ Pinned certificate hashes
OIDC / Generic OAuth2 provider configuration for enterprise SSO
Property Type Required Description providerId string✅ Unique identifier for this provider (e.g., okta, azure-ad) name stringoptional Display name shown in the UI (defaults to providerId) discoveryUrl stringoptional OIDC discovery URL (.well-known/openid-configuration). When provided, authorizationUrl/tokenUrl/userInfoUrl are fetched automatically. issuer stringoptional Expected issuer identifier for token validation authorizationUrl stringoptional OAuth2 authorization endpoint (optional if discoveryUrl is set) tokenUrl stringoptional OAuth2 token endpoint (optional if discoveryUrl is set) userInfoUrl stringoptional 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 booleanoptional Enable PKCE (recommended for public clients)
List of OIDC/OAuth2 providers for enterprise SSO. Product or enterprise packages can pass this directly or contribute it through auth:configure.
Type: { providerId: string; name?: string; discoveryUrl?: string; issuer?: string; … }[]
Social/OAuth provider map forwarded to better-auth socialProviders. Keys are provider ids (google, github, apple, …).
Type: Record<string, { clientId: string; clientSecret: string; enabled: boolean; scope?: string[] } & Record<string, any>>
ObjectStack