@saxess-pro/client-auth SDK

The official Node.js SDK for integrating with the Saxess OIDC CIBA Authentication server.

Installation

npm i @saxess-pro/client-auth

Usage

1. Initialization
   Initialize the client with your credentials. It is recommended to load the private key from a secure location or environment variable.

const { SaxessProAuth,  AuthorizationType, AuthorizationPurpose, AuthorizationAction, DeviceBinding } = require("@saxess-pro/client-auth");
const fs = require("fs");

const config = {
  authServerUrl: process.env.AUTH_SERVER_URL,
  clientId: process.env.CLIENT_ID,
  clientName: process.env.CLIENT_NAME, 
  privateKey: fs.readFileSync("./private_key.pem", "utf8"),
};

const sdk = new SaxessProAuth(config);

2. Start Authentication
   Initiate the CIBA flow by providing the user's email.

const auth = await sdk.startAuthentication({
  email: "[email protected]",
  authorizationDetails: {
        type: AuthorizationType.BIOMETRIC_ASSERTION,
        purpose: AuthorizationPurpose.SECURE_LOGIN,
        actions: [AuthorizationAction.AUTHENTICATE],
        deviceBinding: DeviceBinding.NFC_CARD,
  }
});

console.log("Auth Request ID:", auth.authReqId);
console.log("Poll Interval:", auth.interval);

3. Poll for Status
   Check if the user has completed the authentication on their device.

const result = await sdk.pollAuthentication(auth.authReqId);

if (result.status === "AUTHENTICATED") {
  console.log("Access Token:", result.tokens.accessToken);
  
  // Verify and decode the ID Token
  const user = await sdk.verifyIdToken(result.tokens.idToken);
  console.log("Verified User:", user.email);
}

4. Refresh Tokens
   Rotate your access tokens using a refresh token.

const refreshed = await sdk.refreshTokens(result.tokens.refreshToken);
console.log("New Access Token:", refreshed.accessToken);

Security Features

1. JWS Signing:
   Automatically generates RS256 signed client assertions for all requests.

2. Request Objects:
   Encapsulates CIBA parameters in a signed JWT to ensure integrity.

3. PASETO Verification:
   Native support for verifying V2 PASETO ID tokens with JWKS public key fetching and local caching.

API Reference

Method | Parameters | Description ------------ | ------------ | ------------ startAuthentication | StartAuthInput | Initiates the CIBA authorize request. pollAuthentication | authReqId: string | Checks the status of a pending request. verifyIdToken | idToken: string | Verifies a PASETO token and returns the payload. refreshTokens | refreshToken: string | Exchanges a refresh token for new credentials.

Try the SDK locally

You can try the SDK by cloning the repository and running the example script.

git clone https://github.com/himanshu-serenity/saxess-pro-sdk
cd saxess-pro-sdk
npm install

Generate a private key : openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.key

Create a .env file:

   PORT=4000
   AUTH_SERVER_URL=https://pro-be.s.technology/api
   CLIENT_ID=***
   CLIENT_NAME=***
   PRIVATE_KEY_PATH=./private.key

Run the example: 

npx ts-node examples/try-sdk.ts