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.
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.
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.
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.
Getting a YubiKeysection below)
Getting your Yubico client ID & API keysection below)
Setup your Yubico client ID & API key for use with this pluginsection below)
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:
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.
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:
YubiKey OTPinput field and touch your YubiKey
Terms and Conditionsinput checkbox
Get API keybutton
For setting up your Yubico client ID & API key you must in order:
Yubico client IDinput field with your Yubico client ID
Yubico API keyinput field with your Yubico API key
Yubico OTPinput 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.
To associate a YubiKey with your i-MSCP account, you must in order.
Add a YubiKeybutton
If all goes fine, the YubiKey should be automatically added to the list of your YubiKeys.
To make use of your YubiKey in i-MSCP authentication process, you must in order:
YubiKey OTPinput field and touch your YubiKey
If all goes fine, you should be automatically authenticated.
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.
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.
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.
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.
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.
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:
You can translate this plugin using a gettext translation editor such as
Poedit. Translation files are located under
./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.
i-MSCP YubiKeyAuth plugin © 2016 Laurent Declercq <firstname.lastname@example.org> i-MSCP License <https://www.i-mscp.net/license-agreement.html>