wiki:net.sf.basedb.yubikey/install

Installing the YubiKey authentication extension

Important information related to version 1.5 and higher!
To avoid locking everybody out of BASE it is recommended that the Password login form is enabled before starting the installation for the first time. Login to BASE and go to the Administrate ›› Plug-ins & extensions ›› Overview page. Locate the Login form customization extension point to find it. Once it has been verified that !YubiKey login works properly the Password login form can be disabled if desired.

Installation and updating

  1. Download the latest yubikey-x.y.tar.gz file from the YubiKey main page.
  2. Unpack the downloaded file to a directory of your choice.
  3. If this is a FIRST-TIME INSTALLATION:
    1. Generate a key for use with the Yubico Web Services (see below)
    2. Update the BASE database with additional columns in the users table (see below)
  4. Make additional configuration settings (see below)
  5. Copy the yubikey.jar file to your BASE plug-ins directory. Look in your base.config file if you don't know where this is.
  6. Log in to BASE as an administrator and go to the Administrate ›› Plug-ins & Extensions ›› Overview page.
  7. If this is a FIRST-TIME INSTALLATION (version 1.5 or higher):
    1. Verify that the Password login form is enabled.
  8. Run the installation wizard and select to install yubikey.jar.
  9. Done


FIRST-TIME INSTALLATION

Before installing the YubiKey extension for the first time there are a few configuration steps that must be performed. Unless otherwise noted, these steps only need to be done the first time.

A. Generate a key for use with Yubico Web Services

Without this key the extension is not allowed to validate passwords against the YubiCloud.

  1. Go to https://upgrade.yubico.com/getapikey/ and follow the instructions.
  2. Store the generated KEY and CLIENT_ID in the yubikey.properties file that was included with this extension.
  3. Move or copy the yubikey.properties file to the WEB-INF/classes directory of your BASE installation.

B. Update the BASE database with additional columns in the users table

  1. Move or copy the yubikey-extended-properties.xml file to the WEB-INF/classes/extended-properties directory.
  2. Shut down the BASE server including any job agents.
  3. Run the updatedb.sh script shipped with the BASE installation. This should create additional column in the Users table that are used to store YubiKey-related information.
  4. Restart the BASE server and job agents.

Additional configuration settings

There are some additional configuration settings that can be made in the yubikey.properties file. This step is optional. If you are installing multiple login managers on the same system you probably want to check the value for the allow-other-authentication setting. The authentication method published by this extension is named yubikey. You may need this when configuring the other login managers.

Note! Since version 1.5 changes to the configuration file are automatically detected and applied. There is no longer any need to re-start the server.

no-yubikey (since 1.1)

Comma- or whitespace- separated list of application ids for which YubiKey login should be disabled. For example, if you have installed the FTP server but do not want to use YubiKey for that:

no-yubikey = net.sf.basedb.clients.ftp

require-yubikey (since 1.3)

Comma- or whitespace- separated list of application ids for which YubiKey login is required. Users without a YubiKey will not be able to use those clients. For example, to force all users of the web client to use YubiKey:

require-yubikey = net.sf.basedb.clients.web

allow-other-authentication (since 1.5)

Comma- or whitespace- separated list of other authentication methods that are allowed even if a user has configured a YubiKey. Use * as a wildcard for all other authentication methods (including password authentication). Examples:

# Also allow password authentication even if a user has a YubiKey
allow-other-authentication = password

# Allow all other authentication methods
allow-other-authentication = *

# If the OTP login extension is also installed we can 
# allow users to use either YubiKey or OTP (with or without password)
allow-other-authentication = otp-only otp+password
Last modified 23 months ago Last modified on Dec 7, 2018, 8:42:50 AM