This tutorial is a walk through on setting up a two-factor authentication process using IMIconnect.

Prerequisites

Access to IMIconnect platform (request your trial access here)

 >> Login to the IMIconnect platform using your registered email ID and password

Postman App (or an alternative tool) to invoke the APIs

>> You can install the Postman app from https://www.getpostman.com/apps


Setup Tasks

A. Create a Service
B. Get a Phone Number and Assign it to the Service
C. Configure a Custom Event
D. Create a flow to to setup Two-Factor Authentication
E.Configure a Rule to Invoke the Flow
F. Debug the Flow logs in IMIconnect


A. Create a Service

A service is a workspace that allows you to create and manage communication flows, APIs, integrations and configuration settings for any particular communication use case. Here are the steps to create a service:

Step 1 – Add New Service

  1. Click on the Services tab on the top left corner of the screen and choose ADD NEW SERVICE. You will arrive at the CREATE NEW SERVICE dialog box.

Note: Alternatively, you can find ADD NEW SERVICE from the top right corner of IMIconnect.

2. Choose a name for the service and optionally, add the description.

3. Click on the NEXT button at the bottom. You will arrive at the General Settings page, which will have the service key. See the image below.

Note: Service key is used to identify incoming API calls for messaging and event APIs.

Step 2 – Configure the Service Status

Choose the Live option in the Service Configuration section to activate the service.

Note: Click on the REGENERATE button, if you wish to regenerate the service key. Once the service key is regenerated, replace the existing key with the new key in the API request. Please use this option ONLY in case your current service key is not functioning.

Step 3 – Choose Events

  1. Choose the events that you wish to receive on the Callback URLby choosing from the EVENT FILTERS section.
  2. Click on SAVE on the top-right corner of the screen.


B.Get a Phone Number and Assign it to the Service

Now that the service is created, assign a number to it. Follow the below steps to assign number to the service:

Step 1 – Go to Numbers

Click on Numbers under the Services menu to get to Numbers settings

Step 2 – Assign the Number

  1. Choose the number from the drop-down under the SHORTCODES & PHONE NUMBERS FOR SMS section.
  2. Save the choices by clicking on SAVE on the top right corner of the screen.


C. Configure a Custom Event

Custom event allow you to trigger actions within IMIconnect in response to events that occur within your business systems. Follow the steps below to configure custom events:

Create an Event to Send OTP

Step 1 – Add a New Custom Event

  1. Click Custom Events under Settings in the left menu. You will arrive at the Custom Event screen. 
  2. Click ADD NEW CUSTOM EVENT on the Custom Event screen.
  3. Choose Version 1 on the Custom Event screen. 

Step 2 - Name the Custom Event

  1. Choose a name for the custom event.
  2. Click ADD NEW at the bottom on the Create New Custom Event screen. 

Step 3 – Configure Parameters

  1. Choose String from the Type drop-down and enter msisdn in the Variable Name field. 
  2. Check the Mandatory checkbox.
  3. Click ADD NEW at the bottom.
  4. Choose String from the Type drop-down and enter transref1 in the Variable Name field.
  5. Check the Mandatory checkbox.
  6. Click SAVE at the bottom.

The Custom event is created. See the screenshot below

Create an Event to Validate OTP

Step 1 – Add a New Custom Event

  1. Click Custom Events under Settings in the left menu. You will arrive at the Custom Event screen. 
  2. Click ADD NEW CUSTOM EVENT on the Custom Event screen.
  3. Choose Version 1 on the Custom Event screen. 

Step 2 - Name the Custom Event

  1. Choose a name for the custom event.
  2. Click ADD NEW at the bottom on the Create New Custom Event screen. 

Step 3 – Configure Parameters

  1. Choose String from the Type drop-down and enter transref2 in the Variable Name field. 
  2. Check the Mandatory checkbox.
  3. Click ADD NEW at the bottom.
  4. Choose String from the Type drop-down and enter OTP in the Variable Name field. 
  5. Check the Mandatory checkbox.
  6. Click SAVE at the bottom.

The custom event is created. See the screenshot below.


D. Create a Flow to Setup Two- Factor Authentication

IMIconnect allows you to rapidly configure communication flows using a drag-and-drop flow builder. Here are the steps to configure the flow:

Creating a New Flow

Step 1- Add a Flow

  1. Click on Flows on the left menu under Settings.
  2. Click on Add New Flow on the top right corner of the Flows screen.

Step 2 – Name the New Flow

  1. Enter a Name for the flow on the CREATE NEW FLOW screen.
  2. Choose the Flow type as Workflow.
  3. Choose Create blank flow from the drop-down.
  4. Click on CREATE FLOW on the top right corner.

Configure the Generate OTP Node

Step 1- Add the OTP Node 

Drag and drop the OTP node on to the flow canvas from the NODES menu under UTILITIES.

Step 2 – Configure the Generate OTP Node Parameters

Double-click on the OTP node to open the Settings menu. See the image below.

  1. Click on Generate on the SETTINGS window.

2. Choose the OTP format selecting from Alphabetic, Numeric, or Alphanumeric

3. Choose the OTP length

Note: You can choose any number of characters for OTP length. You can increase the OTP length by using the + button in the OTP length field. If you want to decrease the length, use the button. Alternatively, you can enter the desired value manually.

4. Choose the OTP validity in seconds. 

5. Enter $(transref1) in the Transaction reference field. 

  • Note: The transref1 is the variable in which the OTP generated is stored.

6. Choose the OTP resend request selecting from the below:

7. Enter a name for the node in the Name field.

8. Click on OK at the bottom.

Step 3 – Configure the 'onerror' event

The 'onerror' event is configured to record the instance when the flow fails due to any internal error.

To configure the onerror event:

  1. Drag the red dot next to Generate OTP Node.

2. Choose the onerror option from the Node event drop-down on the END FLOW - SETTINGS tab.

3. Choose the 102 – Flow completed with an error [Error] option from the Custom flow result drop-down.

4. Click on OK at the bottom to save the changes. 

Step 4 - Configure the 'onsuccess' event

  1. Drag and drop the green dot next to Generate OTP node to configure the onsuccess event. 

2. Choose the onsuccess option from the Node event drop-down on the END FLOW - SETTINGS tab. 

3. Choose the 101 – Successfully completed flow [Success] option from the Custom flow result drop-down. 

4. Click on OK at the bottom.

Configure the Send Node

Step 1– Add the Send Node

Drag and drop the Send node on to the flow canvas from the NODES menu under UTILITIES.

Step 2 - Configure the Send Node Parameters

Double-click on the Send node to open the configuration menu. You will arrive at the configuration window. See the image below.

  1. Click on SMS on the Settings window.
  2. Enter $(msisdn) in the Destination field. 

Note: msisdn stands for Mobile Station ISDN number. It refers to the mapping of telephone number to SIM card.

3. Choose msisdn from the Destination Type drop-down.

4. Choose Text from the Message Type drop-down. 

5. Choose the sender id assigned for the service from the senderid drop-down. 

6. Enter the message to be sent to the customer in the Message box. 

Note: In the figure below, the message contains $(sysOtpResponse). This will be replaced with the actual OTP when the SMS is triggered.

7. Enter a name for the node in the Name field.

8. Click on OK at the bottom.

Step 3 – Configure 'onerror' Event 

The 'onerror' event is configured to record the instance when the flow fails due to any internal error.

To configure the onerror event:

  1. Drag and drop the red dot next to SMS node. 

2. Choose the onerror option from the Node event drop-down on the END FLOW - SETTINGS tab.

3. Choose the 102 – Flow completed with an error [Error] option from the Custom flow result drop-down.

4. Click on OK at the bottom to save the changes.

Step 4 – Configure 'onsuccess' Event 

Follow the process mentioned in the Step 4 of Configure OTP Node Parameters above.

Step 5 - Connect the Generate OTP and Send Nodes

  1. Drag and drop the green dot from the Start node onto the Generate OTP node.
  2. Drag and drop the green dot from the OTP node onto the Send node to connect OTP node with the Send node.

Configure the Receive Node

Step 1– Add the Receive Node

Drag and drop the Receive node on to the flow canvas from the NODES menu under UTILITIES.

Step 2 - Configure the Node Parameters

Double-click on the Receive node to open the configuration menu. You will arrive at the Configuration window. See the image below.

  1. Enter the response time in seconds (before which the error is occurred) in the Maximum time out field.
  2. Choose Validate-OTP from the Custom event drop-down.
  3. Enter transref2 in the Resume_key field. 
  4. Enter $(transref1) in the Resume_key­_value field. 
  5. Enter a name for the node in the Name field.
  6. Click on OK at the bottom.

Step 3 – Configure ‘ontimeout’ Event

The 'ontimeout' event occurs when the time (in seconds) mentioned in the Time Out field is expired.

To configure the ontimeout event response:

  1. Drag and drop the orange dot next to Receive node.


2. Choose ontimeout from the Node event drop-down on the END FLOW - SETTINGS tab.

3. Choose 102 – Flow completed with an error [Error] from the Custom flow result drop-down.

4. Click on OK at the bottom.

Step 4 - Configure ‘error’ Event

Follow the process mentioned in the Step 3 of Configure Generate OTP Node Settings.

Step 5 – Configure 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Generate OTP Node Settings.

Configure the Validate OTP Node

Step 1- Add the OTP Node 

Drag and drop the OTP node onto the flow canvas from the NODES menu under UTILITIES.

Step 2 – Configure the Validate OTP Node Parameters

Double-click on the OTP node to open the Settings menu. See the image below.

  1. Click on Validate on the SETTINGS window.

2. Enter $(OTP) in the OTP input variable field. 

Note: The $(OTP) is a variable in which the OTP entered for validation is stored.

3. Enter $(transref2) in the Transaction reference field.

Note: The $(transref2)  is the variable in which the OTP generated is stored. 

4. Enter a name for the node in the Name field.

5. Click on OK at the bottom.

Step 3 - Configure ‘error’ Event

Follow the process mentioned in the Step 3 of Configure Generate OTP Node Settings.

Step 4 – Configure 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Generate OTP Node Settings.

Step 5 – Connect the Nodes

  1. Drag and drop the green dot from the Send OTP node to the Receive node.
  2. Drag and drop the green dot from the Receive node to the Validate OTP node.

Configure Authentication Success

Step 1– Add the Send Node

Drag and drop the Send node on to the flow canvas from the NODES menu under UTILITIES.

Step 2 - Configure the Send Node Parameters

Follow the process mentioned in the Step 4 of Configure the Send Node.

Note: The message entered in the Message box for the Authentication success will differ from what is written in the Step 2 of Configure the Send Node for sending OTP. Refer to the image above.

Step 3 - Configure ‘error’ Event

Follow the process mentioned in the Step 3 of Configure Generate OTP Node.

Step 4 – Configure 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Generate OTP Node.

Configure Authentication Failure

Step 1– Add one more Send Node

Drag and drop the Send node on to the flow canvas from the NODES menu under UTILITIES.


Step 2 - Configure the Send Node Parameters

Follow the process mentioned in the Step 4 of Configure the Send Node.

Note: The message entered in the Message box for the Authentication failure will differ from what is written in the Step 2 of Configure the Send Node for sending OTP. Refer to the image above.

Step 3 - Configure the ‘onerror’ Event

Follow the process mentioned in the Step 3 of Configure Generate OTP Node.

Step 4 – Configure 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Generate OTP Node.

Step 5 – Connect the Nodes

  1. Drag and drop the green dot from the Validate OTP node to the Send (Authentication Success) node.
  2. Drag and drop the red dot from the Validate OTP node to the Send (Authentication Failure) node.

 The overall flow appears as shown below:

Publish the Flow 

  1. Click on MAKE LIVE on the top right corner. You will arrive at Confirm – Make Live message box. 
  2. Click on OK on the Confirm – Make Live message box.

Note: If you wish to add a comment, enter it in the Add an update comment box (optional).



E. Configure a Rule to Invoke the Flow

Configure a rule to invoke the flow whenever the custom event is triggered. Follow the steps below to configure a rule: 

Step 1 – Create a New Rule

  1. Click on Rules under Settings on the left menu.
  2. Click on ADD NEW RULE button on the top right corner of the screen. 
  3. Click on Custom Event on the Choose a trigger channel screen.

4. Click on Send-OTP on the Choose an Event screen.

5. Click on SKIP TO ACTIONS on the Enter trigger conditions screen.

Step 2 – Invoke the Flow

  1. Click on Invoke a flow on the Choose an action screen.

2. Choose the flow for which the rule has to be applied from the drop-down, and then click on COMPLETE RULE button.

Step 3 – Configure the Rule Settings

  1. Choose a name for your rule. Choose the start date and time by clicking on the popup calendar.

Note: The end date is optional. 

2. Choose Active from the Set the status of your rule drop-down, and click on the SAVE & SUBMIT button at the bottom.

The Rule is created. See the screenshot below.


F. Invoke the Flow using Postman or any alternative tools

Postman is a Google Chrome app, used to interact with HTTP APIs.

Follow the process mentioned in Sending automated SMS using IMIconnect Visual Flow Builder tutorial to configure Postman. 



G. Debugging the Flow in IMIconnect 

IMIconnect allows you to debug your flow, analyze the flow process to identify any potential errors and fix. Here’s the process of debugging the flow.

Step 1 – Open Users Screen

  1. Click on the  icon highlighted in red rectangle on the top right menu.

2. Choose USERS from the drop-down.

3. Click on can decrypt logs check box for the user to decrypt the logs.

Note: Only the users with owner access can enable this option.

4. Click on the GENERATE button on the Generate Password window. .

The email is sent to the user with the password for decrypting logs.


Step 2 – Open Debug Screen

  1. Click on the service for which the logs have to be analyzed on the main menu.
  2. Click on Flows on the left menu under Settings.
  3. Choose EDIT from the MANAGE drop-down for the flow. You will arrive at the Flow screen.
  4. Click on DEBUG from the bottom of the screen. You will arrive at the Transaction logs screen.

Note: Alternatively, you can open the DEBUG screen from the top menu of IMIconnect. For more details, refer to https://docs.imiconnect.com/docs/logs

Step 3 – Analyze the transaction

  1. Click on a Transaction ID. You will arrive at the Transaction logs screen.

2. Expand the  node to view the details. You will arrive at the node details.

Here are the node details:

Here is the description for the node details:

  1. Node Trans ID - ID number created for the transaction
  2. Description - Provides the action performed by the node
  3. Encrypted data - Additional description about the action performed by the node under the transaction in encrypted mode.

Note: The encrypted data can be read only by the user having access to decrypt.

Step 4 –Decrypt the logs 

  1. Click on DECRYPT LOGS in the Transaction logs screen.
  2. Note: DECRYPT LOGS option appears only for the user having access to decrypt.
  3. Enter the password provided to decrypt in Data decryption password field.

4. Click on the green tick button. You will see the decrypted data about the transaction.

Did this answer your question?