SOTT (Secure One-Time Token)

Overview

The Secure One-Time Token (SOTT) is a LoginRadius security feature that protects user registration flows from unauthorized or automated sign-ups. It ensures that registration requests originate from trusted sources by requiring a time-bound, encrypted token to be included with each request.

SOTT is dynamically generated using the API Key, API Secret, and a timestamp range (start and end time). While LoginRadius SDKs automatically handle SOTT generation during registration, you can also manually generate a SOTT for custom flows or advanced configurations.

Key Features

• Strengthens registration endpoint security without relying solely on CAPTCHAs.
• Delivers a smooth registration experience on smaller screens compared to visual-based security methods while maintaining robust protection.
• Customizable token validity period by setting the expiration window for advanced scenarios like timed registration links, extended onboarding flows, or security-conscious applications that require short-lived tokens.

Primary Use Cases

Mobile Registration (Alternative to CAPTCHA)

SOTT adds an extra layer of registration security without introducing visual challenges or UI elements, making it a smooth experience across both web and mobile platforms - including smaller screens where traditional security methods may be less convenient.

• The SDK generates a new SOTT for each registration attempt.
• The token is passed to the Auth User Registration by Email API during the request.

Web Registration with SOTT

Even for web apps, SOTT can be used alongside or instead of CAPTCHA to provide an additional layer of bot protection.

• Every new user registration uses a freshly generated SOTT.
• The SOTT is sent as part of the Auth User Registration by Email API call.

Configuration

You can manually generate a Secure One-Time Token (SOTT) in the LoginRadius Admin Console using your API Key and Secret. For step-by-step configuration instructions, refer to the API Configuration ocument.

Integration Guide

Below are the various methods LoginRadius supports for generating the SOTT when leveraging it for custom implementations.

• LoginRadius API
• Manual Generation
• SDK Implementation

Default Expiration Time

By default, a SOTT expires 10 minutes after generation. You can customize this window by:

• Using the Admin Console or Generate SOTT API to configure your preferred expiration duration.
• Passing custom startTime and endTime when generating it manually.

API Implementation

You can leverage the Generate SOTT API to generate the SOTT by ingesting the LoginRadius API Key, LoginRadius Secret Key, and timedifference. The response will include the SOTT and its expiration time.

Below is the sample output of a successful response.

{
  "Sott": "UHvoadn**********/PrJ6DzANoF**********jWGFyk***J8n3COAV**********gjlHh****YN4mGy+mly**********uyp3hZPMqxs48=*c09bd**********a40662e6eb30*****",
  "ExpiryTime": "2017-11-06T07:03:12.1100256Z"
}

Manual Generation

This section outlines the algorithm and required parameters for manually generating a Secure One-Time Token (SOTT) using your Primary API Secret.

NOTE: Only the Primary API Secret can generate a SOTT manually. The Additional Secret is unsupported for manual SOTT generation or SDK-based manual overrides.

Required Constants

It is essential to define the following constants before proceeding with the SOTT generation.

const INIT_VECTOR = "tu89geji340t89u2";
const KEY_SIZE = 256;
const DATE_FORMAT = "YYYY/MM/DD H:i:s";

Step-by-Step Guide to SOTT Generation

1. Calculate Date Interval: Compute the difference between your desired startTime and endTime using the format YYYY/MM/DD H:i:s.

2. Prepare Plain Text: Construct a plain text string using the format: {DateInterval} + "#" + {APIKey} + "#" + {DateInterval}

3. Derive Encryption Key (PBKDF2): Use the PBKDF2 key derivation algorithm with your base64-encoded Primary API Secret to generate a secure encryption key.

4. Encrypt the Plain Text: Encrypt the constructed plain text using:

   • The derived PBKDF2 key
   • The fixed Initialization Vector (INIT_VECTOR).
   • AES encryption with a 256-bit key

5. Base64 Encode the Encrypted Output: Encode the encrypted data to base64 format to make it URL-safe and transportable.

6. Generate MD5 Hash of Encrypted Data: Initialize an MD5 hash context and feed the base64-encoded encrypted string to compute the final SOTT value.

SDK Implementation

PHP

Follow the integration steps in this document to implement the LoginRadius PHP SDK. Once the SDK is set up, add the following code snippet to begin using it:

$timeDifference =''; // (Optional) The time difference will be used to set the expiration time of SOTT, If you do not pass time difference then the default expiration time of SOTT is 10 minutes.

$getLRserverTime=false; //(Optional) If true, it will call LoginRadius Get Server Time Api and fetch basic server and server time information, which is useful when generating an SOTT token.

//The LoginRadius API key and primary API secret can be passed additionally. If the credentials are not passed, this SOTT function will pick the API credentials from the SDK configuration.

$apiKey=""; //(Optional) LoginRadius Api Key

$apiSecret=""; //(Optional) LoginRadius Api Secret (Only Primary Api Secret is used to generate the SOTT manually)

$sottObj = new SOTT();
$sott = $sottObj->encrypt($timeDifference,$getLRserverTime,$apiKey,$apiSecret);

DotNet

Follow the integration steps in this document to implement the LoginRadius DotNet SDK. Once the SDK is set up, add the following code snippet to begin using it:

LoginRadiusSecureOneTimeToken _sott = new LoginRadiusSecureOneTimeToken();

// You can pass the start and end time intervals, and the SOTT will be valid for this time duration. StartTime and EndTime are optional, but if passing the value, both values need to be passed.

var sott = new SottRequest
{
    StartTime = "2017-05-15 07:10:42", // Valid Start Date with Date and time
    EndTime="2017-05-15 07:20:42" // Valid End Date with Date and time
};

//The LoginRadius API key and primary API secret can be passed additionally. If the credentials are not passed, this SOTT function will pick the API credentials from the SDK configuration.

var apiKey = ""; //(Optional) LoginRadius Api Key.

var apiSecret = ""; //(Optional) LoginRadius Api Secret (Only Primary Api Secret is used to generate the SOTT manually).

var generatedSott=_sott.GetSott(sott,apiKey,apiSecret);

Java

Follow the integration steps in this document to implement the LoginRadius Java SDK. Once the SDK is set up, add the following code snippet to begin using it:

ServiceSottInfo serviceSottInfo=new ServiceSottInfo();

// You can pass the start and end time interval and the SOTT will be valid for this time.

serviceSottInfo.setStartTime("2021-01-10 07:10:42");  // Valid Start Date with Date and time

serviceSottInfo.setEndTime("2023-01-15 07:20:42"); // Valid End Date with Date and time

// Or you can pass the time difference in minutes for setting up the validity of SOTT; if you do not pass the time difference, then the default value is 10 minutes

serviceSottInfo.setTimeDifference("20");  // (Optional) The time difference will be used to set the expiration time of SOTT, If you do not pass time difference then the default expiration time of SOTT is 10 minutes.

ServiceInfoModel service=new ServiceInfoModel();

service.setSott(serviceSottInfo);

//The LoginRadius API key and primary API secret can be passed additionally. If the credentials are not passed, this SOTT function will pick the API credentials from the SDK configuration.

String apiKey="";//(Optional) LoginRadius Api Key.

String apiSecret="";//(Optional) LoginRadius Api Secret (Only Primary Api Secret is used to generate the SOTT manually).

try {
    String sottResponse = Sott.getSott(service,apiKey,apiSecret);
    System.out.println("sott = " + sottResponse);

} catch (Exception e) {
    e.printStackTrace();
}

Python

Follow the integration steps in this document to implement the LoginRadius Python SDK. Once the SDK is set up, add the following code snippet to begin using it:

timeDifference='10' #(Optional) The time difference will be used to set the expiration time of SOTT. If you do not pass the time difference, then the default expiration time of SOTT is 10 minutes.

getLRserverTime=False #(Optional) If True, it will call LoginRadius Get Server Time Api and fetch basic server and server time information, which is useful when generating an SOTT token.

# The LoginRadius API key and primary API secret can be passed additionally. If the credentials are not passed, this SOTT function will pick the API credentials from the SDK configuration.

apiKey="" #(Optional) LoginRadius Api Key.

apiSecret = "" # (Optional) LoginRadius Api Secret (Only Primary Api Secret is used to generate the SOTT manually).

sott_data = loginradius.get_sott(timeDifference, getLRserverTime,apiKey,apiSecret)

print(sott_data)

Ruby

Follow the integration steps in this document to implement the LoginRadius Ruby SDK. Once the SDK is set up, add the following code snippet to begin using it:

time_difference=10 # (Optional) The time_difference will be used to set the expiration time of SOTT If you do not pass time_difference, then the default expiration time of SOTT is 10 minutes.

api_key="" # (Optional) LoginRadius Api Key.

api_secret="" # (Optional) LoginRadius Api Secret (Only Primary Api Secret is used to generate the SOTT manually).

sott = AuthenticationApi.local_generate_sott(time_difference,api_key,api_secret);
print sott

Node.js

Follow the integration steps in this document to implement the LoginRadius Node.js SDK. Once the SDK is set up, follow the steps.

1. Create a variable config in the project.

   var config = {
     apidomain: "https://api.loginradius.com",
     apikey: "{{ Your API KEY }}",
     apisecret: "{{ Your API Secret }}",
     sitename: "{{ Your Sitename }}",
   };

2. Require the loginradius-v2-sdk package and pass it the config object.

   var lrv2 = require("loginradius-sdk")(config);

3. Call the getSott function.

   var startDate = "2017-05-15 07:10:42"; // Valid Start Date with Date and time
   var endDate = "2017-05-15 07:20:42"; // Valid End Date with Date and time
   
   lrv2.authentication
     .getSott(startDate, endDate)
     .then(function (response) {
       console.log(response);
     })
     .catch(function (error) {
       console.log(error);
     });

4. This will print the SOTT value on the console.

Demo

See a live example of the SOTT generation here: https://dotnetfiddle.net/fHk8Ah

Best Practices

• Always generate a new SOTT for every registration attempt.
• Use HTTPS to ensure the token is transmitted securely.
• Avoid hardcoding API secrets in client-side code.
• Prefer server-side SOTT generation where possible.

Related Documents

• Web SDKs
• Auth User Registration by Email API
• Generate SOTT API