@devminister/keycloak-admin

NestJS Keycloak Admin client for the Monitoring API. Provides token management and user operations against a Keycloak server using client credentials.

Features

• Automatic client credentials token acquisition and refresh (every 10 minutes)
• List, search, and count realm users via Keycloak Admin REST API
• Get individual user details by ID
• Proper error handling with NestJS HttpException
• Global module — inject KeycloakAdminService anywhere
• Async module registration (for ConfigService integration)

Installation

npm install @devminister/keycloak-admin
# or
pnpm add @devminister/keycloak-admin
# or
yarn add @devminister/keycloak-admin

Peer Dependencies

Make sure you have these installed in your NestJS project:

npm install @nestjs/common @nestjs/core

Setup

1. Create a Keycloak Client

In your Keycloak admin console, create a confidential client with:

• Client authentication: ON
• Service accounts roles: Enabled
• Assign the realm-management → view-users role to the service account

Save the Client ID and Client Secret.

2. Register the Module

Static registration

import { Module } from '@nestjs/common';
import { KeycloakAdminModule } from '@devminister/keycloak-admin';

@Module({
  imports: [
    KeycloakAdminModule.register({
      baseUrl: 'https://auth.example.com',
      realm: 'my-realm',
      clientId: 'my-admin-client',
      clientSecret: 'my-client-secret',
    }),
  ],
})
export class AppModule {}

Async registration (recommended for production)

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { KeycloakAdminModule } from '@devminister/keycloak-admin';

@Module({
  imports: [
    ConfigModule.forRoot(),
    KeycloakAdminModule.registerAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        baseUrl: config.get('KEYCLOAK_BASE_URL'),
        realm: config.get('KEYCLOAK_REALM'),
        clientId: config.get('KEYCLOAK_CLIENT_ID'),
        clientSecret: config.get('KEYCLOAK_CLIENT_SECRET'),
      }),
    }),
  ],
})
export class AppModule {}

3. Environment Variables

Add these to your .env file:

KEYCLOAK_BASE_URL=https://auth.example.com
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=my-admin-client
KEYCLOAK_CLIENT_SECRET=my-client-secret

Usage

Inject KeycloakAdminService into any service or controller:

import { Injectable } from '@nestjs/common';
import { KeycloakAdminService } from '@devminister/keycloak-admin';

@Injectable()
export class UserService {
  constructor(private readonly keycloak: KeycloakAdminService) {}

  async searchUsers(query: string) {
    return this.keycloak.listUsers({ search: query, max: 20 });
  }

  async getUserById(id: string) {
    return this.keycloak.getUser(id);
  }

  async getTotalUsers() {
    return this.keycloak.countUsers();
  }
}

API Reference

KeycloakAdminService

| Method | Parameters | Returns | Description | |---|---|---|---| | getToken() | — | Promise<string> | Obtain an access token via client credentials | | listUsers(params?) | { search?, first?, max? } | Promise<KeycloakUser[]> | List users from the realm | | getUser(userId) | string | Promise<KeycloakUser> | Get a single user by ID | | countUsers(search?) | string? | Promise<number> | Count users in the realm |

listUsers Parameters

| Option | Type | Default | Description | |---|---|---|---| | search | string | — | Search by username, email, first or last name | | first | number | 0 | Pagination offset | | max | number | 50 | Maximum number of results |

Configuration Options

| Option | Type | Default | Description | |---|---|---|---| | baseUrl | string | required | Keycloak server base URL | | realm | string | required | Keycloak realm name | | clientId | string | required | Client ID for admin operations | | clientSecret | string | required | Client secret for admin operations | | clientUUID | string | — | Optional client UUID |

Types

KeycloakUser

interface KeycloakUser {
  id: string;
  username: string;
  email?: string;
  firstName?: string;
  lastName?: string;
  enabled?: boolean;
  attributes?: Record<string, string[]>;
}

Exports

import {
  KeycloakAdminModule,     // NestJS dynamic module
  KeycloakAdminService,    // Service for Keycloak operations
  KeycloakAdminConfig,     // Configuration interface
  KEYCLOAK_ADMIN_CONFIG,   // Injection token
  KeycloakTokenResponse,   // Token response type
  KeycloakUser,            // User type
} from '@devminister/keycloak-admin';

Publishing to npm

First-time setup

1. Create an npm account at npmjs.com if you don't have one
2. Create the @devminister organization at npmjs.com/org/create (free for public packages)
3. Login from your terminal:

npm login

Publish

cd packages/keycloak-admin
pnpm build
npm publish

The package is configured with publishConfig.access: "public" so scoped publishing works automatically.

Version updates

# Patch release (0.0.1 → 0.0.2) — bug fixes
npm version patch

# Minor release (0.0.1 → 0.1.0) — new features
npm version minor

# Major release (0.0.1 → 1.0.0) — breaking changes
npm version major

# Then publish
npm publish

Verify

After publishing, confirm the package is live:

npm info @devminister/keycloak-admin

License

MIT