@mondart/nestjs-common-module-keycloak

NestJS integration for the Keycloak Admin REST API: a KeycloakModule that authenticates once at startup and keeps itself authenticated, and a KeycloakService that exposes the underlying @keycloak/keycloak-admin-client resource clients (users, clients, roles, ...) for injection anywhere in the app.

Registration

import { KeycloakModule } from '@mondart/nestjs-common-module-keycloak';

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

Or asynchronously:

KeycloakModule.registerAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    baseUrl: config.get('KEYCLOAK_BASE_URL'),
    realmName: config.get('KEYCLOAK_REALM'),
    clientId: config.get('KEYCLOAK_CLIENT_ID'),
    clientSecret: config.get('KEYCLOAK_CLIENT_SECRET'),
    username: config.get('KEYCLOAK_ADMIN_USERNAME'),
    password: config.get('KEYCLOAK_ADMIN_PASSWORD'),
  }),
});

KeycloakModule is @Global(), so KeycloakService is available for injection anywhere without re-importing the module. Options extend the admin-client Credentials type, so any grant supported by @keycloak/keycloak-admin-client (client credentials, password, ...) can be passed through.

KeycloakService

On onModuleInit, the service authenticates with the password grant and registers a token provider that refreshes (or re-authenticates) the access token automatically before each admin-client call — callers never need to manage tokens themselves.

constructor(private readonly keycloakService: KeycloakService) {}

async findUser(username: string) {
  const [user] = await this.keycloakService.users.find({ username });
  return user;
}

async createRealmRole(name: string) {
  await this.keycloakService.roles.create({ name });
}

KeycloakService exposes the same resource groups as KeycloakAdminClient as getters — users, realms, clients, roles, groups, organizations, userStorageProvider, clientScopes, clientPolicies, identityProviders, components, serverInfo, whoAmI, attackDetection, authenticationManagement, and cache — each simply forwarding to the underlying admin-client instance, so refer to @keycloak/keycloak-admin-client's own docs for the full method surface on each one.

Types

Commonly needed @keycloak/keycloak-admin-client types are re-exported so consumers don't need a direct dependency on the admin-client package:

import {
  RealmRepresentation,
  UserQuery,
  Users,
  KeycloakUserRepresentation,
  KeycloakGrantType,
} from '@mondart/nestjs-common-module-keycloak';

JWT utility

import { JwtUtils } from '@mondart/nestjs-common-module-keycloak';

const secondsLeft = JwtUtils.getTokenExpiry(accessToken);

JwtUtils.getTokenExpiry decodes a JWT's exp claim and returns the remaining seconds until expiry (0 if already expired, null if the token is missing, malformed, or has no exp claim).