i-MSCP Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<markdown>
# i-MSCP YubiKeyAuth plugin
</markdown>
<WRAP center round important 60%>
**Be aware that this documentation is for the last available version. If you use an older version, you must refer to the README.md file inside the plugin archive.**
</WRAP>
<markdown>
## 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
6. Check the `Terms and Conditions` input checkbox
7. 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
5. Fill the `Yubico client ID` input field with your Yubico client ID
6. Fill the `Yubico API key` input field with your Yubico API key
7. 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 <l.declercq@nuxwin.com>
    i-MSCP License <https://www.i-mscp.net/license-agreement.html>
</markdown>
i-MSCP Documentation

User Tools

Site Tools

Page Tools
