Quick Start Guide for Multi-factor Authentication

Avatar
OverlayTeam
Follow

Overview

To get started, please read and familiarize yourself with the SMFA (Syniverse Multi-factor Authentication) Service offering Overview guide and API resource documents. Both Documents are available in the SDC portal and can be accessed under the Documents menu.   

Once registration is completed through the SDC (Syniverse Developer Community) portal, login to SDC.

After login, proceed to subscribe to the SMFA service offering by following the instructions below:

  1. Click 
    1. Click Multi-Factor Authentication Service Offering
    2. Expand "Subscriptions" menu
    3. Click "Subscribe..." and select "Initial account for [Your username]"
    4. Accept Terms of Service
    5. Click 
    6. Verify that your "Initial account for [Your username]" is listed in Subscriptions
  2. Click 
    1. Click 
    2. Give your Application a name and description, Click Save
    3. Click   icon next to your app name and select "Edit"
    4. Expand "Account & APIs" menu
    5. Select the "Initial account for [Your username]" from drop down menu
    6. Turn "SMFA" and "Whitelisting Services" On
    7. Expand "Auth Keys"
    8. You can Re-Generate the Access token (optional)
    9. Copy and store keys in a safe place
    10. Click "Save"
  3. Hover over "Your Name" on top right corner
    1. Click "Company"
    2. You can give your Company a name (Optional)
    3. Scroll down and Click   tab (Whitelisting is required for the numbers you intend to send to using the Initial Account)
    4. Click "Add phone number"
    5. Enter your mobile number and click "Send confirmation code"
    6. Enter the code you received as an SMS
    7. Click "Add"

Now you are ready to use the MFA service.

Syniverse Multi-factor authentication service APIs can be used to Create a MFA app and users, Associate a mobile user, Validate the user and thereafter authenticated those registered users against your applications. Tokens generated for authenticating users can be delivery via SMS, Voice (Text to Speech) or via Push notification delivery service.

 

To invoke the SMFA service using SMS token Delivery, Customers will need a Sender ID (Shortcode) or if recipients are in US, may use a default Public channel provided by Syniverse.

To execute a MFA call, Customers will need to have the following information ready:

 

  1. SMFA Base URL: https://api.syniverse.com/scg-external-api/api/v1
  2. A Channel ID or a Sender ID. SCG provides a Public Channel ID for your convenience. Please note that if you are Authenticating user outside of the US, a Private Sender ID (Longcode/shortcode) is required.
  3. Bearer Token: This is your Access token that is generated with your registered application.

Using your application, below are the sequence of events to perform a MFA:

1.      Create MFA application with public channel or Sender ID

The MFA application should include the following:

  • "name" = name of your application
  • "description" =  description of your MFA application service
  • "auth_code_length" = Number of characters you want your code to be.
  • "auth_token_type"  = token type which could be (NUMERIC, COMPLEX, ALPHA, ALPHANUMERIC)
  • "auth_token_validity_duration" = validity period of your token (in secs) 
  • "message_from" = This is the sender ID (Shortcode, Longcode, PUSH ) you have provisioned for your MFA application to deliver token to the end-user's address
  • "associate_template" = Body message you want to use to compose the token delivery instructions to the user. Includes inline template attributes ${display_name} and ${PIN}
  • "login_template" =  Body message to subsequently use in composing a delivery token message to the user
curl -X POST 'https://api.syniverse.com/mfa/v1/applications' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"name": "Test_app 0173",
"description": "Test application with 4 digits pins and 5 minutes valid time",
"auth_code_length": 4,
"auth_token_type": "NUMERIC",
"auth_token_validity_duration": 300,
"display_name": "MFA test",
"message_from": "channel:Bxn9SHBYhl89KnuDllO2L4",
"associate_template": "Please verify your mobile number by entering the ${display_name} validation code ${pin} . Enter the code in the next ${validity_duration} min.",
"login_template": "Your ${display_name} validation code is ${pin} . Enter the code in the next ${validity_duration} min. Reply STOP to end.",
"identity_lookup": true
}'

Response: {h7AlKCzNXeJKsulXXXXXX}

2.      Associate a user with your application

This associates a user’s mobile number with the application that was created. You need to use the identifier that was created when the application was created.

You will need the following values:

  • Application ID - from when the MFA was created (h7AlKCzNXeJKsulXXXXXX)
  • User ID - A unique identifier that you can create for the user you are trying to associate with your application. This could be the name of the user, or an account number, e.g userId7373
curl -X POST 'https://api.syniverse.com/mfa/v1/applications/h7AlKCzNXeJKsulXXXXXX/users/userId7373/associate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"display_name":"Syn SCG system", 
"address":"+5066173XXXX"
}'

3.      Validate a user

This validates that the user’s mobile number is authenticated with your application.

curl -X POST 'https://api.syniverse.com/mfa/v1/applications/h7AlKCzNXeJKsulXXXXXX/users/userId7373/validate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"validation_code":"{receivedPIN}"
}'

Response: 204 No Content (indicates a VALID PIN)

4.      Login start

This is the subsequent call made to authenticated the user anytime they log in to your application. These calls are optional and solely dependent on your authentication policy.

Sending a PIN to user

curl -X POST 'https://api.syniverse.com/mfa/v1/applications/h7AlKCzNXeJKsulXXXXXX/users/userId7373/login_start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"display_name":"Test MFA sms"
}'

Response: The mobile will get a PIN code.

 

Validating the PIN from user

curl -X POST 'https://api.syniverse.com/mfa/v1/applications/h7AlKCzNXeJKsulXXXXXX/users/userId7373/validate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"validation_code":"{receivedPIN}"
}'

Response: 204 No Content (indicates a VALID PIN)


If an invalid PIN is typed by the user:
Response:
{
"error_code":2001,
"error_description": "Invalid Authentication Code"
}

 

For more information on how to use the resources, please check out the API resource document on the SDC portal

Was this article helpful?
0 out of 0 found this helpful

0 Comments

Please sign in to leave a comment.