![\"npm](\"https://img.shields.io/npm/v/%40egose%2Fkeycloak-fluent\")
\n ![\"npm](\"https://img.shields.io/npm/dm/%40egose%2Fkeycloak-fluent\")
\n ![\"license\"](\"https://img.shields.io/npm/l/%40egose%2Fkeycloak-fluent\")
\n ![\"docs\"](\"https://img.shields.io/badge/docs-online-blue\"){kind=icon}
\n\n
\n ![\"Keycloak](\"https://raw.githubusercontent.com/egose/keycloak-fluent/main/website/static/img/keycloak-fluent-lockup-dark.png\")
\n
\n Fluent TypeScript wrapper for the Keycloak Admin API with idempotent provisioning for realms, users, clients, authentication flows, organizations, and admin operations.\n
\n\n\n Documentation\n ·\n GitHub\n ·\n npm\n
\n\n## What It Is\n\n`@egose/keycloak-fluent` builds on top of `@keycloak/keycloak-admin-client` and turns low-level admin calls into a fluent, chainable API for Keycloak provisioning and operations.\n\nInstead of stitching together ids, searches, and update payloads everywhere, you work through handles such as:\n\n- `kc.realm('demo')`\n- `realm.user('alice')`\n- `realm.client('app')`\n- `realm.authenticationFlow('browser-copy')`\n- `realm.organization('acme')`\n- `realm.cache()`\n- `kc.serverInfo()`\n\nThe library stays close to Keycloak rather than inventing a separate abstraction model. You keep the official admin client underneath, but get a much better working surface for repeatable automation.\n\n## Why Use It\n\n- Write provisioning code that reads like intent instead of request plumbing.\n- Use `ensure(...)` and `discard()` for idempotent setup and cleanup flows.\n- Traverse Keycloak resources from a realm through dedicated resource handles.\n- Cover more than CRUD: authentication flows, organizations, workflows, cache, attack detection, user storage sync, client policies, `serverInfo`, and `whoAmI` are supported too.\n- Keep access to the official admin client through `kc.core`.\n\n## Why Not Just Use `@keycloak/keycloak-admin-client`?\n\nYou still can, and this package intentionally keeps that option open.\n\nUse the raw admin client when you want direct access to every endpoint with no extra abstraction.\n\nUse `@egose/keycloak-fluent` when you want:\n\n- idempotent provisioning with `ensure(...)` and `discard()`\n- resource-scoped handles instead of passing ids and lookup results around manually\n- readable scripts for realms, users, clients, flows, and organizations\n- a cleaner working surface for operational tasks like cache clearing, attack detection, and server inspection\n\nIn practice, this library is best seen as a better orchestration layer on top of the official Keycloak client, not a replacement for it.\n\n## Supported Keycloak Versions\n\nThis package currently depends on `@keycloak/keycloak-admin-client@^26.5.7`.\n\nTested matrix in this repository:\n\n- Node.js `>=20` is required\n- package dependency range: `@keycloak/keycloak-admin-client@^26.5.7`\n- packed consumer minimum-upstream check: `@keycloak/keycloak-admin-client@26.5.7`\n- lockfile-resolved admin client used by local/CI checks: `@keycloak/keycloak-admin-client@26.6.3`\n- local integration sandbox server: Keycloak `26.6.1`\n\nThe supported policy is Keycloak Admin Client `26.x` from `26.5.7` upward, verified at the declared minimum and at the current lockfile-resolved version. If you target an older or significantly newer Keycloak release, verify the specific endpoints you depend on, especially for newer areas such as organizations, workflows, and authentication-flow administration.\n\n## Public API Shape\n\nThe supported package shape is root-only. Import runtime helpers, catchable errors, and public TypeScript types from `@egose/keycloak-fluent`; implementation subpaths are not supported public entry points.\n\n```ts\nimport KeycloakAdminClientFluent, {\n AuthenticationFlowNotFoundError,\n DuplicateWorkflowNameError,\n UserPasswordProvisioningError,\n WorkflowNotFoundError,\n createManagedKeycloakClient,\n} from '@egose/keycloak-fluent';\n\nimport type { RealmHandle, UserHandle, UserInputData } from '@egose/keycloak-fluent';\n```\n\n## Installation\n\nRequirements:\n\n- Node.js `>=20`\n- A reachable Keycloak server\n- Credentials for the Keycloak Admin API\n\n```bash\nnpm install @egose/keycloak-fluent\n```\n\n## Quick Start\n\n```ts\nimport KeycloakAdminClientFluent from '@egose/keycloak-fluent';\n\nconst kc = new KeycloakAdminClientFluent({\n baseUrl: 'http://localhost:8080',\n realmName: 'master',\n});\n\nawait kc.simpleAuth({\n username: 'admin',\n password: 'admin', // pragma: allowlist secret\n clientId: 'admin-cli',\n});\n\nconst realm = await kc.realm('demo').ensure({\n displayName: 'Demo Realm',\n});\n\nconst user = await realm.user('alice').ensure({\n email: 'alice@example.com',\n enabled: true,\n});\n\nconst group = await realm.group('developers').ensure({\n description: 'Application developers',\n});\n\nawait user.assignGroup(group);\n```\n\n## Authentication\n\n### `simpleAuth(...)`\n\n`simpleAuth(...)` picks the grant type for you:\n\n- `password` grant when `password` is provided\n- `refresh_token` grant when `refreshToken` is provided\n- `client_credentials` grant otherwise\n- `username` and `password` must be provided together\n- `password` and `refreshToken` are mutually exclusive\n- Supplied `username`, `password`, `refreshToken`, `clientId`, and `clientSecret` values must be non-empty strings\n- Authentication failures expose only bounded OAuth error fields plus safe status/code diagnostics; passwords, refresh tokens, client secrets, and arbitrary response bodies are not included in the public error graph\n\n```ts\nawait kc.simpleAuth({\n username: 'admin',\n password: 'admin', // pragma: allowlist secret\n clientId: 'admin-cli',\n});\n\nawait kc.simpleAuth({\n clientId: 'my-service-account',\n clientSecret: 'my-secret', // pragma: allowlist secret\n});\n\nawait kc.simpleAuth({\n clientId: 'admin-cli',\n refreshToken: process.env.KEYCLOAK_REFRESH_TOKEN,\n});\n```\n\n### `auth(...)`\n\nIf you need full control over the grant configuration, call the underlying auth method directly:\n\n```ts\nawait kc.auth({\n grantType: 'password',\n clientId: 'admin-cli',\n username: 'admin',\n password: 'admin', // pragma: allowlist secret\n});\n```\n\n### Managed clients\n\n`createManagedKeycloakClient(...)` authenticates on demand, refreshes expired tokens without timers, and shares one authentication attempt across concurrent requests. Credential resolver functions are called again whenever authentication is required, allowing secret rotation.\n\nService-account authentication uses `client_credentials` and is the default mode:\n\n```ts\nimport { createManagedKeycloakClient } from '@egose/keycloak-fluent';\n\nconst kc = createManagedKeycloakClient({\n baseUrl: 'http://localhost:8080',\n authRealm: 'master',\n clientId: 'provisioning-service',\n clientSecret: () => secretStore.get('keycloak-client-secret'),\n});\n```\n\nDirect user authentication uses the OAuth password grant. The client must have Direct Access Grants enabled:\n\n```ts\nconst kc = createManagedKeycloakClient({\n baseUrl: 'http://localhost:8080',\n authRealm: 'master',\n authMode: 'user_credentials',\n clientId: 'admin-cli',\n username: () => secretStore.get('keycloak-admin-username'),\n password: () => secretStore.get('keycloak-admin-password'),\n});\n```\n\nService accounts are recommended for background automation because their permissions and lifecycle are independent of a human administrator.\n\n## Example Flows\n\n### Realm and User Provisioning\n\n```ts\nconst realm = await kc.realm('my-realm').ensure({\n displayName: 'My Realm',\n});\n\nawait realm.user('john.doe').ensure({\n firstName: 'John',\n lastName: 'Doe',\n email: 'john.doe@example.com',\n});\n```\n\nUsers can also be targeted by immutable Keycloak ID. User handles expose temporary password reset, verification email, managed realm-role reconciliation, and managed attribute reconciliation:\n\n```ts\nconst user = kc.realm('my-realm').userById(userId);\n\nawait user.resetPassword(generatedPassword, { temporary: true });\nawait user.sendVerifyEmail();\nawait user.reconcileRealmRoles(['application-user'], {\n managedRoleNames: ['application-user', 'application-admin'],\n ensureMissing: true,\n});\nawait user.reconcileAttributes({ tenantId: ['tenant-42'] }, { managedKeys: ['tenantId'] });\n```\n\nSupplying `passwordTemporary` during creation or ensure uses the same disabled-create and cleanup guarantees as ordinary password provisioning:\n\n```ts\nawait kc.realm('my-realm').user('new-user').create({\n enabled: true,\n password: generatedPassword,\n passwordTemporary: true,\n});\n```\n\n### Authentication Flows\n\n```ts\nconst flow = await kc.realm('demo').authenticationFlow('browser-copy').ensure({\n description: 'Custom browser flow',\n providerId: 'basic-flow',\n topLevel: true,\n builtIn: false,\n});\n\nawait flow.copy('browser-copy-v2');\nawait flow.addExecution('auth-cookie');\n```\n\n### Organizations\n\n```ts\nconst realm = kc.realm('demo');\nconst organization = await realm.organization('acme').ensure({\n name: 'Acme Corp',\n});\n\nawait organization.addMember(realm.user('alice'));\n\nconst google = realm.identityProvider('google');\nawait organization.linkIdentityProvider(google);\n```\n\n### Operational Helpers\n\n```ts\nconst realm = kc.realm('demo');\n\nawait realm.cache().clearUserCache();\nawait realm.attackDetection('user-id').clear();\n\nconst info = await kc.serverInfo().get();\nconst me = await kc.whoAmI('master').get();\n```\n\n## Main Entry Points\n\n### Root Client\n\n`KeycloakAdminClientFluent` exposes:\n\n- `auth(credentials)`\n- `simpleAuth({...})`\n- `realm(name)`\n- `searchRealms(keyword)`\n- `serverInfo()`\n- `whoAmI(currentRealm, realmName?)`\n\n### Realm Handle\n\n`RealmHandle` is the main entry point for resource-scoped work. From a realm you can access handles for:\n\n- clients\n- authentication flows\n- components\n- client scopes\n- roles\n- groups\n- users\n- identity providers\n- organizations\n- user storage providers\n- workflows\n- browser login client helpers\n- service accounts\n- realm admin service accounts\n- cache\n- attack detection\n- client policies\n\nIt also includes realm-level search and operational methods such as:\n\n- `searchClients(...)`\n- `searchClientScopes(...)`\n- `searchRoles(...)`\n- `searchGroups(...)`\n- `searchUsers(...)`\n- `searchIdentityProviders(...)`\n- `searchOrganizations(...)`\n- `searchAuthenticationFlows(...)`\n- `searchWorkflows(...)`\n- realm import/export helpers\n- event queries\n- localization helpers\n- session helpers\n\n## Main Handles At A Glance\n\n| Handle | Purpose |\n| ------------------------------ | ------------------------------------------------------------------------------------ |\n| `KeycloakAdminClientFluent` | Root entry point for auth, realm access, server info, and who-am-i |\n| `RealmHandle` | Realm-scoped entry point for users, groups, roles, clients, flows, and operations |\n| `UserHandle` | Manage users, credentials, role mappings, groups, sessions, and federated identities |\n| `GroupHandle` | Manage groups, hierarchy, membership, and role mappings |\n| `RoleHandle` | Manage realm roles and related mappings |\n| `ClientHandle` | Manage clients, client roles, and protocol mappers |\n| `ClientScopeHandle` | Manage client scopes and scope mappers |\n| `IdentityProviderHandle` | Manage identity providers and provider-level mapper access |\n| `IdentityProviderMapperHandle` | Manage mappers attached to an identity provider |\n| `AuthenticationFlowHandle` | Manage flows, executions, authenticator config, and required actions |\n| `OrganizationHandle` | Manage organizations, members, invitations, and linked identity providers |\n| `WorkflowHandle` | Manage realm workflows and workflow listing |\n| `ComponentHandle` | Manage realm components such as user storage-related components |\n| `UserStorageProviderHandle` | Trigger sync, unlink, naming, and mapper sync operations for user storage providers |\n| `CacheHandle` | Clear realm caches |\n| `AttackDetectionHandle` | Inspect or clear user and realm attack-detection state |\n| `ClientPoliciesHandle` | Read and update client profiles and client policies |\n| `ServerInfoHandle` | Read root server info and effective message bundles |\n| `WhoAmIHandle` | Inspect the currently authenticated admin user |\n\n## Supported Areas\n\nThe currently documented and tested surface includes:\n\n- realms\n- users\n- groups\n- roles\n- clients\n- client scopes\n- protocol mappers\n- identity providers\n- identity provider mappers\n- authentication flows\n- organizations\n- workflows\n- components\n- user storage providers\n- cache operations\n- attack detection\n- client policies\n- server info\n- who-am-i\n\n## Notes\n\n- For resource-style handles, `update(...)` and the update path of `ensure(...)` now merge the supplied fields into the existing representation before sending the admin update call. This keeps unspecified nested fields such as attributes, config blocks, redirect URIs, and other existing settings intact.\n- `WorkflowHandle` now follows the same contract as the other mutable handles: it exposes `create(...)`, `update(...)`, `ensure(...)`, `delete()`, and `discard()`.\n- Some higher-level helpers resolve resources lazily by alias or name, so code stays concise while still failing explicitly when a resource cannot be resolved.\n- You can always access the underlying official admin client through `kc.core`.\n\n## Documentation\n\n- Site: `https://keycloak-fluent.pages.dev`\n- Quick Start: `https://keycloak-fluent.pages.dev/about/quick-start/`\n- API Reference: `https://keycloak-fluent.pages.dev/api/keycloak-admin-client-fluent/`\n- Examples: `https://keycloak-fluent.pages.dev/example/general/`\n\n## Development\n\nSandbox-free local checks can run without Docker or a Keycloak server:\n\n```bash\npnpm install\npnpm lint:check\npnpm typecheck\npnpm typecheck:tests\npnpm test:unit\npnpm build\npnpm docs:check\n```\n\nLive integration tests need the Docker/Keycloak sandbox described below. Do not run `pnpm test` or `pnpm test:integration` until the sandbox is reachable.\n\n### Build, Type-check, And Release Verification\n\n- `npm run build`\n Produces the publishable `dist/` from current source via `tsup` (ESM + CJS + `.d.ts`/`.d.cts`). The package `exports`/`main`/`module`/`types` entry points all point at `dist/index.{cjs,js,d.ts}`, so the bundle is the source of truth for the installed tarball.\n- `npm run typecheck`\n Runs `tsc --noEmit` for project-wide type validation. This is the non-emitting type gate used by CI and pre-publish checks; it does not write `build/`.\n- `npm run pack:inspect`\n Rebuilds `dist/`, runs `npm pack --dry-run --json`, and asserts the tarball contains only the intended files (`dist/index.*`, `README.md`, `LICENSE`, `CHANGELOG.md`, `package.json`) and no source maps. Useful as a guard against stale or accidental package-file drift.\n- `npm run pack:consumers`\n Builds and packs the tarball, then installs it into isolated ESM, CJS, and TypeScript consumer projects under `.packed-consumers/` and exercises the real root export surface, `simpleAuth()` validation/default flow, and representative handle creation in each. TypeScript consumers also run `tsc --noEmit` with `skipLibCheck: false` against the packed `.d.ts`, including a fixture pinned to the minimum supported `@keycloak/keycloak-admin-client@26.5.7`.\n- `npm run publish:check`\n Runs the sandbox-free pre-publish chain: `lint:check` -> `typecheck` -> `typecheck:tests` -> `test:unit` -> `build` -> `pack:inspect` -> `pack:consumers`. The tag publish workflow adds live `test:integration` in the sandbox before publishing the exact tagged commit.\n- `npm run docs:check`\n Verifies documentation version strings and critical public snippets against checked-in package metadata and source declarations.\n\n### Test Layers\n\nThe repo intentionally has two different kinds of tests:\n\n- `npm run test:unit`\n Runs the mocked implementation/contract tests in `tests/implementation-*.spec.ts`.\n These verify the fluent wrapper behavior itself: lazy resolution, correct admin-client method selection, payload shaping, pagination wiring, and resource-handle contracts.\n- `npm run test:integration`\n Runs the live Keycloak integration tests in the rest of `tests/*.spec.ts`.\n These create real realms and resources against a running Keycloak instance through `tests/test-utils.ts`.\n- `npm test`\n Runs the full suite and therefore requires the integration sandbox to be running.\n\nThe mocked tests are not meant to replace the live integration suite. They exist because some wrapper guarantees are easier and safer to assert at the admin-client call boundary than through a live server alone.\n\n### Integration Sandbox\n\nThe live integration tests (`npm run test:integration`) target a Keycloak instance provisioned by the `sandbox/` Docker Compose stack:\n\n```bash\nmake DAEMON=true up # start Keycloak + Postgres in the background\nmake logs # tail sandbox service logs\nmake down # stop and remove sandbox containers\nmake destroy # down + remove volumes and images\n```\n\nThe stack pins every image by immutable digest (`postgres:18.4-alpine3.22@sha256:...`, `quay.io/keycloak/keycloak:26.6.1@sha256:...`, and the `golang` mkcert build stage) and builds the local mkcert cert from the pinned `mkcert` release tag (`v1.4.4`, commit-pinned inside the Dockerfile), so a forced re-pull cannot silently advance the runtime to a different image than the one the tests were authored against.\n\nThe integration tests read their target endpoint and credentials from environment variables so a non-default Keycloak instance can be targeted without editing the test sources. Defaults match the local sandbox:\n\n| Environment variable | Default | Purpose |\n| ----------------------- | ----------------------- | ------------------------------------------ |\n| `KEYCLOAK_BASE_URL` | `http://localhost:8080` | Keycloak admin API base URL. |\n| `KEYCLOAK_MASTER_REALM` | `master` | Master realm name to authenticate against. |\n| `KEYCLOAK_USERNAME` | `admin` | Admin username for `simpleAuth()`. |\n| `KEYCLOAK_PASSWORD` | `password` | Admin password for `simpleAuth()`. |\n\nFor example, to run the integration suite against Keycloak on `https://kc.example:8443` with custom credentials:\n\n```bash\nKEYCLOAK_BASE_URL=https://kc.example:8443 \\\nKEYCLOAK_USERNAME=ci-admin \\\nKEYCLOAK_PASSWORD=\"$CI_ADMIN_PASSWORD\" \\\n npm run test:integration\n```\n\nIn CI, `.github/actions/setup-tools` delegates tool installation to the pinned `egose/actions/asdf-tools` action commit and the versions in `.tool-versions` (`nodejs`, `pnpm`, `picotools`, and `docker-compose`). The repository does not currently enforce a checksum for the installed Docker Compose binary. The `.github/actions/setup-sandbox` composite action then brings the sandbox up, waits for the master realm `openid-configuration` to be reachable, runs the provided script, and tears the services down via an `EXIT` trap that fires on success, failure, and job cancellation, so cleanup and diagnostic logs run even if the script is interrupted.\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}