i-MSCP YubiKeyAuth plugin

Introduction

This plugin provides 1FA/2FA strong authentication with one-time passwords (OTPs), using YubiKey USB token. It make use of Yubico's Web service (YubiCloud) for verifying OTPs in the i-MSCP authentication process.

The one-time password requirement is enabled on a per user basis, and one user can associate one or many YubiKeys to his i-MSCP account, according the administrator setup.

Usage of a YubiKey in i-MSCP authentication process is either mandatory or optional, depending on the administrator setup. When it is optional, a user that has not associated a YubiKey to his account can simply ignore the YubiKey OTP input field.

1FA (Single-factor) mode

In this mode, a user can authenticate using his YubiKey only. There is no need to enter any credentials.

Be aware that single-factor (YubiKey only) authentication is not recommended for production use, as a lost or stolen YubiKey would suffice to authenticate as a user.

2FA (Two-factor) mode

This mode is more secure than the 1FA mode, as an attacker would need to get an username, a password and a user YubiKey. When this mode is enabled (default), the user need to provide a username, a password and make use of his YubiKey.

Requirements

• i-MSCP version >= 1.3.9 (API 1.0.7)
• A YubiKey (See the Getting a YubiKey section below)
• A Yubico client ID & API key (See the Getting your Yubico client ID & API key section below)

Installation

1. Be sure that all requirements as stated in the requirements section are met
2. Upload the plugin through the plugin management interface
3. Install the plugin through the plugin management interface
4. Setup your Yubico client ID & API key for (see the Setup your Yubico client ID & API key for use with this plugin section below)

Update

1. Read the UPDATE.md file inside the plugin archive
2. Be sure that all requirements as stated in the requirements section are met
3. Upload the plugin through the plugin management interface

Getting a YubiKey

If you don't have a YubiKey yet, you can buy one on our partner site at https://yubikey.ch/ or at the Yubico store: https://www.yubico.com/store/

This plugin has been successfully tested with the following Yubico products:

• YubiKey 4 and YubiKey 4 Nano (see https://yubikey.ch/index.php/webshop/yubikey-4)
• YubiKey NEO and YubiKey NEO-n (see https://yubikey.ch/index.php/webshop/yubikey-neo)

However, note that this plugin should be compatible with any Yubico USB token providing OTP support. All Yubico products are preconfigured for use of the Yubico OTP on slot 1 when they are shipped.

Getting your Yubico client ID & API key

This plugin make use of YubiCloud Web service for verifying OTPS in the i-MSCP authentication process. Therefore, you need first obtain a Yubico client ID and API key for use with YubiCloud Web service. In order you must:

1. Put your YubiKey in USB port of your computer
2. Browse the following URL: https://upgrade.yubico.com/getapikey/
3. Enter your e-mail address
4. Click on the YubiKey OTP input field and touch your YubiKey
5. Check the Terms and Conditions input checkbox
6. Click on the Get API key button

Setting up your Yubico client ID & API key

For setting up your Yubico client ID & API key you must in order:

1. Put your YubiKey in USB port of your computer
2. Login to i-MSCP as administrator
3. Go to the settings section and click on the YubiKeyAuth settings link
4. Fill the Yubico client ID input field with your Yubico client ID
5. Fill the Yubico API key input field with your Yubico API key
6. Click on the Yubico OTP input field and touch your YubiKey

If all goes fine, your Yubico client ID and API key should be automatically saved. Note that if you have just obtained your Yubico client ID and API key, you might have to wait up to 10 minutes before being able to setup them.

Associating a Yubikey to your i-MSCP account

To associate a YubiKey with your i-MSCP account, you must in order.

1. Put your YubiKey in USB port of your computer
2. Login to i-MSCP with your current credentials
3. Go to the profile section of your account
4. Click on the YubiKey management link
5. Click on the Add a YubiKey button
6. Touch your YubiKey to fill the input field in new dialog

If all goes fine, the YubiKey should be automatically added to the list of your YubiKeys.

Making use of your Yubikey in i-MSCP authentication process

To make use of your YubiKey in i-MSCP authentication process, you must in order:

1. Put your YubiKey in USB port of your computer
2. Enter your current credentials (only needed for 2FA authentication mode)
3. Click on the YubiKey OTP input field and touch your YubiKey

If all goes fine, you should be automatically authenticated.

Yubico OTP extended settings

This plugin provides extended settings for the Yubico OTP service. They allow change of the default behavior for the OTP authentication handler, and also to set the maximum number of YubiKeys that one user can associate to his i-MSCP account.

These settings are available in the administrator settings section. They are displayed only when the Yubico Client ID & API key are properly configured.

1FA (YubiKey only) authentication

This setting allows to enable/disable 1FA (YubiKey only) authentication. When enabled, one user can authenticate using his YubiKey only, without the need to enter any other credentials.

Force OTP authentication

This setting allows to force usage of a YubiKey in the i-MSCP authentication process. Enabling this feature only make a sense if all users have already associated at least one YubiKey to their i-MSCP account. That feature is mostly used in a pre-defined i-MSCP user group where the administrator ask all users to associate their YubiKey with their i-MSCP account before enabling this feature.

Max. YubiKeys per user

This setting allows setup of the maximum number of YubiKeys that one user can associate to his i-MSCP account. It acts for new YubiKey associations only, meaning that already associated keys won't be removed when the value of this setting is being lowered.

OTP validation protocol

The authentication handler provided by this plugin acts as a client of the Yubico Web service, implementing the version 2.0 of the Yubico OTP validation protocol.

See https://developers.yubico.com/yubikey-val/Validation_Protocol_V2.0.html for more details.

Self-hosted Yubico OTP validation server(s)

By default, the plugin make use of the YubiCloud Web Service to validate Yubico OTPs. This is the best default option since the YubiKeys are préconfigured for use of Yubico OTP on slot 1. However, it is still possible to use its own OTP validation server(s) by changing default validation server URLs in the plugin configuration file. This alternative is most-suited for enterprises that want install i-MSCP inside an intranet, and make their employees able to authenticate using their YubiKeys without involving any connection to external entity.

For such setup you must in order:

1. Setup your own OTP validation server(s) (See https://developers.yubico.com/OTP/Guides/Self-hosted_OTP_validation.html)
2. Program your YubiKeys using the YubiKey personalization tool
3. Change the OTP validation server URL(s) int the plugin configuration file
4. Distribute the YubiKeys to your employees

Plugin translation

You can translate this plugin using a gettext translation editor such as Poedit. Translation files are located under the ./l10n directory inside of this plugin archive. Once translated you can send us your translation file (po file) for integration in future release.

Note that if no translation file exists for your localization in the ./l10n/po directory, you must create it first from the l10n/YubiKeyAuth.pot file. Be aware that your file must be UTF-8, else, it won't be accepted.

License

i-MSCP YubiKeyAuth plugin
© 2016 Laurent Declercq <[email protected]>
i-MSCP License <https://www.i-mscp.net/license-agreement.html>