passport-trusted-header

passport.js strategy for authentication by a trusted HTTP header.

Node.js apps often have TLS handled by a front-end web server like nginx. For client cert authentication, the web server passes through certificate fields like DN as HTTP headers. The Node app can use these headers for authentication.

This library helps to do this with passport.js. If you have a Node.js app that accepts direct TLS connections, try passport-client-cert instead.

Security

The connection between web server and web app must be secure. The front-end web server must whitelist HTTP headers to send to the web app, and it must be impossible for external processes to reach the web app or interfere with connections between the web server and Node.js. It is completely insecure if these conditions are not met!

Usage

Create the strategy with an options object and a "verify request" callback.

Options

• headers - required. Array of HTTP header names to extract. A request has to contain all of these headers to be authenticated.
• passReqToCallback - optional. Causes the request object to be supplied to the verify callback as the first parameter.

The verify callback decides whether to authenticate each request. It called with the extracted header names/values and a passport.js done callback.

var passport = require('passport');
var Strategy = require('passport-trusted-headers').Strategy;

var options =  {
  headers: ['TLS_CLIENT_DN']
}

passport.use(new Strategy(options, function(requestHeaders, done) {
  var user = null;
  var userDn = requestHeaders.TLS_CLIENT_DN;

  // Authentication logic here!
  if(userDn === 'CN=test-cn') {
    user = { name: 'Test User' }
  }

  done(null, user);
}));

The verify callback can be supplied with the request object by setting the passReqToCallback option to true, and changing callback arguments accordingly.

var options =  {
  headers: ['TLS_CLIENT_DN'],
  passReqToCallback: true
}

passport.use(new Strategy(options, function(req, requestHeaders, done) {
  var user = null;
  var userDn = requestHeaders.TLS_CLIENT_DN;

  // Authentication logic here!
  if(userDn === 'CN=test-cn') {
    user = { name: 'Test User' }
  }

  done(null, user);
}));

Test

$ npm install
$ npm test

Contibuting

Contributions are welcome! Please write unit tests, follow the existing coding style and lint with eslint.

Authors

Joe Whitfield-Seed

Licence

The MIT Licence