BorderPatrol for Nginx

BorderPatrol is an nginx module to perform authentication and session management at the border of your network.

BorderPatrol makes the assumption that you have some set of services that require authentication and a service that hands out tokens to clients to access that service. You may not want those tokens to be sent across the internet, even over SSL, for a variety of reasons. To this end, BorderPatrol maintains a lookup table of session-id to auth token in memcached.

Use cases

Assumption: All content to be access via BorderPatrol requires authentication

There are three primary use cases for BorderPatrol:

• A client has an auth token in the session store and the request is forwarded to the downstream service -or-
• A client does not have an auth_token for the specified service but has a master token, a call to the auth service will be made to get a service token for the downstream service -or-
• A client does not have an auth_token, and the client is redirected to a login page which posts back to nginx, performs an auth service lookup (and returns a master token and a service token from the auth service) and, on success, creates an entry in the session store for subsequent requests.

Use Case 1: Authorized Access

• Client requests a protected resource via BorderPatrol
• BorderPatrol looks up the session_id from the HTTP request in the SessionStore
• If service token present, BorderPatrol sets the Auth-Token header to the service token and allows the request to continue to the protected resource

Use Case 2: Unauthorized Access

• Client requests a protected resource via BorderPatrol
• BorderPatrol looks up the session_id from the HTTP request in the SessionStore
• Record exists in cache and there is a master token but no service token for specified downstream service
• A call is made to the Auth Service using the master token to get a service token
• BorderPatrol updates the session_id/{master_token, service_token_1, service_token_2...} pair in the SessionStore with appropriate expiry
• BorderPatrol redirects with the appropriate service Auth-Token header to the protected resource

Use Case 3: Unauthorized Access

• Client requests a protected resource via BorderPatrol
• BorderPatrol looks up the session_id from the HTTP request in the SessionStore
• If there is a cache miss, BorderPatrol serves up a login page
• On submittal, this posts to the AuthService (via BorderPatrol)
• On successful authentication (which returns a master token and a service token for the downstream service), the AuthService sets the Auth-Token header
• BorderPatrol sets the session_id/{master_token, service_token} pair in the SessionStore with appropriate expiry
• BorderPatrol redirects with the appropriate service Auth-Token header to the protected resource

Caching detail

The tokens cached in the session store are a string representation of a JSON structure as follows.

{
  "master_token" : "MMM",
  "service_tokens" : { "service_a": "AAA", "service_b": "BBB" }
}

The token that has the key of master_token is the Master Token, and can be used to make a call to the Auth Service to get other service tokens. Service Tokens have a key name that corresponds to the name of the downstream service.

Developing/Contributing

IRC

Join #borderpatrol on the Freenode

Installation

Darwin

Ensure you are using lua51, since the Lua Nginx support is 5.1 only.

• Get homebrew
• brew install luarocks
• brew install pcre
• brew install lua
• brew install luajit
• make

Linux

• apt-get install luarocks
• make

Running unit tests

You'll need the Test::Nginx CPAN module.

• cpan install Test::Nginx
• cpan install Test::Nginx::Socket
• make test

Running full mock services locally

• bundle install
• make mocktest
• In a browser, hit localhost:4443/b/ or business.localhost:4443

Additional Notes

make mocktest uses God to run 4 processes, on the following ports

• 4443 Mock BorderPatrol
• 9081 Mock Authorization service
• 9082 Mock downstream service A
• 9083 Mock downstream service B
• 9084 Mock Account Service

Subdomain routing

To test and work with subdomain routing locally, ensure to update your /etc/hosts file to include subdomains to localhost. For example:

127.0.0.1 business.localhost
127.0.0.1 enterprise.localhost

Troublshooting

Once you stop Mocktest, sometimes you must manually kill the processes above (i.e)

pkill -9 -f nginx pkill -9 -f god pkill -9 -f shotgun