ESET Secure Authentication SDK Developer Guide

PHP SDK

Introduction

The ESET Secure Authentication SDK allows two-factor authentication to be added to any system implemented using PHP 5.3 or greater.

This document describes how to use the SDK to provision a user for text message OTPs and how to authenticate OTPs. The document includes PHP code snippets.

Using the SDK

The SDK is distributed as a Composer package (Composer is a dependency manager for PHP: https://getcomposer.org). To install the package, add the ESA repository and package details to your composer.json file (new sections marked):

{
    "minimum-stability": "alpha",

    "require": {
        "analog/analog": "dev-master",
    "eset/secure-authentication-sdk": "*"
    },

    "autoload": {
        "psr-4": {
            "": "src/"
        }
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://esa.eset.com/sdk/packages/composer"
        }
    ]
}

After updating the composer.json file, install the packages:

composer update

Creating an Authenticator Instance

The TwoFactorAuthenticator class is the entry point into the SDK and is used to get users and authenticate OTPs for users.

The TwoFactorAuthenticator integrates with your existing user database via the IUserStorage interface. The two-factor user data will be stored in your database as a string for each user. Add this string as a new column called "esa_data" to your users table. You must implement the IUserStorage interface in order to instantiate the TwoFactorAuthenticator class. The following PHP snippet gives an example of how to implement the interface:

class CustomUserStorage implements IUserStorage
{
    // Associative array containing user data
    private $dataStore;

    public function __construct()
    {
        $this->dataStore = array();
    }

    // Load the two-factor authentication data for a user
    public function loadUser($username)
    {
        if (array_key_exists($username, $this->dataStore)) {
            return $this->dataStore[$username];

        } else {
            return null;
        }
    }

    // Save the two-factor authentication data for a user
    public function saveUser($username, $data)
    {
        $this->dataStore[$username] = $data;
    }
}

The TwoFactorAuthenticator requires an instance of the TwoFactorConfiguration class. The TwoFactorConfiguration class requires your SDK credentials (API key and shared secret) and an instance of your implementation of IUserStorage (eg the CustomUserStorage class from the above snippet). The following PHP snippet illustrates this:

// create an instance of your implementation of IUserStorage
$userStorage = new CustomUserStorage();

// replace with your credentials
$apiKey = "KEY";
$apiSecret = "SECRET";

// create configuration object
$configuration = new TwoFactorConfiguration($apiKey, $apiSecret, $userStorage);

// create authenticator instance
$authenticator = new TwoFactorAuthenticator($configuration);

The authenticator instance can now be used to provision and authenticate users.

Provision a User for Text Message OTPs

Once a user is provisioned for text message OTPs, they will be sent an OTP via text message during each authentication attempt.

The username and mobile number are required to provision a user for text message OTPs.

Note: Mobile numbers must be in the format '42612345678', where '4' is the country code and '26' is the area code.

The following PHP snippet details this:

$username = "user1";
$mobileNumber = "42612345678";

$twoFactorUser = $authenticator->createUser($username, $mobileNumber);
$twoFactorUser->provisionTextMessage();
$twoFactorUser->save(); // persist data after making any changes

Any changes made to instances of the TwoFactorUser class must be persisted by calling the save method.

User Authentication

The authentication process consists of two steps.

The first step is the pre-authentication step. This step will send a text message OTP to the user:

// start the authentication process, which will send a text message OTP to the user
$authenticator->preAuthenticate($username);

The second step authenticates an OTP entered by the user. The result from this step will indicate if authentication succeeded or not. The following PHP snippet details this:

// this value must be captured from the user
$otp = "123456";

// authenticate an OTP entered by the user
$authenticateResult = $authenticator->authenticate($username, $otp);

if ($authenticateResult->getIsAuthenticated()) {
    // the authentication has succeeded, the user may be logged in
}
else {
    // the authentication has failed
}

Details

User Details

The TwoFactorUser class exposes the following methods:

• getIsLocked – specifies if the user has been locked due to too many failed authentication attempts. Locked users cannot be authenticated
• provisionTextMessage – provisions the user for text message OTPs
• provisionMobileApp – provisions the user for mobile app OTPs. The return value contains the mobile app installation URL. This method does not automatically send the URL via text message to the user
• sendMobileAppProvisioningTextMessage – send mobile app installation URL to user via text message. This method accepts the result from provisionMobileApp as an input parameter
• unlock – unlocks a locked user
• deProvisionTwoFactor – disables two-factor authentication for a user. This decrements your license's active user count
• save – persists any changes made to a user (such as provisioning)

Provisioning users for text message OTPs or mobile app OTPs increments your license's active user count.

Configuration Details

Default configuration can be overridden by calling the following methods on the TwoFactorConfiguration class:

• setTokenName – the name of the token displayed in the user's mobile app (defaults to "SDK Token")
• setPinEnforced – if enabled, all users must protect their mobile app with a PIN
• setAppInstallTextMessageText – the text that will be displayed in the text message containing the mobile app installation URL. The text must contain the "__ESA_APP_INSTALL_URL__" placeholder string
• setTextMessageOtpText – the text that will be displayed when text message OTPs are sent. The text must contain the "__ESA_SMS_OTP__" placeholder string
• setMaxFailuresBeforeLocking – the number of failed authentication attempts allowed before the user is locked. The value must be in the range of 3-30 (inclusive)
• setTextMessageOtpLifetime – the number of minutes before a text message OTP expires. The value must be in the range of 5-60 (inclusive)

Pre-authentication Detail

The pre-authenticate method returns a PreAuthenticateResult object. The result includes a getExpectedCredential method (that returns enum type CredentialTypes) that indicates the type of OTP that is to be expected.

The CredentialTypes enum has the following values:

• NONE – the user is not enabled for two-factor authentication
• TEXT_MESSAGE_CREDENTIAL – the user is enabled for text message OTPs
• APP_HOTP_CREDENTIAL – the user is enabled for mobile app OTPs
• TRANSITION_TEXT_TO_APP_HOTP – the user is enabled for both text message and mobile app OTPs

This result can be used to customize OTP prompt text (such as telling the user to expect an OTP via text message).

Transitioning

A user can be enabled for both text message and mobile app OTPs. This state is known as "transitioning". This is done so that a user can be enabled for two-factor authentication without having to install the mobile app immediately.

When a user is in the transitioning state, the pre-authenticate step will still send a text message OTP. A transitioning user can authenticate using either a text message or a mobile app OTP. When a transitioning user authenticates using a mobile app OTP for the first time, they will be automatically transitioned to only being enabled for mobile app OTPs (i.e. they will no longer be enabled for text message OTPs). This is done because mobile app OTPs are preferred to text message OTPs.

Advanced

Logging

The SDK uses the standard PHP PSR-3 LoggerInterface for logging non-critical events. Set the required implementation using the *Internal::setLogger(logger)* method.

Auditing

The SDK audits critical security events using an auditor that can be overridden. The default configuration writes audit events to logging.

The default logging auditor can be overridden as follows:

1. Create a new class that implements the IAuditor interface
2. Call the setAuditor method on the TwoFactorConfiguration instance with an instance of your auditor class.