Getting Started
SMS 2FA
Call Verification
Others

Cecula Proprietor

Cecula Proprietor is a PHP package for implementing Two-Factor Authentication 2FA using your hosted SIM on Cecula Sync Cloud.

Language: php

Table of Content

Getting Started

Requirements

  • Hosted SIM on Cecula Sync Cloud
  • PHP8.0 Installation with PDO_SQLITE extension enabled
  • Set write permission for storage directory

Hosting a SIM

Cecula proprietor uses hosted SIM to execute Two-Factor-Authentication via sms and call. You could own a sim at Cecula Sync Farm either by purchasing on the Cecula Sync Platform or sending your existing sim.

See detailed information on how to host your sim.

Installation

Install Cecula Proprietor using the Composer Dependency Management tool by running:

composer require cecula/proprietor

This will additionally install the package Cecula Proprietor requires: Cecula Sync API Client. Once installation is done, proceed to configuration.

Configuration

Change directory to your project root directory. Navigate to vendor/cecula/proprietor and copy the .ceculasync.json.example file to your project root directory. Rename the file .ceculasync.json.

You can do this on a unix shell by running the command below from your project root directory:

cp vendor/cecula/proprietor/.ceculasync.json.example .ceculasync.json

Open and edit the .ceculasync.json file with your IDE or any text editor of your choice. This is what your configuration file should look like:

                        
{
    "apiKey": "",
    "otp": {
        "validityPeriod": 800,
        "characters": "digits",
        "length": 6,
        "messageTemplate": "Your OTP is {code}"
    },
    "database": {
        "type": "sqlite",
        "smsOtpTableName": "cp_otp_requests",
        "callVerificationTableName": "cp_call_waitlists"
    }
}

The configuration file has three key sections: the apiKey, otp and database configuration. Cecula proprietor does not interfere with your project database. It creates an sqlite database at runtime.

API Key

If you do not already have an API key, login to the Cecula Sync Platform. Navigate to Account > Settings. Select the API Key tab and copy your API Key.

OTP

The OTP section defines criteria for generation of One Time Pin which would be sent via sms to your clients:

validityPeriod
Defines the validity time (in seconds) for the OTP code.
characters
Defines the kind of characters that the OTP will contain. Valid values are digits, alpha numeric (a.k.a alnum), alphabets (a.k.a alpha), and number.
length
The length property defines how long the OTP will be.
messageTemplate
Defines a template for the OTP. At runtime {code} will be replaced with the generated pin.

Database

Cecula proprietor uses sqlite database to persist verification status. The database field allows you to define names for the tables where the status of sms and call verifications will be stored.

SMS 2FA

Initializing 2FA Request

Sms2fa::init(string $mobile):object

The method for initializing 2FA request accepts mobile phone number as string, generates a token and prepares the sms message according to your configuration in the .ceculasync.conf file. The message is submitted to Cecula Sync service and a reference for tracking the sms status is returned as response.

Sample Request:

                      
use Cecula\Proprietor\Sms2fa;

$mobile = "09090000246";
$sms2fa = new Sms2fa();
$smsInfo = $sms2fa->init($mobile);
var_dump($smsInfo);

Output:

                      
object(stdClass)#100 (3) {
  ["code"]=>
  string(3) "200"
  ["message"]=>
  string(73) "OTP Code has been sent to 09090000246. Persist the reference to database."
  ["reference"]=>
  string(36) "c02feb8f-55b4-49c3-9ac4-7bd73707fe5e"
}

Completing 2FA

Sms2fa::complete(string $trackingId, string $otp):object

This method accepts the reference that was generated during the initialization process above as trackingId and the OTP Code that was sent to the user’s mobile phone, and matches them.

Sample Request:

                    
use Cecula\Proprietor\Sms2fa;

$sms2fa = new Sms2fa();
$smsInfo = $sms2fa->complete("c02feb8f-55b4-49c3-9ac4-7bd73707fe5e", "324489");
var_dump($smsInfo);

Output:

                  
  object(stdClass)#31 (2) {
    ["code"]=>
    string(3) "200"
    ["message"]=>
    string(56) "Mobile number 09090000246 has been successfully verified"
  }

Call Verification

This method of verification requires that the customer issues a missed call to the hosted sim.

Initializing Call Verification

Call2fa::init(string $mobile):object

Invoking the Call2fa init method with the user’s mobile number informs Cecula Sync cloud to expect a call from the user’s mobile number and passes the dynamic webhook where the call notification should be sent. The method will return a reference for tracking the call status and the hosted number.

Your client application should display the hosted number and ask the user to call with the number they submitted or have previously signed up with.

Sample Request:

                      
use Cecula\Proprietor\Call2fa;

$mobile = "09090000246";
$call2fa = new Call2fa();
$callInfo = $call2fa->init($mobile);
var_dump($callInfo);

Output:

                  
object(stdClass)#79 (4) {
  ["code"]=>
  int(200)
  ["msisdn"]=>
  string(11) "08176473712"
  ["message"]=>
  string(45) "08176473712 is awaiting call from 09090000246"
  ["reference"]=>
  string(36) "ca464f3b-204f-4c8a-be6f-81cbb2c02fee"
}

Completing Call Verification

Call2fa::complete(string $trackingId): object

Completion of verification should be done by a client script that invokes the complete method with the reference code as trackingId at scheduled intervals. At each call, the complete method checks to confirm if a call notification for that trackingId has been received.

Sample Request:

                      
use Cecula\Proprietor\Call2fa;

$callReference = "ca464f3b-204f-4c8a-be6f-81cbb2c02fee";
$callInfo = $call2fa->complete($callReference);
while($callInfo->code != 200)
{
    echo date("Y-m-d H:i:s").": Call Not Confirmed! Retrying...\n";
    sleep(5);
    $callInfo = $call2fa->complete($callReference);
}
var_dump($callInfo);

Output:

                  
...
2021-10-17 09:20:45: Call Not Confirmed! Retrying...
2021-10-17 09:20:50: Call Not Confirmed! Retrying...
2021-10-17 09:20:55: Call Not Confirmed! Retrying...
object(stdClass)#54 (2) {
  ["code"]=>
  int(200)
  ["message"]=>
  string(49) "Your mobile number has been successfully verified"
}

Dynamic Webhook

A Dynamic Webhook is a webhook registered with Cecula Sync Service at runtime to receive notification when a call or sms from a specific number is received.

During the Call Initialization Call2fa::init($mobile) call, a dynamic webhook is registered. When Cecula Sync service receives a call from the paired mobile number, it sends the notification to the dynamic webhook. The webhook registers the notice on your server so that the Call2fa::complete() method call can consume it.

The webhook file is usually a file called synchook.php which Cecula Proprietor will install to your application's root directory.

Others

Response Codes & Meaning

The table below lists all response codes that might be returned while interacting with this Cecula Proprietor and their meanings.

CE201
Your mobile number has already been verified
CE202
Your OTP has expired
CE203
Invalid OTP
CE204
Invalid tracking ID
CE205
Tracking ID does not reference any authentication request
CE301
Unknown Caller
CE302
Webhook File not found.
CE1804
Your Cecula Balance is low. Kindly top up your credit.

Storage

Out of the box, Cecula Proprietor works with sqlite database but it can be configured to work with other relational database servers such as MySQL, MariaDb, PostgreSQL, MS SQL or Oracle database.

Getting Started
SMS 2FA
Call Verification
Others