Session Strategies

The session option in createAuth configures how Aura Auth stores, validates, and manages sessions across requests.

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

export const auth = createAuth({
  session: {
    maxAge: 60 * 60 * 24 * 7, // 7 days in seconds
    slidingThreshold: 0.5, // 50% of maxAge
    expirationStrategy: "sliding",
  },
})

strategyCopy Anchor Link

The strategy property selects the session management strategy.

• jwt: Uses a JWT to represent the session. Session validation does not require a database lookup, although other application operations may still use a database.
• database: Stores session records in a database, enabling server-side session management, including session revocation and tracking. This strategy is suitable for applications that need direct control over the session lifecycle.

jwtCopy Anchor Link

The jwt option configures the JWT session strategy. Its properties apply only when session.strategy is set to jwt.

modeCopy Anchor Link

The mode property determines how session JWTs are protected.

• sealed (default): Encrypts and authenticates the token, providing confidentiality and integrity. The payload cannot be read without the appropriate key material or modified without detection.
• signed: Signs the token to provide integrity and authenticity, but does not encrypt the payload. Anyone holding the token can read its contents. Use this mode when another service needs to inspect the claims and verify the signature.
• encrypted: Encrypts the token to protect the confidentiality of its payload. Unlike sealed, this mode does not provide a separate signature. Use it only when its behavior meets the application's security requirements and compatibility needs.

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

export const auth = createAuth({
  session: {
    strategy: "jwt",
    jwt: {
      mode: "sealed",
    },
  },
})

issuerCopy Anchor Link

The issuer property sets the JWT issuer (iss) claim. It identifies the entity that issued the token and can be used by token consumers to validate its origin.

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

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "jwt",
    jwt: {
      issuer: "my-app",
    },
  },
})

audienceCopy Anchor Link

The audience property sets the JWT audience (aud) claim. It identifies the intended recipient or recipients of the token and can be used to restrict token acceptance to specific applications or services.

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

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "jwt",
    jwt: {
      audience: "my-app-client",
    },
  },
})

databaseCopy Anchor Link

The database configuration controls database-backed session management. These options apply only when session.strategy is set to database.

deleteStrategyCopy Anchor Link

The deleteStrategy property determines how session records are deleted. It accepts soft or hard and defaults to soft.

• soft: Marks a session as deleted without physically removing its database record. This can preserve records for auditing or recovery, depending on the adapter's implementation.
• hard: Permanently removes the session record from the database.

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

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "database",
    database: {
      deleteStrategy: "soft",
    },
  },
})

maxSessionsCopy Anchor Link

The maxSessions property sets the maximum number of concurrent sessions allowed per user. When the limit is exceeded, the oldest session is invalidated to make room for the new session.

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

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "database",
    database: {
      maxSessions: 5,
    },
  },
})

touchIntervalCopy Anchor Link

The touchInterval property sets the minimum interval, in seconds, between updates to a session's last-activity timestamp in the database. This can reduce database writes while maintaining activity information for session management. The default is 300 seconds (5 minutes).

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

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "database",
    database: {
      touchInterval: 300, // 5 minutes
    },
  },
})

adapterCopy Anchor Link

The adapter property specifies the database adapter used to persist session data. Aura Auth provides a Prisma adapter through the @aura-stack/prisma package.

The adapter must be configured with the application's Prisma client and passed to createAuth when using the database session strategy.

The following example configures the Prisma adapter with PostgreSQL:

import { createAuth } from "@aura-stack/auth"
import { PrismaPg } from "@prisma/adapter-pg"
import { prismaAdapter } from "@aura-stack/prisma"
import { PrismaClient } from "@/generated/prisma/client.ts"

const adapterPg = new PrismaPg({
  connectionString: process.env.DATABASE_URL,
})

export const prismaClient = new PrismaClient({
  adapter: adapterPg,
})

export const adapter = prismaAdapter({
  client: prismaClient as any,
  deleteStrategy: "soft",
})

export const auth = createAuth({
  oauth: [],
  session: {
    strategy: "database",
    adapter,
  },
})

maxAgeCopy Anchor Link

The maxAge property specifies the session's maximum age in seconds. Its exact effect depends on the configured expiration strategy. When the session reaches its applicable expiration time, it can no longer be used and the user must authenticate again. The default is 15 days (60 * 60 * 24 * 15 seconds).

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

export const auth = createAuth({
  session: {
    maxAge: 60 * 60 * 24 * 7, // 7 days
  },
})

maxDurationCopy Anchor Link

The maxDuration property sets the maximum absolute lifetime of a session in seconds, regardless of activity. Once this limit is reached, the session expires even if it has been renewed during that period.

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

export const auth = createAuth({
  session: {
    maxDuration: 60 * 60 * 24 * 30, // 30 days
  },
})

expirationStrategyCopy Anchor Link

The expirationStrategy property determines how session expiration is calculated and renewed.

• fixed: The session expires after a fixed duration from its creation time.
• rolling: The expiration time is renewed as activity occurs.
• absolute: The session has a fixed expiration time that activity does not extend.
• sliding: The expiration time is extended according to the sliding-expiration policy, subject to the configured lifetime limits.

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

export const auth = createAuth({
  session: {
    expirationStrategy: "rolling",
  },
})

slidingThresholdCopy Anchor Link

The slidingThreshold property sets the fraction of maxAge that must elapse before a sliding session's expiration is extended. For example, 0.5 represents 50% of maxAge.

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

export const auth = createAuth({
  oauth: [],
  session: {
    slidingThreshold: 0.5, // 50% of maxAge
    expirationStrategy: "sliding",
  },
})