Two-factor Authentication for CygNet Bridge API

August 1, 2019 / 0 comments / in API  General  / by Peter Franklin

CygNet Bridge API provides web-based access to CygNet data. See Eric's post for an overview of the debut Bridge API release. With the latest version, we've added many new features. We've added the ability to retrieve and acknowledge alarms, send and retrieve device data group transactions, send commands, and more. But the new feature I want to tell you about today is two-factor authentication (TFA).

TFA allows you to add an extra layer of security to your CygNet Bridge API. Instead of only requiring the user's login credentials for authentication, TFA requires the user to additionally provide a temporary 6-digit code that is generated by an authenticator app on their phone. See this video demonstrating how it works for the user.

The TFA feature requires users to install and use a third party authenticator app, such as Google Authenticator, on their mobile device. There are several authenticator apps in the Apple Store or Google Play store that will work with Bridge. The linked video demonstrates Microsoft Authenticator, but we've tested Google Authenticator and LastPass Authenticator and found that they all work nearly identically. This means that the TFA feature should work with almost any authenticator application available.

When you opt into TFA, the feature has two modes to choose from: 'required' or 'optional.' If in 'required' mode, all users must register for two-factor authentication when they first attempt to log in. When in 'optional' mode, each individual user can opt-in if they choose.

There are 2 Bridge API calls used when registering a user for TFA.

/clientloginapi/api/login/tfa-qr This API is returns the QR code image data so that your application can display it for the user to scan. It contains the information needed to register the user’s account in the authenticator mobile app. This API will return a 400 Bad Request error if the user is already registered for TFA.

/clientloginapi/api/login/tfa-confirm This API takes a header containing the 6-digit code generated by the authenticator mobile app. The code is provided in a header named, “X-WFT-AuthCode”. TFA registration is not complete until this confirmation step has been successfully completed.

After the user is registered for TFA, the login API will require the 6-digit code in a header named “X-WFT-AuthCode”. If this header is missing or the code is not correct, login will return a 403 Forbidden error. Your application should check for this error from the login API and prompt the user for the 6-digit code from their authenticator mobile app when it is returned.

To see sample code demonstrating all of this in an Angular web application, see the CygNet Bridge API sample app. The full source code is located on Github at:

https://github.com/cygnet-software/CygNetBridgeSampleApp

You can also refer to the CygNet help topic “Providing Two-factor Authentication for CygNet Bridge API” for details on implementing TFA in your deployment.