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
expclaim of the JWT, and theexpiresAtproperty 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:
| Endpoint | Token sent in |
|---|---|
GET /api/auth/login/:providerName, GET /api/auth/logout | the 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.
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, anonce. 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
redirectUrior fromLIGHT_AUTH_URL, never from theHostheader of the request. - The parameters handled by Light-Auth (
state,nonce,redirect_uri,code_challenge...) can't be overridden by thesearchParamsof 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 (403otherwise). - Sessions and users can only be written by your server code, with
setAuthSession()andsetUser(): 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: setisEncrypted: trueor use a database in production, and never commit nor serve this folder.
Production checklist
- A random
LIGHT_AUTH_SECRET_VALUEof at least 32 characters, stored as a secret, and different for each environment. LIGHT_AUTH_URLset 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
keyGeneratorwhen your application is not behind a trusted reverse proxy. - A production user adapter: a database, or the file adapter with
isEncrypted: trueon a private, persistent folder, excluded from your repository. - Callback URLs written as paths of your application (
/profile). - An
onErrorhook connected to your monitoring.