This How-to applies to:
- Clavister Security Gateway 13.x
- EasyAccess 3.x (also referred to as "EA" here)
- YubiKey 5
- OneConnect 2.02.00
This HOWTO will guide you through what a YubiKey is, how it works, and how you can program and configure it to be used together with EA to protect an SSL VPN server on a Clavister NetWall. The main purpose is to get you started with how to use a YubiKey with some of Clavister's products.
Prerequisites: You need to have a YubiKey 5 hardware token, and it's assumed that you have already installed EA and a Clavister NetWall with a basic SSL VPN server, as well as a client with OneConnect SSL VPN client.
NOTE: In case you encounter problems when installing or using the YubiKey, please refer to this other How-to:
How to troubleshoot the Yubikey token
2. Table of Contents
- Programming the YubiKey
- Convert the YubiKey file to EA format
- Prepare the EA server for Yubikey
- Set up a token-based scenario
- Test the Yubikey token
The YubiKey is a USB hardware authentication device manufactured by the Swedish-founded company Yubico. It can be integrated with EA to provike token authentication. The prefix "Yubi" is the Japanese word for "finger" (similar to how "Clavister" is derived from the latin word "clavis" meaning "key").
By touching the YubiKey with your finger you verify your human presence, and that you are not a remote hacker. NOTE: This is not the same as biometric technology. The Yubikey does not care *who* pushes the button. The idea is that it is a token that only you have access to, so keep it safe, e.g. attached on a keyring that you always carry with you.
3.1. A brief note on how the Yubikey works
If you're using the Yubikey 5 series you should know first a bit how the key itself works:
The OTP application on the YubiKey provides two programmable slots, each of which can hold one of the types of credentials listed below. A Yubico OTP credential is programmed to slot one during manufacturing so that the YubiKey is ready to be used with many popular services that use this feature. The credential in the first slot is accessed by a short touch on the metal contact of the YubiKey; the second slot is accessed by a long touch of 3 seconds (if programmed). Output is sent as a series of keystrokes from a virtual keyboard, allowing the OTP application to work with any environment which supports USB keyboard input.
4. Programming the YubiKey
Yubikey tokens can be programmed in different ways. EA supports tokens with OATH mode.
Normally there will be an import file delivered from the vendor, containing the data for the tokens (also called a seed file).
If you have such a file, you can skip this section and go to step 5.
If no import file has been delivered, tokens can be programmed using the "YubiKey Personalization Tool" from Yubico. You can download it for free here:
https://www.yubico.com/products/service ... ion-tools/
You need to run this tool on the same PC where the Yubikey is plugged in to a USB slot. This PC does NOT need to the same that you end up using the Yubikey once everything is ready.
NOTE: PhenixID has a similar guide on how to program the key. See https://support.phenixid.se/sbs/prepare ... n-for-pas/
4.1. Insert the Yubikey into a USB slot.
4.2. Start the Yubikey personalization tool.
4.2.1. Verify that the tool detects the key.
You should have some information such as serial number etc. in the right hand information bar, as in the figure below:
4.3. In the tool, go to Settings tab.
Here, you only need to make sure the "Logging Settings" has "Log configuration output" checkboxed and set to "Traditional format":
4.4. Go to "OATH-HOTP" tab, then click the "Advanced" button.
(Note: if you later go another tab and then back again to OATH-HOTP it will remember you selected Advanced so you only need to do this once)
4.4.1. Now you should see at the top "Configuration Slot" and two available radio buttons "Configuration slot 1" and "Configuration slot 2".
Select "Configuration slot 1" unless you want to use slot 2 (see above under "A brief note on how the Yubikey works").
4.4.2. Check the "Program Multiple YubiKeys" checkbox
4.4.3. Check the "Automatically program YubiKeys when inserted"
4.4.4. Verify that "Parameter Generation Scheme" says "Incement Identities; Randomize Secret"
4.4.5. Under the OATH-HOTP Parameters section, make sure "OATH TOken Identifier (6 bytes)" is selected.
4.4.6. The dropdown menu next to OATH Token Identifier should read "OMP + TT Modhex, rest numeric"
4.4.7. In the little text form areas below that dropdown menu, enter "ub" in first area and "nu" in the second, and click "Generate MUI".
Verify that the digits in the third area are not "00 00 00 00" but random e.g. "91 45 03 22". Note this code is NOT the same as the OTP length. THis is the token identifier code and will stay the static until next time you program it. Also, the identifier must start with "ubnu" (ubnu12345678) for enrollment to work in EA.
4.4.8. Under the "Actions" section, click "Write configuration".
If you get a popup window about "Confirm: Overwrite configuration slot 1", press Yes if you want to overwrite the configuration. If you don't get such a popup it is probably the first time you program the Yubikey slot. (Or perhaps the configuration has been removed in some other way e.g. via Tools->Delete Configuration).
You will now have a popup window where you can enter the filename where the configuration will be saved.
Note this will be a CSV file. How you name it is irrelevant as long as you use a correct name format later on.
4.4.9. Finally, check the "Results" window at the bottom.
It should say something like "ubnuXXXXXXXX Yubikey has been successfully configured". where XXXXXXXX is the same code that you get in 4.4.7 above. Also, if you have more than one token identifier programmed, it will be visible here. You can also verify that the token has been programmed by checking the rightside bar under "Programming status", where it says "Slot 1 configured".
4.5. Copy the CSV file from 4.4.8 to a folder on the EA server (more about this below).
Contents of the csv file should now look something like this:
Code: Select all
LOGGING START,2019-12-20 09:30 OATH-HOTP,2019-12-20 09:30,1,ubnubfefejbb,,09cc433a254432985f25c18d2878e774d43ddd46,,,0,1,0,6,0,0,0,0,0,0
5. Convert the YubiKey file to EA format
5.1. Open the EA Test Tool, found in <path_to_phenixid_server_root>/bin/
5.2. Go to the "Yubico Formatter" tab, load the yubico file from 4.5 above and click "Write File".
This will generate a new file with a ".yubico" file name extension.
The new file looks something like this:
Code: Select all
Code: Select all
6. Prepare the EA server for Yubikey
6.0. As always, it's a good idea to make a backup of phenix-store.json before making changes.
6.1. Install the import module.
6.1.0. EA works by using a modular approach, which means that when you first install and run it, there are only the minimum amount of modules required to run the most basic service.
The more features you want to add, EA will need more modules added. Ususally this is all done automatically. In order to add a Yubikey to EA, it needs to be imported and consequently the import module is needed. Fortunately, the import module is automatcally added in the next step 6.1.1.
6.1.1. Configure MFA Admin and/or Self service with hardware tokens enabled.
6.1.2. Verify that the module has been installed by going to the Configuration Manager -> Start -> [Hostname] -> Modules.
In the list of modules you should see both "Hardware Token Management API" and "Hardware token admin".
NOTE: the full list of modules in this example may not be the same as the list you have, since it's dependent on what features you have enabled.
6.2. Import the Yubikey token
6.2.1. Note that the import file can have two formats: PSKC or a csv file.
If the file is in PSKC format, see the guide at http://document.phenixid.net/m/90910/l/ ... or-yubikey
In this guide we focus on the csv format file, since it's what we get when using the tool above.
6.2.2. Make sure the import file from 4.5 above has the extension .yubico or .yubikey (both will work when importing).
6.2.3. Place this file in the <path_to_phenixid_server_root>/tokensin/ directory.
Once placed there, it will be automatically processed and within a few seconds moved to <path_to_phenixid_server_root>/tokensout/.
You do not need to restart the EA service for this to take effect. Note also that the token can only be imported once.
6.2.4. After successful import the token will be visible in both the Configuration portal on the Reports tab and in MFA Admin, on the Hardware Token Admin tab.
Verify this by having a look there. The first illustration shows the tokens available under the Reports tab:
The following illustration shows the MFA Admin -> Hardware Token Admin tab (after a search for "*"):
6.3. Enroll the Yubikey token
6.3.1. Before we can start using the token, the user needs to enroll it via Self Serice or the MFA admin user needs to enroll it for the user via MFA Admin. Here we look at Self Service.
6.3.2. Log in to Self service as the user who will use the token.
Make sure you're doing this on the same PC where the Yubikey is inserted.
6.3.3. Go to the "Tokens" tab and click "Register hardware token"
6.3.4. You will see a popup window "Register hardware token" and a text area "Enter token ID".
Make sure the mouse pointer is in that area.
6.3.5. Click the Yubikey button and verify that the ID string has been entered.
Then click "Next".
6.3.6. You will get a text saying "Yubikey token device detected".
6.3.7. The Self Service page will now briefly show a green confirmation text "Hardware token was registered successfully", and below that you can see the token as "ACTIVE".
7. Set up a token-based scenario
7.1. As always, try to start with a very basic scenario, test it, and then add more complex features later if you want.
7.2. Go to the EA Configuration Manager -> Scenarios -> Radius, and create a scenario e.g. "Username, Password and Token".
7.2.1. In the "Username, Password and Token" scenario settings, start by entering a name:
7.2.2. Next, select a user store connection.
7.2.3. Verify and if necessary adjust the LDAP search settings.
7.2.4. Selet a RADIUS Server.
7.2.5. Specify the IP address(es) of the client(s), ie from which IPs the clients should be allowed to connect to the RADIUS server.
Also specify the RADIUS secret.
7.2.6. Skip the PIN code settings - we do not use that in this HOWTO.
So do not enable this.
7.3. Once the scenario has been created, open it and go to the "Execution Flow" tab.
7.3.1. Expand the "Verify token otp" pipe
7.3.2. Expand the "TokenValidationValve"
7.3.3. Go to the "Other" tab and select/check the "Try yubikey" option.
7.3.4. Do NOT change any other values such as OTP length if you have followed the instructions above correctly.
7.3.5. Click Save.
7.3.6. Now we're ready to test this.
8. Test the Yubikey token
8.1. In this guide we use the Clavister OneConnect SSL VPN client together with the Yubikey.
8.2. Configure an SSL VPN server on your Clavister NetWall.
It's a good idea to start by configuring it to authenticate using a local user database, rather than with RADIUS. How to do this is outside the scope of this guide. Once you have this working, proceed to change to use Radius as detailed below:
8.2.1. Set up a new Radius server under Policies -> User Authentication -> User Directories -> RADIUS.
Make sure to enter the IP address of the EA server and the right port and RADIUS secret that you specified in step 7.2.4 above.
8.2.2. Modify the current User Authentication rule (ie the one using the local database) by changing "Authentication Source" (on the "General" tab) to "RADIUS".
8.2.3. On the "Authentication Options" tab, select the RADIUS server from step 8.2.1 on "RADIUS servers".
8.2.4. Note also that on the "Agent Options" tab, you need to deselect all CHAP options, so you only have "PAP" selected.
8.2.5. Activate and commit the changes.
8.3. Now we are ready to test the SSL VPN (OneConnect) client.
8.3.1. Make sure the Yubikey hardware token is inserted into a USB slot on the PC client that will connect.
8.3.2. Start the OneConnect client.
Since you already have tried this using the local database above in step 8.2, you can use the same IP and port to connect, but you need to make sure you specify the username and password of a RADIUS user rather than a user in the local user database on the NetWall.
8.3.3. When you click "Connect", you will get a popup window prompting for the OTP.
Make sure the mouse cursor is in the OTP text area and press the Yubikey button. Note: do not hold the button down for long unless you have configured slot 2 -- se above for details. Also note that the Yubikey will send a newline character which will have the same effect as pressing "OK", so the popup window will disappear immediately and the client will try to connect.
8.3.4. What will happen now is that the Yubikey will send the full text string (identifier + OTP) as well as a newline character, as if pressing the "Enter" key.
So the OTP popup will disappear and the OneConnect client should hopefully now be able to connect. NOTE: Since we told EA to use Yubikey in step 7.3.3 above, EA will be able to process this text string and locate the actual OTP which is only the last 6 (or so) digits. You do not need to worry about this, and do NOT enter anything manually - let the Yubikey do its job.
That was it! Now you can proceed to try out other scenarios, but this is not covered in this guide.
REMEMBER: In case you encounter problems when installing or using the YubiKey, please refer to this other How-to:
How to troubleshoot the Yubikey token