mod_authn_yubikey you can protect your website with a basic auth mechanism (the username password popup box), just more secure 😉
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.
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
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
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
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
We are going to explain every configuration option and supply an example configuration in this chapter.
43200 seconds (12h)
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
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
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
On (secure connection required)
AuthYubiKeyRequireSecure directive takes care of users
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.
Off (built in error page used)
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
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
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
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].