User Tools

Site Tools


plugins:yubikeyauth

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
plugins:yubikeyauth [2016/12/29 04:23]
nuxwin [Setup your Yubico client ID & API key]
plugins:yubikeyauth [2017/01/13 07:33]
nuxwin
Line 1: Line 1:
-====== YubiKeyAuth plugin for i-MSCP ​======+<​markdown>​ 
 +i-MSCP ​YubiKeyAuth plugin 
 +</​markdown>​
 <WRAP center round important 60%> <WRAP center round important 60%>
-**Be aware that this documentation ​always refers to the last YubiKeyAuth plugin ​version.**+**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>​ </​WRAP>​
-===== Introduction ===== +<​markdown>​ 
-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.+## Introduction
  
-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.+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
  
-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) authentication mode ==== 
 In this mode, a user can authenticate using his YubiKey only. There is no need to enter any credentials. 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.  +Be aware that single-factor (YubiKey only) authentication is not recommended for production use, as a lost or stolen 
-==== 2FA (Two-factor) ​authentication ​mode ==== +YubiKey would suffice to authenticate as a user.  
-This authentication ​mode is more secure than the 1FA mode, as an attacker would need to get an username, a password and a user YubiKey.+ 
 +### 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. 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) +## Requirements 
-  ​* ​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) +i-MSCP version >= 1.3.9 (API 1.0.7) 
-===== Installation ​===== +A YubiKey (See the `Getting a YubiKey` ​section below) 
-  ​- ​Be sure that all requirements as stated in the requirements section are met +A Yubico client ID & API key (See the `Getting your Yubico client ID & API keysection below) 
-  ​- ​Upload the plugin through the plugin management interface + 
-  ​- ​Install the plugin through the plugin management interface +## Installation 
-  ​- ​Setup your Yubico client ID & API key (see the **Setup your Yubico client ID & API key** section below) + 
-===== Update ​===== +1. Be sure that all requirements as stated in the requirements section are met 
-  ​- ​Read the UPDATE file inside the plugin archive +2. Upload the plugin through the plugin management interface 
-  ​- ​Be sure that all requirements as stated in the requirements section are met +3. Install the plugin through the plugin management interface 
-  ​- ​Upload 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) 
-===== 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/​+## 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: 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 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)+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. +However, note that this plugin should be compatible with any Yubico USB token providing OTP support. ​All Yubico ​products 
-===== Getting your Yubico ​client ID & API key ===== +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 processTherefore, you need first obtain a Yubico client ID and API key for use with YubiCloud Web service. In order you must:+  
 +## Getting your Yubico client ID API key
  
-  - Put your YubiKey ​in USB port of your computer +This plugin make use of YubiCloud Web service for verifying OTPS in the i-MSCP authentication processTherefore, you 
-  ​Browse the following URL: https://​upgrade.yubico.com/​getapikey/​ +need first obtain a Yubico client ID and API key for use with YubiCloud Web service. In order you must:
-  - Enter your e-mail address +
-  - Click on the **YubiKey OTP** input field and touch your YubiKey +
-  - Check the **Terms and Conditions** input checkbox +
-  - Click on the **Get API key** button +
-===== Setting up your Yubico client ID & API key ===== +
-For setting up your Yubico client ID & API key for use with this plugin ​you must in order:+
  
-  - Put your YubiKey in USB port of your computer +1. Put your YubiKey in USB port of your computer 
-  - Login to i-MSCP as administrator +2. Browse the following URL: https://​upgrade.yubico.com/​getapikey/​ 
-  ​- ​Go to the settings section and click on the **YubiKeyAuth settings** link +3. Enter your e-mail address 
-  ​- ​Fill the **Yubico client ID** input field with your Yubico client ID +4. Click on the `YubiKey OTP` input field and touch your YubiKey 
-  ​- ​Fill the **Yubico API key** input field with your Yubico API key +6. Check the `Terms and Conditions` input checkbox 
-  ​- ​Click on the **Yubico OTP** input field and touch your YubiKey+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 settingslink 
 +5. Fill the `Yubico client IDinput field with your Yubico client ID 
 +6. Fill the `Yubico API keyinput field with your Yubico API key 
 +7. Click on the `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. 
 + 
 +## Associating a Yubikey to your i-MSCP account
  
-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 have to wait up to 10 minutes before being able to setup them. 
-===== Associating a YubiKey with your i-MSCP account ===== 
 To associate a YubiKey with your i-MSCP account, you must in order. To associate a YubiKey with your i-MSCP account, you must in order.
  
-  - Put your YubiKey in USB port of your computer +1. Put your YubiKey in USB port of your computer 
-  ​- ​Login to i-MSCP with your current credentials +2. Login to i-MSCP with your current credentials 
-  ​- ​Go to the profile section of your account +3. Go to the profile section of your account 
-  ​- ​Click on the **YubiKey management** link +4. Click on the `YubiKey managementlink 
-  ​- ​Click on the **Add a YubiKey** button +5. Click on the `Add a YubiKeybutton 
-  ​- ​Touch your YubiKey to fill the input field in new dialog+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. If all goes fine, the YubiKey should be automatically added to the list of your YubiKeys.
-===== Make use of a Yubikey in i-MSCP authentication process ===== 
-To make use of a YubiKey in i-MSCP authentication process, you must in order: 
  
-  ​- Put your YubiKey in USB port of your computer +## Making use of your Yubikey in i-MSCP authentication process 
-  ​- ​Enter your current credentials (only needed for 2FA authentication mode) + 
-  ​- ​Click on the **YubiKey OTP** input field and touch your YubiKey+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 OTPinput field and touch your YubiKey
  
 If all goes fine, you should be automatically authenticated. 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. +## Yubico OTP extended settings 
-==== 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. +This plugin provides extended settings for the Yubico OTP service. They allow change of the default behavior for the OTP 
-==== Force OTP authentication ​==== +authentication handler, and also to set the maximum number of YubiKeys that one user can associate to his i-MSCP 
-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. +account. 
-==== 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. +These settings are available in the administrator settings section. They are displayed only when the Yubico Client ID & 
-===== OTP validation protocol ​===== +API key are properly configured. 
-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.+ 
 +### 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. 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'​s ​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.+## 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: For such setup you must in order:
  
-  - Setup your own OTP validation server(s) (See https://​developers.yubico.com/​OTP/​Guides/​Self-hosted_OTP_validation.html) +1. Setup your own OTP validation server(s) (See https://​developers.yubico.com/​OTP/​Guides/​Self-hosted_OTP_validation.html) 
-  ​- ​Program your YubiKeys using the YubiKey personalization tool +2. Program your YubiKeys using the YubiKey personalization tool 
-  ​- ​Change the OTP validation server URL(s) int the plugin configuration file +3. Change the OTP validation server URL(s) int the plugin configuration file 
-  ​- ​Distribute the YubiKeys to your employees +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 the plugin archive. Once translated you can send us your translation file (po file) for integration in future release.+## Plugin translation 
 + 
 +You can translate this plugin using a gettext translation editor such as `Poedit`. Translation files are located under 
 +the `./l10ndirectory 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
  
-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     i-MSCP YubiKeyAuth plugin
     © 2016 Laurent Declercq <​[email protected]>​     © 2016 Laurent Declercq <​[email protected]>​
     i-MSCP License <​https://​www.i-mscp.net/​license-agreement.html>​     i-MSCP License <​https://​www.i-mscp.net/​license-agreement.html>​
- +</markdown>​
-See [[https://​i-mscp.net/​license-agreement.html|License Agreement for Software Products of i-MSCP (internet - Multi Server Control Panel) project team]]. +
- +
- --- //​[[[email protected]|Nuxwin]] 2016/12/19 21:21//+
/var/www/virtual/i-mscp.net/wiki/htdocs/data/pages/plugins/yubikeyauth.txt · Last modified: 2017/03/25 04:03 by nuxwin