OAth adapter (TOTPAdapter)

The OAth Adapter allows TrustBuilder to generate event and time-based one time passwords.

Prerequisites

A keystore is required in your TB_HOME in order to generate secure private keys. When adding the otp adapter via the gui the key is automatically added into the keystore.

Configuration

AdapterUniqueID: Unique name assigned to this adapter; the name is used to reference the adapter in the workflow. The ID has following requirements:
- START with a letter or _ (underscore)
- FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)
Window: Used to set the maximum difference in time window number between the gerenation and the validation for the one time password so that the generated token is still validated successfully. A time window has a duration of 30 seconds.
Secret: Empty Field, created automatic with the public and private key. When creating the adapter the secret is auto generated and thus not reversable afterwards. Herefore a public key is taken with a private key in the store. (alias and password needed).
PrivateKeyAlias: Alias of the private key in the keystore.
OtpLength: Length of the otp. Between 6 and 10 including boundaries. Default: 6.
PrivatekeyPassword: Password to decode the private key in the keystore.
DigestAlgorithm: The Algorithm used to encode the secret. Default: SHA1.
HashingAlgorithm: The Algorithm used to generate the otp-values. Default: HmacSHA1.

Workflow Settings

A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:

Input Property: the variable containing the instructions the adapter have to execute
Output Property: the variable the adapter will store the response in after execution
Before Adapter Script: script that will be executed before calling the adapter
After Adapter Script: script that will be executed after the adapter fulfilled its task

Request - API

totpGenerateSecret

Generate a secret to be used for Time based OTP

CODE

totpGenerateSecret(identifier)

where:

CODE

identifier: userid (or any combination thereof or for example a transactions hash)

After generation the adapter gives a secret. To calculate the OTP you have to call a function from the output of the adapter.

example TOTP Generation

CODE

// Create a totp request
workItem.totpInput = tb.totpGenerateSecret(key);

tb.log(JSON.stringify(workItem.totpOutput));
// Engine.ScriptLogger - {"status":0,"substatus":0,"nativestatus":0,"message":null,"rc":"OK","generated":true,
//"identifier":"gmtpWm41iUpGv8VubRLsNmZhw0ytXafx2JXavNoS","secret":"TNURQLVFP2USPBE63KK3JZ2K7NPKW24V","roundtrip":2}

 var code = workItem.totpOutput.generate(0);

 tb.log(code,'OTP CODE');
// OTP CODE - 702082

This method "generate" of the responseobject corresponding to a generationrequest will return the generated otp as an integer, possibly with a number of digits that is less than was configured, because leading zeros are not present. It is also possible to get the generated otp as a string which will have the configured number of digits. This is done with the method generatePadded of the same responseobject:

CODE

var code = workItem.totpOutput.generatePadded(0);

totpValidate

Generate a validation request for a certain OTP

CODE

totpValidate(identifier, otp)

where:

CODE

identifier: Identifier used when issuing the request

otp to validate

hotpValidate

Generate a validation request for a certain OTP

CODE

hotpValidate(identifier, otp, reference)

where:

CODE

identifier: Identifier used when issuing the request
otp to validate
reference : reference number (last known)

ocraValidate

Generate a validation request for a certain ocra request

CODE

ocraValidate(identifier, otp, ocrasuite)

where:

CODE

identifier: Identifier used when issuing the request
otp to validate
ocrasuite : the ocrasuite to decode the otp with

Response - API

Common Properties

The response API can be applied to the variable specified in the "output property" (see "Workflow Settings"): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.

All responses have four properties in common:

status: Status flag indicating whether the response is ok (0) or not (1).
substatus
message : Response specific message in case there was a problem (can be null)
rc: Return Code, a human readable code based on the substatus

Adapter Specific Properties

getIdentifier(): Identifier used to create/validate OTP
generated: Is this a generated OTP
secret: Only in case of a generated OTP

Response Codes

If the otp validation was successfull, the status is 0. If the otp validation was unsuccessfull the status is 1. If the status is 1, the substatus gives some more information about why the validation was unsuccessfull. Below you can see the values the substatus can have, in case the status is 1, together with more information about these values:

1: Internal error
2: Invalid OTP

If the status is 0 and the validationrequest was a totpvalidationrequest, the substatus contains the difference in time window of generation compared to validation. If the time window of validation is a later time window than the time window of generation this subtatus is negative.

Examples

Example 1 : Generation

CODE

/**
 * Prepare OTP request
 */
function prepareOtpGeneration(workItem){
    workItem.totprequest = tb.totpGenerateSecret(myIdentifier);
}

Response

CODE

if(workItem.totpresponse.status != 0){
        tb.log("Invalid OTP response, aborting",null,'error');
        workItem.message = "Invalid OTP response, aborting";
        return 'error';
}
else{
    workItem.secret = workItem.totpresponse.secret;
}

Example 2 : Validation

CODE

/**
 * Prepare OTP request
 */
function prepareOtpValidation(workItem){
    workItem.totprequest = tb.totpValidate(workItem.otpKey, workItem.otp);
}

Response

CODE

if(workItem.totpresponse.status != 0){
        tb.log("Invalid OTP response, aborting",null,'error');
        workItem.message = "Invalid OTP response, aborting";
        return 'error';
}