TOTP Authentication

The TOTP Authentication process involves retrieving the Identity Store User before requesting they enter the generated TOTP from their authentication application. TrustX will then perform an authentication request to determine if the secret key stored in TrustX matches the secret key stored on the user's device. This is is similar to the process of completing a registration but requires an active TOTP registration first.

If an authentication fails then the User lock count is incremented. If the User is locked they cannot authenticate.

This guide will describe the steps necessary for implementing a basic authentication process. To configure a TOTP registration process, see the TOTP Registration guide.

Authenticating via Process Definition

Step 1 - Prepare the Custom Form

In this flow, a Custom Form will request the end-user to scan a QR code or enter the secret manually using a text field.

1. In the Backoffice application, navigate to Integration Hub > Custom Forms.
2. Click the 'New Custom Form' button to create a new form.

3. The form builder provides a drag-and-drop Visual Form Builder or a JSON Form Builder to create a new Custom Form. In this example, the Visual Form Builder will be used. For more information on using this feature, see the Custom Data Forms guide.
4. Add a 'Text' form element found under the the 'Inputs' dropdown menu. This text input will be used for inputting the generated TOTP retrieved from the authenticator application and is a required parameter.

5. In this example, the Element ID is set to 'submittedCode'. This value will be required later when accessing the submitted form data.
6. Once the Custom Form is finalized, click the 'Save & Deploy' button.

Step 2 - Create a Process Definition

1. Create a new Process Definition by navigating to Process Definitions > New Process Definition in the Backoffice application.
2. Add a 'Create Start Event' to the Process Designer.

3. Click the 'Start' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.
4. Add a 'Create End Event' to the Process Designer and connect it to the 'Start' event using a sequence flow arrow.

5. Click the 'End' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.

Step 3 - Get User

Before authenticating, the Identity Store User that will be authenticated must be retrieved using the 'Get User' activity.

1. Add a 'Get User' activity to the Process Designer and connect it to the 'start' event using the global connect tool.

2. The 'Get User' activity includes the following input parameters:

Step 4 - Add TOTP Form

After retrieving the Identity Store User, display the form created in Step 1 that requests the user to input the TOTP generated in their authenticator app.

1. Add a 'Custom Data Form' activity to the Process Designer and connect it to the 'Get User' application using the global connect tool.

2. Set the the 'Data form name', 'Data form version' and 'Form data Key' input parameters to utilize the form created in Step 1. In this example, the 'Form data Key' is set to 'enterCodeForm'.

Step 5 - Perform TOTP Authentication

The 'TOTP Authentication' activity will perform authentication against an Identity Store User and submitted TOTP to determine that the user's secret key matches the secret key stored in TrustX.

1. Add the 'TOTP Authentication' activity to the Process Designer and connect it to the 'Custom Data Form v4' activity.

2. The 'TOTP Authentication' activity features the following configurable input parameters:

3. Set the 'Authentication Code' input parameter to ${_customFormData.enterCodeForm.currentCapture.customDataFormDataMap["submittedCode"]} . This represents the code submitted by the user in the Custom Data Form.

   1. _customFormData - Accesses the customFormData table.
   2. enterCodeForm - Represents the 'Form data Key' set for the 'Custom Data Form v4' activity.
   3. currentCapture - Accesses the form data captured during the Process Instance.
   4. customDataFormDataMap["submittedCode"] - Access data from the 'submittedCode' form element inside the data map of the Custom Data Form.

4. Set the 'Store Name', 'TOTP Policy', and 'User Key' input parameters to match the Identity Store and User associated with the TOTP authentication.

Step 6 - Add a Simple Decider

1. Add a 'Simple Decider' activity to the Process Definition and connect it to the 'TOTP Authentication'. This activity will set the decision of the Process Instance based on the outcome of the TOTP authentication attempt.

2. Once the activity is configured, click the 'Save & Deploy' button to complete the Process Definition.

Test and View Results

Create a Token

This section will describe how to test the Process Definition created above by generating a Process Token. After completing the flow, results of the Process Instance can be viewed from the Process Instances page.

1. To test the Process Definition, create a new Process Token by navigating to the Process Definitions > Process Tokens page.
2. Click the 'New Process Token' button found on the top-right of the page to start creating a new token. A popup modal will appear where details of the token can be entered.

3. Once the token is created, scan the QR code or follow the link to begin the flow. The TOTP form will be displayed, enabling the user submit the generated TOTP password.

View Results

The results of a authentication attempt can be found in the Users page in the Backoffice.

1. Navigate to the Users page and use the search tools provided to find the Identity Store User that attempted TOTP authentication.
2. Under the Authentications section of the Users page, select 'Totp' and click 'Search' to view recent authentication attempts.