SSO Keycloak Utils

A comprehensive, framework-agnostic SSO client library for Keycloak integration with React hooks and Vue composables.

Features

🔐 Framework Agnostic: Core library works with any JavaScript/TypeScript framework
⚛️ React Integration: Custom hooks for easy React integration
🟢 Vue Integration: Composables for Vue 3 applications
🔄 Auto Token Refresh: Automatic token refresh with retry mechanisms
🌐 HTTP Client: Authenticated HTTP client with automatic token management
🛡️ Route Protection: Utilities for protecting routes and components
📝 TypeScript Support: Full TypeScript support with comprehensive type definitions
🎯 Error Handling: Custom error classes and comprehensive error handling
📊 Logging: Configurable logging system
✅ Configuration Validation: Runtime configuration validation

Installation

npm install sso-keycloak-utils

Quick Start

1. Initialize Keycloak

import { initializeKeycloak } from 'sso-keycloak-utils';

const keycloakConfig = {
  url: 'https://your-keycloak-server/auth',
  realm: 'your-realm',
  clientId: 'your-client-id',
};

await initializeKeycloak(keycloakConfig);

2. React Usage

import { useKeycloak, useKeycloakAuth } from 'sso-keycloak-utils/react';

function App() {
  const { isAuthenticated, user, login, logout } = useKeycloak();
  const { hasRole, hasPermission } = useKeycloakAuth();

  if (!isAuthenticated) {
    return <button onClick={login}>Login</button>;
  }

  return (
    <div>
      <h1>Welcome, {user?.name}!</h1>
      {hasRole('admin') && <AdminPanel />}
      <button onClick={logout}>Logout</button>
    </div>
  );
}

3. Vue Usage

import { useKeycloak, useKeycloakAuth } from 'sso-keycloak-utils/vue';

export default {
  setup() {
    const { isAuthenticated, user, login, logout } = useKeycloak();
    const { hasRole, hasPermission } = useKeycloakAuth();

    return {
      isAuthenticated,
      user,
      login,
      logout,
      hasRole,
      hasPermission,
    };
  },
};

Core Features

Authentication

import { login, logout, silentCheckSSO } from 'sso-keycloak-utils';

// Login
await login();

// Logout
await logout();

// Silent check SSO
const isAuthenticated = await silentCheckSSO();

Token Management

import { getToken, refreshToken, getTokenExpiration } from 'sso-keycloak-utils';

// Get current token
const token = getToken();

// Refresh token
await refreshToken();

// Check token expiration
const expiresAt = getTokenExpiration();

Auto Token Refresh

import { setupAutoTokenRefresh } from 'sso-keycloak-utils';

const cleanup = setupAutoTokenRefresh({
  minValidity: 60,
  checkInterval: 30000,
  onTokenExpired: () => {
    // Handle token expiration
  },
});

// Cleanup when done
cleanup();

HTTP Client

import { createAuthenticatedClient } from 'sso-keycloak-utils';

const client = createAuthenticatedClient({
  baseURL: 'https://api.example.com',
  timeout: 10000,
});

// Make authenticated requests
const data = await client.get('/protected-endpoint');

API Reference

Core Functions

initializeKeycloak(config) - Initialize Keycloak client
login(options?) - Initiate login flow
logout(options?) - Logout user
silentCheckSSO() - Check SSO status silently
getToken() - Get current access token
refreshToken(minValidity?) - Refresh access token
getUserInfo() - Get current user information

React Hooks

useKeycloak() - Main authentication hook
useKeycloakAuth() - Authorization and permissions hook
useKeycloakUser() - User information hook

Vue Composables

useKeycloak() - Main authentication composable
useKeycloakAuth() - Authorization and permissions composable
useKeycloakUser() - User information composable

Utilities

setupAutoTokenRefresh(config) - Auto token refresh
createAuthenticatedClient(config) - Authenticated HTTP client
protectRoute(Component, options) - Route protection
hasRole(role) - Check user role
hasPermission(permission) - Check user permission

Configuration

Keycloak Configuration

interface KeycloakConfig {
  url: string;
  realm: string;
  clientId: string;
  redirectUri?: string;
  silentCheckRedirectUri?: string;
  enableLogging?: boolean;
  checkLoginIframe?: boolean;
  checkLoginIframeInterval?: number;
  responseMode?: 'query' | 'fragment';
  flow?: 'standard' | 'implicit' | 'hybrid';
  pkceMethod?: 'S256';
  enableBearerInterceptor?: boolean;
  bearerPrefix?: string;
  bearerExcludedUrls?: string[];
}

Auto Refresh Configuration

interface AutoRefreshConfig {
  minValidity?: number;
  checkInterval?: number;
  onTokenExpired?: () => void;
  onRefreshError?: (error: Error) => void;
}

Error Handling

The library provides custom error classes:

import {
  KeycloakError,
  AuthenticationError,
  TokenError,
  ConfigurationError,
} from 'sso-keycloak-utils';

try {
  await login();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  }
}

Logging

Configure logging levels:

import { setLogLevel } from 'sso-keycloak-utils';

setLogLevel('debug'); // 'error', 'warn', 'info', 'debug'

Contributing

For contributions, please contact the package maintainer.

License

MIT License - see LICENSE file for details.

Support

For support and questions:

Create an issue in the repository
Contact the package maintainer
Check the documentation for common issues

Package detail

sso-keycloak-utils

readme