Merge pull request #64 from nikolaev-rd/patch-1

    - **nginx-ldap-auth-daemon.py** – 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

      ```

    - **nginx-ldap-auth-daemon-ctl.sh** – Sample shell script for starting and stopping the daemon. Install on the same host as the ldap-auth daemon.

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

1. Modify the NGINX Plus configuration file as described in [Required Modifications to the NGINX Plus Configuration File](#required-mods) below. For information about customizing your deployment, see [Customization](#customization) below. We recommend running the `nginx -t` command after making your changes to verify that the file is syntactically valid.

   <pre>root# <strong>nginx -s reload</strong></pre>

1. Run the following commands to start the ldap-auth daemon and the back-end daemon.

   <pre>root# <strong>nginx-ldap-auth-daemon-ctl.sh start</strong>

    root# <strong>python backend-sample-app.py</strong></pre>

   <pre>

   root# <strong>nginx-ldap-auth-daemon-ctl.sh start</strong>

   root# <strong>python backend-sample-app.py</strong>

   </pre>

1. 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:

<pre>Hello, world! Requested URL: <em>URL</em></pre>

<pre>

Hello, world! Requested URL: <em>URL</em>

</pre>

<a name="required-mods">

<a name="required-mods"></a>

### Required Modifications to the NGINX Plus Configuration File

</a>

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](https://nginx.com/blog/nginx-plus-authenticate-users#ldap-auth-configure) in the [NGINX Plus and NGINX Can Authenticate Application Users](https://nginx.com/blog/nginx-plus-authenticate-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://nginx.org/en/docs/).

<pre>http {

<pre>

http {

  ...

  proxy_cache_path <strong>cache/</strong> keys_zone=<strong>auth_cache</strong>:<strong>10m</strong>;

         proxy_set_header X-Ldap-BindPass "<strong>secret</strong>";

      }

   }

}</pre>

}

</pre>

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)";

```

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 as shown:

<pre><strong>#</strong>proxy_set_header X-CookieName "nginxauth";

<strong>#</strong>proxy_set_header Cookie nginxauth=$cookie_nginxauth;</pre>

<pre>

<strong>#</strong>proxy_set_header X-CookieName "nginxauth";

<strong>#</strong>proxy_set_header Cookie nginxauth=$cookie_nginxauth;

</pre>

## Customization

### Caching

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:

<pre>http {

<pre>

http {

  ...

  <strong>#</strong>proxy_cache_path cache/ keys_zone=auth_cache:10m;

  ...

      <strong>#</strong>proxy_cache_valid 200 10m;

     }

   }

}</pre>

}

</pre>

### 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:

<pre>proxy_set_header X-Ldap-Template "<strong>(cn=%(username)s)</strong>";</pre>

<pre>

proxy_set_header X-Ldap-Template "<strong>(cn=%(username)s)</strong>";

</pre>

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

<pre>proxy_set_header X-Ldap-Realm "<strong>Restricted</strong>";</pre>

<pre>

proxy_set_header X-Ldap-Realm "<strong>Restricted</strong>";

</pre>

### Authentication Server

## Compatibility

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

* [OpenLDAP](http://www.openldap.org/)</li>

* Microsoft Windows Server Active Directory 2003</li>

* Microsoft Windows Server Active Directory 2012</li>