Getting Started

This document will allow you to quickly configure and test a new YubiX installation, as well as get a grasp of the various parts of YubiX.

Overview

YubiX is a pre-configured packaging of various components that can be used together to integrate secure two-factor authentication with other systems. YubiX can be seen as a base to build your custom solution upon, but can also almost be used out of the box, with relatively little customization.

Getting YubiX

YubiX Virtual Appliance

You may download a virtual appliance of the YubiX: YubiX Virtual Appliance.

Once downloaded, the virtual appliance needs to be booted using some virtualization framework. We provided instructions for the following environments. If you are installing the package directly onto your machine, you don’t need to do anything extra.

Once booted you may login using the username yubikey and password yubico. Change the password if you are concerned with console access security.

Installing YubiX on Ubuntu

As an alternative to the virtual appliance, you can install the yubix package on your Ubuntu 12.04 LTS (or later) machine, via our PPAs:

Note
If your system does not already have the add-apt-repository command, you will need to install it first, which can be done by running:

For Ubuntu 12.10 and earlier:

sudo apt-get install software-properties-common

or

sudo apt-get install python-software-properties

For Ubuntu 13.04 and later:

sudo apt-get install python-software-properties

Once you have the add-apt-repository command available, run the following commands:

sudo add-apt-repository ppa:yubico/stable
sudo add-apt-repository ppa:yubico/yubix
sudo apt-get update
sudo apt-get install yubix

The YubiAdmin web interface

Most configuration can be done by using the YubiAdmin web interface. You can access it by opening a web browser and pointing it to the IP address of the YubiX host. The first time you do this, a setup page will be displayed allowing you to set a username and password for accessing the YubiAdmin interface, to prevent unauthorized access. Even so, it is strongly discouraged to expose the admin interface outside your local network!

Note
If you’ve manually installed YubiX instead of using the Virtual Appliance, the admin interface will be accessible on port 8080 from the machine itself (via the loopback interface only), using the default username and password: yubiadmin/yubiadmin.

Setting up RADIUS

The following describes a quick way to set up a system where users are authenticated over RADIUS with YubiKey OTP support. YubiX comes with FreeRADIUS pre-configured for use with the YubiKey, using a custom module which uses YubiAuth as an authentication backend.

OTP validation

Using YubiCloud for validation

By default, the YubiAuth installation verifies OTPs using the YubiCloud validation service. The YubiCloud service is free to use and YubiKeys are shipped pre-programmed with a key that works with YubiCloud out of the box.

Using your own validation server

If you intend to use the built in validation server, you will need to add some YubiKeys to the KSM which is also running on localhost. This isn’t required if you intend to use the YubiCloud service. Please follow along these three guides describing the steps retuired to generate and import keys into the KSM:

You also need to change the YubiAuth configuration so that it uses the local validation server, instead of YubiCloud. During installation, a client should have been automatically created, which we can use. To find out the client ID and API key, open the YubiKey Validation Server section in the YubiAdmin web interface, then click on the API Clients tab, and you should be presented with the Client ID and the API key. If you need more API clients, you can create those using this page.

To change the YubiAuth configuration, use the YubiAdmin web interface. Open to the YubiAuth section, and click on the Validation Server(s) tab. Enter the Client ID and API key, and replace the Validation Server URLs with the following single line:

http://127.0.0.1/wsapi/2.0/verify

Now click on the Save button, and you’re done. Remember to reload the web server for the changes to take effect (which can be done from the General tab).

Adding users

Adding users is done via the YubiAdmin web interface. Open the YubiAuth section, and click on the Manage Users tab. Using the on-screen buttons you can create, modify and delete users, as well as assign or unassign YubiKeys for them to use.

Auto-Provisioning

Auto-Provisioning gives you an easy way to associate YubiKeys with existing accounts. It is enabled by default, if you wish to disable it you can do so by unchecking the Auto Provision YubiKeys checkbox under the General tab of the YubiAuth section in the YubiAdmin web interface.

With Auto-Provisioning enabled, YubiKeys are assigned to users automatically. When an existing user that does not already have a YubiKey provisioned logs in using a YubiKey, that YubiKey is then assigned to the user. This allows you to hand out YubiKeys to some or all of the users, and let the keys become locked to the accounts when they are used. If you need to make changes to the auto-provisioned mapping or need to assign multiple YubiKeys to the same user, use the Manage Users tab of the YubiAuth section of the YubiAdmin web interface, as described in the previous section.

Test the setup

Once everything is configured, you should be able to authenticate using the radtest utility.

The YubiKey OTP can be provided by appending it either to the username or to the password. Here’s an example:

$ radtest user1 testingcccccccccccbbtrtikevthrvhceudvvuveidihckgrgl 127.0.0.1 0 testing123
Sending Access-Request of id 51 to 127.0.0.1 port 1812
        User-Name = "user1"
        User-Password = "testingcccccccccccbbtrtikevthrvhceudvvuveidihckgrgl"
        NAS-IP-Address = 127.0.1.1
        NAS-Port = 0
rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, id=51, length=20

Usage

Using YubiKey authentication with RADIUS is done by supplying a valid YubiKey OTP together with the users other credentials. This is done by appending the OTP to either the username, or to the password.