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

1. Python 3.6+
2. Gunicorn (Linux)
3. Waitress (Windows)
4. pipenv
5. 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;
    }

• NGINX Auth Request Module
• NGINX Proxy Module (including proxy_cache)

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:

1. sAMAccountName of 'tony.stark' or 'steve.rogers'
2. 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.