Passcode Renewal

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 guide first before continuing to the renewal process.

Renewing via Process Definition

Passcode renewal requires three TrustX tasks:

1. Start Passcode Renewal activity
2. Passcode Renewal form
3. End Passcode Renewal activity

A more complex flow may contain custom forms describing errors to the user and transition to a Passcode Registration flow if a passcode doesn’t exist.

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 - Start the Renewal Process

The 'Start Passcode Renewal' activity is used to begin the renewal process.

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

2. The 'Start Passcode Renewal' 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.
4. When the renewal process is started, the end-user will see a button that allows them to begin the registration process.

Optional - Start Passcode Renewal via API

The following API endpoints perform a passcode renewal where the existing passcode is verified and replaced with a new passcode. This will be a two step process on the server.

1. Client gets the initial passcode registration and verification parameters from the server.
2. Client derives verification data from the existing passcode and supplies it to the server. The client also validates the new passcode, generates the registration data and supplies it to the server.

There are two API endpoints to initialize passcode renewal for a user.

Permissions:

• TNT#{tenant}#createPasscodeRenewalForUser
• TNT#{tenant}#createUserPasscodeRenewalForUserByExtUserId

Endpoints:

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

Example Request:

xxxxxxxxxx

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/users/{userId}/passcodes/renewals/{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}",

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

    }

  },

  "sessionId": "UGIRW7QN727EIV2XLXG4YH42N4"

}

Step 3 - Configure the Renewal Form

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

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 old/ existing passcode and a passcode to replace the existing one.

xxxxxxxxxx

{

    "title": {...},

    "components": [...]

}

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

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

Step 4 - Complete Passcode Renewal

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

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

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

Optional - Complete Passcode Renewal via API

TrustX provides an API to complete a passcode renewal by validating passcode registration parameters for the new passcode and verification parameters for the existing passcode from the client.

Permission:

TNT#{tenant}#completePasscodeRenewal

Endpoint:

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

Example Request:

xxxxxxxxxx

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storeName}/passcodes/renewals/sessions/{sessionId}

Content-Type: application/json

Authorization: Bearer {{token}}

{

  "srpRegistrationData": {

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

  },

  "srpVerificationData": {

    "a": "{base-64 encoded value}",

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

  }

}

Example Response:

xxxxxxxxxx

{

  "algorithmInfo": {

    "type": "SRP",

    "parameters": {

      "hashAlgorithm": "SHA-256",

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

    }

  },

  "user": {...}

}

Response Codes:

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

Step 5 - Add a Simple Decider

A 'Simple Decider' can be used to reach a decision regarding the passcode renewal 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.

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 renewal 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.