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.