Using entersekt Javascript SCA SDK

CustomerAuthn SDK by @entersekt

Entersekt's JavaScript SDK offers a seamless and straightforward integration process, enabling customers to add Browser Authentication functionality to their existing web applications. Customers can effortlessly incorporate authentication features - such as secure login, multi-factor authentication, and session management - into web-based interfaces. The JavaScript SDK leverages on-device cryptography to identify returning devices in a privacy-conscious manner.

The JavaScript SDK also provides a range of customization options, enabling customers to tailor the authentication flow to their specific requirements. Institutions can easily configure the behavior and user experience of the authentication prompts, ensuring a cohesive integration with their overall application design.

Furthermore, the SDK supports various authentication factors, enabling institutions to select the security level that best aligns with their risk tolerance and compliance standards.

Getting started

The CustomerAuthn Web SDK is a NPM package that is used in conjunction with the CustomerAuthn API to enable strong customer authentication in your browser. To install the plugin you will need to setup NPM to be able to pull from the private registry.

Setting up Authentication

The following environment variables need to be configured for the plugin to pull in these GitLab dependencies:

• ENT_USERNAME - The Entersekt provided username.
• ENT_TOKEN - The Entersekt provided token generated for your project.

Setting up .npmrc file

The easiest way to install this plugin is to set up an .npmrc file. Your .npmrc file should look as follows:

@entersekt:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken="<ENT_TOKEN>"

Installing

You can then add the plugin to your web project via the CLI:

npm i @entersekt/customerauthn-sdk-web

Configuration

The SDK's initialize method takes a ICustomerAuthnConfig object as parameter. This object contains fields that can be used to modify the configuration of the SDK such as the connectionURL and timeout values.

Using the SDK

The SDK can then be included into your project as follows:

npm i @entersekt/customerauthn-sdk-web

API Methods

joinInteraction

joinInteraction(joinOptions: IJoinOptions): Promise<void>

Used to indicate that an existing interaction needs to be joined. This is used when the interaction originated on a system other than the browser.

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelID: "SOME_CHANNEL",
};
const sdk = await CustomerAuthn.init(config);
await sdk.joinInteraction({ entersektJoinCode: "fec5dc04-cd76-4ba6-b05e-977f1f339beb" });

onChallengeCustomer

onChallengeCustomer(): Subject<IChallenge>

Observable to monitor for events when a new challenge is received

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelID: "SOME_CHANNEL"
};
const sdk = await CustomerAuthn.init(config);
sdk.onChallenge.subscribe().then(async (challenge) => {
 await challenge.proceed();
});

onIdentifyCustomer

onIdentifyCustomer(): Subject<IIdentifyCustomer>

Observable to monitor for events when a new identify customer event is received

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelID: "SOME_CHANNEL",
};
const sdk = await CustomerAuthn.init(config);
sdk.onIdentifyCustomer.subscribe().then(async (identifyCustomer) => {
  // show identifyCustomer UI
  await identifyCustomer.proceed()
  // hide identifyCustomer UI
});

onInteractionCompleted

onInteractionCompleted(): Subject<IInteractionCompleted>

Observable to monitor for events when an interaction has been completed

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelShortName: "SOME_CHANNEL",
};
const sdk = await CustomerAuthn.init(config);
sdk.onInteractionCompleted.subscribe().then(async (result) => {
 console.log(result)
});

onNotify

onNotify(): Subject<INotify> Observable to monitor for eve_nts when a new notify event is received

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelID: "SOME_CHANNEL",
};
const sdk = await CustomerAuthn.init(config);
sdk.onNotify.subscribe().then(async (notify) => {
 if (notify.userInteractionRequired){
   await notify.proceed();
 }
});

onRedirect

onRedirect(): Subject<IRedirect>

Observable to monitor for events when a new redirect event is received

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelID: "SOME_CHANNEL",
};
const sdk = await CustomerAuthn.init(config);
sdk.onRedirect.subscribe().then(async (redirect) => {
 if (redirect.userInteractionRequired){
   await redirect.proceed();
 }
});

onSetAuthenticationFactor

onSetAuthenticationFactor(): Subject<ISetAuthenticationFactor>

Observable to monitor for events when a new authentication factor is being registered

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelShortName: "SOME_CHANNEL",
};
const sdk = await CustomerAuthn.init(config);
sdk.onSetAuthenticationFactor.subscribe().then(async (result) => {
 await result.proceed();
});

Static init

init(configParams: ICustomerAuthnConfig): Promise<CustomerAuthn>

Used to initialize the SDK. This method should be called prior to making any calls to the SDK.

Example:

import CustomerAuthn from "@entersekt/customerauthn-sdk-web"

const config: ICustomerAuthnConfig = {
 connectionURL: "wss://connection.example.com/live",
 timeoutInMilliseconds: 10000,
 channelShortName: "SOME_CHANNEL",
};
CustomerAuthn.init(config).then(() => {
 // success
}).catch((error) => {
 // error
});