Configuration Options

createAuth configuration options

oauth

Configures OAuth providers for an auth instance. Aura Auth's built-in providers can be used, or custom providers supplied.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
})

Built-in OAuth Providers

Aura Auth ships ready-to-use OAuth providers. The oauth option in createAuth autocompletes these provider IDs (names are lowercase).

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: ["github", "gitlab", "bitbucket"],
})

Custom OAuth Providers

Provider configs are available via @aura-stack/auth/oauth/index (all providers) or @aura-stack/auth/oauth/:provider (specific). See OAuth Providers for details. Custom providers must implement OAuthProvider.

import { createAuth, type OAuthProvider } from "@aura-stack/auth"
import { github } from "@aura-stack/auth/oauth/index"

export const auth = createAuth({
  oauth: [
    github({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
  ],
})

or

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [
    {
      id: "github",
      name: "GitHub",
      authorize: {
        url: "https://github.com/login/oauth/authorize",
        params: {
          scope: "read:user user:email",
          responseType: "code",
        },
      },
      accessToken: "https://github.com/login/oauth/access_token",
      userInfo: "https://api.github.com/user",
    },
  ],
})

cookies

Per-cookie configuration to override Aura Auth's defaults. You can set a cookie name prefix and adjust the cookies Aura Auth uses internally. See API Reference for details.

Supported cookies: sessionToken, csrfToken, state, codeVerifier, redirectTo, and redirectURI. Set per-cookie attributes as needed. For autocomplete and safer suggestions, set the strategy field, which provides type-safe defaults that follow cookie best practices.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  cookies: {
    prefix: "aura-auth",
    overrides: {
      sessionToken: {
        name: "session_token",
        attributes: {},
      },
    },
  },
})

session

Defines the session management strategy and options for Aura Auth. The session strategy determines how user sessions are stored and maintained across requests. Supported strategies include jwt (JSON Web Tokens). Each strategy has its own configuration options for token expiration, refresh behavior, and storage mechanisms.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "jwt",
    jwt: {
      mode: "sealed",
      maxAge: 60 * 60 * 24 * 7, // 7 days in seconds
    },
  },
})

jwt Session Strategy

The jwt session strategy is the stateless option that uses JSON Web Tokens to manage user session. It includes options for token mode (sealed, signed or encrypted).

• mode: determines how the JWT is protected. sealed (default) provides confidentiality and integrity by encrypting the token. signed provides integrity only by signing the token, but the payload is visible. encrypted provides confidentiality by encrypting the token, but does not include a signature for integrity verification.
• maxAge: sets the maximum age of the JWT in seconds. After this period, the token expires and the user must re-authenticate.
• issuer: (optional) sets the iss claim in the JWT, which identifies the issuer of the token. This can be used for additional validation on the client or server side.
• audience: (optional) sets the aud claim in the JWT, which identifies the intended audience of the token. This can be used to restrict token usage to specific clients or services.
• maxExpiration: (optional) sets the maximum expiration time for the JWT in seconds. This is a hard limit that prevents tokens from being valid indefinitely, even if they are refreshed.
• expirationStrategy: (optional) determines how token expiration is handled. absolute (default) means the token expires after a fixed time from issuance. rolling means the token expiration is extended on each request, keeping the user logged in as long as they are active.

basePath

Base path prefix where Aura Auth endpoints are mounted and exposed to your routing system. Defaults to /auth.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  basePath: "/auth",
})

baseURL

Base URL of the application used to construct absolute URLs for redirects and API calls. It should include the protocol and domain, and optionally a port if not standard (80 for HTTP, 443 for HTTPS). If not set, Aura Auth attempts to infer it from the request headers, which may not always be reliable.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  baseURL: "https://example.com",
})

secret

Secret used to sign, encrypt, and hash JWTs, CSRF tokens, and other sensitive values.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  secret: "secret-key",
})

AURA_AUTH_SECRETorAUTH_SECRET environment variables are loaded automatically. If neither is set, an error is thrown during Auth initialization.

To generate a secret value:

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Using OpenSSL
openssl rand -base64 32

trustedProxyHeaders

Enables Aura Auth to read proxy headers when an application runs behind reverse proxies, load balancers, or CDNs to detect the original client protocol and IP.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedProxyHeaders: true,
})

When to Enable: reverse proxy (Nginx, Apache); platforms with automatic proxying (Vercel, Netlify, Heroku); load balancer (AWS ALB, Google Cloud LB); CDN (Cloudflare)

When NOT to Enable: localhost or direct internet connection; untrusted or misconfigured proxy; unclear infrastructure setup

trustedOrigins

Defines the allowed origins for CORS and redirect URI validation. It supports static matches and wildcards in subdomains and ports.

Static Matches

Set the static origins accepted by Aura Auth.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: ["http://example.com", "https://app.example.com:3000"],
})

Dynamic Matches

Set the origin dynamically based on the original request.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: (request) => {
    const origin = request.headers.get("origin")
    if (origin && origin.endsWith(".example.com")) {
      return [origin]
    }
    return []
  },
})

Wildcard Patterns

The * wildcard is supported for flexible matching of subdomains and ports. The wildcard can only be used at the start of a subdomain or as an entire port.

Subdomain Wildcards

Trust one level of subdomains under a specific domain.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: ["https://*.example.com"],
})

It matches any origin that starts with https:// and ends with .example.com, allowing for any single subdomain level (e.g., https://app.example.com, https://www.example.com), but not the root domain itself (https://example.com) or multiple subdomain levels (https://sub.app.example.com).

Port Wildcards

Trust any port on a specific domain.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: ["https://example.com:*"],
})

It matches any port on https://example.com (e.g., https://example.com:3000, https://example.com:3001, https://example.com:8080), but not the domain without a port (https://example.com) or with a different protocol (http://example.com:3000).

identity

Defines the identity schema used to validate and manage user identities in Aura Auth. The identity schema specifies the required fields, validation rules, and storage mechanisms for user identities. This allows you to customize how user information is structured and validated during authentication and session management.

Uses the UserIdentity zod schema to extend the default identity fields (id, name, email and image) with custom fields relevant to your application. It is also provided the createIdentity function to generate a complete identity object from the provided fields, ensuring that all required fields are included and properly formatted.

import { createAuth, UserIdentity, type InferShape } from "@aura-stack/auth"

const schema = UserIdentity.extend({
  role: z.enum(["user", "admin"]),
})

type Shape = InferShape<typeof schema>

export const auth = createAuth<Shape>({
  oauth: [],
  identity: {
    schema,
    unknownKeys: "strip",
  },
})

• schema: a zod schema that defines the structure and validation rules for user identities. It extends the default UserIdentity schema, allowing you to add custom fields while retaining the required fields (id, name, email, image).
• unknownKeys: (Optional) determines how to handle unknown fields in the identity object. It can be set to strip (default) to remove any fields not defined in the schema, passthrough to allow unknown fields without validation, or strict to throw an error if unknown fields are present.
• skipValidation: (optional) if set to true, it skips the validation of the identity schema. This can be useful in scenarios where you want to allow any shape of identity object without enforcing the schema rules, but it should be used with caution as it may lead to inconsistent or invalid identity data.

logger

Enables the built-in logger for debugging and monitoring, with configurable log levels and output formats. The logger supports structured syslog metadata for better insights into authentication events and errors.

The built-in logger prints the metadata following the syslog format, which includes fields like timestamp, level, message, and msgId for correlation. Log levels can be set to control the verbosity of logs, and the logger can be enabled or disabled as needed.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  logger: true,
})

Custom Logger

Custom logger to replace the default syslog-based logger. The custom logger must implement the Logger interface, which includes methods for different log levels (debug, info, warn, error) and supports structured logging with metadata.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  logger: {
    level: "info",
    log(metadata) {
      console.log(`[${metadata.message}] - ${metadata.timestamp.toISOString()} - ${metadata.level.toUpperCase()} - `${metadata.msgId}`)
    },
  },
})