Using entersekt React Native SCA SDK

CustomerAuthn SDK by @entersekt

The CustomerAuthn SDK is an React Native Plugin developped by Enterskt that is used in conjunction with the CustomerAuthn API to enable strong customer authentication in your mobile apps.

Getting Started

To install the plugin you will need to setup NPM to be able to pull from the private registry.

Setting up Authentication

The React Native plugin is configured to pull in the native SDKs from Entersekt's release registry. The following environment variables need to be configured for the plugin to pull in these dependencies:

ENT_USERNAME - The username associated the deploy token. ENT_TOKEN - The deploy token generated for the project.

Once you have received your credentials from us, execute the following commands in your terminal:

export ENT_USERNAME=username
export ENT_TOKEN=token

You can also permanently export the variables by updating your ~/.bash_profile or ~/.zprofile.

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}

Installation

You can then add the plugin to your app via the CLI:

npm install @entersekt/react-native-customerauthn-sdk

Configuration

The customerauthn_config.json and a customerauthn_config.plist files are used to configure the Android and iOS SDKs respectively. These files contain fields that can be used to modify the configuration of the project (e.g. channelId).

Android

Add your customerauthn_config.json at the following location: android/app/src/main/res/raw/customerauthn.json.

To pull in the needed dependencies add GITLAB_MAVEN_URL = 'https://gitlab.com/api/v4/groups/12583526/-/packages/maven' to android/build.gradle and add the following snippet to android/app/build.gradle :

repositories {
    maven {
        url GITLAB_MAVEN_URL
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'Deploy-Token'
            value = System.getenv("ENT_TOKEN")
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

iOS

Add your customerauthn_config.plist in the following location: ios/customerauthn_config.plist.

To pull in dependencies via CocoaPods add the following line to your Podfile:

source 'https://' + ENV['ENT_USERNAME'] + ':' + ENV['ENT_TOKEN'] + 
'@gitlab.com/entersekt/repos/STR/saas-sdk/sdk-releases/ios-podspecs.git'

Using the SDK

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

import RNCustomerAuthnSDK from '@entersekt/react-native-customerauthn-sdk';

Initializing the SDK

Below is an example of creating and initializing the SDK:

useEffect(() => {
    const initializeSdk = async () => {
        await RNCustomerAuthnSDK.create();
        // Register your listeners here.
        await RNCustomerAuthnSDK.initialize();
    };
    initializeSdk();
    return RNCustomerAuthnSDK.removeAllListeners();
}, []);

The application can then listen to various events by setting the relevant listener. Below is an example of a Challenge event listener:

RNCustomerAuthnSDK.onChallengeCustomer((challenge: Challenge) => {
    // Display challenge here
});

Once imported, see the available API calls in RNCustomerAuthnSDK API methods.

Error Codes

The CustomerAuthn SDK can generate any of the Error Codes documented below.

Push Notifications

If a Challenge is received while the user's mobile application is closed, Push Notifications can be used to alert the user that a Challenge is pending.

Refer to the react-native-push-notification plugin on how to install it into your project: react-native-push-notification

API Methods

answerChallenge

answerChallenge(answerChallenge: ChallengeAnswer): Promise<void>

Used to send the answer to the Customer Challenge received on ChallengeCustomer

create

create(): Promise<void>

Creates a new instance of the CustomerAuthn SDK.

endpointPinError

endpointPinError(): void

Used to indicate to the SDK that the implementing application has not been able to capture the PIN code from the user, according to the constraints received as part of the EndpointPinListener event.

endpointPinSuccess

endpointPinSuccess(pin: string): void

Used to indicate to the SDK that the implementing application has successfully captured the PIN code from the user, according to the constraints received as part of the EndpointPinListener event.

getEndpointIDToken

getEndpointIDToken(): Promise<EndpointIDToken>

Used to request a new EndpointIDToken that can be included with other requests and validated server-side.

Example:

RNCustomerAuthnSDK.getEndpointIDToken()
    .then((token: EndpointIDToken) => {
        // Success
    })
    .catch((reason: string) => {
        // Failure
    });

getName

getName(): string

Get the name of the current application, used by React Native

getSDKInfo

getSDKInfo(): Promise<SdkInfo>

Used to get the SDK info such as SDK Version, underlying Transakt SDK version and EndpointID.

Example:

RNCustomerAuthnSDK.getSDKInfo()
    .then((info: SdkInfo) => {
        // Success
    })
    .catch((reason: string) => {
        // Failure
    });

getSDKName

getSDKName(): Promise<string>

Get the name of the current SDK, used by React Native.

handlePushMessage

handlePushMessage(pushMessage: PushMessage): Promise<PushMessageServiceResult>

Used to set the Push Notification details. This unique ID is used to enable push messaging.

handleUniversalLink

handleUniversalLink(request: UniversalLinkRequest): Promise<void>

Used to indicate that a universal link request had been received.

initialize

initialize(): Promise<void>

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

Example:

RNCustomerAuthnSDK.initialize()
    .then(() => {
        // Success
    })
    .catch((reason: string) => {
        // Failure
    });

joinInteraction

joinInteraction(joinInteractionRequest: JoinInteractionRequest): 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 mobile device.

Example:

RNCustomerAuthnSDK.joinInteraction(joinInteractionRequest) // The JoinInteractionRequest object for this request, containing Interaction data.
    .then(() => {
        // Success
    })
    .catch((reason: string) => {
        // Failure
    });

onChallengeCustomer

onChallengeCustomer(listener: (challenge: Challenge) => any): void

Used to add a listener to receive ChallengeCustomer events.

Example:

RNCustomerAuthnSDK.onChallengeCustomer((challenge => this.showChallenge(challenge)));
// The listener on which the operation result is returned.
showChallenge(challenge: Challenge){
    //show challenge
}

onInteractionCompleted

onInteractionCompleted(listener: (result: CustomerAuthnResult) => any): void

Used to add a listener to receive InteractionCompleted events.

Example:

RNCustomerAuthnSDK.onInteractionCompleted((result: CustomerAuthnResult) => this.showInteractionCompletedNotification(result));
// The listener on which the operation result is returned.
showInteractionCompletedNotification(result: CustomerAuthnResult){
    //show notify alert
}

onRequireBiometricAuthenticationFactor

onRequireBiometricAuthenticationFactor(listener: () => any): void

Used to add a listener to receive BiometricAuthenticationFactor authentication events.

Example:

RNCustomerAuthnSDK.onRequireBiometricAuthenticationFactor(() => this.showRequireBiometricPrompt());
// The listener on which the operation result is returned.
showSetBiometricPrompt() {
    // notify user biometric authentication is required
    RNCustomerAuthnSDK.proceedBiometricAuthenticationFactor()
}

onRequireEndpointPinAuthenticationFactor

onRequireEndpointPinAuthenticationFactor(listener: (pinProperties: PinProperties) => any): void

Used to add a listener to receive EndpointPinAuthenticationFactor PIN authentication events.

Example:

RNCustomerAuthnSDK.onRequireAuthenticationFactorEndpointPin((pinProperties => this.showRequireEndpointPinDialog(challenge)));
// The listener on which the operation result is returned.
showRequireEndpointPinDialog(pinProperties: PinProperties){
    //show require pin dialog
}

onSetBiometricAuthenticationFactor

onSetBiometricAuthenticationFactor(listener: () => any): void

Used to add a listener to receive BiometricAuthenticationFactor enrolment events.

Example:

RNCustomerAuthnSDK.onSetBiometricAuthenticationFactor(() => this.showSetBiometricPrompt());
// The listener on which the operation result is returned.
showSetBiometricPrompt() {
    // notify user biometric enrolment is required
    RNCustomerAuthnSDK.proceedBiometricAuthenticationFactor()
}

onSetEndpointPinAuthenticationFactor

onSetEndpointPinAuthenticationFactor(listener: (pinConstraints: PinConstraints) => any): void

Used to add a listener to receive EndpointPinAuthenticationFactor PIN enrolment events.

Example:

RNCustomerAuthnSDK.onSetAuthenticationFactorEndpointPin((pinConstraints => this.showSetEndpointPinDialog(challenge)));
// The listener on which the operation result is returned.
showSetEndpointPinDialog(pinConstraints: PinConstraints){
    //show set pin dialog
}

proceedBiometricAuthenticationFactor

proceedBiometricAuthenticationFactor(): void

Indicates that the SDK can proceed with the biometric enrolment or authentication.

proceedInteractionCompleted

proceedInteractionCompleted(): Promise<void>

Indicates that the SDK can proceed with the interaction completed response.

removeAllListeners

removeAllListeners(): void

Used to remove all event listeners that have been added.

setPushConfig

setPushConfig(pushConfig: PushConfig): Promise<void>

startInteraction

startInteraction(startInteractionRequest: StartInteractionRequest): Promise<void>

Used to indicate that a new interaction has been started. This is used when the interaction originates from the mobile device.

Example:

RNCustomerAuthnSDK.startInteraction(startInteractionRequest) // The StartInteractionRequest object for this request, containing Interaction data.
    .then(() => {
        // Success
    })
    .catch((reason: string) => {
        // Failure
    });