The RADIUSOV overlay allows the OpenLDAP `slapd` daemon to provide 802.1x authentication services via the RADIUS protocol.
## The RADIUS protocol?
It's never easy, figuring out what information to include in a README. Assuming the reader knows more than they do leads to frustration. But including too much information obfuscates what the user probably really needs to know.
So, first, a very quick summary:
The RADIUS protocol has been under active development since about 1989, first at the University of Michigan. That software base was taken over by the FreeRADIUS project in the late 1990s, and has been under active development ever since.
A very common use case, to the tune of hundreds of millions of installations, are Enterprise WiFi Access Points (also known as base stations).
In contrast to a typical home or small business, which has a single password for the WiFi network, each user in a large organization has their own unique WiFi password. When such a user connects to an Access Point, the user is asked for their username and password.
The AP then sends an authentication request to the well-known RADIUS UDP port 1812 on a designated RADIUS server. The server's IP address has to be configured into the AP, along with a RADIUS protocol "shared secret" known to both the AP and the server.
The RADIUS server looks up the username's password in a backend database, and the AP and the server go through the protocol and the AP is told that the password is good or bad.
That's enough information to understand the following instructions for deploying and configuring the RADIUSOV overlay. It is highly recommended that users who want a deeper understanding of RADIUS install FreeRADIUS and go through their documentation, which we are not going to attempt to duplicate here.
## Before deployment, compilation
Navigate to `<repositories>/openldap/contrib/slapd-modules/radiusov` and execute
make && make install
Pretty much the only thing that might need changing is the `OPT=` line of the Makefile; right now it's set to the `-O0` optimization level, and you might want something else. In testing, the optimization level made no obvious difference; overall processing time is, I speculate, swamped by communications latencies.
## Loading and configuring the overlay.
Loading and configuring the overlay is primarily controlled by entries in the OpenLDAP `slapd.conf` file. By default, it is found (at least sometimes!) in `/usr/local/etc/openldap` See the [OpenLDAP Administrator's Guide](https://www.openldap.org/doc/) for more information.
### Causing the overlay to load
These entries in `slapd.conf` will load and configure the overlay:
```
# Load the mdb backend
moduleload back_mdb.la
moduleload radiusov.so # Add this to the list of "moduleload" entries
```
The RADIUSOV overlay understands these `slapd.conf` parameters, which get associated with the backend that contains the passwords for the usernames:
```
radiusPort
radiusHost
radiusClientURI
radiusUserURI
radiusTlsConfigFile
```
I don't know about you, but I find examples to be the richest source of answers to the question, "What in tarnation is going on here!" Please look at the Makefile and related configuration files in `./demonstration/ldap`. In particular, the relevant section of `slapd.conf` in the demonstration looks like this:
radiusPort is set to `18129` so that RADIUSOV and FreeRADIUS can exist concurrently; FreeRADIUS listens for RADIUS packets on the well-known UDP port `1812`, while OpenLDAP will look for RADIUS packets on UDP port `18129`. This is a demonstration configuration; in ordinary operation, FreeRADIUS and OpenLDAP will not run concurrently, and OpenLDAP will listen on `1812`.
radiusHost is set to `0.0.0.0`, so that OpenLDAP will accept packets from anywhere.
radiusClientURI describes how the RADIUS `sharedSecret` for a particular IP address (the `ipa`) is found in the `dc=renbud,dc=com` database.
radiusUserURI describes how the `password` for a particular username (the `uid`) is found in that same database.
With that description as the starting point, I think the most understanding will come the most quickly from examining the working example in `./demonstration/ldap`
## Certificate difficulties
The most likely cause of problems will come when efforts are made to use certificates for authenticating both ends of the TLS link set up by the RADIUS protocol.
The included demonstration shows how to set up radiusclient, OpenLDAP, and FreeRADIUS to do the most rigorous authentication: The servers *demand* that the client send a client certificate, and the servers and the client all check the certificates, and the specified Certificate Authority, for validity and unexpired status.
But setting up a TLS tunnel doesn't have to be that persnickety.
It is necessary for the server to send the client a certificate -- it's needed for the initial handshake that results in a session key for encrypting data through the tunnel -- it is not necessary that that the certificate be current, or that it be signed by a Certificate Authority.
This is controlled, in both the `radiusclient` and RADIUSOV, by the `verify_mode` parameter, which has these four possible values for the server.
```
never - The server doesn't ask the client for a certificate.
allow - The server asks the client for a certificate, but ignores whether or not a certificate is sent, and ignores the certificate if it is sent.
try - The server asks the client for a certificate. If no certificate is sent, processing continues with no error indication. If a certificate is sent, it is checked for validity and an error issued if the certificate is invalid.
demand - The server requires that the client send a valid certificate.
```
On the client side, `never` and `demand` are effectively the valid possibilities.
In the interests of not throwing an error by default, the OpenLDAP RADIUSOV out-of-the-box configuration points to a TLS configuration `radiustls.conf` file that itself points to `/usr/local/etc/openldap/simple.pem`.
That `simple.pem` is a self-signed expired certificate with an unprotected private key. It is completely insecure and utterly unsuitable for *any* purpose except getting RADIUSOV working.
By default, and for the same reasonse, RADIUSOV sets `verify_mode` to `none`.
The included ./radiusclient and ./ldap directories demonstrate how the home-grown `radiusclient` application is able to authenticate users by sending RADIUS packets to FreeRADIUS on UDP port 1812, and to OpenLDAP's RADIUSOV overlay on UDP port 18129.
FreeRADIUS isn't necessary, but if you don't want it involved, you'll need to edit it out of the `./radiusclient\Makefile.` Specifically, comment out these lines:
On my system, I did a FreeRADIUS build from source, which puts configuration files at `/usr/local/etc/raddb`. The various configuration files here that need certificates all use the certificates at `/usr/local/etc/raddb/certs`. To make sure there are valid certificates there, the `./radiusclient` Makefile generates a compatible set of certificates and creates, or overwrites (as necessary), the certificates at `/usr/local/etc/raddb/certs`.
3) Navigate to `openldap/contrib/slapd-modules/radiusov` and execute
make && make install
4) Navigate to `./radiusclient` and execute
make
You need to do this before launching `slapd` or `radiusd` to make sure the correct certificates are in place.
5) Edit the `SLAPD` variable in ./slapd/Makefile. I mostly have been working with a debug build of `slapd`, hence the specific path to `slapd`.
7) Open a terminal window and navigate to `./ldap`. Execute
make scratch
You have to do this once to create a purely local OpenLDAP directory that will be used for the demonstration. Note further that the demonstration uses its own local `slapd.conf` file -- if I did everything right, the demonstration doesn't require any default information, nor will it affect in any way, an OpenLDAP installation on the same computer. It even uses its own TCP/IP port -- port 3899 -- for the demo.
6) Open a terminal window and navigate to `./ldap`. Execute
make both
If you have edited `./radiusclient/Makefile` to eliminate the two `rad:` instructions that reference port 1812, then just execute
make slapd
7) In another terminal window, navigate to `./radiusclient` and execute
make rad
In a perfect world, the process will result in SUCCEEDED indications.
The world being what it is, well, hopefully the error messages in the two terminal windows will give you enough information to figure out what's wrong.
Otherwise, well, give me a yell at support@symas.com
This directory can create and launch a purely local OpenLDAP instance that doesn't use any OpenLDAP global or default configuration files or data locations.
You'll need to run `make scratch` once to create the Directory Tree.
The base domain is "dc=renbud,dc=com"
The password for each user is the same as that user's "uid".
There is an Access Control List that prevent display of the userPassword hash to anybody except the Manager `"cn=Manager,dc=renbud,dc=com" -w secret`
After that, `make slapd` will launch the `slapd` daemon. It does so with a set of configuration files that allow it to respond to the `radiusclient` demonstration.
The RADIUSOV demonstration also authenticates against the FreeRADIUS `radiusd` daemon; you can launch that here with `make radiusd`.
In general, you'll want to launch them both with `launch both`.
You can shut down `slapd` and `radiusd` with `make kill`.
Note: Although I took pains to make sure that this local instance of slapd and its configuration files do not interfere with any other installation of OpenLDAP, I didn't make an effort to change the name. Thus, my ham-handed `make kill` will kill not just this local instance of `slapd` but any others that might be running.