ESET Secure Authentication SDK documentation
|
Java SDK
The ESET Secure Authentication SDK allows two-factor authentication to be added to any system implemented using Java.
This document describes how to use the SDK to provision a user for text message OTPs and how to authenticate OTPs. The document includes Java code snippets.
The entire SDK is encapsulated in a single JAR package. The "eset-secure-authentication-sdk" package with group "com.eset.secureauthentication" must be installed from the https://esa.eset.com/sdk/packages/maven Maven repository, which will manage the required dependencies. The library must be added to your Java project. Specific instructions are given for the Gradle and Maven project automation tools.
The SDK can be added to a Gradle project by modifying your "build.gradle" file and adding the following snippet to the "repositories" block:
The following snippet should then be added to the "dependencies" block:
Gradle will then be able to install the SDK package and all required dependencies.
The SDK can be added to a Maven project by modifying your "pom.xml" file and adding the following snippet to the "repositories" element:
The following snippet should then be added to the "dependencies" element:
Maven will then be able to install the SDK package and all required dependencies.
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 Java snippet gives an example of how to implement the interface:
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 Java snippet illustrates this:
The authenticator instance can now be used to provision and authenticate users.
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 Java snippet details this:
Any changes made to instances of the TwoFactorUser class must be persisted by calling the save method.
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:
The second step authenticates an OTP entered by the user. The result from this step will indicate if authentication succeeded or not. The following Java snippet details this:
The TwoFactorUser class exposes the following methods:
Provisioning users for text message OTPs or mobile app OTPs increments your license's active user count.
Default configuration can be overridden by calling the following methods on the TwoFactorConfiguration class:
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:
This result can be used to customize OTP prompt text (such as telling the user to expect an OTP via text message).
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.
The SDK uses Simple Logging Facade for Java (SLF4J) for logging non-critical events. SLF4J makes it easy to use your existing logging framework, see the SLF4J website for more details: http://www.slf4j.org
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: