Passcode Registration

Early Access

Introduction

This guide will describe the steps necessary to register a passcode to an Identity Store User. This document assumes that an Identity Store with a Passcode Policy already exists in the TrustX system.

Passcode Registration

Passcode registration requires three TrustX activities:

1. 'Start Passcode Registration' activity
2. 'Passcode Registration form'
3. 'Complete Passcode Registration' activity

A more complex flow may contain custom forms describing errors to the user and transition to a passcode renewal flow if registration fails due to a passcode already being registered.

Step 1 - 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 2 - Add a User (Optional)

This step is only required if the User has not been added to the Identity Store. See Managing Users for more information on adding a User.

1. The 'Add User' activity is used to add a new User to an Identity Store. Find the activity and connect it to the 'Start' and 'End' events using a sequence flow arrow.

2. The 'Add User' activity includes two error events. In this example, the error events have been connected to the 'End' event.

   1. Failed to add the user - This event is triggered when an error occurs adding the User to the Identity Store.
   2. ExtId Not Unique - This event occurs if the External ID provided is not unique.

3. Click the 'Add User' activity to open the right-side contextual menu. Using the available input parameters, information about the User can be defined, including the External ID and which Identity Store the user will be added to.

Step 3 - Start the Registration Process

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

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

2. The 'Start Passcode Registration' provides the following configurable parameters described below:

3. 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. If Step 2 - Add a User (Optional) was completed, the default User ID value can be used.
4. When the registration process is started, the end-user will see a button that allows them to begin the registration process.

Optional - Start Passcode Registration via API

Two APIs to initialize passcode registration for a user.

Permissions:

• TNT#{tenant}#createPasscodeRegistrationForUser
• TNT#{tenant}#createUserPasscodeRegistrationForUserByExtUserId

Endpoints:

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

Example Request:

xxxxxxxxxx

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/users/{userId}/passcodes/registrations/{policyName}

Content-Type: application/json

Authorization: Bearer {{token}}

{

}

Example Response:

xxxxxxxxxx

{

  "passcodeRequirements": {

    "minimumLength": 6,

    "maximumLength": 12,

    "digitCount": 1,

    "symbolCount": 1,

    "lowerCaseCount": 1,

    "upperCaseCount": 1,

    "characterVariety": 1,

    "passcodeHistory": 1,

    "requiredRegExes": [

      {

        "pattern": "",

        "error": ""

      }

    ],

    "allowedRegExes": [

      {

        "pattern": "",

        "error": ""

      }

    ],

    "disallowedRegExes": [

      {

        "pattern": "",

        "error": ""

      }

    ]

  },

  "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}"

    }

  },

  "sessionId": "UGIRW7QN727EIV2XLXG4YH42N4"

}

Response Codes:

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

Step 4 - Configure the Registration Form

The registration 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.

1. 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.
2. The example below demonstrates a JSON form that requests the passcode.

xxxxxxxxxx

{

    "title": {...},

    "components": [...],

    "submitButton": {...}

}

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

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

Step 5 - Complete Passcode Registration

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

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

2. The 'Complete Passcode Registration' activity features the following input parameters:

Optional - Complete Passcode Registration via API

TrustX provides an API to complete a passcode registration by validating passcode registration parameters from the client.

Permissions:

TNT#{tenant}#completePasscodeRegistration

Endpoint:

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

Example Request:

xxxxxxxxxx

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/users/{userId}/passcodes/registrations/{policyName}

Content-Type: application/json

Authorization: Bearer {{token}}

{

  "srpRegistrationData": {

    "verifier": "{base-64 encoded value}"

  }

}

Example Response:

xxxxxxxxxx

{

  "user": {...}

}

Response Codes:

• 200: Success
• 404: Tenant/store/policy/user not found.
• 400: Other error, see processing details.

Step 6 - Add a Simple Decider

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

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

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

Dergister Passcode

A passcode can be deregistered from an Identity Store User using the 'Deregister Passcode' activity in the Backoffice application or but calling the TrustX API directly.

Backoffice Example

Using the 'Deregister Passcode' activity, a passcode can be registered from the User.

This activity features the following input parameters:

Define the mandatory input parameters to ensure the passcode will be deregistered as expected.

API Example

TrustX provides two APIs to deregister a passcode for a User.

Permission:

• TNT#{tenant}#deregisterPasscodeForUser
• TNT#{tenant}#deregisterPasscodeForUserByExtUserId

Endpoints:

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

Example Request:

xxxxxxxxxx

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/users/{userId}/passcodes/deregistrations/{policyName}

Content-Type: application/json

Authorization: Bearer {{token}}

{

}

Example Response:

xxxxxxxxxx

{

  "user": {...}

}

Response Codes:

• 200: Success
• 404: Tenant/store/user/policy/passcode registrations not found.
• 400: Any other error, see processing details.

Test and View Results

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

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

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

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

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

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

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

9. Registered passcodes can be found under the 'Registered Passcodes' section of the User Details page.