@haventec/native-ux-adapter-sdk

Haventec Native UX Adapter Node.js SDK

Your backend service can use this SDK to authenticate users into the Haventec Identity Platform.

This project contains a demo app explained in the section "Demo app" on this README file.

Requirements

• Node.js

• Typescript (tsc) : version 4.1.5

Type the following command to install tsc as a dev dependency.

npm install --save-dev typescript@4.1.5

Installation

Add to your file package.json the following dependency:

npm install @haventec/native-ux-adapter-nodejs-sdk@1.0.0

and run "npm install"

Usage

Instantiate the class "HaventecOidc" with your environment variables at your platform:

Note: Please refer to the keycloak documentation: https://docs.haventec.com/docs/authenticate/v1.2/integrations/keycloak-iam to understand how to create the realm, idp and idp alias.

• iam.base.url: The URL of the Identity Access Management (IAM). Demo Haventec IAM is at:
  • https://iam.demo.haventec.com/auth and production is at:
  • https://iam.haventec.com/auth
• iam.realm: The name of your Realm at the Haventec IAM e.g. xyzCorp
• iam.client: The ID of the OpenID Client configured at your realm
• iam.base.url: The URI where users are usually redirected upon a successful login, but the whole OpenID Connect flow is handled by the SDK and won't do any redirect. You only need to make sure that this same value is whitelisted at the OpenID Client configuration at your Realm.
• haventec.app.client.id: The client ID of the application in Haventec Console. e.g.: 13f9d956-9bcc-447f-b7c1-7719cb53901d

and then you can start using any of the methods within the SDK: (Please see a description of the request/response parameters below in a table)

• registerUserOrDevice: Register a new user or device and send an activation token to the user via mobile. RegistrationRequest:

  mobileNumber : string;
  clientId : string;
  

  RegistrationResponse:

  registrationUuid : string;
  registrationSession : string;
  nextAction : string;
  

• validateChallenge: Validate the challenge (OTP) for either mobile or email in the multistep registration flow.

  ChallengeRequest:

  otpValue : string;
  clientId : string;
  registrationSession : string;
  registrationUuid : string;
  

  ChallengeResponse:

  otpCorrect : boolean;
  nextAction : string;
  

• resendRegistrationChallenge: Resend the challenge (OTP) for either mobile or email in the multistep registration flow.

  ResendRegistrationChallengeRequest:

  clientId : string;
  registrationSession : string;
  registrationUuid : string;
  

  ResendRegistrationChallengeResponse:

  nextAction : string;
  

• updateRegistrationWithEmail: Update email in the registration flow after mobile is verified for a user registration only.

  EmailRegistrationRequest:

  clientId : string;
  email : string;
  registrationUuid : string;
  registrationSession : string;
  

  EmailRegistrationResponse:

  nextAction : string;
  

• activateUserOrDevice: Activate a new user or device if both the steps are verified in the multistep registration flow. ActivationRequest:

  clientId         : string;
  registrationUuid : string;
  activationToken  : string; 
  hashedPin        : string; 
  

  IamAccessToken

  deviceUuid : string;
  authKey    : string;
  iamUserJwt : string; 
  iamIdToken : string;
  

• loginPinDevice: Login a user's device with single-step multi-factor authentication. LoginPinDeviceRequest:

  username  : string;
  hashedPin : string;
  clientId  : string;
  authKey   : string;
  deviceUuid: string;
  

  IamAccessToken

  authKey    : string;
  iamUserJwt : string;
  iamIdToken : string;
  

• forgotPin: It triggers a forgot PIN request for a user's device and the user will receive a challenge via mobile to reset the PIN. ForgotPinRequest

  username   : string;
  clientId   : string;
  

  ForgotPinResponse

  requestUuid   : string;
  requestSession : string;
  nextAction   : string;
  

• forgotPinValidateChallenge: Validate the challenge (OTP) for either mobile or email in the forgot pin flow. ForgotPinChallengeRequest

  otpValue   : string;
  clientId   : string;
  requestSession   : string;
  requestUuid   : string;
  

  ChallengeResponse

  nextAction   : string;
  otpCorrect : boolean;
  

• forgotPinResendChallenge: Resend the challenge (OTP) for either to mobile or email in the forgot pin flow. ForgotPinResendChallengeRequest

  clientId   : string;
  requestSession   : string;
  requestUuid   : string;
  

  ForgotPinResendChallengeResponse

  nextAction   : string;
  

• resetPin: It resets the PIN of a user's device if both the steps are verified in the multistep forgot pin flow. ResetPinRequest

  clientId   : string;
  deviceUuid : string;
  hashedPin  : string;
  requestSession  : string;
  requestUuid  : string;
  

  IamAccessToken

  deviceUuid : string; // (Not returned with this method)
  authKey    : string;
  iamUserJwt : string;
  iamIdToken : string;
  

• logout: It logs out a user's session. LogoutRequest

  idToken : string;
  

Parameter descriptions

Parameter name	Description
clientId	UUID that you can find in the Application details page at Haventec Console, under the section "Authentication Protocol"
username	User's email address
hashedPin	Hashed PIN using methods at the iOS (https://github.com/Haventec/authenticate-ios-sdk), Android (https://github.com/Haventec/authenticate-android-sdk) or Web Haventec SDKs (https://github.com/Haventec/authenticate-web-sdk)
registrationUuid	UUID to identify the registration and activation of users or devices.
registrationSession	128 bit session id to maintain multistep flow for registration and activation of users or devices.
requestUuid	UUID to identify the forgot pin and reset pin of user's device.
requestSession	128 bit session id to maintain multistep flow for forgot pin and reset pin of user's device.
otpValue	One time password sent to the user via email or mobile.
nextAction	Indicates the next step to be taken in a multistep registration or forgot pin flow.
authKey	Crypto string required for the login algorithm. It rotates on each successful login, reset PIN or device/user activation.
iamUserJwt	Access token generated by the IAM
iamIdToken	ID token generated by the IAM
deviceUuid	UUID to identify a logical Haventec device
resetToken	Token sent to the user via email to reset their device PIN

Demo app

The demo app guides you to sign up and authenticate users to demonstrate the different user flows.

1. Access the demo folder and create a personal config.properties file based on the template:

cd demo
cp config.properties.template config.properties

2. Fill in the environment variables described on the previous section.

3. Run the demo

npm run-script demo1

License

This code is available under the MIT license. A copy of the license can be found in the LICENSE file included with the distribution.