Page 1 of 1

How to troubleshoot the Yubikey token

Posted: 24 Jan 2020, 15:30
by frba
This How-to applies to:
  • EasyAccess 3.0
  • YubiKey 5 (firmware 4.3.7)

1. Objectives with this article:

This How-to will provide some ideas what to look for when you encounter certain Yubikey issues. If you have problems registering, importing or using the token, or perhaps just encountered an error message in the EasyAccess logs, you can hopefully find some clues on this page. First there is an introductory section that explains briefly what the YubiKey is and how it works. Next follows a section on what a successful import, registration and usage of the token will look like, especially with regards to EasyAccess logs. The last section focuses on potential issues if any of these steps go wrong.

It is recommended that you also have a look at the following related How-to, which shows how to program, install and use the Yubikey:
Protect SSL VPN with YubiKey using EasyAccess

2.Table of content:
  • Introduction
  • Successful behaviour
  • Potential problems

3. Introduction

This section gives a brief introduction on the Yubikey.

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.

For details on how to configure the Yubikey, see the Forum HOWTO post:
Protect SSL VPN with YubiKey using EasyAccess

When everything is working as it should, the yubikey token ID should consist of the serial number which is something like "ubnu12345678" followed by the OTP code which is usually a 6-digit number e.g. "123456", so the full token ID will be e.g. "ubnu12345678123456". When you press the Yubikey button, the key will "type" that string (incl a newline) into the current window where your cursor is located, which can be a text editor, SSLVPN client, whatever.

Also, you can see which tokens are currently active in EA by going to the webui Config Mgr -> Reports -> Tokens -> All hardware tokens, and you'll get a list.

NOTE: the EasyAccess logs on this page represents running EA in normal logging mode (INFO log level). You can of course run it in DEBUG level, which also includes the logs from INFO log level. (The debug is so verbose that this page would become difficult to read.)

3.1. Token file format

Here we will have a look at which formats the token file can have.

Unconverted file

The expected syntax of an unconverted token file, ie a token file that has been programmed with e.g. the Yubico personalization tool but not yet been converted using the EasyAccess test tool, should be as follows:

Code: Select all

LOGGING START,2020-01-15 12:37
OATH-HOTP,2020-01-15 12:37,1,ubnubkhcijeh,,d0dae450c42c8b14c33b120fe01a206df5319e22,,,0,1,0,6,0,0,0,0,0,0
Converted file

The correct syntax of token file after converting it using the EasyAccess Testtool:

Code: Select all

ubnu19607836,ubnu19607836,0,d0dae450c42c8b14c33b120fe01a206df5319e22,,,
Advice: the "ubnu19607836" string consistst of the "ub" (OMP) + "nu" (TT) + "19607836" (MUI) which was programmed in the Yubico personalization tool (see the other How-to linked on this page). If you still have those details, you can cross-compare to check everything looks okay.

Later, once the token has been installed successfully and is ready to be used, this string together with the OTP (which is appended when the Yubikey is pressed) will make up the Token ID. So for instance: "ubnu19607836123456" ("ubnu19607836" followed by "123456")

4. Successful behaviour

This section provides explanation and logs when things work as they should, ie the behaviour when successfully installing/using the token.

4.1. Import of token file

These are the EasyAccess logs which are generated when the (converted) token file was successfully imported:

Code: Select all

2020-01-15 13:08:31,692 [HwTokenImporter]  INFO: Found a Yubico CSV file 'C:\Program Files\EasyAccess\Server\tokensin\frba-token-20200115a.yubico'
2020-01-15 13:08:31,754 [HwTokenImporter]  INFO: Imported '1' tokens from Yubico CSV file to store file.
Moreover, you should be able to find the yubico/yubikey file in the "tokensout" folder as well as be able to see in the EasyAccess Config Manager and/or MFA Admin.

4.2. Registration of a hardware token

When the user successfully registers the hw token in e.g. Self Service (or the admin does it in MFA Admin), no regular logs are generated. In order to see logs you need to enable DEBUG logging.

4.2. Logging in with the token

When the user successfully uses the Yubikey to login, e.g. together with our SSL VPN client, the following logs will be generated:

Code: Select all

2020-01-14 13:18:28,237 [TokenValidationValve]  INFO: Found '2' tokens for user 'foo'
2020-01-14 13:18:28,237 [OATHToken]  ERROR: Token type is not supported 'null'
2020-01-14 13:18:28,237 [TokenValidationValve]  WARN: Unsupported token type (Non HOTP/TOTP/PREFETCH ****** - will try next (if available)
2020-01-14 13:18:28,237 [TokenValidationValve]  INFO: Token validation successful for user 'foo'
2020-01-14 13:18:28,268 [TokenValidationValve]  INFO: Token was updated for user 'foo'
Note: the first three lines always seem to occur regardless if it's a successful or failed login.

Also, note that the first INFO line says found "2" tokens is because my user "foo" has two tokens registered. In your case it might be 1 or another number.

Besides the above logs generated in EA, the NetWall will also generate a USERAUTH log and other logs (e.g. SSLVPN) as usual (not shown here).


5. Potential problems

Here we focus on potential issues if anything goes wrong, e.g. when installing or using the token.

5.1. No token visible in Config Manager or MFA Admin

If the token was imported but doesn't show up in Config Mgr -> Reports -> Tokens -> All hardware tokens (nor in MFA Admin):

1) Check that the Hardware Token module has been installed. Configuration Manager -> Start -> [Hostname] -> Modules.
In the list of modules you should see both "Hardware Token Management API" and "Hardware token admin".
download/file.php?id=1687

2) Has the token actually been imported? The correct procedure is to format the file correctly (using the Testtool) and then place it in the "tokensin" folder. After a few seconds the MFA server will import it and move the file to "tokensout". If the user forgot to format the file or perhaps put the wrong file in "tokensin", the MFA logs will report this (here I'm specifically trying to import the unformatted Yubikey csv file):

Code: Select all

2020-01-15 12:55:01,688 [HwTokenImporter]  INFO: Found a CSV file 'C:\Program Files\EasyAccess\Server\tokensin\frba-token-20200115a.csv'
2020-01-15 12:55:01,688 [CSVParser]  ERROR: Invalid OATH HOTP token data 'LOGGING START,2020-01-15 12:37'
2020-01-15 12:55:01,688 [CSVParser]  ERROR: Invalid OATH HOTP token data 'OATH-HOTP,2020-01-15 ******'
2020-01-15 12:55:01,688 [HwTokenImporter]  INFO: Imported '0' tokens from CSV file to store file.
See also the section "Token file format" above.

5.2. Nothing happens when the Yubikey button is pressed

If the user is pressing the button on the Yubikey token but nothing happens, ie no text string (token ID) is written:

1) Check that the key has been properly programmed using the Yubikey Personalisation tool (see my HOWTO linked above)
2) The key should generate an ID regarless if you have configured EA or not. You can test this using a simple text editor like Notepad.

5.3. Failure to register the hardware token in Self Service

When the user goes to Self Service and clicks "Register hardware token", he gets a popup window "Enter token ID". If this string doesn't match what is expected (see above under "brief intro"), for instance if he is entering the wrong token ID, this is the log you get (in this example I entered "ullabella888888"):

Code: Select all

2020-01-14 13:48:06,697 [RequestHandler]  ERROR: Could not find TOKENS with serial 'ullabella888888'
com.phenixidentity.core.CoreException: Could not find TOKENS with serial 'ullabella888888'
        at com.phenixidentity.mpl.handlers.RequestHandler.get(RequestHandler.java:160) ~[com.phenixidentity~phenix-store-mpl~3.0.0/:?]
        at com.phenixidentity.mpl.handlers.RequestHandler.handle(RequestHandler.java:73) ~[com.phenixidentity~phenix-store-mpl~3.0.0/:?]
        at com.phenixidentity.mpl.handlers.RequestHandler.handle(RequestHandler.java:46) ~[com.phenixidentity~phenix-store-mpl~3.0.0/:?]
        at org.vertx.java.core.eventbus.impl.DefaultEventBus$11.run(DefaultEventBus.java:963) [vertx-core-2.1.6-2.jar:?]
        at org.vertx.java.core.impl.DefaultContext$3.run(DefaultContext.java:175) [vertx-core-2.1.6-2.jar:?]
        at org.vertx.java.core.impl.DefaultContext$3.run(DefaultContext.java:175) [vertx-core-2.1.6-2.jar:?]
        at org.vertx.java.core.impl.OrderedExecutorFactory$OrderedExecutor$1.run(OrderedExecutorFactory.java:92) [vertx-core-2.1.6-2.jar:?]
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149) [?:1.8.0_192]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624) [?:1.8.0_192]
        at java.lang.Thread.run(Thread.java:748) [?:1.8.0_192]
2020-01-14 13:48:06,697 [ScriptHandler]  WARN: [mods\com.phenixidentity~phenix-prism-selfservice~3.0.0\js\backend.js] Load token failed: org.vertx.java.core.eventbus.ReplyException: Could not find TOKENS with serial 'ullabella888888'
2020-01-14 13:48:06,697 [ScriptHandler]  WARN: [mods\com.phenixidentity~phenix-prism-selfservice~3.0.0\js\backend.js] Failed to find token with serial: ullabella888888
5.4. Failure to authenticate using the token

The following EA logs will be generated if there is something wrong when authenticating the Yubikey. For instance, if the user tries to login with our SSL VPN client but has done a mistake such as (to mention three examples, see further below for another scenario):

-Entered the wrong OTP
-Uses a disabled token (ie. the token exists in EA but has for some reason become disabled e.g. via Self Service)
-Uses a token that has been revoked/remoevd (ie. the token still exists in the EA database, just not for this specific user)

Code: Select all

2020-01-14 13:35:54,603 [TokenValidationValve]  INFO: Found '2' tokens for user 'foo'
2020-01-14 13:35:54,603 [OATHToken]  ERROR: Token type is not supported 'null'
2020-01-14 13:35:54,603 [TokenValidationValve]  WARN: Unsupported token type (Non HOTP/TOTP/PREFETCH ****** - will try next (if available)
2020-01-14 13:35:54,603 [HOTPToken]  WARN: Failed to synchronize token for user 'foo'
2020-01-14 13:35:54,603 [FlowImpl]  WARN: Pipe 'e7e62c51-a19d-434d-89e1-010bb3c691c2': Valve #1 'com.phenixidentity.pipes.valves.otp.token.TokenValidationValve' failed: 1104: Token validation failed (Wrong Token OTP)
2020-01-14 13:35:54,603 [Pipe]  WARN: Pipe failure: 1104: Token validation failed (Wrong Token OTP)
2020-01-14 13:35:54,650 [AbstractValve]  INFO: User 'foo' failed authentication, incrementing failed login attempts '1' (of '100')
2020-01-14 13:35:54,650 [AbstractValve]  INFO: Lockout data was persisted for user 'foo'
NOTE: When the token has been revoked/removed, the number of tokens in the first INFO line is lower than expected, so in the above logs it would be "1" instead of "2".

If the user tries to login with a Yubikey that has a deleted slot configuration, but everything else in EA is setup correctly (ie. the token was first programmed, imported etc but then for whatever reason the slot config was deleted):

-No logs are generated in EA, at least not when testing using SSL VPN, since the client refuses to proceed when the ID field is empty and an empty slot config generates no ID.

Note that the token will still be visible in EA under "Reports" and MFA Admin etc.