rlm_yubico
FreeRADIUS module for using YubiKeys for authentication.
Introduction
This is a rlm_perl based module for FreeRadius that allows adding authentication by YubiKey OTP (One Time Password). It works in addition to existing authentication methods, such as username and password. A YubiKey OTP can be passed by appending it either to the username or the password. When possible, rlm_yubico will use an Access-Challenge response to query the user for an OTP if one is required but not provided.
Installation
-
Run 'make install'
-
Edit /etc/freeradius/modules/perl:
-
Set module = /usr/share/rlm_yubico/rlm_yubico.pl
-
-
Edit /etc/freeradius/sites-available/default:
-
Add "perl" (without quotes) to a line by itself in the "authorize" section. It needs to occur early on, at least before "files".
-
Add "perl" to a line by itself in the "post-auth" section.
-
-
Edit /etc/freeradius/dictionary:
-
Add the following line: $INCLUDE /usr/share/rlm_yubico/dictionary
-
Configuration
Place configuration in /etc/yubico/rlm/ykrlm-config.cfg Place username → YubiKey mappings in /etc/yubico/rlm/ykmapping or see below for using SQLite to manage mappings.
See the included ykrlm-config.cfg file for a description of available settings.
Any changes to configuration will require a full restart of freeradius to take effect. Even though freeradius supports reloading configuration without restarting (by sending a HUP signal), rlm_perl, which is used by rlm_yubico, does not.
NOTE: When running freeRADIUS (< 2.1.12) on a Debian based system, you need to preload Perl libraries for rlm_yubico to work. This can be done by running freeRADIUS using the following command (change the version to match your Perl installation):
LD_PRELOAD=/usr/lib/libperl.so.5.10 freeradius
SQLite Mappings
Set $mapping_file in ykrlm-config.cfg to an SQLite DSN and use the included radius-users script to manage the username → Yubikey mappings. Example:
$mapping_file = "dbi:SQLite:dbname=/etc/yubico/rlm/ykmapping.sqlite";
Changes to the SQLite database do not require a restart of FreeRADIUS, though the configuration change to enable SQLite support does.
When configured as described below in the notes section, maintaining the contents of the users file may no longer be necessary, as rlm_yubico.pl will handle looking up users and their passwords in SQLite.
The radius-users script draws upon the rlm_yubico.pl configuration, so there’s only one place to worry about the mapping_file. Make sure ykrlm-config.cfg is set correctly before using radius-users.
Example usage:
Create the initial database:
$ radius-users --create Creating database at DSN: dbi:SQLite:dbname=/tmp/ykmapping-temp.sqlite Success!
Add a user (will add yubikey later):
$ radius-users --adduser testuser Added user: testuser Password: pat336
Add/associate a yubikey with an existing user:
$ radius-users --addyubikey testuser ccccccccccccklvgijtgthnhfvvurjnilnbdflffuhke Added yubikey: cccccccccccc for user: testuser
Add a user and associate a yubikey with that user in one step:
$ radius-users --adduser testuser ccccccccccccriljtrcrgnfugjhgcigvdlgingfdriur Added user: testuser Password: eom669
List users:
$ radius-users --listusers Username Keys ------------------------------------------------------------------- testuser cccccccccccc
Disassociate a yubikey from a user (public_id or otp):
$ radius-users --delyubikey testuser cccccccccccc Removed yubikey: cccccccccccc for user: testuser
See who owns a yubikey (public_id or otp):
$ radius-users --whohas ccccccccccccerdtjbjguecbkeeudjchrhnlgrghketl testuser
Delete a user and associations:
$ radius-users --deluser testuser Deleted user: testuser
Notes:
-
A simple password is generated for every user. This password is random. This is a good thing. People suck at making passwords. This password is inert unless…
-
To require this password + OTP auth (making two-factor):
-
Set in the users file:
DEFAULT Auth-Type = Perl
-
Set in the radius config inside the authenticate {} block:
Auth-Type Perl { perl }
-
Remove references to PAP from the authenticate {} and authorize {} blocks. (Don’t worry, FreeRADIUS will still talk PAP, just without the PAP module overriding rlm_yubico.pl’s decisions.)
-
-
If you have performed the above two steps, then your users file only needs the DEFAULT line. All user management can be handled via radius-users and rlm_yubico.pl.
-
You can (but should not) set DEFAULT Auth-Type = Accept for OTP-only authentication. Do so only after understanding the ramifications of doing so. Hint: they depend on your environment.
Dependencies
rlm_yubico requires the following Perl modules:
Digest:: Error:: DBI:: DBD::SQLite Crypt::OpenSSL::Random Digest::HMAC_SHA1 Getopt::Long HTTP::Tiny MIME::Base64 URI::Escape
FreeRADIUS is also required.