With Auth.js mounted in an Express app, when are sessions an encrypted JWT cookie and when are they database rows?
answer
- the adapter flips the default
- session.strategy: jwt or database
- JWE in the cookie
- Credentials needs JWT
- 30 days, refreshed daily
basics
~20 sAuth.js uses the jwt strategy, an encrypted JWT in the session cookie, unless the config has an adapter; then it defaults to database, where the cookie holds only a session token looked up in the adapter's tables. session.strategy overrides either default.
solid answer
~40 sAuth.js's `session.strategy` is `"jwt"` or `"database"`. With no `adapter`, it defaults to `"jwt"`: the whole session is an encrypted JWT (JWE) in the cookie and nothing about the user is stored on the server. Add an adapter and the default becomes `"database"`: the cookie carries only a random `sessionToken`, and each `getSession` call loads the session and user through the adapter. You can still set `"jwt"` explicitly with an adapter. The choice decides more than storage: a database session can be ended by deleting its row, while a JWT session stays valid until it expires (30 days by default); email sign-in and database sessions both refuse to start without an adapter, and a config whose only provider is `Credentials` fails with `UnsupportedStrategy` under `"database"`.
go deeper
Recall the two values of session.strategy and that adding an adapter switches the default from jwt to database.
Explain what the cookie holds under each strategy, the 30-day maxAge and 1-day updateAge defaults, and which providers need an adapter.
Reason about revocation: a database row can be deleted, a JWT session lasts until expiry, and AUTH_SECRET protects every JWT session.
Set a team default for strategy and adapter based on whether you must list and end sessions, and what that adds to every request.
## Two strategies behind one option When an Express app mounts Auth.js through `@auth/express`, there is no `express-session` and no session store to wire. Auth.js keeps the session itself, in one of two ways selected by **`session.strategy`** in the config: - **`"jwt"`**: the session is an **encrypted JSON Web Token (JWE)** written into the session cookie. The server stores nothing per session. - **`"database"`**: the cookie holds only a **session token** (a random UUID by default), and the session record lives in tables reached through an **adapter**, the Auth.js plug-in that talks to your database. The **default depends on the adapter**. In `@auth/core` 0.41.3 the initialisation code reads, in effect, `strategy: config.adapter ? "database" : "jwt"`, and then spreads your own `session` options over it. So: | Config | Effective strategy | Where the user lives | |---|---|---| | No `adapter`, no `session.strategy` | `jwt` | Nowhere on the server; claims ride in the cookie | | `adapter`, no `session.strategy` | `database` | Adapter tables (users, accounts, sessions) | | `adapter` and `strategy: "jwt"` | `jwt` | Users and accounts in adapter tables, session in the cookie | | No `adapter` and `strategy: "database"` | refused | Fails with `MissingAdapter` | ## What the configuration check refuses Auth.js asserts its config on each request, and several combinations stop it outright: 1. **`strategy: "database"` without an adapter** fails with `MissingAdapter` ("Database session requires an adapter"). 2. **An email (magic-link) provider without an adapter** fails with `MissingAdapter`, because the verification tokens have to be stored. 3. **Database sessions when every provider is `Credentials`** fail with `UnsupportedStrategy` ("Signing in with credentials only supported if JWT strategy is enabled"). The `Credentials` provider's documentation states the reason: users signed in that way are not persisted in the database. 4. **An adapter missing a required method** fails with `MissingAdapterMethods`; database sessions need methods such as `createSession`, `getSessionAndUser`, `updateSession` and `deleteSession`. ## What each strategy changes for the Express app - **Revocation.** With `database`, signing out or deleting the session row ends the session for every copy of the cookie. With `jwt`, sign-out clears the browser's cookie, but a copied cookie keeps working until the token expires, unless you add your own check in the `jwt` callback. - **Lifetime.** `session.maxAge` defaults to 2592000 seconds (30 days). `session.updateAge` defaults to 86400 seconds (1 day) and throttles how often a database session's expiry is written back; `0` writes on every request. - **Request cost.** Every `getSession(req, config)` under `database` is an adapter read; under `jwt` it is a decryption with `AUTH_SECRET`, which makes that secret the thing protecting every session. - **Callbacks.** The `session` callback receives `token` under `jwt` and `user` under `database`, so code that shapes `session.user` has to match the strategy. - **Cookie size.** Everything you add to the token travels in every request's cookie, so a fat token makes every request heavier. ## Setting it explicitly in an Express config Because the default silently changes when someone adds an adapter later, many teams write the strategy down in the shared config module that both `ExpressAuth` and `getSession` import: ```js export const authConfig = { adapter: myAdapter, session: { strategy: 'database', maxAge: 7 * 24 * 60 * 60, updateAge: 60 * 60 }, providers: [GitHub], } ``` Writing it out has three effects worth naming: - A reviewer sees the session model without knowing the adapter rule. - Removing the adapter later produces a loud `MissingAdapter` instead of a quiet switch to cookies. - Callback code written for one strategy (reading `user` or `token`) is not broken by a dependency change. ## Choosing within Auth.js A JWT session suits an API that signs in only through OAuth providers and needs no user table of its own; it is also the only option when `Credentials` is the sole provider. A database session suits a product that needs to list or end a user's sessions, uses email links or passkeys (both need an adapter), or wants the session record queryable. The framework-neutral trade-off between server-held sessions and self-contained tokens is covered with token storage and transport in the authentication material; here the point is which Auth.js settings select each one and what the library refuses.
- Can you keep users in a database but still use JWT sessions with Auth.js?Yes. Configure an adapter so users and linked accounts are stored, then set `session: { strategy: "jwt" }` explicitly. Auth.js writes users and accounts through the adapter but keeps the session in the encrypted cookie, so no session rows are created and `getSession` does not read the database for the session itself.
- Why does Auth.js refuse database sessions when Credentials is the only provider?The `Credentials` provider calls your `authorize()` function and signs the user in with whatever it returns; its documentation says such users are not persisted in the database. With nothing written for them, a database session has no user to point at, so the config check returns `UnsupportedStrategy` and asks for the JWT strategy.
- Says Auth.js always stores sessions in a database table
- Thinks the default JWT session cookie is signed but readable by the client
- Expects signing out to invalidate every copy of a JWT session cookie
- Configures database sessions with only a Credentials provider
- Mounts express-session alongside Auth.js to hold its sessions