or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdauthorization.mdindex.md
tile.json

tessl/npm-keycloak-js

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/keycloak-js@26.2.x

To install, run

npx @tessl/cli install tessl/npm-keycloak-js@26.2.0

index.mddocs/

Keycloak JavaScript Client

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;
}