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
-
Node.js 24 or later, npm 10.8.2 or later
-
Bundler: any bundler able to provide Node.js
Bufferandeventsmodules in the browser.
The sample application uses Vite.
Installation
To install TrustBuilder Safe-T SDK Web app:
-
Install the library from npm.
npm install @inwebo-trustbuilder/mfa-lib@{VERSION} -
Provide Node.js modules in the browser.
The library relies on the Node.jsBufferandeventsmodules, which browsers do not provide.-
Install the polyfills:
npm install buffer events -
Expose
Bufferas a global variable before using the library, for example at the top of your entry file:JavaScriptimport { Buffer } from 'buffer' globalThis.Buffer = BufferThe sample application uses Vite. See
vite.config.tsandsrc/main.ts.
-
-
Import the library and create an instance:
JavaScriptimport { TrustBuilderMfaLib } from '@inwebo-trustbuilder/mfa-lib' const trustBuilderMfaLib = new TrustBuilderMfaLib()
Run the sample application
-
Prerequisites:
-
Node.js 24 or later, npm 10.8.2 or later.
-
Java 17
-
In the Admin Portal:
-
Create a custom application (custom login portal) that points to the sample application URL
-
Create a custom internal authentication method (web) that uses the custom application previously created.
See White label integration.
-
-
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:
-
Register the browser: open the portal and enter an activation code to register the browser as an authentication method.
-
Authenticate: start authentication from an application that uses your custom authentication method. The portal opens with
session_id,tnt_aliasandlogin_hintin 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 |
|---|---|
|
|
Identifier of this browser installation Sample application value: |
|
|
Device name shown to users and administrators Sample application value: browser name detected |
|
|
Kind of authenticator Sample application value: |
|
|
Any non-empty string. Not used to authenticate, but required for registration, reset and change Sample application value: |
|
|
Sample application value: Demo application name, version |
|
|
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:
-
Call the corresponding
startXxx(params)method to create an operation. -
Call
setup()to initialise the operation and retrieve the information required to continue. -
Check the result using
isError. -
If setup succeeds, call
execute(cred)with the user's credentials. Check the execution result usingisError.
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 |
|---|---|---|
|
|
|
See Core objects |
|
|
|
Activation code received by the user |
-
Steps:
-
Start the registration operation using the activation code and host information.
-
Call
setup()to initialise the registration. -
Check the result using
isError. -
Check the returned
credMode:-
EXISTING: ask the user to enter their existing secret code. -
NEW: ask the user to define a secret code.
-
-
Call
execute()with the secret code and check the result usingisError.
-
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:
JavaScriptconst 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 |
|---|---|---|
|
|
|
See Core objects |
|
|
|
Alias of the registered browser authentication method. The sample app retrieves the user's registered authentication methods (secure tokens) using |
|
|
|
ID of the authentication session. This parameter is provided by the |
-
Steps:
-
Start the authentication operation with the host information, token alias and session ID.
-
Call
setup()to initialise the operation. -
Check the result using
isError. -
Ask the user to enter their secret code.
-
Call
execute()with the secret code and check the result usingisError.
-
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:
JavaScriptconst 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 |
|---|---|---|
|
|
|
See Core objects |
|
|
|
Alias of the registered browser token. |
|
|
|
Reset code entered by the user |
-
Steps:
-
Start the reset operation with host, the token alias and reset code.
-
Call
setup()to initialise the operation. -
Check the result using
isError. -
Ask the user to enter a new secret code.
-
Call
execute()with the new secret code and check the result usingisError.
-
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:
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 |
|---|---|---|
|
|
|
See Core objects |
|
|
|
Alias of the registered browser token. |
-
Steps:
-
Start the change operation with the host information and token alias.
-
Call
setup()to initialise the operation. -
Check the result using
isError. -
Ask the user to enter their current secret code and a new secret code.
-
Call
execute()with both secret codes and check the result usingisError.
-
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:
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 |
|---|---|
|
|
Wrong secret code |
|
|
Too many wrong secret codes, the secret code is blocked |
|
|
The new secret code does not follow the required format |
|
|
Invalid or already used reset code |
|
|
The server rejected the OTP sent after the user’s credentials were retrieved |
|
|
The login session is invalid or expired |
|
|
No authentication method found in this browser’s local storage (typically after the site data was cleared). The browser must be registered again. |
|
|
This authentication method no longer exists (it may have been deleted by an administrator or the user). The browser must be registered again. |
|
|
This authentication method is blocked. |
|
|
The user no longer exists in the tenant |
|
|
The user account is blocked |
|
|
The operation is not allowed for this user |
|
|
The browser storage could not be read |
|
|
No usable HTTP response from the server (for example: server unreachable or request blocked) |
|
|
A required parameter is missing or invalid |
|
|
Internal cryptographic error |
|
|
Unexpected error |