Nginx Ldap Auth

Example of LDAP authentication using ngx_http_auth_request_module
Alternatives To Nginx Ldap Auth
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Authelia16,449118 hours ago34September 19, 202298apache-2.0Go
The Single Sign-On Multi-Factor portal for web apps
Errbit4,21315810a month ago7February 26, 201665mitRuby
The open source error catcher that's Airbrake API compliant
7 days ago47gpl-3.0Rust
Light LDAP implementation
Pac4j2,262146129a day ago96September 08, 2022apache-2.0Java
Security engine for Java (authentication, authorization, multi frameworks): OAuth, CAS, SAML, OpenID Connect, LDAP, JWT...
Glauth1,92932 months ago20February 28, 202263mitGo
A lightweight LDAP server for development, home use, or CI
Kanidm1,4743a day ago9May 01, 2022115mpl-2.0Rust
Kanidm: A simple, secure and fast identity management platform
Adldap2 Laravel910991625 days ago96November 12, 2020107mitPHP
LDAP Authentication & Management for Laravel
Caddy Security789
2 months ago36June 20, 202295apache-2.0Go
🔐 Authentication, Authorization, and Accounting (AAA) App and Plugin for Caddy v2. 💎 Implements Form-Based, Basic, Local, LDAP, OpenID Connect, OAuth 2.0 (Github, Google, Facebook, Okta, etc.), SAML Authentication. MFA/2FA with App Authenticators and Yubico. 💎 Authorization with JWT/PASETO tokens. 🔐
3 days ago7apache-2.0Java
MaxKey SSO ,Leading-Edge IAM-IDaas(Identity and Access Management) Product.
8 years agoapache-2.0PHP
Authentication layer for a YaCy webclient
Alternatives To Nginx Ldap Auth
Select To Compare

Alternative Project Comparisons

PLEASE note that this project is not designed or hardened for production. It is intended as a model for such connector daemons

The nginx-ldap-auth project

This project provides a reference model implementation of a method for authenticating users on behalf of servers proxied by NGINX or NGINX Plus.


For ease of reading, this document refers to NGINX Plus, but it also applies to open source NGINX. The prerequisite ngx_http_auth_request_module module is included both in NGINX Plus packages and prebuilt open source NGINX binaries.


The nginx-ldap-auth software is a reference model implementation of a method for authenticating users who request protected resources from servers proxied by NGINX Plus. It includes a daemon (ldap-auth) that communicates with an authentication server, and a sample daemon that stands in for an actual back-end server during testing, by generating an authentication cookie based on the user’s credentials. The daemons are written in Python for use with a Lightweight Directory Access Protocol (LDAP) authentication server (OpenLDAP or Microsoft Windows Active Directory 2003 and 2012).

The ldap-auth daemon, which mediates between NGINX Plus and the LDAP server, is intended to serve as a model for "connector" daemons written in other languages, for different authentication systems, or both. NGINX, Inc. Professional Services is available to assist with such adaptations.

NGINX LDAP Architecture

For a step-by-step description of the authentication process in the reference implementation, see How Authentication Works in the Reference Implementation in NGINX Plus and NGINX Can Authenticate Application Users.

Installation and Configuration

The NGINX Plus configuration file that is provided with the reference implementation configures all components other than the LDAP server (that is, NGINX Plus, the client, the ldap-auth daemon, and the back-end daemon) to run on the same host, which is adequate for testing purposes. The LDAP server can also run on that host during testing.

In an actual deployment, the back-end application and authentication server typically each run on a separate host, with NGINX Plus on a third host. The ldap-auth daemon does not consume many resources in most situations, so it can run on the NGINX Plus host or another host of your choice.

To install and configure the reference implementation, perform the following steps.

  1. Create a clone of the GitHub repository (nginx-ldap-auth).

  2. If NGINX Plus is not already running, install it according to the instructions for your operating system.

  3. If an LDAP authentication server is not already running, install and configure one. By default the ldap-auth daemon communicates with OpenLDAP, but can be configured to work with Active Directory.

    If you are using the LDAP server only to test the reference implementation, you can use the OpenLDAP server Docker image that is available on GitHub, or you can set up a server in a virtual environment using instructions such as How To Install and Configure a Basic LDAP Server on an Ubuntu 12.04 VPS.

  4. On the host where the ldap-auth daemon is to run, install the following additional software. We recommend using the versions that are distributed with the operating system, instead of downloading the software from an open source repository.

    • Python versions 2 and 3 are supported.
    • The Python LDAP module, python-ldap (created by the open source project).
  5. Copy the following files from your repository clone to the indicated hosts:

    • nginx-ldap-auth.conf – NGINX Plus configuration file, which contains the minimal set of directives for testing the reference implementation. Install on the NGINX Plus host (in the /etc/nginx/conf.d directory if using the conventional configuration scheme). To avoid configuration conflicts, remember to move or rename any default configuration files installed with NGINX Plus.

    • – Python code for the ldap-auth daemon. Install on the host of your choice.

      Alternatively, use provided Dockerfile to build Docker image:

      docker build -t nginx-ldap-auth-daemon .
      docker run nginx-ldap-auth-daemon

      If you desire to use a container with Python3, you can supply an appropriate build argument:

      docker build -t nginx-ldap-auth-daemon --build-arg PYTHON_VERSION=3 .
    • – Sample shell script for starting and stopping the daemon. Install on the same host as the ldap-auth daemon.

    • – Python code for the daemon that during testing stands in for a real back-end application server. Install on the host of your choice.

  6. Modify the NGINX Plus configuration file as described in Required Modifications to the NGINX Plus Configuration File below. For information about customizing your deployment, see Customization below. We recommend running the nginx -t command after making your changes to verify that the file is syntactically valid.

  7. Start NGINX Plus. If it is already running, run the following command to reload the configuration file:

    root# nginx -s reload
  8. Run the following commands to start the ldap-auth daemon and the back-end daemon.

    root# start
    root# python
  9. To test the reference implementation, use a web browser to access http://nginx-server-address:8081. Verify that the browser presents a login form. After you fill out the form and submit it, verify that the server returns the expected response to valid credentials. The sample back-end daemon returns this:

Hello, world! Requested URL: URL

Required Modifications to the NGINX Plus Configuration File

Modify the nginx-ldap-auth.conf file, by changing values as appropriate for your deployment for the terms shown in bold font in the following configuration.

For detailed instructions, see Configuring the Reference Implementation in the NGINX Plus and NGINX Can Authenticate Application Users blog post. The nginx-ldap-auth.conf file includes detailed instructions (in comments not shown here) for setting the proxy-set-header directives; for information about other directives, see the NGINX reference documentation.

http {
  proxy_cache_path cache/ keys_zone=auth_cache:10m;

  upstream backend {

  server {

      location = /auth-proxy {
         proxy_pass_request_body off;
         proxy_pass_request_headers off;
         proxy_set_header Content-Length "";
         proxy_cache auth_cache; # Must match the name in the proxy_cache_path directive above
         proxy_cache_valid 200 10m;

         # URL and port for connecting to the LDAP server
         proxy_set_header X-Ldap-URL "ldap://";

         # Negotiate a TLS-enabled (STARTTLS) connection before sending credentials
         proxy_set_header X-Ldap-Starttls "true";

         # Base DN
         proxy_set_header X-Ldap-BaseDN "cn=Users,dc=test,dc=local";

         # Bind DN
         proxy_set_header X-Ldap-BindDN "cn=root,dc=test,dc=local";

         # Bind password
         proxy_set_header X-Ldap-BindPass "secret";

If the authentication server runs Active Directory rather than OpenLDAP, uncomment the following directive as shown:

proxy_set_header X-Ldap-Template "(sAMAccountName=%(username)s)";

In addition, the X-Ldap-Template header can be used to create complex LDAP searches. The code in ldap-auth-daemon creates a search filter that is based on this template header. By default, template is empty, and does not make any effect on LDAP search. However, you may decide for instance to authenticate only users from a specific user group (see LDAP documentation for more information regarding filters).

Suppose, your web resource should only be available for users from group1 group. In such a case you can define X-Ldap-Template template as follows:

proxy_set_header X-Ldap-Template "(&(cn=%(username)s)(memberOf=cn=group1,cn=Users,dc=example,dc=com))";

The search filters can be combined from less complex filters using boolean operations and can be rather complex.

The reference implementation uses cookie-based authentication. If you are using HTTP basic authentication instead, comment out the following directives, and enable the Authorization header as shown:

#proxy_set_header X-CookieName "nginxauth";
#proxy_set_header Cookie nginxauth=$cookie_nginxauth;
proxy_set_header Authorization $http_authorization;



The nginx-ldap-auth.conf file enables caching of both data and credentials. To disable caching, comment out the four proxy_cache* directives as shown:

http {
  #proxy_cache_path cache/ keys_zone=auth_cache:10m;
  server {
    location = /auth-proxy {
      #proxy_cache auth_cache;
      # note that cookie is added to cache key
      #proxy_cache_key "$http_authorization$cookie_nginxauth";
      #proxy_cache_valid 200 10m;

Optional LDAP Parameters

If you want to change the value for the template parameter that the ldap-auth daemon passes to the OpenLDAP server by default, uncomment the following directive as shown, and change the value:

proxy_set_header X-Ldap-Template "(cn=%(username)s)";

If you want to change the realm name from the default value (Restricted), uncomment and change the following directive:

proxy_set_header X-Ldap-Realm "Restricted";

Authentication Server

To modify the ldap-auth daemon to communicate with a different (non-LDAP) type of authentication server, write a new authentication-handler class to replace LDAPAuthHandler in the script.


The auth daemon was tested against default configurations of the following LDAP servers:

  • OpenLDAP
  • Microsoft Windows Server Active Directory 2003
  • Microsoft Windows Server Active Directory 2012


The back-end daemon uses Base64 encoding on the username and password in the cookie. Base64 is a very weak form of scrambling, rendering the credentials vulnerable to extraction and misuse. We strongly recommend using a more sophisticated algorithm in your actual back-end application.


The reference implementation is subject to the same 2-clause BSD license as the open source NGINX software.

Popular Authentication Projects
Popular Ldap Projects
Popular Security Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.