NGINX Active Directory Proxy

Service for authenticating users against Active Directory for the NGINX auth_request_module

Overview

This software provides a service that can be used with the NGINX auth_request_module. If you need to protect a website, part of a website or even a downstream application that you are protecting, you are able to use this service in conjunction with the auth_request_module.

Features

Authenticates against Active Directory.
No need for a bind user service account. Validates using user credentials entered.
Allows specifying Groups in the nginx.conf file. Users must belong to listed Groups to be allowed access.
Allows specifying Users (via username) that are allowed access.
Allows mixing of Groups and User (via OR - i.e. User must be in either the specified Groups or the specified Users).
Can configure multiple BASE DNs to search through.
Can be run as a Docker image or as a standard process.
Uses TLS over port 389

Requirements

Python 3.6+
Gunicorn (Linux)
Waitress (Windows)
pipenv
Docker (optional)

Getting started - configuring NGINX AD Proxy

Recommended: create a user with which to run nginx-ad-proxy - e.g.:

useradd -m -s /bin/bash -c "NGINX AD Proxy User" nginx-ad-proxy
passwd nginx-ad-proxy
sudo su - nginx-ad-proxy

Obtain nginx-ad-proxy and install dependencies

git clone https://github.com/nishen/nginx-ad-proxy
cd nginx-ad-proxy
pipenv sync

Configure your environment

Edit the .env file and add your settings:

AD_DOMAIN=COMPANY
AD_HOST=server.company.org
AD_PORT=389
AD_BASEDN=OU=Active,OU=Users,DC=company,DC=org|OU=Admins,OU=Users,DC=company,DC=org
DEBUG=0

NOTE: Works with using TLS over port 389

Start the service

The run scripts are configured in Pipfile under the scripts section.

[scripts]
launch = "gunicorn -b 127.0.0.1:9091 service_auth_ad:api"
launch-win = "waitress-serve --listen 127.0.0.1:9091 service_auth_ad:api"

Linux (assumes gunicorn installed)

pipenv run launch

Windows (assumes waitress-serve installed)

pipenv run launch-win

Getting started - configuring NGINX

Creating the block that points to the proxy

    location /auth-ad {
      internal;

      # this line points to the service you've configured above.
      proxy_pass                http://127.0.0.1:9091/auth;
      proxy_http_version        1.1;
      proxy_pass_request_body   off;
      proxy_set_header          Host $host;
      proxy_set_header          Connection "";
      proxy_set_header          Content-Length "";
      proxy_set_header          X-Real-IP $remote_addr;
      proxy_set_header          X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header          X-Forwarded-Proto $scheme;
      proxy_set_header          X-Original-URI $request_uri;

      # the next 2 lines allow us to pass a list of valid groups and/or users
      proxy_set_header          X-Auth-Groups $xAuthGroups;
      proxy_set_header          X-Auth-Users $xAuthUsers;

      # caching strategy - configure this however you'd like. Helps with performance.
      proxy_cache               auth_cache;
      proxy_cache_key           "$http_authorization";
      proxy_cache_valid         200 1m;
      proxy_ignore_headers      Cache-Control Expires Set-Cookie;
    }

Protecting the resource

You can protect 1 or more resources with a block like this:

    location /protected-resource {
      proxy_pass         http://127.0.0.1:8080/protected/resource/backend/url;

      # variable is used in the /auth-ad block to make authorization decisions.
      set $xAuthGroups   "AD-GRP-SHIELD";
      set $xAuthUsers    "tony.stark,steve.rogers";
      set $realm "Protected web Application";

      proxy_http_version 1.1;
      proxy_redirect     off;
      proxy_set_header   Connection "";
      proxy_set_header   Host              $host;
      proxy_set_header   X-Real-IP         $remote_addr;
      proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
      proxy_set_header   X-Forwarded-Proto $scheme;

      auth_request            /auth-ad;
      auth_request_set        $auth_status $upstream_status;

      # This helps if you don't want to create a login page and do redirects
      # for asking a user to login. This will generate the browser login box
      # on the client so they can login. You can create an empty htpasswd.dat
      # file and use the 'satisfy any' directive to allow authentication against
      # Active Directory only.
      auth_basic              $realm;
      auth_basic_user_file    /path/to/empty/htpasswd.dat;
      satisfy any;
    }

The above block will grant permission to a user that has EITHER of the following:

sAMAccountName of 'tony.stark' or 'steve.rogers'
Belongs to the Active Directory group 'AD-GRP-SHIELD'

Hope it helps!

If you have any questions or enhancement requests, feel free to drop a message or open an issue.

decision-labs / nginx-ad-proxy