Config reference

Every field on goauth.Config and nested structs. This is the authoritative map for developers integrating the package.

goauth.Config (top level)

type Config struct {
    Secret    []string
    BasePath  string
    URL       string
    TrustHost bool
    Providers []Provider
    Adapter   Adapter

    Session   SessionConfig
    JWT       JWTConfig
    Tokens    TokensConfig
    MFA       MFAConfig
    WebAuthn  WebAuthnConfig
    Pages     Pages
    Cookies   CookieOptions
    Callbacks Callbacks
    Events    Events

    Debug  bool
    Logger Logger
}

Secret (required)

Type	[]string
Purpose	Encrypts JWE session cookies, CSRF, MFA challenges, trusted-device cookies
Rotation	First element signs new tokens; all entries tried on decode

Secret: []string{
    os.Getenv("AUTH_SECRET_CURRENT"),
    os.Getenv("AUTH_SECRET_PREVIOUS"), // optional rotation
},

Minimum practical length: 32 bytes of entropy.

BasePath

Default	"/auth"
Mount	mux.Handle("/auth/", auth) — trailing slash required

URL and TrustHost

Field	When to set
URL	Production canonical URL: "https://app.example.com"
TrustHost	true in local dev or behind a proxy that sanitizes Host

If neither allows deriving origin → ErrUntrustedHost.

Providers (required)

Non-empty slice of goauth.Provider values from providers/* subpackages.

Adapter

Required when	Optional when
Database sessions	JWT-only OAuth without persistence
Email / OTP providers	GitHub-only JWT demo
MFA (recommended)	Credentials-only without OTP storage
Passkey provider	—

Must implement AuthenticatorStore for passkeys.

---

SessionConfig

type SessionConfig struct {
    Strategy             SessionStrategy // "jwt" | "database"
    MaxAge               time.Duration   // default 30d
    UpdateAge            time.Duration   // default 24h
    GenerateSessionToken func() string
}

Field	Default	Notes
Strategy	Auto — see below	Credentials forces JWT at New()
MaxAge	30 * 24h	Database session expiry
UpdateAge	24h	Throttle session row refresh
GenerateSessionToken	UUID v4	Database strategy only

Auto strategy:

if Session.Strategy set     → use it
else if Adapter && !credentials → database
else                        → jwt

---

JWTConfig

type JWTConfig struct {
    MaxAge time.Duration
    Encode func(JWTEncodeParams) (string, error)
    Decode func(JWTDecodeParams) (JWT, error)
}

Used for JWT strategy and bearer token encoding. Override Encode/Decode only if you need custom JWE (default uses goauth/jwt, Auth.js-compatible).

---

TokensConfig

type TokensConfig struct {
    Enabled            bool
    AccessTokenMaxAge  time.Duration // default 15m
    RefreshTokenMaxAge time.Duration // default 30d
    AlwaysReturn       bool
    CallbackPage       string
}

Field	Effect
Enabled	Serves POST /auth/token, GetSession accepts Bearer
AlwaysReturn	Every sign-in returns JSON tokens (no cookies)
CallbackPage	Browser OAuth redirect after HTML token page

Client opt-in (when AlwaysReturn is false): X-Auth-Flow: token or ?flow=token.

---

MFAConfig

type MFAConfig struct {
    Enabled           bool
    CodeLength        int           // default 6
    MaxAge            time.Duration // default 10m
    TrustDeviceMaxAge time.Duration // default 90d; <0 disables trust
    SendCode          func(ctx, MFASendCodeParams) error
}

Applies to	CredentialsProvider only
SendCode	Required when Enabled — you deliver the OTP
Storage	Adapter CreateVerificationToken with identifier: mfa:{userId}
IsDeviceTrusted	Optional callback: (userId, deviceId) → skip MFA
TrustDevice	Optional callback: persist trust on trustDevice=true

See MFA and OTP guide.

---

WebAuthnConfig

type WebAuthnConfig struct {
    Enabled bool
}

Passkey is enabled when a PasskeyProvider is in Providers or WebAuthn.Enabled is true.

---

Pages

type Pages struct {
    SignIn        string
    SignOut       string
    Error         string
    VerifyRequest string
    NewUser       string
}

Page	Trigger
SignIn	GET /auth/signin without provider id
Error	Sign-in failure redirect ?error=Kind
VerifyRequest	After email/OTP sent ("check your inbox")
NewUser	Reserved for future flows

---

CookieOptions

Override per-cookie: SessionToken, CallbackURL, CSRFToken, PKCECodeVerifier, State, Nonce.

Cookies: goauth.CrossSubdomainCookies(".example.com"),

All subdomains must share the same Secret and cookie names.

---

Callbacks

type Callbacks struct {
    SignIn      func(ctx, SignInCallbackParams) (bool, error)
    ResolveUser func(ctx, ResolveUserParams) (*User, error)
    Redirect    func(ctx, url, baseURL string) (string, error)
    JWT         func(ctx, JWTCallbackParams) (JWT, error)
    Session     func(ctx, SessionCallbackParams) (*Session, error)
}

Execution order on successful OAuth sign-in:

1. Provider Profile → User
2. SignIn callback (allow/deny)
3. resolveUser (adapter + optional ResolveUser)
4. issueSession → JWT callback (JWT strategy) → Session callback
5. Events.SignIn, Events.Session

Detailed examples: Callbacks overview.

---

Events

type Events struct {
    SignIn      func(ctx, SignInCallbackParams)
    SignOut     func(ctx, *Session, JWT)
    CreateUser  func(ctx, *User)
    UpdateUser  func(ctx, *User)
    LinkAccount func(ctx, *User, *Account)
    Session     func(ctx, *Session, JWT)
}

Fire-and-forget — cannot block sign-in. Use for audit logs, analytics, webhooks.

---

Debug and Logger

Debug: true,
Logger: myStructuredLogger{}, // implements Error, Warn, Debug

---

Validation at goauth.New

Check	Error
Empty Secret	MissingSecret
Empty Providers	configuration error
Credentials + database strategy	configuration error
Passkey without AuthenticatorStore	configuration error
Migrator adapter	runs Migrate(ctx)

---

Related docs

• Configuration scenarios — copy-paste full configs
• Developer cookbook — production stack
• Feature map — every package capability