Introduction
With mod_authn_yubikey
you can protect your website with a basic auth mechanism (the username password popup box), just more secure 😉
The mod_authn_yubikey
module is an authentication provider for the apache 2.2 platform. It leverages the YubiKey which is a small token that acts as an authentication device. By enabling your apache installation with this module you can use your YubiKey for authentication with your website.
The mod_authn_yubikey
module provides one and two factor authentication for your website and is completely independend from the technlogy that implements your website (like CGI, JSP or PHP).
In your backend application you can read the HTTP_X_YUBI_AUTH_TYPE
header, which is either OneFactor
or TwoFactor
stating that the user authenticated using either just the Yubikey itself or in conjunction with an additional password, where TwoFactor would be sent instead.
Installation From Source
For mod_authn_yubikey
to work you first need libcurl
. You have to install libcurl according to the installation instructions valid for your distribution and/or platform.
On a Debian system you would typically do a simple
aptitude install libcurl3
As a next step you need to download the source from the module
here. After extracting the module you need to
adopt the Makefile to point to an apache source tree, so the module is able to
compile (of course for compiling you might want to have libcurl-dev
too).
If you are not installing the module into a custom built apache, you might want
to use the apache server already installed on your system. If you are running
debian you need to have the apxs
tool for building the module. You can get
this tool by typing
aptitude install apache-threaded-dev
After you installed that, you can build and install the module with the following command (after changing into the directory you unpacked the module source of course):
apxs2 \
-DYK_PACKAGE=\\\"mod_authn_yubikey\\\" \
-DYK_PACKAGE_VERSION=\\\"0.1\\\" -I. -Wc -c -lcurl \
mod_authn_yubikey.c libykclient.c libykclient.slo mod_authn_yubikey.slo \
&& su -c "apxs2 -i mod_authn_yubikey.la"
After your finished installing libcurl
and coping/compiling/installing the module, you now can go on configuring mod_authn_yubikey
.
Configuration
We are going to explain every configuration option and supply an example configuration in this chapter.
AuthnYubiKeyTimeout
Parameter Name: AuthnYubiKeyTimeout
Default Value: 43200
seconds (12h)
Description: The AuthYubiKeyTimeout
directive specifies an absolute
timeout since the user last logged in. This means, that if the timeout is set
to 120 seconds, the user has to log in again after 120 seconds of using the
page. This is a hard timeout which is not renewed as the user is working with
the page.
AuthnYubiKeyTmpFile
Parameter Name: AuthnYubiKeyTmpFile
Default Value: $SERVER_ROOT/conf/ykTmpDb
Description: The AuthYubiKeyTmpFile
directive specifies the temporary file
which is used to store authenticated users. If a user successfully
authenticates, the authentication time is stored within this file.
It is used to determine when the user logged in last.
Remember, if you specify the location of the file, that if you
configure it to /tmp
on UNIX systems, that possibly everyone can view
that file.
AuthnYubiKeyUserFile
Parameter Name: AuthnYubiKeyUserFile
Default Value: $SERVER_ROOT/conf/ykUserDb
Description: The AuthYubiKeyUserFile
directive is the file which is
responsible for the tokenid/username mapping. Additionally it is required for
users to be present with their Yubikey id within this file to access the site
protected by mod_authn_yubikey
.
AuthnYubiKeyRequireSecure
Parameter Name: AuthnYubiKeyRequireSecure
Default Value: On
(secure connection required)
Description: The AuthYubiKeyRequireSecure
directive takes care of users
using https
with your selected target. This is especially useful if you are
authenticating users with two factors (password AND yubikey), since the
password and the token itself are just Base64 encoded when they are sent back
to the server authenticating the user.
AuthnYubiKeyExternalErrorPage
Parameter Name: AuthnYubiKeyExternalErrorPage
Default Value: Off
(built in error page used)
Description: The AuthYubiKeyExternalErrorPage
directive let’s you specify
an error page different from the built in error page, so that you are able to
design your own. By using the ErrorDocument
directive within your
configuration you can even redirect the user to a site not residing on you
machine.
Example Configuration
A example configuration using mod_authn_yubikey
is looking as follows (configured on a mac):
# These are global parameters, libcurl needs to be loaded from
# wherever it is installed on your system
LoadFile /opt/local/lib/libcurl.dylib
LoadModule authn_yubikey_module modules/mod_authn_yubikey.so
ErrorDocument 406 http://coffeecrew.org/index.html
# This tells apache that you really do not want any security in the
# first place and that you will protect your login location or directory
# by responsibly setting up an SSL connection to that location. If you
# just use OneFactor authentication (just the key, no password) this is
# of course unneccessary, since a stolen password (the token output)
# cannot be reused.
AuthYubiKeyRequireSecure Off
# Global configuration end
AuthType Basic
AuthBasicProvider yubikey
AuthName "Please Log In using your YubiKey"
AuthYubiKeyTimeout 30
AuthYubiKeyTmpFile conf/ykTmpDb
AuthYubiKeyUserFile conf/ykUserDb
AuthYubiKeyRequireSecure On
AuthYubiKeyExternalErrorPage Off
Require valid-user
Using mod_authn_yubikey
Now that you have configured the mod_authn_yubikey
module, you’ll probably
want to use it. For this to happen, you have to add the tokenId/user mapping
into the file configured with AuthYubiKeyUserFile
which defaults to
conf/ykUserDb
if not specified otherwise.
To add the user jensfrey
with the password test123
and the token id
abcdefghijkl
you would do:
htpasswd -csb conf/ykUserDb abcdefghijkl jensfrey:test123
Which lets the user jensfrey
access the site when he:
- Enters his username (
jensfrey
) in the username field. - Enters his password (
test123
) in the password field. - And the presses the button on the YubiKey (while having the cursor still set on the password field)
Note: Remember to put the -s
option into the command, since UNIX
platforms use crypt()
by default. The -s
switch forces SHA hashing of the password (you can also use -m
which is for MD5 hashing). [Thanks to Fredrik Soderblom for pointing that out].