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`.
