nginx 1.4.7 with nginx-auth-ldap on CentOS
How to compile and install nginx 1.4.7 with Valery's nginx-auth-ldap module and proxy to a python cgi server in CentOS.
Friday, March 21, 2014 | Careerism, Programming
If you look at my "recently used" emojis, it's like, heart, alien, poop, kiss, smile, pizza, rainbow. Those are the ones I always use.
|Sonny John Moore|
So, the latest twist with my hobby server at the job is that I've got to hide it behind an LDAP basic auth.
I will not go into specifics, but let it suffice that adding credential-checking has been the price of fame: as my hobby project has caught on, it was determined by my fearless leader that persons lacking an LDAP credential should be excluded from taking advantage of my project.
Since I run nginx, which does not have an off-the-rack LDAP authentication module (e.g. something like Apache's mod_ldap), this required just a little bit of hackery and the use of a module called "nginx-auth-ldap.
Background LiteratureBefore getting started, I recommend reviewing three resources:
- If you're not in the habit of installing nginx from source, read this SliceHost tutorial on installing nginx from source.
- The nginx-auth-ldap README.md on GitHub, which will outline most of the install and config process
- This (older) how-to at AllGoodBits.org, which points out some config subtleties that the README.md gdoes not.
- Compile and install nginx with the module
- Update your nginx.conf and your server/location configs
- Start the server
Compile and Install nginxAssuming that you haven't already installed nginx from a package (e.g. using yum) and you're working with a blank slate, you can follow the steps below.
When I did this on my work VM, I started out with a system where a previous install had to be removed and I lost a lot of time/sanity troubleshooting mystery seg faults caused by left-over bits of the previous install that I had not fully removed. If you are doing something similar, you are going to want to make sure that you're not overwriting/sharing directories with that previous install.
At any rate, downloading, configuring and installing (with make) is pretty straightforward, assuming that you don't have a previous install in your way.
Personally, I like to do this kind of stuff as root, in root's "home" directory: <code class="removed"></code> Some things to note about this piece:
- --with-http_ssl_module:This is important: LDAP authentication in nginx will not work without SSL support. I don't know if this is a bug, or something odd about my setup, but when I compiled nginx without the SSL flag, I was unable to start the server once I put auth_ldap directives in my config files.
- pcre-devel: I had to install the PCRE dev package, because (for whatever reason) it isn't included in the developer VM puppet configs at work.<code class="removed"></code>
- openldap-devel: If you see either of the following lines while running make or make install, you're missing the LDAP dev libraries: <code class="removed"></code> Do this to add them:<code class="removed"></code>
- --prefix:I use default prefixes, i.e. install directories, for installing the files, because I like manually-installed software to have all of its information in places that clearly indicate that it was installed by hand (e.g. and not by a package manager). If you do not want your binaries, configs, etc. to be installed in /usr/local/nginx, you'll want to use the --prefix=/whatever flag.
Configuration File UpdatesThis can get a little tricky.
Personally, I found the documentation on the http-auth-ldap GitHub a little ambiguous about where the various auth_ldap directives belong, so what I will do here is c/p all of my config files in full and then comment on the salient bits.
/usr/local/nginx/conf/nginx.conf<code class="removed"></code> One major thing to note about this:
- auth_ldap_cache_enabled: my nginx.conf is vanilla/default, except for these:
When I first started my server and trying to authentication via LDAP, I was getting errors like this:
I ended up finding this issue on the http-auth-ldap "Issues" index at GitHub and following the advice about halfway down the thread, which said to add the auth_ldap_cache_* directives.
tl;dr: adding the three lines above to my nginx.conf fixed my "Authentication timed out" errors.
/usr/local/nginx/conf/sites-available/001_toc_homepage<code class="removed"></code> This is where the magic happens. Notable features:
- ldap_server:The ldap_server definition is not placed under the global/http part of the nginx.conf. I originally had my nginx.conf set up like that, e.g. with the ldap_server in the http section, and I got seg faults every time I ran the nginx binary. No bueno.
- url: At my shop, the LDAP server is pretty vanilla, which is nice: I was basically able to use a user called "proxyuser" to access the server and pass along the user creds. While I was working on this, I noticed that there are some good configs out there if you're working against an LDAP server that's a little pickier about who does what and how, but I didn't save any links. Google is your friend.
- binddn_passwd: My LDAP server's "proxyuser" has a bunch of weird punctuation in his password and I was getting authentication timeout errors (similar to the ones above) until I put his password in quotes. YMMV.
- location: The location labeled "/cm/" is my application. You can review my last one for more details on setting up a python cgi server.
At this point, you're ready to start the server manually and try it out. My experience of this is that the module logs the majority of issues connecting to the LDAP server as some kind of timeout.
At the end of the day, as long as you're not getting seg faults, you're going to get some logging in the access and error logs: that's ultimately what's going to get you through whatever issues you've still got at this point.
Start the ServerSometimes I like to write my own init scripts, but I typically prefer to copy them from other people, especially when I'm on an unfamiliar OS.
In this case, I copied the one from the SliceHost tutorial I mentioned above.
I made a couple of extremely trivial modifications, and ended up with this:
<code class="removed"></code> Adding the init script to my init routine (e.g. using chkconfig) is not something that I wanted to do (for various reasons beyond the scope of this write-up), but the SliceHost article has a walkthrough below the script, if you're looking for a leg-up.
If you try to run the init script and you get this:
...then you forgot to create an nginx user (or never had one, etc.).
The fastest/cheapest way to make an effective, safe user is probably this: <code class="removed"></code>