diff --git a/README.md b/README.md index aaf8131c19d1bdbc727b59187b02b4d1cc2c8151..3f4a6fef9a74b1d622b8d384b8d2a9a3ea0029b4 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ To install and configure the reference implementation, perform the following ste 1. 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](https://github.com/osixia/docker-openldap) 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](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-a-basic-ldap-server-on-an-ubuntu-12-04-vps). + If you are using the LDAP server only to test the reference implementation, you can use the [OpenLDAP server Docker image](https://github.com/osixia/docker-openldap) 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](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-a-basic-ldap-server-on-an-ubuntu-12-04-vps). 1. 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. @@ -38,15 +38,15 @@ To install and configure the reference implementation, perform the following ste 1. 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. - **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. @@ -55,21 +55,25 @@ To install and configure the reference implementation, perform the following ste <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>; @@ -101,10 +105,10 @@ For detailed instructions, see [Configuring the Reference Implementation](https: 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)"; ``` @@ -113,22 +117,25 @@ In addition, the **X-Ldap-Template** header can be used to create complex LDAP 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; ... @@ -141,17 +148,20 @@ The **nginx-ldap-auth.conf** file enables caching of both data and credentials. <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 @@ -160,7 +170,6 @@ To modify the ldap-auth daemon to communicate with a different (non-LDAP) type o ## 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>