Added StartTLS support.

This is a rebased version and slightly modified version of patch submitted by
Matthieu Cerda <matthieu.cerda@gmail.com> via pull-request #29
(https://github.com/nginxinc/nginx-ldap-auth/pull/29)

README.md

@@ -86,7 +86,10 @@ For detailed instructions, see [Configuring the Reference Implementation](https:
          proxy_cache_valid 200 <strong>10m</strong>;
 
          # URL and port for connecting to the LDAP server
-         proxy_set_header X-Ldap-URL "<strong>ldaps</strong>://<strong>example.com</strong>:<strong>636</strong>";
+         proxy_set_header X-Ldap-URL "<strong>ldap</strong>://<strong>example.com</strong>";
+
+         # Negotiate a TLS-enabled (STARTTLS) connection before sending credentials
+         proxy_set_header X-Ldap-Starttls "true";
 
          # Base DN
          proxy_set_header X-Ldap-BaseDN "<strong>cn=Users,dc=test,dc=local</strong>";

nginx-ldap-auth-daemon.py

@@ -148,6 +148,7 @@ class LDAPAuthHandler(AuthHandler):
              # parameter      header         default
              'realm': ('X-Ldap-Realm', 'Restricted'),
              'url': ('X-Ldap-URL', None),
+             'starttls': ('X-Ldap-Starttls', 'false'),
              'basedn': ('X-Ldap-BaseDN', None),
              'template': ('X-Ldap-Template', '(cn=%(username)s)'),
              'binddn': ('X-Ldap-BindDN', ''),
@@ -193,6 +194,20 @@ class LDAPAuthHandler(AuthHandler):
             ctx['action'] = 'initializing LDAP connection'
             ldap_obj = ldap.initialize(ctx['url']);
 
+            # Python-ldap module documentation advises to always
+            # explicitely set the LDAP version to use after running
+            # initialize() and recommends using LDAPv3. (LDAPv2 is
+            # deprecated since 2003 as per RFC3494)
+            #
+            # Also, the STARTTLS extension requires the
+            # use of LDAPv3 (RFC2830).
+            ldap_obj.protocol_version=ldap.VERSION3
+
+            # Establish a STARTTLS connection if required by the
+            # headers.
+            if ctx['starttls'] == 'true':
+                ldap_obj.start_tls_s()
+
             # See http://www.python-ldap.org/faq.shtml
             # uncomment, if required
             # ldap_obj.set_option(ldap.OPT_REFERRALS, 0)
@@ -257,6 +272,9 @@ if __name__ == '__main__':
     group.add_argument('-u', '--url', metavar="URL",
         default="ldap://localhost:389",
         help=("LDAP URI to query (Default: ldap://localhost:389)"))
+    group.add_argument('-s', '--starttls', metavar="starttls",
+        default="false",
+        help=("Establish a STARTTLS protected session (Default: false)"))
     group.add_argument('-b', metavar="baseDn", dest="basedn", default='',
         help="LDAP base dn (Default: unset)")
     group.add_argument('-D', metavar="bindDn", dest="binddn", default='',
@@ -279,6 +297,7 @@ if __name__ == '__main__':
     auth_params = {
              'realm': ('X-Ldap-Realm', args.realm),
              'url': ('X-Ldap-URL', args.url),
+             'starttls': ('X-Ldap-Starttls', args.starttls),
              'basedn': ('X-Ldap-BaseDN', args.basedn),
              'template': ('X-Ldap-Template', args.filter),
              'binddn': ('X-Ldap-BindDN', args.binddn),

nginx-ldap-auth.conf

@@ -53,7 +53,7 @@ http {
             proxy_cache_key "$http_authorization$cookie_nginxauth";
 
             # As implemented in nginx-ldap-auth-daemon.py, the ldap-auth daemon
-            # communicates with an OpenLDAP server, passing in the following
+            # communicates with a LDAP server, passing in the following
             # parameters to specify which user account to authenticate. To
             # eliminate the need to modify the Python code, this file contains
             # 'proxy_set_header' directives that set the values of the
@@ -61,17 +61,25 @@ http {
             #
             #    Parameter      Proxy header
             #    -----------    ----------------
+            #    url            X-Ldap-URL
+            #    starttls       X-Ldap-Starttls
             #    basedn         X-Ldap-BaseDN
             #    binddn         X-Ldap-BindDN
             #    bindpasswd     X-Ldap-BindPass
             #    cookiename     X-CookieName
             #    realm          X-Ldap-Realm
             #    template       X-Ldap-Template
-            #    url            X-Ldap-URL
 
             # (Required) Set the URL and port for connecting to the LDAP server,
-            # by replacing 'example.com' and '636'.
+            # by replacing 'example.com'.
-            proxy_set_header X-Ldap-URL      "ldaps://example.com:636";
+            # Do not mix ldaps-style URL and X-Ldap-Starttls as it will not work.
+            proxy_set_header X-Ldap-URL      "ldap://example.com";
+
+            # (Optional) Establish a TLS-enabled LDAP session after binding to the
+            # LDAP server.
+            # This is the 'proper' way to establish encrypted TLS connections, see
+            # http://www.openldap.org/faq/data/cache/185.html
+            #proxy_set_header X-Ldap-Starttls "true";
 
             # (Required) Set the Base DN, by replacing the value enclosed in
             # double quotes.