Passport-ReverseProxy

HTTP reverse proxy authentication strategies for Passport.

This module lets you authenticate HTTP requests using HTTP header values injected by a HTTP reverse proxy server in front of your application server. Reverse proxy authentication is a technique for enterprise networks to provide Single Sign On (SSO) for enterprise users.

By plugging into Passport, support for these schemes can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

Install

$ npm install passport-reverseproxy

Usage of HTTP

Using Apache as a reverse proxy

Here is an example of configuring Apache for use as a reverse proxy using a local passwd file.

Credit: Jenkins Reverse Proxy Auth Plugin

<Location />
    AuthName "Please sign in with your Apache user name and password"
    AuthType BASIC
    AuthUserFile /etc/apache2/passwd
    Require valid-user

    # prevent the client from setting this header
    RequestHeader unset X-Forwarded-User

    # Adds the X-Forwarded-User header that indicates the current user name.
    # this portion came from http://old.nabble.com/Forcing-a-proxied-host-to-generate-REMOTE_USER-td2911573.html#a2914465
    RewriteEngine On
    # see the Apache documentation on why this has to be lookahead
    RewriteCond %{LA-U:REMOTE_USER} (.+)
    # this actually doesn't rewrite anything. what we do here is to set RU to the match above
    RewriteRule .* - [E=RU:%1]
    RequestHeader set X-Forwarded-User %{RU}e
</Location>

Notes:

• Make sure that clients cannot bypass the reverse proxy. If they can send requests directly to Jenkins, then a malicious client can send in arbitrary header name with arbitrary value, thus compromising the security of Jenkins
• Make sure you configure the reverse proxy to erase the header that you use to pass the authenticated user name. This prevents malicious client from setting the header name with arbitrary value, which would ruin the security.

Configure Strategy

The HTTP Reverse proxy authentication strategy authenticates users by inspecting a configurable set of HTTP request headers.

By default, the strategy will look for a request header named 'X-Forwarded-User', which will be used as the value for req.user.username.

Optionally, you can specify the request headers that should participate in authentication decisions via the options.headers map:

var express = require('express'),
    passport = require('passport'),
    ReverseProxyStrategy = require('passport-reverseproxy');

passport.use(new ReverseProxyStrategy({
    headers: {
      'X-Forwarded-User': { alias: 'username', required: true },
      'X-Forwarded-UserEmail': { alias: 'email', required: false }
    }
  })
);

// require authentication for all requests except favicon.ico
app.configure(function() {
  app.use(express.favicon())
  app.use(express.bodyParser());
  app.use(passport.initialize());
  app.use(passport.authenticate('reverseproxy', { session: false }));
  app.use(express.static(path.join(__dirname, 'public')));
});

You can also specify a network range as a whitelist of allowed client connections to your app. The whitelist is a cursory security check to verify the end user did not circumvent the reverse proxy server. Your deployment should use this setting merely as a defense in depth layer alongside more robust network access control techniques (e.g., IPSec tunnels, VLANs, firewall rules). Advanced enterprise reverse proxy appliances may also include a non-repudiatable token, like a digital signature, that you should validate in the verify function.

passport.use(new ReverseProxyStrategy({
    headers: {
      'X-Forwarded-User': { alias: 'username', required: true },
      'X-Forwarded-UserId': { alias: 'id', required: false }
    },
     // only allow localhost to proxy requests
    whitelist: '127.0.0.1/0'
  })
);

Unlike most Passport authentication strategies, it is unlikely you will need session caching of the authentication ticket, since the reverse proxy should inject the headers into every request to your server.

The strategy optinally supports a verify callback, which accepts these reverse proxy header values and calls done providing a user.

passport.use(new ReverseProxyStrategy({
   headers: { 
      'X-Forwarded-User': { alias: 'username', required: true },
      'X-Forwarded-UserId': { alias: 'id', required: false }
   },
   // only allow localhost to proxy requests
   whitelist: '127.0.0.1/0'
  },
  function(headers, user, done) {
    var err = null;

    // verify that the username is an email address
    if (! /^.*@.*$/.test(headers['X-Forwarded-User'])) { return done(err, false, 401); }

    return done(err, user);
  })
);

Authenticate Requests

Use passport.authenticate(), specifying the 'reverseproxy' strategy, to authenticate requests. Requests relying on request header values are inherently stateless, and should not require session support, so the session option can be set to false.

For example, as route middleware in an Express application:

app.get('/private', 
  passport.authenticate('reverseproxy', { session: false }),
  function(req, res) {
    res.json(req.user);
  });

Examples

For a complete, working example, refer to the Reverse Proxy example.

Credits

• Steve Jansen

License

The MIT License