Passcode Authentication

Early Access

Introduction

This document assumes that a User has been added to an Identity Store and that the User has registered a passcode. Please follow the Passcode Registration guide first before continuing to the authentication process.

Authenticating via Process Definition

Passcode authentication requires three TrustX activities:

'Start Passcode Authentication' activity
'Passcode Authentication form'
'Complete Passcode Authentication' activity

Step 1 - Create a Process Definition

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

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

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

Step 2 - Start the Authentication Process

The 'Start Passcode Authentication' activity is used to begin the authentication process.

In the Process Designer, add the 'Start Passcode Authentication' activity after the 'start' event and connect using a sequence flow arrow.

The 'Start Passcode Authentication' provides the following configurable parameters described below:

Input Parameters

Parameter	Description	Type	Required	Default
Passcode Authentication Key	The key used to identify the passcode authentication attempt.	String	Yes	passcodeAuth1
Passcode Key	Represents the passcode.	String	Yes
Store Name	The Identity Store containing the policy and User.	String	Yes
User External ID	The external ID of the user to be authenticated.	String	No
User ID	Identifies the user to be authenticated.	String	No
User Key	The TrustX reference key for the user to be authenticated. If the user has already been obtained earlier in the TrustX flow, this field is used to identify the user. If the user has not already been obtained, one of the user ID or user external ID is used to reference the user and the user will be stored under the user key so it can be referenced later in the flow.	String	Yes	user1

Ensure that each mandatory input parameter is defined. Identify the Identity Store User using the 'Get User' activity or but entering the User ID or User External ID manually.
When the authentication process is started, the end-user will see a button that allows them to begin the authentication process.

Optional - Start Passcode Authentication via API

There are two API endpoints that initialize passcode authentication for a user.

Permissions:

TNT#{tenant}#createPasscodeAuthenticationForUser
TNT#{tenant}#createUserPasscodeAuthenticationForUserByExtUserId

Endpoints:

POST tenants/{tenantId}/stores/{storeName}/users/{userId}/passcodes/authentications/{policyName}
POST tenants/{tenantId}/stores/{storeName}/users/{extUserId}/passcodes/authentications/{policyName}/ext

Example:

HTTP
    
xxxxxxxxxx
 
POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/users/{userId}/passcodes/authentications/{policyName}Content-Type: application/jsonAuthorization: Bearer {{token}} { }
Copy

Example Response:

JSON
    
xxxxxxxxxx
 
{  "algorithmInfo": {    "type": "SRP",    "parameters": {      "i": "{26 character ID"}",      "n": "{base-64 encoded value}",      "g": 2,      "hashAlgorithm": "SHA-256",      "salt": "{base-64 url encoded salt value}",      "serverPublicKey": "{base-64 encoded value}"    }  },  "sessionId": "UGIRW7QN727EIV2XLXG4YH42N4"}
Copy

Response Codes:

201: Success
404: Tenant/store/user/policy not found.
400: Error, see processing details.

Step 3 - Configure the Authentication Form

The authentication form is used to accept input from the end-user who will be completing the passcode authentication. In this example, the end-user will be requested to provide their passcode to complete the authentication process.

Create a new Custom Form from the Integration Hub > Custom Forms section of the Backoffice. For more information using the Custom Form builder, see the Custom Data Forms guide.
The example below demonstrates a JSON form that requests the passcode.

JSON
    
xxxxxxxxxx
 
{    "title": {        "values": {            "en": "Title"        },        "isValid": true,        "type": "title"    },    "components": [        {            "type": "text",            "isValid": true,            "readOnly": false,            "id": "passcode",            "label": {                "values": {                    "en": "Passcode"                }            },            "default": "",            "transient": false,            "validate": {                "required": true,                "minLength": "",                "maxLength": "",                "missingMessage": {                    "values": {                        "en": ""                    }                },                "invalidMessage": {                    "values": {                        "en": ""                    }                },                "invalidLengthMessage": {                    "values": {                        "en": ""                    }                }            },            "index": 0        }    ]}
Copy

Once the Custom Form has been created, add a 'Passcode Authentication Form' activity to the Process Designer and connect to the 'Start Passcode Authentication' activity using a sequence flow arrow.

The 'Passcode Authentication Form' activity includes the following Input Parameters:

Input Parameters

Parameter	Description	Type	Required	Default
Data form name	A drop-down list of all available custom forms created in TrustX. The chosen form will be displayed to the end user in the flow.	String	Yes
Data form version	Determines which version of the selected custom form will be displayed.	Integer	Yes	1
Form data Key	When multiple Custom Data Forms are used in one Process Definition, the form data key will be used as a unique identifier to distinguish Custom Form activities from each other.	String	Yes	passcodeAuthForm1
Passcode Authentication Key	The key associated with the passcode authentication attempt.	String	Yes	passcodeAuth1
Starting Component ID	The name of the step to be sent to the UI.	String	Yes	passcode-authentication
UI Component ID	The name of the screen used by the UI.	String	Yes	passcode-authentication

Step 4 - Complete Passcode Authentication

The 'Complete Passcode Authentication' activity is used to finalize the passcode registration process.

Add the 'Complete Passcode Authentication' activity after the 'Passcode Authentication Form' and connect using a sequence flow arrow.

Optional - Complete Passcode Authentication via API

An API query to complete a passcode authentication by validating passcode verification parameters from the client.

To prevent user enumeration attacks, authentication failures return a generic error code (2615) regardless of the specific reason (invalid user, wrong password, expired passcode, etc.).

Permission:

TNT#{tenant}#completePasscodeAuthentication

Endpoint:

POST tenants/{tenantId}/stores/{storeName}/passcodes/authentications/sessions/{sessionId}

Example Request:

HTTP
    
xxxxxxxxxx
 
POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/passcodes/authentications/sessions/{sessionId}Content-Type: application/jsonAuthorization: Bearer {{token}} {  "srpVerificationData": {    "clientPublicKey": "{base-64 encoded value}",    "m1": "{base-64 encoded value}"  }}
Copy

Example Response:

JSON
    
xxxxxxxxxx
 
{  "algorithmInfo": {    "type": "SRP",    "parameters": {      "hashAlgorithm": "SHA-256",      "m2": "{base-64 encoded value}"    }  },  "user": {...}
Copy

Step 5 - Add a Simple Decider

A 'Simple Decider' can be used to reach a decision regarding the passcode authentication attempt.

Add the 'Simple Decider' activity to the Process Designer and connect the activity to the 'Complete Passcode Authentication' and 'End' event.

Once all configurations are made, click the 'Save & Deploy' button to finalize the Process Definition.

Test and View Results

To test the flow, create a new Process Token from the Process Definitions page.

Navigate to the Process Definitions page and find the passcode authentication Process Definition.
Click the 'key' under the 'Actions' tab to create a new Process Token.

A pop-up modal will appear where parameters of the token can be defined.

When the Process Instance starts, the user will be met with the registration form.

When the passcode has been added successfully, a confirmation screen will appear.

To view the newly added passcode, navigate to the 'Users' page in the Backoffice: Identity Store > Users.
Choose an Identity Store to view the store Users.

Under the 'Actions' column, select the 'Users Details' button to view the full User details.

The authenticated passcode can be found under the 'Registered Passcodes' section of the User Details page.

Last updated on