skip to content

Behind a TLS-terminating load balancer, why does an Express 5 app using express-session with cookie.secure: true never set its session cookie?

level: middleimportance: must knowfreq 50%

answer

  1. the hop to Node is plain HTTP
  2. who decides the request is secure
  3. req.protocol and X-Forwarded-Proto
  4. skipped silently, no error

basics

~20 s

With cookie.secure set, express-session sends the cookie only when it judges the request secure. Behind a TLS-terminating proxy the hop to Node is plain HTTP and Express ignores X-Forwarded-Proto unless trust proxy is set, so the cookie is silently skipped.

solid answer

~40 s

A `Secure` cookie is only meant for HTTPS, so express-session checks the request before writing `Set-Cookie`. The socket from the load balancer to Node is unencrypted, and with its `proxy` option undefined express-session asks Express: `req.secure`, which is `req.protocol === 'https'`. Express reads `X-Forwarded-Proto` into `req.protocol` only when the `trust proxy` setting trusts the connecting address, and that setting defaults to `false`, so `req.protocol` is `'http'`. express-session then skips the cookie without an error. The login handler still returns 200 and its session can still be saved to the store, but the browser never receives an ID, so the next request is anonymous. The fix is to trust the proxy hop with `app.set('trust proxy', 1)` or a value matching the topology; `proxy: true` on the session also works but trusts the header from anyone.

code

javascript · 12 lines
javascript
const express = require('express')
const session = require('express-session')

const app = express()
app.set('trust proxy', 1) // believe X-Forwarded-Proto from the first hop

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: { secure: true }
}))

go deeper

for a junior

Recall that a Secure cookie is sent only over HTTPS and that the app behind a balancer sees plain HTTP unless told otherwise.

for a middle

Trace the chain: express-session asks req.secure, Express derives it from req.protocol, and req.protocol reads X-Forwarded-Proto only when trust proxy trusts the hop.

for a senior

Diagnose it from the symptom: a 200 login with no Set-Cookie, orphan records in the store, and only a debug line as evidence.

for a principal

Make trust proxy part of the deployment contract per environment, so session security does not depend on someone remembering one line.

## The symptom An Express 5 dashboard works locally over `http://localhost`. In production it sits behind a **load balancer** that terminates TLS: browsers speak HTTPS to the balancer, and the balancer forwards plain HTTP to Node, adding an `X-Forwarded-Proto: https` header. The team set `cookie: { secure: true }` on **express-session** for production. Now login appears to succeed — the handler runs and returns 200 — but the next request is anonymous, and the browser's dev tools show no `connect.sid` cookie at all. No error appears in any log. ## How express-session decides a request is secure Before writing `Set-Cookie`, express-session checks: if `req.session.cookie.secure` is set and the request is not secure, it **returns without setting the cookie**. Its check runs in this order: 1. If the socket itself is encrypted (Node is serving TLS directly), the request is secure. 2. If the session's `proxy` option is `false`, nothing else counts: not secure. 3. If `proxy` is `undefined` (the default), use Express's `req.secure`. 4. If `proxy` is `true`, read the first value of `X-Forwarded-Proto` and compare it to `https`. In the default case, everything turns on `req.secure`, and in Express 5 that getter is simply `req.protocol === 'https'`. ## Why req.protocol says http Express's `req.protocol` getter starts from the socket: unencrypted means `'http'`. It then reads `X-Forwarded-Proto` **only if the `trust proxy` setting trusts the address the request came from**. An Express application sets `trust proxy` to `false` by default, so the header is ignored and `req.protocol` stays `'http'` even though the browser used HTTPS. That is deliberate: a client could send any `X-Forwarded-Proto` it likes, and only a proxy you trust should be believed. So the chain is: unencrypted socket → `trust proxy` off → `req.protocol` is `'http'` → `req.secure` is `false` → express-session drops the `Secure` cookie. ## Why it fails silently The skip is a plain `return` with a debug message, not an error: - The response status is unaffected, so monitoring sees a healthy 200. - The session can still be **saved to the store**, because saving and cookie-setting are separate decisions. Each login attempt leaves an orphan record whose ID no browser holds. - The only trace is the `not secured` line that the package's debug output prints when the `DEBUG` environment variable includes `express-session`. ## The fixes, compared | Change | Effect on the cookie | Caveat | |---|---|---| | `app.set('trust proxy', 1)` | `req.protocol` reads `X-Forwarded-Proto` from the first hop, cookie is sent with `Secure` | the value must match the real proxy chain | | session `proxy: true` | express-session reads `X-Forwarded-Proto` itself, ignoring `trust proxy` | believes the header from whoever connects | | `cookie.secure: 'auto'` | `Secure` set only when the request is judged secure | behind the balancer it is judged insecure, so the cookie loses `Secure` | | `cookie.secure: false` | cookie always sent | gives up `Secure` in production | The usual fix is the first row: the express-session README pairs `secure: true` with `app.set('trust proxy', 1)` for an app behind one proxy. Choosing the right `trust proxy` value for a given chain of proxies, and what it does to `req.ip`, is covered with Express production hardening. Note what `'auto'` does and does not do. It is useful when `trust proxy` is already correct, so one configuration serves plain-HTTP development and HTTPS production. It does **not** repair the detection: without `trust proxy` the request still looks insecure, and `'auto'` simply sends the cookie without `Secure`. ## The same trap in cookie-session **cookie-session**, which keeps the whole session in the cookie, has the same dependency. With `secure: true` it relies on the underlying cookies library, which checks `req.protocol`; on an insecure-looking request that library throws, and cookie-session catches the error and only logs it through debug. The result is the same: no cookie and no visible error until `trust proxy` is set. cookie-session's README points to the Express behind-proxies guide for this reason. ## What to remember - `cookie.secure: true` is recommended, but it needs Express to know the request was HTTPS. - Behind a TLS-terminating proxy, Express learns that only from a trusted `X-Forwarded-Proto`. - A missing session cookie with a 200 login is the signature of this misconfiguration.

  • Why not just set express-session's proxy: true instead of trust proxy?
    `proxy: true` makes express-session read `X-Forwarded-Proto` itself for every request, from whoever connected. If anything other than the balancer can reach the app, a client can claim HTTPS. `trust proxy` instead trusts the header only from addresses you configured, and it also fixes `req.protocol`, `req.secure` and `req.ip` for the rest of the app, so it is the more coherent setting.
  • How do you confirm this is the cause without guessing?
    Run the app with `DEBUG=express-session` and look for the `not secured` line on the login response, or log `req.protocol` and `req.secure` in a handler: behind the balancer they read `'http'` and `false` until `trust proxy` is set. Seeing a 200 login with no `Set-Cookie` for the session name confirms it from the outside.

  • express-session throws an error when it cannot send a Secure cookie.
  • Express reads X-Forwarded-Proto by default, so req.protocol is already https.
  • cookie.secure: 'auto' fixes the problem without touching trust proxy.
  • The session is not stored either, so nothing accumulates in the store.
  • Setting cookie.httpOnly to false lets the Secure cookie through the proxy.