Small Nest Keycloak

Minimal, type-safe NestJS integration with Keycloak. ESM-only, strict TypeScript, no build output. Includes a ready-to-use AuthController, JWT strategy (cookie/header), role decorator and guards.

Quick Start (NestJS)

import { Module } from '@nestjs/common';
import { KeycloakModule } from '@small/nest-keycloak';

@Module({
  imports: [
    KeycloakModule.register({
      baseUrl: process.env.KEYCLOAK_BASE_URL ?? 'http://localhost:8080/auth',
      realm: process.env.KEYCLOAK_REALM ?? 'master',
      clientId: process.env.KEYCLOAK_CLIENT_ID ?? 'nest-app'
    }),
  ],
})
export class AppModule {}

Guards and roles

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, RolesGuard, Roles } from '@small/nest-keycloak';

@Controller('users')
@UseGuards(JwtAuthGuard, RolesGuard)
export class UserController {
  @Get()
  @Roles('admin')
  list() { return ['user1']; }
}

Example .env

KEYCLOAK_BASE_URL=http://localhost:8080/auth
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=nest-app
ACCESS_COOKIE=access_token
REFRESH_COOKIE=refresh_token
PORT=3000

License

MIT © 2025 Sébastien Kus