@slickteam/nestjs-keycloak

Module NestJS pour intégrer facilement l'authentification Keycloak avec des guards pré-configurés.

Fonctionnalités

• Configuration simplifiée via variables d'environnement
• Guards d'authentification et de rôles pré-configurés
• Décorateurs pour la gestion des accès (@Public, @Roles, @Scopes, @Resource)
• Interface TypeScript pour l'utilisateur Keycloak (IKeycloakUser)
• Support du mode de validation online/offline des tokens

Installation

npm install @slickteam/nestjs-keycloak

Configuration

Variables d'environnement

Ajoutez ces variables dans votre fichier .env :

# Obligatoires
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=my-client
KEYCLOAK_CLIENT_SECRET=my-secret

# Optionnelles
KEYCLOAK_POLICY_ENFORCEMENT_MODE=permissive  # permissive | enforcing
KEYCLOAK_TOKEN_VALIDATION=offline            # online | offline | none

Import du module

Importez KeycloakModule dans le module où vous souhaitez activer l'authentification :

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { KeycloakModule } from '@slickteam/nestjs-keycloak';

@Module({
  imports: [ConfigModule.forRoot(), KeycloakModule],
})
export class AppModule {}

Note : Le ConfigModule de NestJS doit être importé pour que les variables d'environnement soient accessibles.

Utilisation

Routes publiques

Par défaut, toutes les routes sont protégées. Utilisez le décorateur @Public() pour rendre une route accessible sans authentification :

import { Controller, Get } from '@nestjs/common';
import { Public } from '@slickteam/nestjs-keycloak';

@Controller('health')
export class HealthController {
  @Get()
  @Public()
  check() {
    return { status: 'ok' };
  }
}

Restriction par rôles

Utilisez le décorateur @Roles() pour restreindre l'accès à certains rôles :

import { Controller, Get } from '@nestjs/common';
import { Roles } from '@slickteam/nestjs-keycloak';

@Controller('admin')
export class AdminController {
  @Get()
  @Roles({ roles: ['admin'] })
  getAdminData() {
    return { message: 'Admin only' };
  }
}

Récupérer l'utilisateur connecté

Utilisez le décorateur @KeycloakUser() pour accéder aux informations de l'utilisateur :

import { Controller, Get } from '@nestjs/common';
import { IKeycloakUser, KeycloakUser } from '@slickteam/nestjs-keycloak';

@Controller('profile')
export class ProfileController {
  @Get()
  getProfile(@KeycloakUser() user: IKeycloakUser) {
    return {
      id: user.sub,
      email: user.email,
      name: user.name,
      roles: user.realm_access.roles,
    };
  }
}

API

Exports disponibles

| Export | Description | | ----------------------- | ------------------------------------------- | | KeycloakModule | Module principal à importer | | IKeycloakUser | Interface TypeScript de l'utilisateur | | KeycloakUser | Décorateur pour injecter l'utilisateur | | Public | Décorateur pour les routes publiques | | Roles | Décorateur pour restreindre par rôles | | Scopes | Décorateur pour restreindre par scopes | | Resource | Décorateur pour définir une ressource | | AuthGuard | Guard d'authentification | | RoleGuard | Guard de vérification des rôles | | ResourceGuard | Guard de vérification des ressources | | PolicyEnforcementMode | Enum des modes d'application des politiques | | TokenValidation | Enum des modes de validation des tokens | | EnforcerOptions | Options de configuration de l'enforcer |

Interface IKeycloakUser

interface IKeycloakUser {
  exp: number; // Timestamp d'expiration du token
  iat: number; // Timestamp d'émission du token
  auth_time: number; // Timestamp d'authentification de la session
  iss: string; // URL de l'émetteur
  sub: string; // ID utilisateur Keycloak
  aud: string; // Audience
  typ: string; // Type de token
  realm_access: {
    roles: string[]; // Rôles du realm
  };
  sid: string; // ID de session
  scope: string; // Scopes accordés
  email_verified: boolean; // Email vérifié
  email: string; // Adresse email
  name: string; // Nom complet
  given_name: string; // Prénom
  family_name: string; // Nom de famille
  preferred_username: string; // Nom d'utilisateur
}

Dépendances

| Package | Version | | ----------------------- | -------------- | | @nestjs/common | ^11.1 | | @nestjs/config | ^4.0 | | @nestjs/core | ^11.1 | | keycloak-connect | ^26.1.1 | | nest-keycloak-connect | ^2.0.0-alpha.2 |

Licence

MIT - Slickteam