Skip to main content

Quick Start

You can install the package using the npm package manager.

Installation​

npm install @egose/keycloak-fluent --save

Usage​

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

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

Configure Keycloak Connection​

You can configure the Keycloak connection using either a user account or a service account.

  • Authenticate with a username and password:
await kc.simpleAuth({
  username: 'admin',
  password: 'admin', // pragma: allowlist secret
  clientId: 'admin-cli',
});
  • Authenticate with a service account:
await kc.simpleAuth({
  clientId: 'my-service-account',
  clientSecret: 'my-secret', // pragma: allowlist secret
});
  • Authenticate with a refresh token:
await kc.simpleAuth({
  clientId: 'admin-cli',
  refreshToken: process.env.KEYCLOAK_REFRESH_TOKEN,
});

If you need full control over the underlying Keycloak grant configuration, you can still call kc.auth(...) directly.

Resource Handlers​

You can create resource handlers for Keycloak resources such as realms, users, groups, roles, clients, authentication flows, organizations, and more.

For resource-style handles, ensure(...) will create the resource if it does not exist, or update the existing resource by merging the supplied fields into the current representation. It then returns the resource handle.

const realm = await kc.realm('my-realm').ensure({
  displayName: 'My Realm',
});

const user = await realm.user('john.doe').ensure({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@example.com',
});

const group = await realm.group('my-group').ensure({
  description: 'My Group',
});

await user.assignGroup(group);

Beyond CRUD​

The fluent API also exposes realm-scoped operational helpers that are covered by the current test suite:

const flow = realm.authenticationFlow('browser-copy');
await flow.copy('browser-copy-v2');

const organization = await realm.organization('acme').ensure({ name: 'Acme Corp' });
await organization.addMember(user);

await realm.cache().clearUserCache();
await realm.attackDetection(user.user!.id!).clear();

const serverInfo = await kc.serverInfo().get();
const currentAdmin = await kc.whoAmI('master').get();

For the full surface area, start with the API reference pages for KeycloakAdminClientFluent, RealmHandle, AuthenticationFlowHandle, OrganizationHandle, and the realm system helpers.