Troubleshooting: Yubikey HOTP Suddenly Stops Working

Version Affected: All
 
 

Overview

This article covers two unrelated ways Yubikey authentication can stop working correctly.

• See Cause 1 - HOTP Counter Falls Out of Sync
• See Cause 2 - The IdP Can't Reach Yubico's Verification Endpoints

These causes are not related, so a fix for one cause will not resolve the others.

 

In this article

• Cause 1: HOTP Counter Falls Out of Sync
• Cause 2: The IdP Can't Reach Yubico's Verification Endpoints

Cause 1: HOTP Counter Falls Out of Sync

HOTP relies on a counter to calculate the next valid passcode. If this counter falls out of sync between the Yubikey and SecureAuth, the passcode is considered invalid. The counter falls out of sync when the OATH Token attribute isn't set to writable on the Data tab for realms that use HOTP.

Resolution 1:

To resolve this:

To prevent this from happening going forward:

1. Open the Admin Console.
2. Go to the Data tab for the realm.
3. Check the Writable checkbox for the OATH Token attribute.
4. Save the changes.

If users are already experiencing the issue, first resynchronize the counter:

1. Open the Admin Console.
2. Go to the System Info tab for the realm and click Decrypt.
3. Open web.config and find the line <add key="OATHLookAhead" value="50" />.
4. Change the value to 100 and save web.config.
5. Have the affected users log in -- this resynchronizes the counter.
6. Change OATHLookAhead back to 50 and save again.

Cause 2: The IdP Can't Reach Yubico's Verification Endpoints

Yubikey enrollment and OTP validation call out to Yubico's own cloud API to verify the passcode:

• api.yubico.com
• api2.yubico.com
• api3.yubico.com
• api4.yubico.com
• api5.yubico.com

If the IdP can't reach these endpoints, enrollment fails with a verification error, and it can also stop previously-enrolled Yubikeys from working as an MFA method. The realm logs show an entry similar to:

Message="SecureAuth.Integration.YubiKey.YubiKeyHelper.GetResponse exception: Unable to connect to the remote server"

Yubikey enrollment and validation ignore the realm's own proxy settings and try to reach Yubico's endpoints directly -- so if the IdP needs a proxy to reach the internet, Yubikey traffic needs to be routed through one explicitly.

Resolution 2:

To resolve this:

1. Back up the realm's web.config.
2. In the WebAdmin console (Classic view), go to the realm's System Info tab and click Decrypt.
3. Edit web.config in a text editor. Directly below <system.net>, add:

<defaultProxy>
    <proxy
        proxyaddress="http://<proxy-address>:<port>"
        bypassonlocal="true"
    />
</defaultProxy>

4. Save web.config, then repeat this on every realm that uses Yubikey for MFA.

Special Considerations

For the proxy configuration in Cause 2: it isn't possible to add credentials directly to the <defaultProxy> section. If the proxy requires authentication, make sure that's configured correctly on the realm's System Info tab -- the IdP will already be authenticated to the proxy by the time Yubikey uses it.


 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.