tessl/npm-keycloak-js

JavaScript adapter for Keycloak providing OpenID Connect authentication and UMA authorization for web applications.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Keycloak JavaScript Client

Name: tessl/npm-keycloak-js
Author: tessl

The Keycloak JavaScript client library provides seamless integration between web applications and Keycloak authentication servers. It supports OpenID Connect, Single Sign-On (SSO), OAuth2 authentication flows, and fine-grained authorization through User-Managed Access (UMA) policies.

Package Information

Package Name: keycloak-js
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install keycloak-js

Core Imports

import Keycloak from "keycloak-js";
import KeycloakAuthorization from "keycloak-js/keycloak-authz";

For CommonJS:

const Keycloak = require("keycloak-js");
const KeycloakAuthorization = require("keycloak-js/keycloak-authz");

Basic Usage

import Keycloak from "keycloak-js";

// Initialize Keycloak instance
const keycloak = new Keycloak({
  url: "http://keycloak-server",
  realm: "my-realm", 
  clientId: "my-app"
});

// Initialize authentication
async function initAuth() {
  try {
    const authenticated = await keycloak.init({
      onLoad: "check-sso",
      pkceMethod: "S256",
      responseMode: "query"
    });
    
    if (authenticated) {
      console.log("User is authenticated");
      console.log("Access token:", keycloak.token);
    } else {
      console.log("User is not authenticated");
    }
  } catch (error) {
    console.error("Authentication initialization failed:", error);
  }
}

// Start authentication process
initAuth();

Architecture

The Keycloak JavaScript client is built around several key components:

Authentication Core: Main Keycloak class handling login, logout, and token management
Token Management: Automatic token refresh, validation, and storage
Event System: Callback-based architecture for authentication lifecycle events
Authorization Extension: Separate KeycloakAuthorization class for UMA and policy enforcement
Multi-Protocol Support: OpenID Connect, OAuth2, and OAuth flows
Browser Integration: Seamless integration with browser authentication flows

Capabilities

Authentication and Session Management

Core authentication functionality including login, logout, token management, and session handling. Essential for any application requiring user authentication through Keycloak.

/**
 * Main Keycloak authentication client
 */
class Keycloak {
  constructor(config?: KeycloakConfig);
  
  // Authentication methods
  init(options?: KeycloakInitOptions): Promise<boolean>;
  login(options?: KeycloakLoginOptions): Promise<void>;
  logout(options?: KeycloakLogoutOptions): Promise<void>;
  register(options?: KeycloakRegisterOptions): Promise<void>;
  accountManagement(options?: KeycloakAccountOptions): Promise<void>;
  
  // Token management
  updateToken(minValidity?: number): Promise<boolean>;
  isTokenExpired(minValidity?: number): boolean;
  clearToken(): void;
  
  // User information
  loadUserInfo(): Promise<any>;
  loadUserProfile(): Promise<KeycloakProfile>;
  
  // Role checking
  hasRealmRole(role: string): boolean;
  hasResourceRole(role: string, resource?: string): boolean;
  
  // URL generation
  createLoginUrl(options?: KeycloakLoginOptions): string;
  createLogoutUrl(options?: KeycloakLogoutOptions): string;
  createRegisterUrl(options?: KeycloakRegisterOptions): string;
  createAccountUrl(options?: KeycloakAccountOptions): string;
  
  // Properties
  authenticated?: boolean;
  token?: string;
  refreshToken?: string;
  idToken?: string;
  tokenParsed?: KeycloakTokenParsed;
  idTokenParsed?: KeycloakTokenParsed;
  subject?: string;
  realmAccess?: KeycloakRoles;
  resourceAccess?: KeycloakResourceAccess;
  timeSkew?: number;
  
  // Event handlers
  onReady?: (authenticated: boolean) => void;
  onAuthSuccess?: () => void;
  onAuthError?: (errorData: KeycloakError) => void;
  onAuthRefreshSuccess?: () => void;
  onAuthRefreshError?: () => void;
  onAuthLogout?: () => void;
  onTokenExpired?: () => void;
}

Authentication and Session Management

Authorization and Policy Enforcement

User-Managed Access (UMA) and policy enforcement capabilities for fine-grained authorization. Enables applications to obtain permissions and enforce access control policies.

/**
 * Authorization client for UMA and policy enforcement
 */
class KeycloakAuthorization {
  constructor(keycloak: Keycloak);
  
  init(): Promise<void>; // deprecated
  authorize(request?: AuthorizationRequest): Promise<string>;
  entitlement(resourceServerId: string, request?: AuthorizationRequest): Promise<string>;
  
  // Properties  
  rpt?: string;
  config?: { rpt_endpoint: string };
}

Authorization and Policy Enforcement

Core Types

interface KeycloakConfig {
  url: string;
  realm: string;
  clientId: string;
}

interface KeycloakInitOptions {
  onLoad?: "login-required" | "check-sso";
  token?: string;
  refreshToken?: string;
  idToken?: string;
  checkLoginIframe?: boolean;
  checkLoginIframeInterval?: number;
  responseMode?: "query" | "fragment";
  redirectUri?: string;
  silentCheckSsoRedirectUri?: string;
  flow?: "standard" | "implicit" | "hybrid";
  scope?: string;
  timeSkew?: number;
  useNonce?: boolean;
  adapter?: "default" | "cordova" | "cordova-native";
  messageReceiveTimeout?: number;
  pkceMethod?: "S256";
  enableLogging?: boolean;
}

interface KeycloakLoginOptions {
  redirectUri?: string;
  scope?: string;
  locale?: string;
  idpHint?: string;
  loginHint?: string;
  action?: string;
}

interface KeycloakLogoutOptions {
  redirectUri?: string;
}

interface KeycloakRegisterOptions {
  redirectUri?: string;
  locale?: string;
}

interface KeycloakAccountOptions {
  redirectUri?: string;
}

interface KeycloakProfile {
  id?: string;
  username?: string;
  email?: string;
  firstName?: string;
  lastName?: string;
  enabled?: boolean;
  emailVerified?: boolean;
  totp?: boolean;
  createdTimestamp?: number;
  attributes?: { [key: string]: string[] };
}

interface KeycloakTokenParsed {
  exp?: number;
  iat?: number;
  auth_time?: number;
  jti?: string;
  iss?: string;
  aud?: string | string[];
  sub?: string;
  typ?: string;
  azp?: string;
  session_state?: string;
  realm_access?: KeycloakRoles;
  resource_access?: KeycloakResourceAccess;
  [key: string]: any;
}

interface KeycloakRoles {
  roles: string[];
}

interface KeycloakResourceAccess {
  [key: string]: KeycloakRoles;
}

interface KeycloakError {
  error: string;
  error_description?: string;
}

interface AuthorizationRequest {
  ticket?: string;
  tickets?: string[];
  permissions?: ResourcePermission[];
  metadata?: AuthorizationMetadata;
  submit_request?: boolean;
  incrementalAuthorization?: boolean;
  submitterId?: string;
  claimToken?: string;
  claimTokenFormat?: string;
}

interface ResourcePermission {
  id?: string;
  name?: string;
  scopes?: string[];
}

interface AuthorizationMetadata {
  response_include_resource_name?: boolean;
  response_permissions_limit?: number;
}