initial commit

Author: brigriffin

.gitignore

@@ -0,0 +1,2 @@
+config.yaml
+Gemfile.lock

Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'net-ldap'

README.md

@@ -0,0 +1,90 @@
+# Ruby LDAP authentication servlet for nginx HTTP auth request module
+
+nginx does not offer HTTP authentication using LDAP (or any other type of databases) as backend out of the box. Fortunately nginx features a module named ngx_http_auth_request_module which enables client authorization based on the result of an HTTP/HTTPS subrequest. Using this module in combination with the nginx HTTP proxy module it is possible to authenticate against any web service returning either an HTTP 200 code on authentication success or HTTP 401 code on authentication failure.
+
+This simple Ruby script implements a WEBrick HTTPS servlet listening by default on port 8888 in order to authenticate against an LDAP server using STARTTLS and thus enabling you to provide LDAP authentication for your nginx website.
+
+## Installation
+
+You will need Ruby and the bundler gem in order to install and run this script. Read below for the installation instructions.
+
+### Install bunlder
+
+	$ gem install bundler
+
+### Install dependencies
+Currently the only required gem is net-ldap.
+
+	$ bundle
+
+### Configure the script
+
+Copy the sample `config.sample.yaml` file as `config.yaml` and adapt it for your LDAP environment.
+
+### Configure nginx
+
+1. Add to your nginx http configuration (e.g. `/etc/nginx/conf.d/auth_cache.conf`):
+
+	```
+	proxy_cache_path cache/ keys_zone=auth_cache:5m;
+	```
+
+	The credentials are cached for 5 minutes, feel free to increase or decrease. If you change this parameter do not forget to also adapt `proxy_cache_valid` under point 2. below.
+
+2. Add to your nginx server configuration (e.g. `/etc/nginx/conf.d/mywebsite.ch`):
+
+	```
+	satisfy any;
+	auth_basic "Ruby LDAP authentication servlet";
+	auth_basic_user_file "/etc/nginx/empty.htpasswd";
+	auth_request /auth;
+
+	location = /auth {
+		proxy_pass https://localhost:8888;
+		proxy_cache auth_cache;
+		proxy_cache_valid 200 5m;
+		proxy_pass_request_body off;
+		proxy_set_header Content-Length "";
+		proxy_set_header X-Original-URI $request_uri;
+	}
+	```
+
+	This will protect the whole website. It is also possible to protect parts of it by including the first block in an nginx specific location such as `/private`:
+
+	```
+	location /private {
+		satisfy any;
+		auth_basic "Ruby LDAP authentication servlet";
+		auth_basic_user_file "/etc/nginx/empty.htpasswd";
+		auth_request /auth;
+	}
+	```
+
+3. Create an empty htpasswd file
+
+	This is required and I did not find any way around it.
+
+		$ touch /etc/nginx/empty.htpasswd
+
+4. Reload nginx
+
+		$ systemctl reload nginx
+
+### Start the script
+
+	$ ./ldap-auth-servlet.rb
+
+Once you have tested that everything works well it is recommended to run the script in background in daemon mode by changing the `daemonize` parameter in the `config.yaml` file to `true`.
+
+## Tested with
+
+This script has been tested with the following setup:
+
+- Debian 8
+- Ruby 2.4.0
+- nginx 1.6.2
+- OpenLDAP 2.4
+
+## TODO
+
+- Support multiple LDAP servers

config.sample.yaml

@@ -0,0 +1,9 @@
+# Config file for Ruby LDAP authentication servlet for nginx HTTP auth request module
+daemonize: false
+http_auth_realm: 'Ruby LDAP authentication servlet'
+ldap_host: 'ldap.enterprise.ch'
+ldap_port: 389
+ldap_auth_attribute: 'uid'
+ldap_auth_base_dn: 'ou=people,dc=enterprise,dc=ch'
+servlet_port: 8888
+servlet_ssl_certificate_cn: 'localhost'

ldap-auth-servlet.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+
+### Ruby LDAP authentication servlet for nginx HTTP auth request module ###
+
+# Purpose: This simple Ruby script implements a WEBrick HTTPS servlet listening by default on port 8888 in order to authenticate against an LDAP server using STARTTLS and thus enabling you to provide LDAP authentication for your nginx website.
+
+require 'webrick'
+require 'webrick/https'
+require 'base64'
+require 'net/ldap'
+require 'yaml'
+
+# Path to config file and default configuration parameters
+config_file = File.join(__dir__, 'config.yaml')
+config = {}
+config['daemonize'] = false
+config['http_auth_realm'] = 'Ruby LDAP authentication servlet'
+config['ldap_host'] = 'localhost'
+config['ldap_port'] = 389
+config['ldap_auth_attribute'] = 'uid'
+config['ldap_auth_base_dn'] = 'ou=people,dc=domain,dc=tld'
+config['servlet_port'] = 8888
+config['servlet_ssl_certificate_cn'] = 'localhost'
+
+class LDAPAuthServlet < WEBrick::HTTPServlet::AbstractServlet
+	def initialize server, config
+		super server
+		@config = config
+	end
+
+    def do_GET (request, response)
+		# Check for authorization HTTP header to perform authentication
+		if request.header.include?('authorization')
+			http_auth_header = request.header['authorization']
+
+			# Extract basic auth string
+	 		auth_encoded = http_auth_header[0].split(' ').last
+
+	 		# Decode basic auth string
+			auth_decoded = Base64.decode64(auth_encoded)
+
+			# Split auth string into an array with username and password
+			credentials = auth_decoded.split(':')
+
+			# Check for empty credentials, empty password or empty username
+			unless credentials.empty? or credentials.count == 1 or credentials[0].to_s.strip.length == 0
+				# Define LDAP connection using STARTTLS for encryption
+				ldap = Net::LDAP.new(:encryption => { :method => :start_tls })  
+				ldap.host = @config['ldap_host']
+				ldap.port = @config['ldap_port']
+
+				# Generate bind DN using passed username
+				bind_dn = @config['ldap_auth_attribute']+'='+credentials[0].strip+','+@config['ldap_auth_base_dn']
+				
+				# Authenticate with LDAP server
+				ldap.auth bind_dn, credentials[1].strip
+
+				# Catch errors such as Errno::ECONNREFUSED
+				begin
+					# Check for succesfull authentication
+					if ldap.bind
+						# Return HTTP OK on successful auth
+						puts '[INFO]: Authentication succesful for user '+credentials[0]
+						response.status = 200
+						return
+					else
+						# HTTP Unauthorized on failed auth
+						puts '[INFO]: Authentication failed for user '+credentials[0]
+					end
+				rescue => e
+					$stderr.puts '[ERROR]: Class -> '+e.class.to_s
+					$stderr.puts '[ERROR]: Message -> '+e.message
+					$stderr.puts '[ERROR]: LDAP result object -> '+ldap.get_operation_result.to_s
+					$stderr.puts '[ERROR]: LDAP result message -> '+ldap.get_operation_result.message
+				end
+			end
+		else
+			# First HTTP authentication attempt
+			puts '[INFO]: Authentication started'
+		end
+		# Default behaviour is to return HTTP Unauthorized
+		response.status = 401
+		response.header['Cache-control'] = 'no-cache'
+		response.header['WWW-Authenticate'] = 'Basic realm="'+@config['http_auth_realm']+'"'
+    end
+end
+
+puts "\n### Ruby LDAP authentication servlet for nginx HTTP auth request module ###\n\n"
+
+if File.exist?(config_file)
+	puts '[INFO]: Config file config.yaml found, using this file for configuration parameters.'
+	config = YAML::load_file(config_file)
+else
+	puts '[WARNING]: Config file config.yaml does not exist, using default configuration parameters.'
+end
+
+# Setup WEBrick with servlet
+cert_name = [['CN', config['servlet_ssl_certificate_cn']]]
+server = WEBrick::HTTPServer.new(:Port => config['servlet_port'], :SSLEnable => true, :SSLCertName => cert_name)
+server.mount '/', LDAPAuthServlet, config
+
+# Start WEBrick as daemon in background
+if config['daemonize'] == true
+	WEBrick::Daemon.start
+end
+
+trap('INT') {
+	  server.shutdown
+}
+
+server.start