mod_authn_yubikey Documentation by Jens Frey V 1.0


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"

After your finished installing libcurl and coping/compiling/installing the module, you now can go on configuring mod_authn_yubikey.


We are going to explain every configuration option and supply an example configuration in this chapter.


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.


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.


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.


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.


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/
ErrorDocument 406    

# 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:

  1. Enters his username (jensfrey) in the username field.
  2. Enters his password (test123) in the password field.
  3. 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].