README

The 2FAS SDK makes it easy to interact with the API from your PHP application. The latest version of the 2FAS SDK can be found on Github. The 2FAS SDK requires PHP version 5.4 or higher.

Follow these steps to integrate your application with 2FAS:

Installation and configuration
User configuration
Using authentication

Full documentation for our SDK can be found here

Installation and configuration

Prerequisites

Before you start using this SDK, you have to create an account and have a token to authenticate.

Installation

The SDK can only be installed using a composer. You can add the PHP SDK to your composer.json file with the require command:

composer require twofas/sdk

If you are using a framework like Symfony or Laravel, the 2FAS SDK may be automatically loaded for you and ready to use in your application. If you're using Composer in an environment that doesn't handle autoloading, you can require the autoload file from the "vendor" directory created by Composer if you used the install command above.

Upgrade

If you're upgrading major version, please refer to upgrade guide.

Creating SDK client

<?php
// Required if your environment does not handle autoloading
require __DIR__ . '/vendor/autoload.php';

// Copy from your 2FAS dashboard
$token = 'XXXXXXXXXXXXXXXXXXXXXXXXX...';

$sdk = new \TwoFAS\Api\Sdk($token);

Encryption

All sensitive data in 2FAS is encrypted on the client side, and we are not able to decrypt it. So, before sending it to 2FAS, you should encrypt them using our methods and keep the encryption key in your storage. Out of the box we provide AES encryption. All you have to do is implement ReadKey interface which retrieves data from your storage (eg. env, database). Remember that the key is in byte format so you should encode it before save, and decode after read - you can use for example base64_encode and base64_decode function. If you want store key in environment file, you can generate and paste the string to the file, and only retrieve from env in your storage:

<?php
//generate AES Key
$key = new \TwoFAS\Encryption\AESGeneratedKey();
echo base64_encode($key->getValue()); //paste to your environment file

//only retrieve key from storage
class EnvStorage implements \TwoFAS\Encryption\Interfaces\ReadKey
{
  public function retrieve()
  {
    return new \TwoFAS\Encryption\AESKey(base64_decode(getenv('AES_KEY')));
  }
}

User configuration

Creating integration user

Each of your users should be represented by integration user in 2FAS so you have to set your local user id as external id of integration user:

<?php
// SDK client has to be created

$myStorage = new EnvStorage();
$integrationUser = new \TwoFAS\Api\IntegrationUser();
$integrationUser->setExternalId(123); //This is your local user id

$sdk->addIntegrationUser($myStorage, $integrationUser);

Generate QR Code

Our main and default authentication method is TOTP. To use it you have to generate a QR Code according to this documentation and configure your mobile app and store data in integration user. Our SDK allows you to generate a QR code based on your string:

<?php

$qrClient = new \TwoFAS\Api\QrCode\EndroidQrClient();
$generator = new \TwoFAS\Api\QrCodeGenerator($qrClient);

$uri = 'otpauth://totp/Acme:foo@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Acme';
$imgSrc = $generator->generateBase64($uri);

//in html:
//<img src="{{ $imgSrc }}">

Configuring integration user

Before using authentication, you have to configure one of the authentication methods: totp, sms/vms or email. To do this, you need to verify that the user has provided the correct code. For example, we will open the TOTP authentication and validate the code generated from a mobile app:

<?php
// SDK client has to be created

$totpSecret = 'JBSWY3DPEHPK3PXP'; // from QR Code
$totpCode = '210866'; // from text input, generated by mobile app
$authentication = $sdk->requestAuthViaTotp($totpSecret);
$result = $sdk->checkCode([$authentication->id()], $totpCode);

if ($result->accepted()) {
  // update user, described below
} else {
  // check other result types and handle them
}

For other authentication methods the scenario looks similar, but you have to send a code via sms/vms or email using our other authentication methods. Keep in mind that sms/vms methods are paid so you have to add your credit card in 2FAS dashboard to work properly.

Each authentication is valid for 15 minutes and the provided code can be checked up to 5 times.

Updating integration user

After successful configuration you have to update data in your integration user:

<?php
// SDK client has to be created

$myStorage = new MyStorage();
$localUserId = 123;
$integrationUser = $sdk->getIntegrationUserByExternalId($myStorage, $localUserId);
$integrationUser
  ->setTotpSecret('JBSWY3DPEHPK3PXP') //if you're configuring TOTP
  ->setPhoneNumber($this->formatNumber('+48 555 088013')) //if you're configuring SMS/VMS
  ->setEmail('foo@example.com'); //if you're configuring EMAIL

$sdk->updateIntegrationUser($myStorage, $integrationUser);

Using authentication

Creating authentication and check code

If your integration user has been configured successfully, you can use it to open authentication in your login process as the second factor. The authentication process looks very similar to the configuration, but instead of using the secret from QR code, use the one from integration user:

<?php
// SDK client has to be created

$totpCode = '210866'; // from text input, generated by mobile app
$authentication = $sdk->requestAuthViaTotp($integrationUser->getTotpSecret());
$result = $sdk->checkCode([$authentication->id()], $totpCode);

if ($result->accepted()) {
  // authentication ok, log in user
} else {
  // forbidden, check other result types and handle them
}

Backup codes

2FAS also allows you to authenticate using backup codes that can be printed, and then used to log in to your site in case you do not have your mobile device. You can generate 5 backup codes at the same time and each code can only be used once.

<?php
// SDK client has to be created

//generate codes
$codes = $sdk->regenerateBackupCodes($integrationUser);

//open authentication
$authentication = $sdk->requestAuthViaTotp($integrationUser->getTotpSecret());

//check code
$backupCode = 'XXXX-XXXX-XXXX'; // from text input
$result = $sdk->checkBackupCode($integrationUser, [$authentication->id()], $backupCode);

if ($result->accepted()) {
  // authentication ok, log in user
} else {
  // forbidden, check other result types and handle them
}

twofas / sdk

Maintainers

Details