Providing Two-Factor Authentication for CygNet Bridge API

Provide two-factor authentication to add an additional layer of security when using CygNet Bridge API over the web. When the option is available, providing two-factor authentication (2FA) better protects access to your CygNet data and controls. To provide two-factor authentication, you must set it up for applicable parts of your system. Currently two-factor authentication can be used with the CygNet Bridge API feature in CygNet Bridge.

Configure the Two-Factor Authentication Mode

Configure the settings governing usage of two-factor authentication during installation of CygNet Bridge API, in the Multi-factor authentication section of the CygNet Bridge installer. The Two-factor mode selection determines how, or if, two-factor authentication is available for use with CygNet Bridge API. Possible settings are as follows.

• Disabled — CygNet Bridge API has not enabled the use of 2FA; this is the default setting
• Optional — each CygNet Bridge API user can decide whether or not they want to use 2FA
• Required — all CygNet Bridge API users are required to use 2FA

See Installing CygNet Bridge for more information about selecting 2FA mode during the installation process.

Provide Two-Factor Authentication

Providing two-factor authentication for CygNet Bridge API adds considerations to your preparation process. If you intend on using two-factor authentication, plan your CygNet Bridge installation to include the following elements.

Element	Description
CygNet elements
CygNet Group service (GRP service type)	You will need to set up a separate CygNet Group service specifically to store user authentication information used for 2FA. When installing CygNet Bridge with the Bridge API feature selected, you will be asked to supply the information for this separate Group service in the Multi-factor authentication section of the Bridge API page. See Preparing your System for CygNet Bridge API for more information.
CygNet Bridge API sample web application	(Optional) When you build the CygNet Bridge API sample web application, you will have access to samples provided to help you build calls to interact with your CygNet Bridge APIs, including an example for two-factor authentication. See Building the CygNet Bridge API Sample Web Application for more information.
Additional requirements
Mobile phone	You will need consistent access to a mobile phone device capable of installing a two-factor authenticator app and scanning a QR code as necessary. (Examples: iOS or Android mobile devices)
Two-factor authenticator app	You will need to select and install an authenticator app that is capable of generating a time-based, one-time passcode, and is compatible with your mobile phone device. (Examples: LastPass Authenticator, Microsoft Authenticator, Google Authenticator)

Use the following procedure to provide two-factor authentication for CygNet Bridge API.

To Provide Two-Factor Authentication for CygNet Bridge API

1. Complete the following preparations for two-factor authentication.
1. Verify or create a dedicated Group service (GRP service type) in your CygNet installation, to use specifically for storing user authentication information. See Preparing your System for CygNet Bridge API for more information about the process.

   Note: During CygNet Bridge and Bridge API installation, when 2FA is enabled, the new Group service information will be required in the "Multi-factor authentication" section of the Bridge API page.

2. Secure access to a mobile phone device capable of installing and running a two-factor authenticator app and scanning a QR code as necessary.
3. Select an authenticator app capable of generating a time-based, one-time passcode, that meets your needs and is compatible with your mobile phone device. Install the authenticator app you have selected on your mobile phone device.
4. Install CygNet Bridge, with the CygNet Bridge API feature selected, the multi-factor authentication mode set to Optional or Required, and information supplied for the dedicated Group service. See Installing CygNet Bridge for more information.
5. Start your CygNet Bridge site in the IIS Manager.

Enable Two-Factor Authentication for a User Account

When the multi-factor authentication mode is set to Required, all users must enable 2FA for their user login. When the mode is set to Optional, each user can decide whether or not to enable 2FA.

To Enable Two-Factor Authentication for Your User Account

Using your API client, do the following to enable two-factor authentication for your user account.

1. Access the QR code and generate an authentication passcode.
1. Create a GET clientloginapi/api/login/tfa-qr request to generate the CygNet Bridge API QR code image data.
2. Provide your user credentials (username, password, and domain/workstation etc. if applicable).
3. Display the QR code image data contained in the response.
4. Using the 2FA app on your mobile phone device, scan the QR code and process the image to produce an authentication passcode.

   Note: You can still change your mind and stop the setup process at this point, if desired. The passcode will not become required until the next step (confirmation) is complete.

2. Confirm the authentication passcode.
1. Create a GET clientloginapi/api/login/tfa-confirm request to confirm the authentication passcode.
2. Provide your user credentials (username, password, and domain/workstation etc. if applicable).
3. Add a header named X-WFT-AuthCode.
4. Enter the authentication passcode generated by your 2FA app into the value column of the X-WFT-AuthCode header.

   Note: Once the confirmation action is complete, the X-WFT-AuthCode header will be required to log in successfully, until it is reset by an administrator.

3. Optionally log in at this time, to verify the process and generate an authentication token.
1. Create a GET clientloginapi/api/login request to log in using the authentication passcode.
2. Provide your user credentials (username, password, and domain/workstation etc. if applicable).
3. Add a header named X-WFT-AuthCode.
4. Provide the authentication passcode generated by your 2FA app into the value column of the X-WFT-AuthCode header.

   Note: Because the authentication passcode is time based, you may need to regenerate the code using your 2FA app. Repeat as necessary.

5. The authentication token contained in the response is used in your CygNet Bridge API calls.

Use Two-Factor Authentication for CygNet Bridge API

Once it is set up, your CygNet Bridge API calls will have the additional protections of two-factor authentication. In Required multi-factor authentication mode, all users must use 2FA. In Optional mode, users may use 2FA if they choose.

When you access the CygNet Bridge API, do the following to use two-factor authentication.

1. Using your API client, log in to CygNet Bridge API using your authorization credentials and 2FA passcode.
1. Create a GET clientloginapi/api/login request.
2. Provide your user credentials (username, password, and domain/workstation etc. if applicable).
3. Add a header named X-WFT-AuthCode.
4. Provide the authentication passcode generated by your 2FA app in the X-WFT-AuthCode header.

   Note: Because the authentication passcode is time based, you may need to regenerate the code using your 2FA app. Repeat as necessary.

5. The authentication token contained in the response is used by your CygNet Bridge API calls.

2. Create a CygNet Bridge API request including the authentication token.
1. Create a CygNet Bridge API request.
2. Add a header named X-WFT-AuthToken.
3. Provide the authentication token generated at login in the X-WFT-AuthToken header. The token is retained for 7 days before expiration.

---

More:

Managing Two-Factor Authentication Users