Skip to main content

KeycloakAdminClientFluent API

KeycloakAdminClientFluent is the root entry point for the library. It wraps a @keycloak/keycloak-admin-client instance and gives you fluent access to realm-scoped handles, root-scoped system helpers, and convenience authentication helpers.

The package intentionally exposes one supported import path: @egose/keycloak-fluent. Runtime helpers, catchable errors, and public TypeScript types are exported from that root path; subpath imports are not part of the public contract.

Supported Keycloak Versions​

The package dependency range is @keycloak/keycloak-admin-client@^26.5.7. Packed consumer checks compile the public declarations against the minimum supported admin client 26.5.7 and the current lockfile-resolved admin client 26.6.3; live integration tests target the repository sandbox server, Keycloak 26.6.1.

Use Keycloak Admin Client 26.x from 26.5.7 upward unless you have verified the exact endpoints you need against another server/client version.

Constructor​

new KeycloakAdminClientFluent(connectionConfig?)

connectionConfig is passed straight to the underlying KeycloakAdminClient constructor.

Common Usage​

import KeycloakAdminClientFluent from '@egose/keycloak-fluent';

const kc = new KeycloakAdminClientFluent({
  baseUrl: 'http://localhost:8080',
  realmName: 'master',
});

await kc.simpleAuth({
  username: 'admin',
  password: 'admin', // pragma: allowlist secret
});

const realm = await kc.realm('demo').ensure({ displayName: 'Demo Realm' });

Methods​

auth(credentials)​

Calls the underlying Keycloak admin client's auth method directly.

await kc.auth({
  grantType: 'password',
  clientId: 'admin-cli',
  username: 'admin',
  password: 'admin', // pragma: allowlist secret
});

Use this when you want full control over the exact grant configuration.

simpleAuth({ username?, password?, refreshToken?, clientId?, clientSecret? })​

Chooses the grant type for you:

  • password grant when password is provided
  • refresh_token grant when refreshToken is provided
  • client_credentials grant otherwise
  • username and password must be provided together
  • password and refreshToken are mutually exclusive
  • Supplied username, password, refreshToken, clientId, and clientSecret values must be non-empty strings
await kc.simpleAuth({ username: 'admin', password: 'admin' }); // pragma: allowlist secret
await kc.simpleAuth({ refreshToken, clientId: 'admin-cli' });
await kc.simpleAuth({ clientId: 'svc-admin', clientSecret: 'secret' }); // pragma: allowlist secret

By default, clientId is admin-cli.

Authentication failures are rethrown with a Keycloak authentication failed: ... message. The public error message and cause expose only bounded OAuth error fields and safe status/code diagnostics; passwords, refresh tokens, client secrets, and arbitrary response bodies are not included.

The SimpleAuthOptions type is available from the root package export:

import type { SimpleAuthOptions } from '@egose/keycloak-fluent';

Public Exports​

Import supported symbols from the package root only:

import KeycloakAdminClientFluent, {
  AuthenticationFlowNotFoundError,
  DuplicateWorkflowNameError,
  UserPasswordProvisioningError,
  WorkflowNotFoundError,
  createManagedKeycloakClient,
} from '@egose/keycloak-fluent';

import type {
  ClientHandle,
  RealmHandle,
  UserHandle,
  UserInputData,
  WorkflowListOptions,
} from '@egose/keycloak-fluent';

Supported root exports include:

  • Runtime: the default KeycloakAdminClientFluent class, createManagedKeycloakClient, handle classes, and documented catchable error classes.
  • Types: supported handle classes, input and option types, query types, and Keycloak representation aliases used by public method signatures.
  • Paths: only @egose/keycloak-fluent is supported. Do not import from implementation subpaths such as @egose/keycloak-fluent/user.

The public API is snapshot-tested for ESM runtime exports, CJS runtime exports, and declaration exports in packed consumers.

realm(name)​

Returns a RealmHandle for a specific realm.

const realm = kc.realm('demo');
await realm.user('alice').ensure({ email: 'alice@example.com' });

serverInfo()​

Returns a ServerInfoHandle for root-scoped server metadata and effective message bundle lookups.

const serverInfo = await kc.serverInfo().get();

whoAmI(currentRealm, realmName?)​

Returns a WhoAmIHandle for inspecting the currently authenticated admin user.

const me = await kc.whoAmI('master').get();
const inDemoRealm = await kc.whoAmI('master', 'demo').get();

The first argument is always the current realm used for the admin request. The optional second argument asks Keycloak to resolve the user within another realm.

searchRealms(keyword)​

Lists realms through the admin client and filters them locally by name.

const matches = await kc.searchRealms('demo');
  • RealmHandle: realm-scoped resource entry point
  • ServerInfoHandle: server metadata helpers
  • WhoAmIHandle: current admin identity lookup