ccci-campus-sso

A lightweight, zero-dependency TypeScript utility for SSO (Single Sign-On) integration. Handles redirection URL resolution, access token exchange via a handshake endpoint, and JWT payload decoding. Fully compatible with browsers and Node.js 16+.

Installation

npm install ccci-campus-sso

yarn add ccci-campus-sso

pnpm add ccci-campus-sso

Node.js note: fetch is available natively from Node.js 18+. For Node.js 16–17, use a polyfill such as node-fetch.

API

getRedirectionUrl(payload)

Fetches the SSO redirection URL for a given application. Typically used to redirect a user to the SSO login page.

const result = await getRedirectionUrl({
    ssoURL: 'https://sso.example.com',
    appId: 'my-app',
});

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | ssoURL | string | ✅ | Base URL of the SSO server | | appId | string | ✅ | Application identifier, sent as referer query param | | path | string | ❌ | Override the default path /iam/v1.0/client/redirect |

Returns: Promise<unknown> — the parsed JSON response from the SSO server.

Throws: if ssoURL or appId are missing, or if the server returns a non-2xx response.

requestAccessToken(payload)

Exchanges an existing access token for a short-lived session token via the SSO handshake endpoint. Call this after authenticating to obtain a token your app can use for further requests.

const sessionToken = await requestAccessToken({
    ssoURL: 'https://sso.example.com',
    appId: 'my-app',
    accessToken: 'eyJhbGciOiJSUzI1NiJ9...',
});

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | ssoURL | string | ✅ | Base URL of the SSO server | | appId | string | ✅ | Application identifier, sent as referer header | | accessToken | string | ✅ | The access token to exchange | | username | string | ❌ | Defaults to 'cl13nt' if not provided | | path | string | ❌ | Override the default path /management/v1.0/auth/handshake/token |

Returns: Promise<string> — the session token string from response.data.token.

Throws: if required fields are missing, the server returns a non-2xx response, or data.token is absent from the response body.

getAccessData(accessToken)

Decodes the payload segment of a JWT access token without verifying its signature. Useful for reading claims such as sub, exp, roles, etc. on the client side.

const payload = getAccessData('eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyMSJ9...');
console.log(payload?.sub); // 'user1'

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | accessToken | string | ✅ | A JWT string in header.payload.signature format |

Returns: Record<string, unknown> | null — the decoded payload object, or null if decoding fails.

⚠️ Security note: This function does not verify the token's signature. Never use decoded claims to make trust decisions — always validate tokens server-side.

Defaults

These path defaults are used when no path override is provided:

| Constant | Value | |----------|-------| | Redirect path | /iam/v1.0/client/redirect | | Handshake path | /management/v1.0/auth/handshake/token | | Default username | cl13nt |

Error Handling

All async functions throw descriptive Error instances on failure. Errors include the function name, HTTP status code, and response body where available.

try {
    const token = await requestAccessToken({ ssoURL, appId, accessToken });
} catch (err) {
    // e.g. "[requestAccessToken] HTTP 401 Unauthorized: invalid token"
    console.error(err.message);
}

getAccessData never throws — it returns null on failure and logs a warning via console.warn.

Browser & Runtime Compatibility

| Feature | Browser | Node.js | |---------|---------|---------| | fetch | All modern browsers | 18+ (native), 16–17 (polyfill needed) | | atob | All modern browsers | 16+ | | TypeScript | Via bundler (Vite, webpack, etc.) | Via ts-node or tsc |

No Buffer, no crypto, no Node.js built-ins — safe for direct use in any browser-targeted bundle.

Usage Example

import { getRedirectionUrl, requestAccessToken, getAccessData } from 'ccci-campus-sso';

const SSO_URL = 'https://sso.example.com';
const APP_ID  = 'my-app';

// 1. Get the login redirect URL
const redirect = await getRedirectionUrl({ ssoURL: SSO_URL, appId: APP_ID });

// 2. After the user authenticates, exchange the access token
const sessionToken = await requestAccessToken({
    ssoURL: SSO_URL,
    appId: APP_ID,
    accessToken: redirect.accessToken,
});

// 3. Inspect the token claims (client-side only — do not trust without server validation)
const claims = getAccessData(sessionToken);
console.log('Expires at:', new Date((claims?.exp as number) * 1000));