How to integrate a new SMS gateway for two factor authentication in ExSign

HC Control Panel > General Topics
How to integrate a new SMS gateway for two-factor authentication in ExSign?

ExSign offers a feature whereby the top-level administrator can enable 2FA for user logins. When 2FA is enabled, users while logging into the ExSign portal must provide two different authentication factors to verify themselves. The first typical factor is the password and the second is a one-time-password (OTP). Only after providing this OTP can they log into the portal. Admins can receive their OTP through SMS besides other modes. If SMS is selected as the mode to receive OTP, an SMS is sent to the phone number specified in the user profile. You may choose to integrate your own SMS gateway to receive OTP. The objective of the guide is to elaborate the process of integrating your own SMS gateway with ExSign.

Steps for Integrating New Gateway

Integrating a new SMS gateway involves three major steps:

  1. Exposing APIs
  2. Hosting APIs
  3. Linking API with ExSign
  • Exposing APIs
    You must expose the integration to the third-party SMS gateway via an API endpoint which will then be consumed by ExSign. The details of the API endpoint are as below. It must adhere to these. 
HEADERSThe API endpoint will receive an HTTP Authorization header in the following format:
Authorization: token OTE1ZjBiY2EtY2I4YS00NmQzLWFkNTItOGQ3MTQ5OTcxN2Fk
The developer of the API must write code to authenticate the incoming requests by validating the token in this header. The token here will be the one specified in step 3. It will be sent as a base64 encoded string.
REQUEST BODYThe endpoint should be receiving the input in the following JSON format:
{   
 "MobileNumber":"+923335500000",
 "MessageText":"Your one-time password (OTP) is 1344."
}
“MobileNumber” is the property that will contain the receiver's phone number and “MessageText” property will hold the actual SMS body sent by the third-party gateway that is to be integrated.
RESPONSEThe output of the API endpoint must be in the following JSON format:
{
 "ErrorDetails":"Some error detail",
 "IsSuccess": false
}
The “IsSuccess” property should be set to “true” if everything works well, for errors it must be set to “false”. In case some error occurs in the API, the “ErrorDetails” property can also be set for the application to log it.
RESPONSE CODEThe HTTP Response Code should always be 200.

  • Hosting APIs
    Once the API is done, the next step is hosting the API. Host it under any web server and make sure the endpoint receives the requests. It can be tested via Postman.

    Please note, that the SMS API will only be consumed server side so for security reasons it can be restricted to the IP address the portal (ExSign) is running on so that no one outside that machine gets unauthorized access to it. It is recommended to run the API on “localhost” and restrict its access over the internet.

  • Linking API with ExSign
    Open the relevant SMS Delivery Configuration page and input the URL the API is running under and input the authentication token which will be sent to the API endpoint in the “authorization” header.

    The token here can be any set of characters that will be sent to the API endpoint for authentication.
      
Article ID: 3419, , Modified: 10/12/2023 at 7:12 AM

Was this article helpful?

Share this article