Security

How Light-Auth protects your sessions, your tokens and your endpoints.

The secret

LIGHT_AUTH_SECRET_VALUE encrypts the session cookie and signs the CSRF tokens. It is mandatory: CreateLightAuth throws at startup when it is missing or shorter than 32 characters.

# generate a random secret
openssl rand -base64 32
  • The first 32 characters are used as the encryption key: use a random value, not a passphrase, and keep it ASCII (a base64 string is fine).
  • Changing the secret invalidates all the sessions, and the users saved by the encrypted file adapter.

Session cookie

  • The session is an encrypted JWT (JWE, dir + A128CBC-HS256): its content can't be read nor modified by the browser.
  • The cookie is HttpOnly, Secure, SameSite=Lax, and expires with the session.
  • The expiration is enforced twice: the standard exp claim of the JWT, and the expiresAt property of the session. A session without a valid expiration date is considered as expired.
  • Sessions slide: they are renewed when less than half of their lifetime remains. See Session.

CSRF protection

The endpoints triggered by the browser are protected against cross-site request forgery with two mechanisms.

Double-submit token

Before calling a protected endpoint, the client functions get a new token from POST /api/auth/csrf. The token and its signature (an HMAC-SHA256 with a key derived from the secret) are stored in the light_auth_csrf_token cookie, and the token is sent back with the request:

EndpointToken sent in
GET /api/auth/login/:providerName, GET /api/auth/logoutthe csrfToken query parameter
POST /api/auth/credentials/*the x-light-auth-csrf-token header

The server checks that the cookie signature is authentic, and that the token of the cookie matches the token of the request (constant-time comparisons). A cross-site attacker can neither read the cookie nor forge a signature. The client functions (signIn, signOut, credentialsLogin...) handle all of this for you.

Origin check

When a request has an Origin header, its host must match the Host (or X-Forwarded-Host) header, otherwise the request is rejected. The OAuth callback is the only exception: some providers post their response from their own domain, and the callback is protected by the state, the PKCE code verifier and the nonce.

The server signIn() and signOut() functions don't check a CSRF token, as there is no browser round-trip to carry it. Call them from POST actions protected by your framework: Next.js Server Actions and SvelteKit form actions verify the origin of the request, and the SameSite=Lax session cookie is never sent with a cross-site POST request.

Open redirect protection

The callbackUrl given to signIn, signOut and to the login and logout endpoints must be a path of your application. Any other value (another domain, a protocol-relative URL such as //evil.com, a javascript: URL...) is replaced by /.

OAuth 2.0 and OpenID Connect

  • Each sign in uses a random state, a PKCE code verifier (S256) and, for OpenID Connect providers, a nonce. They are kept in HTTP-only cookies for 10 minutes, and deleted by the callback.
  • The id_tokens are fully validated: signature against the JSON Web Key Set of the provider, issuer, audience, expiration (with a 30 seconds tolerance) and nonce.
  • The callback URL comes from the provider redirectUri or from LIGHT_AUTH_URL, never from the Host header of the request.
  • The parameters handled by Light-Auth (state, nonce, redirect_uri, code_challenge...) can't be overridden by the searchParams of a provider.
  • The requests to the providers time out after 10 seconds.
  • On sign out with revokeToken, the refresh token then the access token are revoked at the provider, when it supports it.

Tokens and users stay on the server

  • The access and refresh tokens are saved by the user adapter, on the server. The getUser() client function never returns them, and the browser can only read the user of its own session (403 otherwise).
  • Sessions and users can only be written by your server code, with setAuthSession() and setUser(): there is no HTTP endpoint to modify them. Their content is not validated, so never save values coming from the browser without checking them.
  • The server functions (getAuthSession(), getUser()...) read the session and the user in-process, without any HTTP call to your own application.
  • The default file adapter writes the users (with their tokens) in plain JSON in ./users_db: set isEncrypted: true or use a database in production, and never commit nor serve this folder.

Production checklist

  • A random LIGHT_AUTH_SECRET_VALUE of at least 32 characters, stored as a secret, and different for each environment.
  • LIGHT_AUTH_URL set to the public HTTPS URL of your application, and the exact callback URLs registered in the provider consoles.
  • Your application served over HTTPS: the session cookie is always marked Secure.
  • A rate limiter, with a keyGenerator when your application is not behind a trusted reverse proxy.
  • A production user adapter: a database, or the file adapter with isEncrypted: true on a private, persistent folder, excluded from your repository.
  • Callback URLs written as paths of your application (/profile).
  • An onError hook connected to your monitoring.