README.md
1# LDAP Authentication module for nginx
2LDAP module for nginx which supports authentication against multiple LDAP servers.
3
4# How to install
5
6## FreeBSD
7
8```bash
9cd /usr/ports/www/nginx && make config install clean
10```
11
12Check HTTP_AUTH_LDAP options
13
14
15```
16[*] HTTP_AUTH_LDAP 3rd party http_auth_ldap module
17```
18
19## Linux
20
21```bash
22cd ~ && git clone https://github.com/kvspb/nginx-auth-ldap.git
23```
24
25in nginx source folder
26
27```bash
28./configure --add-module=path_to_http_auth_ldap_module
29make install
30```
31
32# Example configuration
33Define list of your LDAP servers with required user/group requirements:
34
35```bash
36 http {
37 ldap_server test1 {
38 url ldap://192.168.0.1:3268/DC=test,DC=local?sAMAccountName?sub?(objectClass=person);
39 binddn "TEST\\LDAPUSER";
40 binddn_passwd LDAPPASSWORD;
41 group_attribute uniquemember;
42 group_attribute_is_dn on;
43 require valid_user;
44 }
45
46 ldap_server test2 {
47 url ldap://192.168.0.2:3268/DC=test,DC=local?sAMAccountName?sub?(objectClass=person);
48 binddn "TEST\\LDAPUSER";
49 binddn_passwd LDAPPASSWORD;
50 group_attribute uniquemember;
51 group_attribute_is_dn on;
52 require valid_user;
53 }
54 }
55```
56
57And add required servers in correct order into your location/server directive:
58```bash
59 server {
60 listen 8000;
61 server_name localhost;
62
63 auth_ldap "Forbidden";
64 auth_ldap_servers test1;
65 auth_ldap_servers test2;
66
67 location / {
68 root html;
69 index index.html index.htm;
70 }
71
72 }
73```
74
75# Available config parameters
76
77## url
78expected value: string
79
80Available URL schemes: ldap://, ldaps://
81
82## binddn
83expected value: string
84
85## binddn_passwd
86expected value: string
87
88## group_attribute
89expected value: string
90
91## group_attribute_is_dn
92expected value: on or off, default off
93
94## require
95expected value: valid_user, user, group
96
97## satisfy
98expected value: all, any
99
100## max_down_retries_count
101expected value: a number, default 0
102
103Retry count for attempting to reconnect to an LDAP server if it is considered
104"DOWN". This may happen if a KEEP-ALIVE connection to an LDAP server times
105out or is terminated by the server end after some amount of time.
106
107This can usually help with the following error:
108
109```
110http_auth_ldap: ldap_result() failed (-1: Can't contact LDAP server)
111```
112
113## connections
114expected value: a number greater than 0
115
116## ssl_check_cert
117expected value: on or off, default off
118
119Verify the remote certificate for LDAPs connections. If disabled, any remote certificate will be
120accepted which exposes you to possible man-in-the-middle attacks. Note that the server's
121certificate will need to be signed by a proper CA trusted by your system if this is enabled.
122See below how to trust CAs without installing them system-wide.
123
124This options needs OpenSSL >= 1.0.2; it is unavailable if compiled with older versions.
125
126## ssl_ca_file
127expected value: file path
128
129Trust the CA certificate in this file (see ssl_check_cert above).
130
131## ssl_ca_dir
132expected value: directory path
133
134Trust all CA certificates in this directory (see ssl_check_cert above).
135
136Note that you need to provide hash-based symlinks in the directory for this to work;
137you'll basically need to run OpenSSL's c_rehash command in this directory.
138
139## referral
140expected value: on, off
141
142LDAP library default is on. This option disables usage of referral messages from
143LDAP server. Usefull for authenticating against read only AD server without access
144to read write.
145
146