auth-proxy

Authenitcating Proxy

STATUS - This project is under active development and while it is currently functional it is not yet stable or properly documented, I'll keep the README up to date as this project takes shape.

This module is a little bit of glue wrapping express, passport, and HTTP Proxy. It allows you to setup a simple reverse proxy server to provide authentication for otherwise unsecured services in your infrastructure. It currently ships with authentication using either Google apps oauth2. You must add apps domains and allowed users to a whitelist before anyone can authenticate, you'll also need to define your proxy routes before auth-proxy does anything useful for you.

Pull requests adding support for other authentication strategies are most welcome.

Installation

1. Clone the repo
2. cd into the directory and run npm install
3. Create a config.yaml in the root of the repository, any configuration added to this yaml file will override the defaults (set in default.config.yaml)
4. Setup your authentication strategies in the config.yaml file. See examples/config for more.
5. Setup your routes in config.yaml (see the documentation and examples below).
6. Verify that you have your configuration correct by starting the server with npm start.
7. Copy and edit the appropriate init script from the init directory to your system daemon.

Configuring

The default.config.yaml file holds the default configuration used by the proxy. If a config.yaml file is created in the root of the repository then any keys set will override defaults set in the default configuration file. Environment variables will override anything set in the configuration files. Environment variables can be set for any configuration key but are converted (all capital letters with underscores rather than camel case).

Defining Routes

The routes configuration key is an array of route objects. This list of routes is searched (in the order they are defined) when any incomming request is received in the proxy. A path and/or a hostname are checked (if configured - both optional) and the first matching route is used. For a small performance gain the most commonly used routes should probably be at the beginning of the list.

Required configuration keys

• host The host to proxy matching requests to.
• port The port at host to route the requests to.

Optional configuration keys

• name A name for the route; used on the index page to list this service.
• description A description for the route; used on the index page.
• link Used on the index page to link to this resource. This can be relative if paths are used to match or absolute for hosts.
• pathPattern A regex of the path to match, usually this should start with a ^/ (to match only instances at the beginning of the path and end with /? to optionally allow a trailing slash.
• hostPattern A regex to search for host to match for incomming routes. This allows you to route to different applications based on host name.
• pathRewritePattern This rewrites the request path sent to the backend used for this route. This may use regex matches from the pathPattern setting in normal javascript replace() syntax.
• hostRewritePattern This rewrite the request host sent in the headers to the backend for this route. Like pathRewritePattern this may use tokens from the hostPattern regex as per the normal javascript replace() syntax.
• basicAuth An object with attributes of name and password. This will be added as http basic auth for all requests proxied through this route.

Configuration example

routes:
  - name: "Jenkins"
    description: "An extendable open source continuous integration server."
    host: localhost
    port: 8080
    pathPattern: "^/jenkins/?"
    link: /jenkins
  - name: "Jenkins Git Calback"
    description: A brutal task master
    pathRewritePattern: /
    host: localhost
    port: 8080
    pathPattern: "^/jenkins/?"
  - name: test route
    pathPattern: "/test/?"
    description: debug info
    pathRewritePattern: "/"
    host: localhost
    hostPattern: 127.0.0.1
    link: test
    hostRewritePattern: fooozbazzzz
    port: 8989

Authentication Strategy Plugins

Auth-proxy uses a plugin system for authentication strategies which are pluggable. It ships with a couple of strategies but if a strategy is specified in configuration that is not found when requiring lib/plugins/index.js than a global require will be attempted.

Built in strategies

1. Google OAuth 2
2. Mock Strategy

Writing a Passport Authentication Strategy Plugin

An auth-proxy strategy plugin is a simple wrapper around the passport strategy responsible for receiving it's configuration, instantiating the underlying passport plugin, registering any necessary express routes, and rendering whatever widget needs to appear on the login page.

Required methods:

1. attach()

attach = function(passport, app, config, pluginConfig, logger) {}

Parameters:

• passport: The instantiated and configured passport object.
• app: The express app object, use this to register new routes needed for authentication.
• config: The current configuration for the server as a whole.
• pluginConfig: The configuration for this specific plugin.
• logger: The instantiated and configured winston logger object.

2. renderLogin()

Render login is responsible for rendering the necessary logn widget for the login page. It receives no parameters and if the module needs to use configurationfor this portion it should be retained from the attach() call which will always run first.