Cookie Management

Aura Auth uses HTTP cookies to store authentication-related information, including session data, CSRF tokens, and temporary OAuth values. Cookies are used regardless of whether the application uses a stateful or stateless session strategy.

By default, cookies are configured with security-focused attributes based on the HTTP State Management Mechanism (RFC 6265). Aura Auth also supports customizing cookie names and attributes while preserving security requirements.

Aura Auth uses the following cookies:

Option	Default Cookie Name	Purpose
`sessionToken`	`session_token`	Stores the session token used to identify the user's session.
`csrfToken`	`csrf_token`	Stores the token used for CSRF verification.
`state`	`state`	Temporarily stores the OAuth state parameter during sign-in.
`codeVerifier`	`code_verifier`	Temporarily stores the PKCE code verifier.
`redirectTo`	`redirect_to`	Stores the destination to redirect to after authentication.
`redirectURI`	`redirect_uri`	Stores the OAuth callback redirect URI.
`nonce`	`nonce`	Temporarily stores the OAuth nonce used to mitigate replay attacks.
`accessToken`	`access_token`	Stores an OAuth access token when applicable.

Cookie prefixes such as __Secure- and __Host- have specific browser-enforced requirements. Aura Auth can apply these prefixes through its cookie configuration strategy; browsers do not automatically add them to cookie names.

The createAuth function exposes a cookies configuration object for customizing cookie names and attributes.

Prefix

The cookies.prefix option defines the prefix applied to cookie names. Its default value is aura-auth, and it is combined with each cookie's name using a period (.) as the separator.

@/lib/auth.ts

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

export const auth = createAuth({
<<<<<<< HEAD
  oauth: [],
=======
>>>>>>> origin/master
  cookies: {
    prefix: "my_app",
  },
})

For example, the default cookie name aura-auth.session_token becomes my_app.session_token.

Overrides

For more granular control, cookies.overrides allows customization of individual cookies. Each override can specify a custom cookie name through name and modify cookie attributes through attributes.

@/lib/auth.ts

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

export const auth = createAuth({
  cookies: {
    overrides: {
      sessionToken: {
        name: "jwt_session",
      },
    },
  },
})

The attributes property allows customization of cookie attributes. For more information, see the Set-Cookie header attributes reference.

domain: Specifies the domain for which the cookie is sent. When omitted, the browser applies the default host-only behavior.
expires: Specifies the cookie's expiration date.
httpOnly: Determines whether the cookie is inaccessible to client-side JavaScript. Defaults to true.
maxAge: Specifies the cookie's lifetime in seconds.
path: Specifies the URL path for which the cookie is sent. Defaults to /.
sameSite: Controls when the browser sends the cookie in cross-site requests. Defaults to lax.
secure: Determines whether the cookie is sent only over secure connections, such as HTTPS. Defaults to true.

Expiration behavior depends on the cookie type. For example, session-related cookies and temporary OAuth cookies may have different lifetimes.

Not all cookie attributes can be freely customized. If an override weakens a security guarantee, Aura Auth may enforce a safer value instead.

@/lib/auth.ts

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

export const auth = createAuth({
  oauth: [],
  cookies: {
    overrides: {
      sessionToken: {
        attributes: {
          maxAge: 3600,
          domain: ".example.com",
          sameSite: "strict",
        },
      },
    },
  },
})

The attributes.strategy option controls how Aura Auth configures a cookie for compatibility with cookie prefixes. It accepts three values: standard, secure, and host. The default is standard.

Strategy	Description
`standard`	Uses the standard cookie configuration, subject to Aura Auth's security defaults.
`secure`	Configures the cookie to satisfy the requirements for the `__Secure-` prefix.
`host`	Configures the cookie to satisfy the stricter requirements for the `__Host-` prefix.

For details about the browser requirements for these prefixes, see the Cookies: HTTP.

@/lib/auth.ts

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

export const auth = createAuth({
  cookies: {
    overrides: {
      sessionToken: {
        attributes: {
          strategy: "secure",
        },
      },
    },
  },
})

Cookie NamesCopy Anchor Link

Cookie OverridesCopy Anchor Link

PrefixCopy Anchor Link

OverridesCopy Anchor Link

Cookie Name OverrideCopy Anchor Link

Cookie AttributesCopy Anchor Link

Cookie Prefix StrategyCopy Anchor Link

On this page

Cookie Names

Cookie Overrides

Prefix

Overrides

Cookie Name Override

Cookie Attributes

Cookie Prefix Strategy