@connectivenetwork/sso-sdk

connective SSO SDK for Single Sign-On authentication integration.

Installation

npm install @connectivenetwork/sso-sdk

Usage

Initialize Client

For SSO Tokensite Flow (Carii API):

import { SSOClient } from '@connectivenetwork/sso-sdk';

// No config required - uses default Carii API
const client = new SSOClient();

// Or with custom API URL:
const client = new SSOClient({
  cariiApiUrl: 'https://api.dev.carii.pro'
});

For OAuth2 PKCE Flow:

import { SSOClient } from '@connectivenetwork/sso-sdk';

const client = new SSOClient({
  baseUrl: 'https://auth.connective.id',
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  timeout: 30000, // optional, default 30s
});

SSO Tokensite Flow (Carii API Integration)

Flow for Carii SSO integration. Encrypts user data and sends to Carii API to get redirect URL.

import { SSOClient, SSOInitPayload } from '@connectivenetwork/sso-sdk';

const client = new SSOClient();

// 1. Prepare payload data
const payload: SSOInitPayload = {
  email: '[email protected]',
  fullname: 'John Doe',
  membershipTypeName: 'Corporate Team', // Membership type (required for multi tier membership)
  domain: 'your-domain.com',        // Domain of website using this SDK
  tokenWebsite: 'token-from-carii', // Token provided by Carii
};

// 2. Initiate SSO - encrypt and call Carii API
const secretKey = 'token-from-carii'; // Token provided by Carii
const response = await client.initiateSSO(payload, secretKey);

// Example response:
// {
//   "redirectUrl": "https://sso.carii.pro/auth?session=abc123&callback=https://your-app.com/callback",
//   "sessionId": "sess_123456789",
//   "expiresAt": "2024-01-15T10:30:00Z"
// }

// 3. Redirect to the URL returned by Carii API
window.location.href = response.redirectUrl;

Verify Callback Response

When Carii redirects back to your domain with a tokensite parameter:

// After Carii redirects back to your callback URL
const callbackUrl = window.location.href;
// e.g., https://your-app.com/callback?tokensite=encrypted_data

try {
  const result = client.parseSSOCallback(callbackUrl, secretKey);
  console.log('Decrypted payload:', result.decryptedPayload);
  // { email, fullname, domain, tokenWebsite, timestamp }
} catch (error) {
  // Handle invalid/expired tokensite
}

Authentication Flow with PKCE (OAuth2 Standard)

// 1. Generate PKCE challenge
const pkceChallenge = client.generatePKCEChallenge();

// 2. Save codeVerifier for later use (session storage)
sessionStorage.setItem('codeVerifier', pkceChallenge.codeVerifier);

// 3. Create authorization URL
const state = crypto.randomUUID();
const authUrl = client.getAuthorizationUrl(state, pkceChallenge);

// 4. Redirect user to login page
window.location.href = authUrl;

Exchange Authorization Code

// After user returns from login page with code
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const codeVerifier = sessionStorage.getItem('codeVerifier');

if (code && codeVerifier) {
  const tokens = await client.exchangeCodeForTokens(code, codeVerifier);
  // Store tokens
  localStorage.setItem('accessToken', tokens.access_token);
  localStorage.setItem('refreshToken', tokens.refresh_token);
}

Get User Info

const userInfo = await client.getUserInfo(accessToken);
console.log(userInfo.email, userInfo.name);

Refresh Token

const newTokens = await client.refreshToken(refreshToken);

Revoke Token

await client.revokeToken(refreshToken);

API Reference

SSOClient

Constructor

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | baseUrl | string | No* | Base URL for OAuth2 (required for OAuth2 flow) | | clientId | string | No | Client ID (required for OAuth2 flow) | | clientSecret | string | No | Client Secret (server-side only) | | redirectUri | string | No | OAuth callback URI (*required for OAuth2 flow) | | cariiApiUrl | string | No | Carii API URL (default: https://api.dev.carii.pro) | | timeout | number | No | Request timeout in ms (default: 30000) |

Methods

OAuth2/PKCE Methods:

• generatePKCEChallenge() - Generate PKCE challenge
• getAuthorizationUrl(state, pkceChallenge?, scopes?) - Build authorization URL
• exchangeCodeForTokens(code, codeVerifier?) - Exchange code for tokens
• refreshToken(refreshToken) - Refresh access token
• getUserInfo(accessToken) - Get user information
• revokeToken(token, tokenTypeHint?) - Revoke token

SSO Tokensite Methods:

• initiateSSO(payload, secretKey) - Encrypt payload, call Carii API, get redirect URL
• encryptTokensite(payload, secretKey) - Encrypt SSO payload to tokensite
• buildSSOCallbackUrl(baseUrl, payload, secretKey) - Build callback URL with encrypted tokensite
• decryptTokensite(tokensite, secretKey) - Decrypt tokensite to payload
• parseSSOCallback(callbackUrl, secretKey) - Parse callback URL and decrypt tokensite

Error Handling

This SDK provides several custom error classes:

• SSOError - Base error class
• AuthenticationError - Authentication failed
• TokenError - Token related errors
• NetworkError - Network request errors
• ValidationError - Validation errors

import { AuthenticationError, TokenError } from '@connectivenetwork/sso-sdk';

try {
  const user = await client.getUserInfo(token);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle authentication error
  } else if (error instanceof TokenError) {
    // Handle token error
  }
}