Vaave SSO SDK – Client-Side (Node.js)

This SDK helps you integrate Single Sign-On (SSO) with Vaave (or similar providers) in your Node.js application. It provides utilities to build SSO redirect URLs and decrypt SSO tokens.

This SDK supports both CommonJS and ES Modules, making it compatible with any Node.js project regardless of your module system preference.

1. Installation

Install the SDK in your project:

npm install vaave-sso-sdk

2. Building the SSO Redirect URL

Use buildSSORedirectURL to generate the URL to which you should redirect users for SSO login.

Parameter Reference

| Parameter | Type | Required | Description | |-----------------|----------|----------|---------------------------------------------------------------------------------------------------| | client_id | string | Yes | Provided by your SSO provider. | | redirect_url | string | No | Where to redirect after login. This domain should match the registered domain for Vaave SSO. | | server_domain | string | Yes | The SSO provider's login domain. | | token | string | Yes | The encrypted token received as a query parameter after SSO login. | | client_secret | string | Yes | The base64 symmetric key shared with you to decrypt the token. |

Note: The redirect_url is optional, but if provided, its domain must match the registered domain for Vaave SSO.

Example Usage

ES Modules (ESM):

import { buildSSORedirectURL } from 'vaave-sso-sdk';

CommonJS:

const { buildSSORedirectURL } = require('vaave-sso-sdk');

const params = { client_id: "abcdef", // Required redirect_url: "https://your-app.example.com/dashboard", // optional. server_domain: "login.example.com" // Required };

const result = buildSSORedirectURL(params);

if (result.success) { // Redirect the user to result.url console.log(result.url); } else { // Handle error console.error(result.message); }

**Example generated URL:**

https://login.example.com/sso/auth/abcdef

---

## 3. Handling the Redirect

After the user logs in, the SSO provider will redirect them to your provided `redirect_url` with a `token` query parameter.In case of error redirected with `error` query parameter. 

**Example:**

https://your-app.example.com/dashboard?token= https://your-app.example.com/dashboard?error=ERROR_CODE

---

## 4. Decrypting the SSO Token

Use `decryptSSOToken` to decrypt the token received after SSO login.

### Example Usage

**ES Modules (ESM):**
```js
import { decryptSSOToken } from 'vaave-sso-sdk';

CommonJS:

const { decryptSSOToken } = require('vaave-sso-sdk');

const token = "token_received_from_query_params"; const client_secret = "base64_symmetric_key_shared_with_you"; const result = await decryptSSOToken(token, client_secret);

if (result.success) { // result.details contains user information console.log(result.details); } else { // Handle error console.error(result.message); }

---

## 5. Error Codes

The SDK may return the following error codes in the `result.error` or `result.message` fields. Use these to handle errors gracefully in your application:

| Error Code                    | Description                                                                 |
|-------------------------------|-----------------------------------------------------------------------------|
| `ERROR_MISSING_FIELDS`        | Missing required fields in the SSO request.                                 |
| `ERROR_DOMAIN_MISMATCH`       | The domain in the redirect URL does not match the expected client domain.   |
| `ERROR_INVALID_SERVER_DOMAIN` | Invalid site ID: the server domain does not match the requested server domain.|
| `ERROR_USER_DATA`             | Failed to get user data or user data is invalid.                            |
| `ERROR_ENCRYPTION_FAILED`     | Failed to encrypt user data.                                                |

---

## 6. Required Setup Details (To Share with SSO Provider)

To configure SSO for your app, provide the following to your SSO provider:

- **Domain**: The domain from which you will initiate the SSO request.
  - Example: `your-app.example.com`
- **Redirect URL**: The full URL where users should be redirected after login. The SSO provider will append a token to this URL.
  - Example: `https://your-app.example.com/dashboard`

---

## 7. After Setup

Once you provide the above:
- You will receive a symmetric key (base64) to decrypt the token.
- You will receive a client ID to use in your SSO requests.

---

## Example Files

- See `examples/ssoUrlBuild.js` for an example of building the SSO redirect URL.
- See `examples/decrypt.js` for an example of decrypting the SSO token.

---

## License

ISC