lions-user-manager-server-impl-quarkus/README.md

Lions User Manager

Module de gestion centralisée des utilisateurs via Keycloak Admin REST API.

🎯 Objectif

Fournir une gestion complète des utilisateurs Keycloak via une interface PrimeFaces Freya moderne et une API REST sécurisée, en respectant strictement les contraintes suivantes:

• ✅ AUCUNE écriture directe dans la DB Keycloak (utilisation exclusive de l'Admin REST API)
• ✅ Architecture multi-modules Maven (API, Impl, Client)
• ✅ Authentification OIDC via Keycloak
• ✅ Délégation multi-realm (superadmin global, admin de realm)
• ✅ Audit complet (qui, quoi, quand, IP, succès/échec)
• ✅ Tests avec Testcontainers (80% minimum de couverture)
• ✅ Déploiement Kubernetes via Helm

🏗️ Architecture

lions-user-manager/
├── lions-user-manager-server-api         # Contrats (DTOs, interfaces, enums)
├── lions-user-manager-server-impl-quarkus  # Implémentation (Resources, Services, Keycloak Client)
└── lions-user-manager-client-quarkus-primefaces-freya  # UI (PrimeFaces, Beans JSF, REST Clients)

Modules

1. server-api (JAR)

Contrats purs sans dépendances lourdes:

• DTOs avec validation Bean
• Interfaces de services
• Enums métiers
• Constantes de validation

Package: dev.lions.user.manager.server.api

2. server-impl-quarkus (JAR)

Implémentation serveur Quarkus:

• Resources REST JAX-RS (/api/users, /api/roles, /api/audit)
• Services métier (implémentations des interfaces)
• KeycloakAdminClient (interface + impl)
• Configuration sécurité OIDC
• Entités JPA pour audit local (optionnel)

Package: dev.lions.user.manager.server

3. client-quarkus-primefaces-freya (JAR)

Client web PrimeFaces Freya:

• Services REST Client (MicroProfile Rest Client)
• Beans JSF (@Named, @SessionScoped/@RequestScoped)
• Pages XHTML PrimeFaces
• Filtres de sécurité
• Converters & Validators JSF

Package: dev.lions.user.manager.client

🚀 Stack Technique

Technologie	Version
Java	17+
Quarkus	3.15.1
PrimeFaces	14.0.5
Quarkus PrimeFaces	3.13.3
Keycloak Admin Client	23.0.3
PostgreSQL (optionnel)	15+
Lombok	1.18.30
MapStruct	1.5.5.Final
Testcontainers	1.19.3

📂 Structure du Projet

Module server-api

lions-user-manager-server-api/
└── src/main/java/dev/lions/user/manager/server/api/
    ├── dto/
    │   ├── base/
    │   │   └── BaseDTO.java                 # DTO de base avec UUID id
    │   ├── user/
    │   │   ├── UserDTO.java                 # DTO utilisateur complet
    │   │   ├── UserSearchCriteria.java      # Critères de recherche
    │   │   └── UserSearchResultDTO.java     # Résultat de recherche paginé
    │   ├── role/
    │   │   ├── RoleDTO.java                 # DTO rôle
    │   │   └── RoleAssignmentDTO.java       # Assignation rôle → utilisateur
    │   └── audit/
    │       └── AuditLogDTO.java             # Log d'audit
    ├── enums/
    │   ├── user/
    │   │   └── StatutUser.java              # ACTIF, INACTIF, SUSPENDU, etc.
    │   └── role/
    │       └── TypeRole.java                # REALM_ROLE, CLIENT_ROLE
    ├── service/
    │   ├── UserService.java                 # Interface CRUD utilisateurs
    │   ├── RoleService.java                 # Interface gestion rôles
    │   ├── AuditService.java                # Interface consultation audit
    │   └── SyncService.java                 # Interface synchronisation
    └── validation/
        └── ValidationConstants.java          # Constantes de validation

Module server-impl-quarkus

lions-user-manager-server-impl-quarkus/
└── src/main/java/dev/lions/user/manager/server/
    ├── resource/
    │   ├── UserResource.java                # GET/POST/PUT/DELETE /api/users
    │   ├── RoleResource.java                # GET/POST/DELETE /api/roles
    │   ├── AuditResource.java               # GET /api/audit
    │   └── HealthResource.java              # /health/ready, /health/live
    ├── service/
    │   ├── UserServiceImpl.java             # Impl UserService
    │   ├── RoleServiceImpl.java             # Impl RoleService
    │   ├── AuditServiceImpl.java            # Impl AuditService
    │   └── SyncServiceImpl.java             # Impl SyncService
    ├── client/
    │   ├── KeycloakAdminClient.java         # Interface centralisée Keycloak Admin API
    │   └── KeycloakAdminClientImpl.java     # Implémentation avec retry/circuit breaker
    ├── security/
    │   ├── KeycloakService.java             # Gestion tokens service account
    │   └── SecurityConfig.java              # Configuration sécurité Quarkus
    ├── entity/                              # Optionnel: audit local
    │   └── AuditLog.java                    # Entité JPA audit
    └── repository/                          # Optionnel: audit local
        └── AuditLogRepository.java          # Repository Panache

Module client-quarkus-primefaces-freya

lions-user-manager-client-quarkus-primefaces-freya/
└── src/main/
    ├── java/dev/lions/user/manager/client/
    │   ├── service/
    │   │   ├── UserService.java             # REST Client (@RegisterRestClient)
    │   │   ├── RoleService.java             # REST Client
    │   │   └── AuditService.java            # REST Client
    │   ├── dto/
    │   │   ├── UserDTO.java                 # DTO client simplifié
    │   │   ├── RoleDTO.java                 # DTO rôle client
    │   │   └── AuditLogDTO.java             # DTO audit client
    │   ├── view/
    │   │   ├── UserRechercheBean.java       # Bean recherche utilisateurs
    │   │   ├── UserListeBean.java           # Bean liste utilisateurs
    │   │   ├── UserProfilBean.java          # Bean profil utilisateur
    │   │   ├── RoleGestionBean.java         # Bean gestion rôles
    │   │   └── AuditConsultationBean.java   # Bean consultation audit
    │   └── security/
    │       ├── JwtTokenManager.java         # Gestion tokens JWT
    │       ├── AuthenticationFilter.java    # Filtre authentification
    │       └── PermissionChecker.java       # Vérification permissions
    └── resources/
        ├── application.properties            # Configuration client
        └── META-INF/resources/pages/
            ├── users-search.xhtml           # Page recherche utilisateurs
            ├── users-list.xhtml             # Page liste utilisateurs
            ├── user-profile.xhtml           # Page profil utilisateur
            ├── roles-management.xhtml       # Page gestion rôles
            └── audit-logs.xhtml             # Page consultation audit

⚙️ Configuration

application.properties (server-impl)

# Application
quarkus.application.name=Lions User Manager Server
quarkus.application.version=1.0.0

# HTTP
quarkus.http.port=8080
quarkus.http.host=0.0.0.0

# CORS
quarkus.http.cors=true
quarkus.http.cors.origins=http://localhost:8081
quarkus.http.cors.methods=GET,POST,PUT,DELETE,OPTIONS

# OIDC
quarkus.oidc.auth-server-url=https://security.lions.dev/realms/btpxpress
quarkus.oidc.client-id=lions-user-manager-server
quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET}
quarkus.oidc.application-type=service

# Keycloak Admin Client
lions.user.manager.keycloak.server-url=${KEYCLOAK_SERVER_URL:http://localhost:8180}
lions.user.manager.keycloak.realm=${KEYCLOAK_REALM:master}
lions.user.manager.keycloak.client-id=${KEYCLOAK_CLIENT_ID:lions-user-manager}
lions.user.manager.keycloak.client-secret=${KEYCLOAK_CLIENT_SECRET}
lions.user.manager.keycloak.connection-timeout=5000
lions.user.manager.keycloak.read-timeout=30000

# Feature Toggles
lions.user.manager.keycloak.write.enabled=true

# Database (optionnel pour audit)
%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.jdbc.url=${DATABASE_URL}
%prod.quarkus.datasource.username=${DATABASE_USER}
%prod.quarkus.datasource.password=${DATABASE_PASSWORD}
%prod.quarkus.hibernate-orm.database.generation=none
%prod.quarkus.flyway.migrate-at-start=true

# OpenAPI
quarkus.smallrye-openapi.path=/q/openapi
quarkus.swagger-ui.always-include=true
quarkus.swagger-ui.path=/q/swagger-ui

# Health
quarkus.smallrye-health.root-path=/health

# Metrics
quarkus.micrometer.export.prometheus.enabled=true
quarkus.micrometer.export.prometheus.path=/metrics

# Logging
quarkus.log.level=INFO
quarkus.log.category."dev.lions.user.manager".level=DEBUG

application.properties (client)

# Application
quarkus.application.name=Lions User Manager Client
quarkus.application.version=1.0.0

# HTTP
quarkus.http.port=8081
quarkus.http.host=0.0.0.0

# OIDC
quarkus.oidc.auth-server-url=https://security.lions.dev/realms/btpxpress
quarkus.oidc.client-id=lions-user-manager-client
quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET}
quarkus.oidc.application-type=web-app
quarkus.oidc.authentication.redirect-path=/
quarkus.oidc.authentication.restore-path-after-redirect=true

# PrimeFaces
primefaces.THEME=freya
primefaces.FONT_AWESOME=true
primefaces.CLIENT_SIDE_VALIDATION=true

# REST Client
lions.user.manager.backend.url=${BACKEND_URL:http://localhost:8080}
quarkus.rest-client."lions-user-manager-api".url=${lions.user.manager.backend.url}
quarkus.rest-client."lions-user-manager-api".scope=jakarta.inject.Singleton
quarkus.rest-client."lions-user-manager-api".connect-timeout=5000
quarkus.rest-client."lions-user-manager-api".read-timeout=30000

# Logging
quarkus.log.level=INFO
quarkus.log.category."dev.lions.user.manager.client".level=DEBUG

🔑 Provisioning Keycloak

Script de création du client service account

Voir scripts/kcadm-provision.sh:

#!/bin/bash

# Configuration
KEYCLOAK_URL="${KEYCLOAK_URL:-http://localhost:8180}"
ADMIN_USER="${ADMIN_USER:-admin}"
ADMIN_PASSWORD="${ADMIN_PASSWORD:-admin}"
REALM="${REALM:-master}"
CLIENT_ID="lions-user-manager"

# Login admin
kcadm.sh config credentials --server "$KEYCLOAK_URL" \\
    --realm master --user "$ADMIN_USER" --password "$ADMIN_PASSWORD"

# Créer le client service account
kcadm.sh create clients -r "$REALM" -f - <<EOF
{
  "clientId": "$CLIENT_ID",
  "enabled": true,
  "serviceAccountsEnabled": true,
  "standardFlowEnabled": false,
  "directAccessGrantsEnabled": false,
  "publicClient": false,
  "protocol": "openid-connect"
}
EOF

# Récupérer le client UUID
CLIENT_UUID=$(kcadm.sh get clients -r "$REALM" --fields id,clientId | \\
    jq -r ".[] | select(.clientId==\"$CLIENT_ID\") | .id")

# Assigner les rôles admin realm
kcadm.sh add-roles -r "$REALM" --uusername "service-account-$CLIENT_ID" \\
    --rolename admin

# Récupérer le client secret
kcadm.sh get "clients/$CLIENT_UUID/client-secret" -r "$REALM"

🧪 Tests

Tests unitaires

mvn clean test

Tests d'intégration (avec Testcontainers)

mvn clean verify

Couverture de code (minimum 80%)

mvn clean test jacoco:report
# Rapport: target/site/jacoco/index.html

📦 Build & Run

Build complet

mvn clean install

Run server

cd lions-user-manager-server-impl-quarkus
mvn quarkus:dev

Accès:

• API: http://localhost:8080
• OpenAPI: http://localhost:8080/q/swagger-ui
• Health: http://localhost:8080/health
• Metrics: http://localhost:8080/metrics

Run client

cd lions-user-manager-client-quarkus-primefaces-freya
mvn quarkus:dev

Accès:

• UI: http://localhost:8081

🐳 Docker

Build images

# Server
cd lions-user-manager-server-impl-quarkus
mvn clean package -Dquarkus.package.type=uber-jar
docker build -t lions-user-manager-server:1.0.0 .

# Client
cd lions-user-manager-client-quarkus-primefaces-freya
mvn clean package -Dquarkus.package.type=uber-jar
docker build -t lions-user-manager-client:1.0.0 .

☸️ Déploiement Kubernetes (Helm)

helm install lions-user-manager ./helm \\
    --set server.image.tag=1.0.0 \\
    --set client.image.tag=1.0.0 \\
    --set keycloak.url=https://security.lions.dev \\
    --set keycloak.clientSecret=$KEYCLOAK_CLIENT_SECRET

📊 Métriques & Observabilité

Métriques disponibles (Prometheus format)

• http_server_requests_total: Nombre de requêtes HTTP
• keycloak_admin_api_calls_total: Nombre d'appels Admin API
• keycloak_admin_api_errors_total: Nombre d'erreurs Admin API
• keycloak_admin_api_duration_seconds: Latence des appels Admin API

Health checks

• /health/ready: Readiness probe
• /health/live: Liveness probe

📚 Documentation

Voir dossier docs/:

• architecture.md: Architecture détaillée
• runbook.md: Guide opérationnel
• security-policy.md: Politique de sécurité
• integration-guide.md: Guide d'intégration

🔐 Sécurité

Contraintes strictes

1. AUCUNE écriture directe dans la DB Keycloak

   • Toutes les opérations passent par l'Admin REST API
   • Les accès DB en lecture sont documentés et désactivables

2. Authentification OIDC

   • Server: Service account (client credentials)
   • Client: Authorization code flow

3. Délégation multi-realm

   • Superadmin global: accès tous realms
   • Admin de realm: limité à son realm

4. Audit complet

   • Toutes les actions sensibles sont loggées
   • Format: qui, quoi, quand, IP, succès/échec

🚧 Statut du Projet

✅ Créé

• Structure des répertoires
• POMs (parent + 3 modules)
• Configuration de base
• Documentation README

🔄 À Créer

Module server-api

• BaseDTO.java
• UserDTO.java, UserSearchCriteria.java, UserSearchResultDTO.java
• RoleDTO.java, RoleAssignmentDTO.java
• AuditLogDTO.java
• Enums (StatutUser, TypeRole)
• Interfaces de services (UserService, RoleService, AuditService, SyncService)
• ValidationConstants.java

Module server-impl-quarkus

• UserResource.java, RoleResource.java, AuditResource.java, HealthResource.java
• UserServiceImpl.java, RoleServiceImpl.java, AuditServiceImpl.java, SyncServiceImpl.java
• KeycloakAdminClient.java (interface + impl)
• KeycloakService.java, SecurityConfig.java
• Entité AuditLog.java (optionnel)
• Repository AuditLogRepository.java (optionnel)
• application.properties (dev + prod)
• Migration Flyway (optionnel)

Module client-quarkus-primefaces-freya

• REST Clients (UserService, RoleService, AuditService)
• DTOs client
• Beans JSF (UserRechercheBean, UserListeBean, UserProfilBean, RoleGestionBean, AuditConsultationBean)
• Filtres de sécurité (JwtTokenManager, AuthenticationFilter, PermissionChecker)
• Pages XHTML (users-search.xhtml, users-list.xhtml, user-profile.xhtml, roles-management.xhtml, audit-logs.xhtml)
• application.properties

Infrastructure

• Helm charts (Chart.yaml, values.yaml, templates/)
• Scripts Keycloak (kcadm-provision.sh, rotate-secrets.sh)
• Dockerfiles (server + client)

Tests

• Tests unitaires (UserServiceImplTest, KeycloakAdminClientTest)
• Tests d'intégration (UserResourceIT, RoleResourceIT avec Testcontainers)

Documentation

• docs/architecture.md
• docs/runbook.md
• docs/security-policy.md
• docs/integration-guide.md

📖 Prochaines Étapes

Pour générer le projet complet, poursuivez dans cet ordre:

1. Créer les DTOs et enums du module server-api
2. Créer les interfaces de services du module server-api
3. Créer les Resources REST du module server-impl
4. Créer les Services impl du module server-impl
5. Créer le KeycloakAdminClient (interface + impl)
6. Créer les REST Clients du module client
7. Créer les Beans JSF du module client
8. Créer les pages XHTML du module client
9. Créer les tests (unitaires + intégration)
10. Créer les Helm charts et scripts

📞 Support

Pour toute question ou problème, consultez:

• Documentation: docs/
• Issues GitHub: [lien à définir]
• Email: support@lions.dev

---

Projet généré avec Claude Code