# 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](https://nodejs.org/en/)

* 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.