eAuthenticator

Features by category

Getting started

Introduction

Welcome to our Authentication System integration guide! This document provides step-by-step instructions to help you set up and integrate our secure authentication service into your system. Our solution ensures seamless user verification, enhancing both security and user experience.

The aim is to ensure smooth, efficient, and secure authentication for users, as well as a seamless experience for developers integrating the 2FA flow into their systems.

Integrate

The integration process involves initiating the 2FA workflow, handling the authentication request, and processing the user’s verification through a webview interface.

Step 1. Create authorization credentials

To integrate our 2FA solution, you need to set up an account, configure your application, and obtain the necessary credentials for API access.

Create an account on our platform by visiting the registration page.
Sign in to the Domain Console with your newly created account credentials. The Domain Console is where you will manage your application settings and configure 2FA for your platform.
Create a new application: Click on the “Create Application” button to start setting up your application.
Enter Required Information: Fill in the necessary details such as the application name, ip, and any other required fields.
Obtain API Key: After completing the setup, you will receive an API Key. This key will be used in subsequent steps to communicate with our API and enable 2FA functionality in your application.

Note: Please ensure that you enter the correct IP address for your server when prompted. This is required to pass the whitelist check from our system and ensure secure communication with our API.

Step 2. Update your application

Add 2FA Settings in Your Application
- Navigate to the Security page of your application.
- Build a screen that allows users to enable or disable 2FA.
Generate a QR Code
Generate a QR code containing the TOTP provisioning URI and display it. This allows the user to scan the QR code with an eAuthenticator app to add their account.
QR Code Format
The QR code should encode the following URL format:
otpauth://totp/{issuer}:{user_email}?secret={secret_key}&issuer={issuer}&algorithm=SHA1&digits=6&client_id={client_id}&email={user_email}
- Replace {issuer} with your application name.
- Replace {user_email} with the user’s email address.
- Replace {client_id} with your application’s client ID.
- Replace {secret_key} with the TOTP secret assigned to the user.
Display the QR Code and Guide users to scan the QR Code using eAuthenticator App
- Instruct users to download and install the eAuthenticator app from the Google Play Store or Apple App Store.
- Guide users to:
  - Open the eAuthenticator app and tap the ’+’ icon to add a new account.
  - Scan the QR code displayed on your application.
  - Enter the OTP generated by the eAuthenticator app into the input field on your application.
- Alongside the QR code, display an input field where users can enter the TOTP code generated by the eAuthenticator app.
Verify the OTP
After scanning the QR code, users must enter the OTP generated by eAuthenticator app. Your backend must verify this OTP to enable 2FA for the user.
Notify the Server After Enabling/Disabling 2FA
Once the user enables or disables 2FA, your application must send a request to the authentication server to synchronize the updated 2FA status. This ensures that the server is aware of the user’s current 2FA configuration and can enforce it during authentication attempts.
*It is crucial to handle these requests securely by using the API key provided during the setup process. Ensure that all sensitive data is transmitted over HTTPS to prevent unauthorized access or interception.
- API reference

Step 3. Update Your Application to Support Session Creation

After your application is configured to use 2FA, you need to make sure that it can handle user sessions properly.

Upon successful login, your server must call API to create a sessionfor the user using their email.
This API call will return asession_token, which will be used in subsequent requests.

Securely store the session_token for Authentication Validation

After obtaining the session_token, your portal server should store it securely for at least 2 minutes. This token will be compared with the authentication results received from the eAuthenticator service once the user completes the 2FA authentication. By matching the session token with the 2FA response, your system can ensure that the authentication was completed successfully and verify the user’s identity.

Key Steps:

Create User Session: Upon successful login, call the API to generate a session_token.
Store the session_token: Securely store the session_token for at least 2 minutes to allow time for 2FA completion.
Compare session_token with eAuthenticator results: Once the user completes 2FA, retrieve the stored session_token and compare it with the authentication response from the eAuthenticator service.

By implementing this mechanism, your system ensures that authentication is verified correctly while preventing unauthorized access.

Step 4. Redirect to eAuthenticator server

Your portal will then trigger the authentication process by opening a webview that points to a specific URL. This will load the 2FA interface, where the user will be prompted to complete the authentication process.

Generate a URL to request access from eAuthenticator endpoint at https://identifier.ekyc.com/start-authentication. This endpoint is accessible over HTTPS; plain HTTP connections are refused.

The eAuthenticator server supports two sign-in methods:

Option 1: Signing in with a redirect:

https://identifier.ekyc.com/start-authentication?signin_method=redirect&session_token={sessionToken}&redirect_uri={redirectUri}

Parameters
`signin_method`	Required The sign-in method to use. The value must be `redirect` in this case.
`session_token`	Required A unique token generated during the session creation process. This token must be included when the webview calls back to the portal.
`redirect_uri`	Required The URL where the portal will receive the callback once the 2FA process is completed. This URL will include the session_token and indicate the outcome of the authentication.

Option 2: Signing in with a popup:

To authenticate using a popup, your application should open the eAuthenticator Webview in a new tab. The authentication server will then handle user login and return a response via postMessage.

Opening the Authentication Popup

To initiate the authentication process, construct the authentication URL with the necessary query parameters:

https://identifier.ekyc.com/start-authentication?signin_method=popup&session_token={sessionToken}&redirect_uri={redirectUri}&state={state}

Parameters
`signin_method`	Required The sign-in method to use. The value must be `popup` in this case.
`session_token`	Required A unique token generated during the session creation process. This token must be included when the webview calls back to the portal.
`redirect_uri`	Recommended The origin URL of the portal. This URL will be used to strict targetOrigin
`state`	Recommended Specifies any string value that your application uses to maintain state between your authorization request and the authorization server’s response. If you generate a random string or encode the hash of a cookie or another value that captures the client’s state, you can validate the response to additionally ensure that the request and response originated in the same browser, providing protection against attacks such as cross-site request forgery (CSRF).

Example Implementation:

const state = generateAuthState();
sessionStorage.setItem("oauth_state", state);

const authUrl = 'https://identifier.ekyc.com/start-authentication?signin_method=popup&session_token={sessionToken}&redirect_uri={redirectUri}&state={state}';
// Open authentication in a new popup window
const popup = window.open(authUrl, "_blank", "width=500,height=600");

// Ensure the popup is opened successfully (handling potential pop-up blockers)
if (!popup) {
  console.error("Popup blocked. Please allow pop-ups and try again.");
}

Note: The sign-in with popup method may not work on mobile devices, as popups are often blocked or behave differently in mobile browsers.

Step 5. Handle the eAuthenticator server response

Once the user has completed the two-factor authentication (2FA) process, the verification result must be handled appropriately to ensure secure access to the portal.

1. Notifying your Backend of the Verification result

Before the portal client retrieves the access token, your backend must be notified of the 2FA verification result. This ensures that the backend can validate the outcome of the authentication process and take the necessary actions.

The backend will receive the callback that has been pre-defined in the Domain console and check the result of the 2FA authentication (e.g., whether the verification was successful or failed).
If the verification is successful, the backend will proceed with generating an access token for the user and initiate the necessary steps to grant access.
If the verification fails, the backend will reject the request, and the user will be notified of the failure, preventing access to your app.

2. How to handle response in your client side?

Option 1: Signing in with a redirect:

Successful verification:

If the 2FA verification is successful, the eAuthenticator will automatically redirect to the redirect_uri provided earlier in the integration process. This redirect serves as a signal to your portal that the authentication process has been completed successfully.

https://your-application.example.com/callback?session_token=1234567890

Redirection process:

The eAuthenticator will make a request to the specified redirect_uri, passing along the session_token and indicating the success of the authentication.
Upon receiving the callback, the portal’s frontend must call the designated API to retrieve the authentication token from the your backend server.

Failure Verification:

If 2FA verification fails, the eAuthenticator displays a UI notifying the user that they do not have access. In this case, the UI will also show a ’Sign In’ button. When the user clicks this button, they will be redirected to the redirect_uri without a session_token to indicate that authentication has failed.

https://your-application.example.com/callback?error=REJECT|TIMEOUT|INTERNAL_SERVER_ERROR

Your app should handle this scenario by detecting the absence of a session token and automatically redirecting the user to the /sign-in page for re-authentication or further instructions.

Option 2: Signing in with a popup:

The authentication response will be posted via postMessage to the parent window, passing along the session token and success status.

Handling postMessage:

To securely process the authentication response, your app’s frontend must:

Listen for the postMessage event – This allows your application to receive authentication data from the popup window.
Validate the message origin – Ensure the response comes from the trusted authentication server to prevent unauthorized messages.
Verify the state parameter – Compare the state received in the authentication response with the previously stored state value that was sent during the initial authentication request. This prevents CSRF (Cross-Site Request Forgery) attacks.

Data response:

{
    session_token: string | null;
    state?: string;
    error?: string | "REJECT" | "TIMEOUT" | "INTERNAL_SERVER_ERROR";
  }

Example:

window.addEventListener("message", (event) => {
    if (event.origin !== "https://identifier.ekyc.com") return; // Validate the origin
  
    const { state, session_token } = event.data;
    if (state !== sessionStorage.getItem("oauth_state")) {
      console.error("Invalid state: Possible CSRF attack!");
      return;
    }
    if (session_token) {
      // Call API to retrieve the authentication token
    }
  }, false);

In the event of failure, your app should listen for the postMessage event, and if the response indicates failure, you can redirect the user to the /sign-in page or provide further instructions.

window.addEventListener("message", (event) => {
    if (event.origin !== "https://identifier.ekyc.com") return; // Validate the origin
  
    const data = event.data;
    if (data.error) {
      // Show failure UI, and provide option to sign in again
      alert("Authentication failed. Please try again.");
      window.location.href = "/sign-in"; // Redirect to sign-in page
    }
  }, false);

API reference

Get session token
Request Headers
- X-API-Key: API key from the Authenticator console of the application. This key is required for authentication.
Request Body Parameters
Parameter Type Required Description
email string ✅ Yes The email address of the user.
client_id string ✅ Yes Your application’s client ID.
Request Example
curl --location 'https://authen.ekyc.com/authen-api/api/v1/session-token' --header 'X-API-Key: abcd' --header 'Content-Type: application/json' --data '{ "email": "[email protected]", "client_id": "84c2ad6c-62eb-4217-8f46-a66852e6fe92" }'
Success Response
{ "code": "SUCCESS", "message": "Success", "data": { "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbXBsb3llZV9pZCI6IjEyMzQiLCJjbGllbnRfaWQiOiI4NGMyYWQ2Yy02MmViLTQyMTctOGY0Ni1hNjY4NTJlNmZlOTIiLCJleHAiOjE3MzY4Mzg0NjIsImlhdCI6MTczNjgzODM0Mn0.1nJtIEalRVxhLoxQLIepHxcK6dsPDwfUsyM1YtAqq58" } }
Case of inactive client – This indicates that your application has been marked as inactive in the Domain Console
{ "code": "INACTIVE", "message": "client not active", "data": null }
Error Response
{ "code": "INVALID_REQUEST", "message": "get session token failed", "data": "" }
API receive verification response
The verification response will be sent to the callback_url specified in the Console, with the params request format outlined below. It is your responsibility to process this response and grant user access accordingly.
{CALLBACK_URL}?result=true&session_token={SESSION_TOKEN}
Parameters:
- result: A boolean value indicating the verification status. true means the verification was successful, while false indicates failure.
- session_token: A unique identifier for the authentication session. Your backend needs this parameter to identify the session in progress. It should compare the stored session token with the received one and proceed accordingly.
For more details: Notifying your Backend of the Verification result

Parameter	Type	Required	Description
email	string	✅ Yes	The email address of the user.
client_id	string	✅ Yes	Your application’s client ID.

Synchronizing the 2FA status

This API endpoint is responsible for synchronizing the 2FA status for a given user. Your backend must call this API whenever a user enables or disables 2FA in your application.

Request Headers

X-API-Key: API key from the Authenticator console of the application. This key is required for authentication.

Request Body Parameters

Parameter	Type	Required	Description
client_id	string	✅ Yes	Your application’s client ID.
email	string	✅ Yes	The email address of the user whose 2FA status is being updated.
secret	string	⚠️ Optional (for DISABLE)	The last known TOTP secret for the user. Required only when enabling 2FA, to verify ownership.
action	string	✅ Yes	Must be either "ENABLE" to activate 2FA or "DISABLE" to deactivate it.
type	string	✅ Yes	The type of 2FA. Currently supports "TOTP".
algorithm	string	✅ Yes	The hashing algorithm for TOTP generation (e.g., "SHA1").
digits	number	✅ Yes	Number of digits in the TOTP code (typically 6).
period	number	✅ Yes	The validity period of each TOTP code in seconds (e.g., 30).

Example Request

curl --location 'https://authen.ekyc.com/authen-api/api/v1/mfa/toggle'   --header 'X-API-Key: ybz4gkzlgzla4u4txhn6ju'   --header 'Content-Type: application/json'   --data-raw '{
      "email": "[email protected]",
      "client_id": "CLIENT_ID",
      "secret": "SECRET_KEY",
      "action": "ENABLE",
      "type": "TOTP",
      "algorithm": "SHA1",
      "digits": 6,
      "period": 30
  }'

Success Response

{
      "code": "SUCCESS",
      "message": "Success",
      "data": ""
  }

Error Response

{
      "code": "INVALID_REQUEST",
      "message": "toggle failed",
      "data": ""
  }

QR Code Format

2. How to handle response in your client side?