TrustBuilder Safe-T

MFA SDK - Web

The TrustBuilder Safe-T SDK Web turns a user's browser into an authentication method. Users can then use it to sign in to secured applications.

This guide covers the browser-based authentication flows used by the sample application:

  • registering the browser as an authentication method with an activation code;

  • authenticating with the registered browser and the user's secret code;

  • resetting a forgotten secret code;

  • changing the secret code.

The web sample application also shows the out-of-band authentication flow. Out-of-band authentication is not covered in this documentation page. For more details, refer to White label integration.

Requirements

  • TrustBuilder Safe-T tenant

  • Download TrustBuilder sample app for Web

  • Node.js 24 or later, npm 10.8.2 or later

  • Bundler: any bundler able to provide Node.js Buffer and events modules in the browser.
    The sample application uses Vite.

Installation

To install TrustBuilder Safe-T SDK Web app:

  1. Install the library from npm.

    npm install @inwebo-trustbuilder/mfa-lib@{VERSION}
    
  2. Provide Node.js modules in the browser.
    The library relies on the Node.js Buffer and events modules, which browsers do not provide.

    1. Install the polyfills: npm install buffer events

    2. Expose Buffer as a global variable before using the library, for example at the top of your entry file:

      JavaScript
      import { Buffer } from 'buffer'
      globalThis.Buffer = Buffer
      

      The sample application uses Vite. See vite.config.ts and src/main.ts.

  3. Import the library and create an instance:

    JavaScript
    import { TrustBuilderMfaLib } from '@inwebo-trustbuilder/mfa-lib'
    
    const trustBuilderMfaLib = new TrustBuilderMfaLib()
    

Run the sample application

To run the sample application:

npm install
npm run swagger   # generates the Login API client in src/swagger/ from api-specs/login-api.json 
npm run dev       # serves the portal on http://localhost:8080

To test the authentication flow:

  1. Register the browser: open the portal and enter an activation code to register the browser as an authentication method.

  2. Authenticate: start authentication from an application that uses your custom authentication method. The portal opens with session_id, tnt_alias and login_hint in its URL. Enter a secret code to complete the authentication.

Core objects

Host object

Each operation takes a host describing the browser and your application. appInfo.name, appInfo.version and osInfo.name are mandatory.

Field

Description

serial

Identifier of this browser installation

Sample application value: 'serial'

name

Device name shown to users and administrators

Sample application value: browser name detected

type

Kind of authenticator

Sample application value: TokenType.IW_WEB

appAlias

Any non-empty string. Not used to authenticate, but required for registration, reset and change

Sample application value: 'trustbuilder_mfa_web_demo_app'

appInfo

{ id, name, version, browser? } of your application

Sample application value: Demo application name, version '1.0', browser name

osInfo

{ name, version? } of the user's device

Sample application value: OS name detected

Credentials

The secret code is passed to execute() as a Cred object, with the code converted to a UTF-8 Buffer.

For the secret code change, execute() takes the old and new codes as plain strings.

During registration, setup() returns a CredentialProvider whose credMode tells you which form to display: NEW when the user must create a secret code, EXISTING when they must enter the one they already have. Its credProperties.secretCodeFormat gives the length and character rules for a new code.

Operations

Each operation follows the same general sequence:

  1. Call the corresponding startXxx(params) method to create an operation.

  2. Call setup() to initialise the operation and retrieve the information required to continue.

  3. Check the result using isError.

  4. If setup succeeds, call execute(cred) with the user's credentials. Check the execution result using isError.

For operations requiring a secret code, pass the credentials using the expected credential type and format.

Registration

startSecureTokenEnrollment(params): registers the browser as an authentication method for a user.

Prerequisites:

  • The user must already exist in the TrustBuilder tenant.

  • The user must have a valid activation code to register the browser as an authentication method.

Parameter

Type

Description

host

IHost

See Core objects

activationCode

string

Activation code received by the user

  • Steps:

  1. Start the registration operation using the activation code and host information.

  2. Call setup() to initialise the registration.

  3. Check the result using isError.

  4. Check the returned credMode:

    • EXISTING: ask the user to enter their existing secret code.

    • NEW: ask the user to define a secret code.

  5. Call execute() with the secret code and check the result using isError.

  • Returns: SecureTokenDTO, the registered authentication method. It is also saved in the browser.

  • Errors: IW_INV_OTP_ERR, IW_INV_CRED_ERR, IW_BLOCKED_CRED_ERR, IW_INVALID_SECRET_CODE_FORMAT, IW_USR_IS_UNKNOWN_ERR, IW_USR_IS_BLOCKED_ERR, IW_TKN_IS_UNKNOWN_ERR, IW_TKN_IS_BLOCKED_ERR, IW_FORBIDDEN_ERR, IW_CORE_CNX_ERR, IW_UNKNOWN_ERR, InvalidParameterError.

Example:

JavaScript
const operation = trustBuilderMfaLib.startSecureTokenEnrollment({
  host,
  activationCode
})

const setupResult = await operation.setup()

if (setupResult.isError) {
  throw setupResult.error
}

if (setupResult.value.credMode === 'EXISTING') {
  // The user already has a secret code: ask them to enter it
} else {
  // NEW: ask the user to create a secret code
  // Format rules: setupResult.value.credProperties.secretCodeFormat
}

const secretCode = /* secret code entered by the user */

const result = await operation.execute({
  cred: Buffer.from(secretCode),
  credType: 'SECRET_CODE'
})

if (result.isError) {
  throw result.error
}

Authentication

startAuthentication(params): authenticates the user within the login session.

Prerequisites:

  • The user must have registered the browser as an authentication method.

  • An authentication session must have been created by the application initiating the authentication flow.

Parameter

Type

Description

host

IHost

See Core objects

tknAlias

string

Alias of the registered browser authentication method.

The sample app retrieves the user's registered authentication methods (secure tokens) using startSecureTokensListing() and displays them under Available secure tokens. If a stored token’s usrLogin matches the login_hint URL parameter, the sample pre-fills the field. The corresponding tknAlias is used for authentication.

sessionId

string

ID of the authentication session.

This parameter is provided by the /authorize request.

  • Steps:

  1. Start the authentication operation with the host information, token alias and session ID.

  2. Call setup() to initialise the operation.

  3. Check the result using isError.

  4. Ask the user to enter their secret code.

  5. Call execute() with the secret code and check the result using isError.

  • Returns: { result: boolean } confirming that the user has been authenticated within the session.

  • Errors: IW_INV_CRED_ERR, IW_BLOCKED_CRED_ERR, IW_INV_AUTH_SESS_ERR, IW_LOCAL_TKN_NOT_FOUND_ERR, IW_USR_IS_UNKNOWN_ERR, IW_USR_IS_BLOCKED_ERR, IW_TKN_IS_UNKNOWN_ERR, IW_TKN_IS_BLOCKED_ERR, IW_INV_OTP_ERR, IW_CORE_CNX_ERR, IW_UNKNOWN_ERR, InvalidParameterError.

Example:

JavaScript
const operation = trustBuilderMfaLib.startAuthentication({
  host,
  tknAlias,
  sessionId
})

const setupResult = await operation.setup()

if (setupResult.isError) {
  throw setupResult.error
}

const secretCode = /* secret code entered by the user */

const result = await operation.execute({
  cred: Buffer.from(secretCode),
  credType: 'SECRET_CODE'
})

if (result.isError) {
  throw result.error
}

Complete the login flow
After a successful authentication, the login portal must call the Login API get-auth-code endpoint, then redirect the browser to the returned redirect URI. Otherwise, the login flow does not complete.
For an implementation example, see handleRedirection in authentication.component.ts in the sample application.

Secret code reset

startSecretCodeReset(params): defines a new secret code using a reset code. This allows a user who has forgotten their secret code to set a new one.

Prerequisites:

  • The user must have registered the browser as an authentication method.

  • The user must have a valid reset code.

Parameter

Type

Description

host

IHost

See Core objects

tknAlias

string

Alias of the registered browser token.

code

string

Reset code entered by the user

  • Steps:

  1. Start the reset operation with host, the token alias and reset code.

  2. Call setup() to initialise the operation.

  3. Check the result using isError.

  4. Ask the user to enter a new secret code.

  5. Call execute() with the new secret code and check the result using isError.

  • Returns: { result: boolean }.

  • Errors: IW_INV_CODE_ERR, IW_INVALID_SECRET_CODE_FORMAT, IW_INV_OTP_ERR, IW_LOCAL_TKN_NOT_FOUND_ERR, IW_CORE_CNX_ERR, IW_UNKNOWN_ERR, GenerateOtpError, InvalidParameterError.

Example:

JavaScript
const operation = trustBuilderMfaLib.startSecretCodeReset({
  host,
  tknAlias,
  code: resetCode
})

const setupResult = await operation.setup()

if (setupResult.isError) {
  throw setupResult.error
}

const newSecretCode = /* new secret code entered by the user */

const result = await operation.execute({
  cred: Buffer.from(newSecretCode),
  credType: 'SECRET_CODE'
})

if (result.isError) {
  throw result.error
}

Secret code change

startSecretCodeChange(params): allows an authenticated user to replace their current secret code with a new one.

Prerequisites:

  • The user must have registered the browser as an authentication method.

  • The user must know their current secret code.

Parameter

Type

Description

host

IHost

See Core objects

tknAlias

string

Alias of the registered browser token.

  • Steps:

  1. Start the change operation with the host information and token alias.

  2. Call setup() to initialise the operation.

  3. Check the result using isError.

  4. Ask the user to enter their current secret code and a new secret code.

  5. Call execute() with both secret codes and check the result using isError.

  • Returns: { result: boolean }.

  • Errors: IW_INV_CRED_ERR, IW_BLOCKED_CRED_ERR, IW_INVALID_SECRET_CODE_FORMAT, IW_LOCAL_TKN_NOT_FOUND_ERR, IW_USR_IS_UNKNOWN_ERR, IW_USR_IS_BLOCKED_ERR, IW_TKN_IS_UNKNOWN_ERR, IW_TKN_IS_BLOCKED_ERR, IW_INV_OTP_ERR, IW_CORE_CNX_ERR, IW_UNKNOWN_ERR, InvalidParameterError.

Example:

JavaScript
const operation = trustBuilderMfaLib.startSecretCodeChange({
  host,
  tknAlias
})

const setupResult = await operation.setup()

if (setupResult.isError) {
  throw setupResult.error
}

const oldSecretCode = /* current secret code */
const newSecretCode = /* new secret code */

const result = await operation.execute({
  oldSecretCode,
  newSecretCode
})

if (result.isError) {
  throw result.error
}

Errors

Identify an error by its name and map it to a user-friendly message.

Error name

Description

IW_INV_CRED_ERR

Wrong secret code

IW_BLOCKED_CRED_ERR

Too many wrong secret codes, the secret code is blocked

IW_INVALID_SECRET_CODE_FORMAT

The new secret code does not follow the required format

IW_INV_CODE_ERR

Invalid or already used reset code

IW_INV_OTP_ERR

The server rejected the OTP sent after the user’s credentials were retrieved

IW_INV_AUTH_SESS_ERR

The login session is invalid or expired

IW_LOCAL_TKN_NOT_FOUND_ERR

No authentication method found in this browser’s local storage (typically after the site data was cleared). The browser must be registered again.

IW_TKN_IS_UNKNOWN_ERR

This authentication method no longer exists (it may have been deleted by an administrator or the user). The browser must be registered again.

IW_TKN_IS_BLOCKED_ERR

This authentication method is blocked.

IW_USR_IS_UNKNOWN_ERR

The user no longer exists in the tenant

IW_USR_IS_BLOCKED_ERR

The user account is blocked

IW_FORBIDDEN_ERR

The operation is not allowed for this user

IW_TKN_STORAGE_ERR

The browser storage could not be read

IW_CORE_CNX_ERR

No usable HTTP response from the server (for example: server unreachable or request blocked)

InvalidParameterError

A required parameter is missing or invalid

GenerateOtpError

Internal cryptographic error

IW_UNKNOWN_ERR

Unexpected error