or run

npx @tessl/cli init

tessl/npm-keycloak--keycloak-admin-client

A comprehensive TypeScript client library for interacting with Keycloak's Administration API.

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 4 months ago
Describes: pkg:npm/@keycloak/keycloak-admin-client@26.3.x

To install, run

npx @tessl/cli install tessl/npm-keycloak--keycloak-admin-client@26.3.0

Keycloak Admin Client

Keycloak Admin Client is a comprehensive TypeScript library that provides a type-safe API for interacting with Keycloak's Administration API. It enables developers to programmatically manage realms, users, groups, roles, clients, and authentication policies with full TypeScript support and automatic token management.

Package Information

Package Name: @keycloak/keycloak-admin-client
Package Type: npm
Language: TypeScript
Installation: npm install @keycloak/keycloak-admin-client

Core Imports

import KeycloakAdminClient from "@keycloak/keycloak-admin-client";
import { requiredAction, NetworkError } from "@keycloak/keycloak-admin-client";

For CommonJS:

const KeycloakAdminClient = require("@keycloak/keycloak-admin-client").default;
const { requiredAction, NetworkError } = require("@keycloak/keycloak-admin-client");

Basic Usage

import KeycloakAdminClient from "@keycloak/keycloak-admin-client";

// Initialize client
const kcAdminClient = new KeycloakAdminClient({
  baseUrl: 'http://localhost:8080',
  realmName: 'master',
});

// Authenticate with password grant
await kcAdminClient.auth({
  username: 'admin',
  password: 'admin',
  grantType: 'password',
  clientId: 'admin-cli',
});

// Create a user
const { id } = await kcAdminClient.users.create({
  username: 'newuser',
  email: 'newuser@example.com',
  enabled: true,
});

// Find users
const users = await kcAdminClient.users.find({ max: 10 });

// Create a client
const client = await kcAdminClient.clients.create({
  clientId: 'my-client',
  enabled: true,
  publicClient: false,
});

Architecture

Keycloak Admin Client is built around several key components:

KeycloakAdminClient Class: Main client class that manages authentication and provides access to all resource endpoints
Resource Classes: Specialized classes for each API area (Users, Clients, Realms, etc.) that handle HTTP operations
Authentication System: Flexible authentication supporting multiple grant types and token providers
Type System: Complete TypeScript definitions for all Keycloak entities and API parameters
Error Handling: Custom NetworkError class with detailed response information
Agent Infrastructure: Base HTTP client with automatic URL templating and query parameter handling

Capabilities

Client Configuration

Core client setup, authentication flows, and token management for connecting to Keycloak Admin API.

class KeycloakAdminClient {
  // Resource properties
  users: Users;
  userStorageProvider: UserStorageProvider;
  groups: Groups;
  roles: Roles;
  organizations: Organizations;
  clients: Clients;
  realms: Realms;
  clientScopes: ClientScopes;
  clientPolicies: ClientPolicies;
  identityProviders: IdentityProviders;
  components: Components;
  serverInfo: ServerInfo;
  whoAmI: WhoAmI;
  attackDetection: AttackDetection;
  authenticationManagement: AuthenticationManagement;
  cache: Cache;

  constructor(connectionConfig?: ConnectionConfig);
  
  async auth(credentials: Credentials): Promise<void>;
  registerTokenProvider(provider: TokenProvider): void;
  setAccessToken(token: string): void;
  async getAccessToken(): Promise<string | undefined>;
  setConfig(connectionConfig: ConnectionConfig): void;
}

interface ConnectionConfig {
  baseUrl?: string;
  realmName?: string;
  requestOptions?: RequestInit;
  requestArgOptions?: Pick<RequestArgs, "catchNotFound">;
}

Client Configuration

User Management

Complete user lifecycle management including creation, updates, role assignments, group membership, credential management, and session handling.

interface Users {
  find(query?: UserQuery): Promise<UserRepresentation[]>;
  create(user: UserRepresentation): Promise<{ id: string }>;
  findOne(params: { id: string; userProfileMetadata?: boolean }): Promise<UserRepresentation | undefined>;
  update(query: { id: string }, user: UserRepresentation): Promise<void>;
  del(params: { id: string }): Promise<void>;
  
  // Role mappings
  addRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;
  listRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
  
  // Group management
  addToGroup(params: { id: string; groupId: string }): Promise<string>;
  listGroups(params: { id: string } & PaginationQuery): Promise<GroupRepresentation[]>;
}

User Management

Client Management

OAuth/OIDC client configuration, authorization services, client roles, protocol mappers, and client policy management.

interface Clients {
  find(query?: ClientQuery): Promise<ClientRepresentation[]>;
  create(client: ClientRepresentation): Promise<{ id: string }>;
  findOne(params: { id: string }): Promise<ClientRepresentation | undefined>;
  update(query: { id: string }, client: ClientRepresentation): Promise<void>;
  del(params: { id: string }): Promise<void>;
  
  // Client roles
  createRole(params: { id: string }, role: RoleRepresentation): Promise<{ roleName: string }>;
  listRoles(params: { id: string }): Promise<RoleRepresentation[]>;
  
  // Authorization services
  listResources(params: { id: string }, query?: ResourceQuery): Promise<ResourceRepresentation[]>;
  createResource(params: { id: string }, resource: ResourceRepresentation): Promise<ResourceRepresentation>;
}

Client Management

Realm Management

Realm configuration, import/export, event management, default groups, and administrative settings.

interface Realms {
  find(query?: { briefRepresentation?: boolean }): Promise<RealmRepresentation[]>;
  create(realm: RealmRepresentation): Promise<{ realmName: string }>;
  findOne(params: { realm: string }): Promise<RealmRepresentation | undefined>;
  update(query: { realm: string }, realm: RealmRepresentation): Promise<void>;
  del(params: { realm: string }): Promise<void>;
  
  // Import/Export
  partialImport(params: { realm: string; rep: PartialImportRealmRepresentation }): Promise<PartialImportResponse>;
  export(params: { realm: string; exportClients?: boolean; exportGroupsAndRoles?: boolean }): Promise<RealmRepresentation>;
}

Realm Management

Group Management

Group hierarchy management, member administration, and group-based role assignments.

interface Groups {
  find(query?: GroupQuery): Promise<GroupRepresentation[]>;
  create(group: GroupRepresentation): Promise<{ id: string }>;
  findOne(params: { id: string }): Promise<GroupRepresentation | undefined>;
  update(query: { id: string }, group: GroupRepresentation): Promise<void>;
  del(params: { id: string }): Promise<void>;
  
  // Group hierarchy
  listSubGroups(query: SubGroupQuery): Promise<GroupRepresentation[]>;
  setOrCreateChild(query: { id: string }, group: GroupRepresentation): Promise<{ id: string }>;
  listMembers(params: { id: string } & PaginatedQuery): Promise<UserRepresentation[]>;
}

Group Management

Role Management

Realm and client role management with composite role support and role mapping operations.

interface Roles {
  find(query?: RoleQuery): Promise<RoleRepresentation[]>;
  create(role: RoleRepresentation): Promise<{ roleName: string }>;
  findByName(params: { name: string }): Promise<RoleRepresentation>;
  update(query: { name: string }, role: RoleRepresentation): Promise<void>;
  del(params: { name: string }): Promise<void>;
  
  // Composite roles
  getCompositeRoles(params: { name: string }): Promise<RoleRepresentation[]>;
  getCompositeRolesForRealm(params: { name: string }): Promise<RoleRepresentation[]>;
  getCompositeRolesForClient(params: { name: string; clientId: string }): Promise<RoleRepresentation[]>;
}

Role Management

Organization Management

Organization lifecycle management, member administration, and organizational identity provider configuration.

interface Organizations {
  find(query?: OrganizationsQuery): Promise<OrganizationRepresentation[]>;
  create(organization: OrganizationRepresentation): Promise<OrganizationRepresentation>;
  findOne(params: { orgId: string }): Promise<OrganizationRepresentation | undefined>;
  update(params: { orgId: string }, organization: OrganizationRepresentation): Promise<void>;
  del(params: { orgId: string }): Promise<void>;
  
  // Members
  findMembers(params: { orgId: string }, query?: MembersQuery): Promise<UserRepresentation[]>;
  inviteUser(params: { orgId: string }, invitation: InvitationRequest): Promise<void>;
}

Organization Management

Identity Providers

External identity provider configuration including SAML, OIDC, and social login integrations.

interface IdentityProviders {
  find(): Promise<IdentityProviderRepresentation[]>;
  create(identityProvider: IdentityProviderRepresentation): Promise<void>;
  findOne(params: { alias: string }): Promise<IdentityProviderRepresentation | undefined>;
  update(params: { alias: string }, identityProvider: IdentityProviderRepresentation): Promise<void>;
  del(params: { alias: string }): Promise<void>;
  
  // Mappers
  findMappers(params: { alias: string }): Promise<IdentityProviderMapperRepresentation[]>;
  createMapper(params: { alias: string }, mapper: IdentityProviderMapperRepresentation): Promise<IdentityProviderMapperRepresentation>;
}

Identity Providers

Authentication Management

Authentication flow configuration, execution management, and authenticator configuration.

interface AuthenticationManagement {
  getFlows(): Promise<AuthenticationFlowRepresentation[]>;
  createFlow(flow: AuthenticationFlowRepresentation): Promise<void>;
  getFlow(params: { flowId: string }): Promise<AuthenticationFlowRepresentation>;
  updateFlow(params: { flowId: string }, flow: AuthenticationFlowRepresentation): Promise<void>;
  deleteFlow(params: { flowId: string }): Promise<void>;
  
  // Executions
  getExecutions(params: { flowAlias: string }): Promise<AuthenticationExecutionInfoRepresentation[]>;
  addExecution(params: { flowAlias: string }, execution: AuthenticationExecutionRepresentation): Promise<void>;
}

Authentication Management

Client Scopes

Client scope management including protocol mappers, default scopes, and scope mappings for OpenID Connect and SAML protocols.

interface ClientScopes {
  find(): Promise<ClientScopeRepresentation[]>;
  create(clientScope: ClientScopeRepresentation): Promise<{ id: string }>;
  findOne(params: { id: string }): Promise<ClientScopeRepresentation | undefined>;
  update(query: { id: string }, clientScope: ClientScopeRepresentation): Promise<void>;
  del(params: { id: string }): Promise<void>;
  
  // Protocol mappers
  addProtocolMapper(query: { id: string }, mapper: ProtocolMapperRepresentation): Promise<void>;
  listProtocolMappers(params: { id: string }): Promise<ProtocolMapperRepresentation[]>;
  
  // Default scopes
  listDefaultClientScopes(): Promise<ClientScopeRepresentation[]>;
  addDefaultClientScope(params: { id: string }): Promise<void>;
}

Client Scopes

Client Policies

Client policies and profiles for enforcing security policies and configuration standards across registered clients.

interface ClientPolicies {
  listProfiles(params?: { includeGlobalProfiles?: boolean }): Promise<ClientProfilesRepresentation>;
  createProfiles(profiles: ClientProfilesRepresentation): Promise<void>;
  listPolicies(params?: { includeGlobalPolicies?: boolean }): Promise<ClientPoliciesRepresentation>;
  updatePolicy(policies: ClientPoliciesRepresentation): Promise<void>;
}

Client Policies

Components

Keycloak component management for user storage providers, event listeners, and other pluggable system extensions.

interface Components {
  find(query?: ComponentQuery): Promise<ComponentRepresentation[]>;
  create(component: ComponentRepresentation): Promise<{ id: string }>;
  findOne(params: { id: string }): Promise<ComponentRepresentation | undefined>;
  update(query: { id: string }, component: ComponentRepresentation): Promise<void>;
  del(params: { id: string }): Promise<void>;
  listSubComponents(params: { id: string; type: string }): Promise<ComponentTypeRepresentation[]>;
}

Components

Server Info

Server information and configuration details including version, providers, themes, and message bundles.

interface ServerInfo {
  find(): Promise<ServerInfoRepresentation>;
  findEffectiveMessageBundles(query: MessageBundleQuery): Promise<EffectiveMessageBundleRepresentation[]>;
}

Server Info

WhoAmI

Current admin user context and permissions information within the Keycloak admin console.

interface WhoAmI {
  find(params: { currentRealm: string }): Promise<WhoAmIRepresentation>;
}

WhoAmI

Attack Detection

Brute force protection management for monitoring and clearing attack detection data.

interface AttackDetection {
  findOne(params: { id: string }): Promise<Record<string, any> | undefined>;
  del(params: { id: string }): Promise<void>;
  delAll(): Promise<void>;
}

Attack Detection

Cache Management

Cache clearing operations for refreshing various Keycloak system caches.

interface Cache {
  clearUserCache(): Promise<void>;
  clearKeysCache(): Promise<void>;
  clearCrlCache(): Promise<void>;
  clearRealmCache(): Promise<void>;
}

Cache Management

User Storage Provider

Management of external user storage systems including synchronization and user federation operations.

interface UserStorageProvider {
  name(params: { id: string }): Promise<NameResponse>;
  removeImportedUsers(params: { id: string }): Promise<void>;
  sync(params: { id: string; action?: ActionType }): Promise<SynchronizationResultRepresentation>;
  unlinkUsers(params: { id: string }): Promise<void>;
  mappersSync(params: { id: string; parentId: string; direction?: DirectionType }): Promise<SynchronizationResultRepresentation>;
}

User Storage Provider

Utility Functions

Error handling, network utilities, authentication helpers, and common constants for robust client operations.

class NetworkError extends Error {
  response: Response;
  responseData: unknown;
  constructor(message: string, options: NetworkErrorOptions);
}

function fetchWithError(
  input: Request | string | URL,
  init?: RequestInit,
): Promise<Response>;

const requiredAction: typeof RequiredActionAlias;

enum RequiredActionAlias {
  VERIFY_EMAIL = "VERIFY_EMAIL",
  UPDATE_PROFILE = "UPDATE_PROFILE",
  CONFIGURE_TOTP = "CONFIGURE_TOTP",
  UPDATE_PASSWORD = "UPDATE_PASSWORD",
  TERMS_AND_CONDITIONS = "TERMS_AND_CONDITIONS",
}

Utility Functions

Core Types

interface UserRepresentation {
  id?: string;
  username?: string;
  email?: string;
  firstName?: string;
  lastName?: string;
  enabled?: boolean;
  emailVerified?: boolean;
  attributes?: Record<string, string[]>;
  groups?: string[];
  roles?: string[];
  credentials?: CredentialRepresentation[];
}

interface ClientRepresentation {
  id?: string;
  clientId?: string;
  name?: string;
  description?: string;
  enabled?: boolean;
  publicClient?: boolean;
  protocol?: string;
  attributes?: Record<string, string>;
  redirectUris?: string[];
  webOrigins?: string[];
  defaultRoles?: string[];
}

interface RealmRepresentation {
  id?: string;
  realm?: string;
  displayName?: string;
  enabled?: boolean;
  sslRequired?: string;
  registrationAllowed?: boolean;
  loginWithEmailAllowed?: boolean;
  duplicateEmailsAllowed?: boolean;
  resetPasswordAllowed?: boolean;
  editUsernameAllowed?: boolean;
  bruteForceProtected?: boolean;
}

interface RoleRepresentation {
  id?: string;
  name?: string;
  description?: string;
  scopeParamRequired?: boolean;
  composite?: boolean;
  composites?: {
    realm?: string[];
    client?: Record<string, string[]>;
  };
  clientRole?: boolean;
  containerId?: string;
  attributes?: Record<string, string[]>;
}

interface GroupRepresentation {
  id?: string;
  name?: string;
  path?: string;
  attributes?: Record<string, string[]>;
  realmRoles?: string[];
  clientRoles?: Record<string, string[]>;
  subGroups?: GroupRepresentation[];
}

Version

Tile

Files

tessl/npm-keycloak--keycloak-admin-client

To install, run

index.mddocs/

Keycloak Admin Client

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Client Configuration

User Management

Client Management

Realm Management

Group Management

Role Management

Organization Management

Identity Providers

Authentication Management

Client Scopes

Client Policies

Components

Server Info

WhoAmI

Attack Detection

Cache Management

User Storage Provider

Utility Functions

Core Types

Version

Tile

Files

tessl/npm-keycloak--keycloak-admin-client

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Keycloak Admin Client

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Client Configuration

User Management

Client Management

Realm Management

Group Management

Role Management

Organization Management

Identity Providers

Authentication Management

Client Scopes

Client Policies

Components

Server Info

WhoAmI

Attack Detection

Cache Management

User Storage Provider

Utility Functions

Core Types

index.mddocs/