passport-trusted-header

1.1.0 verified Sat Apr 25 auth: no javascript

Passport.js strategy for authentication by trusted HTTP headers, typically used when TLS is terminated at a front-end proxy (e.g., nginx). Version 1.1.0 is current, with no recent updates. Key differentiators: specifically for proxied setups, complements passport-client-cert for direct TLS. Security warning about proxy whitelisting is critical; alternatives include passport-client-cert.

Common errors

error Error: Unknown authentication strategy 'trusted-header' ↓

cause Strategy name mismatch: passport.authenticate() uses a different name than the strategy's registered name.

fix

Ensure the strategy is registered with the same name: passport.use('trusted-header', new Strategy(...)) or use passport.authenticate('trusted-header'). Default name might be 'trusted-header' if not specified.

error TypeError: Cannot read properties of undefined (reading 'TLS_CLIENT_DN') ↓

cause Request headers object is undefined or missing because the verify callback signature was used incorrectly with passReqToCallback option.

fix

Check passReqToCallback setting: if true, first argument is req, second is headers; if false, first is headers. Access requestHeaders.TLS_CLIENT_DN only after checking it exists.

error Error: No headers specified for authentication ↓

cause Options object does not include a 'headers' array.

fix

Add a headers array with at least one header name, e.g., { headers: ['X-Client-DN'] }.

Warnings

gotcha If the front-end proxy does not whitelist or strip incoming headers, external users can spoof authentication headers. ↓

fix Configure your proxy (e.g., nginx) to set and only accept trusted headers from internal network; ensure no external traffic reaches the Node app directly.

gotcha All specified headers must be present; otherwise authentication fails. Missing headers cause 401. ↓

fix Ensure the proxy forwards all required headers; maybe include optional headers by separate logic.

gotcha The verify callback receives header names in an object, not string values; accessing non-existent headers yields undefined. ↓

fix Access headers with bracket notation (e.g., requestHeaders['TLS_CLIENT_DN']) and handle missing keys.

gotcha passReqToCallback changes callback signature; mixing up arguments causes runtime errors. ↓

fix When passReqToCallback: true, use callback signature (req, requestHeaders, done). Otherwise use (requestHeaders, done).

gotcha The package only extracts headers, does not validate TLS or proxy integrity; security depends entirely on deployment. ↓

fix Implement additional security measures: use HTTPS between proxy and app, restrict network access, and validate proxy identity (e.g., shared secret).

Install

npm install passport-trusted-header

yarn add passport-trusted-header

pnpm add passport-trusted-header

Imports

Strategy

wrong

const Strategy = require('passport-trusted-header').Strategy

correct

import { Strategy } from 'passport-trusted-header'

Package supports both ESM and CJS; named export 'Strategy' is the main class.

passport-trusted-header
```
const Strategy = require('passport-trusted-header').Strategy
```
CommonJS require works; if using ESM, use named import.

default import

wrong

import { default as Strategy } from 'passport-trusted-header'

correct

import pkg from 'passport-trusted-header'; const Strategy = pkg.Strategy

No default export; use named import or require with destructuring.

Quickstart

Initializes passport-trusted-header strategy with custom headers and a verify callback; shows Express usage.

const passport = require('passport');
const { Strategy } = require('passport-trusted-header');

const options = {
  headers: ['X-Client-DN', 'X-Client-CN']
};

passport.use(new Strategy(options, (requestHeaders, done) => {
  const userDn = requestHeaders['X-Client-DN'];
  const userCn = requestHeaders['X-Client-CN'];
  // Authentication logic
  if (userDn === 'CN=test-user') {
    return done(null, { name: 'Test User' });
  }
  return done(null, false);
}));

// Express example
const express = require('express');
const app = express();
app.use(passport.initialize());
app.get('/login', passport.authenticate('trusted-header', { session: false }), (req, res) => {
  res.json({ user: req.user });
});