lionsdev/lions-user-manager-server-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: nettoyage racine - suppression docs/scripts obsoletes, mise a jour pom.xml et .gitignore

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
lionsdev
2026-02-18 03:27:28 +00:00
parent 91cbede16f
commit 84ca04b3a8
92 changed files with 405 additions and 20287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

571
README.md
View File

@@ -1,502 +1,181 @@
# Lions User Manager
Module de gestion centralisée des utilisateurs via Keycloak Admin REST API.
> Gestion centralisée des utilisateurs via Keycloak Admin API — Backend REST + Frontend JSF PrimeFaces Freya
## 🎯 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
## 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)
├── pom.xml # POM parent (multi-modules)
├── lions-user-manager-server-api/ # Contrats API : DTOs, interfaces, enums
├── lions-user-manager-server-impl-quarkus/ # Serveur REST Quarkus + Keycloak Admin
├── lions-user-manager-client-quarkus-primefaces-freya/ # Client Web JSF + PrimeFaces Freya
└── scripts/ # Scripts DevOps (Keycloak, DB, Git)
```
### Modules
## Stack Technique
#### 1. **server-api** (JAR)
Contrats purs sans dépendances lourdes:
- DTOs avec validation Bean
- Interfaces de services
- Enums métiers
- Constantes de validation
| Composant | Technologie | Version |
|-----------|------------|---------|
| Runtime | Java | 17 |
| Framework | Quarkus | 3.15.1 |
| UI Framework | PrimeFaces (Freya theme) | 14.0.5 |
| Auth | Keycloak (OIDC + Admin API) | 26.0.4 |
| Base de données | PostgreSQL + Hibernate ORM Panache | — |
| Migration DB | Flyway | — |
| Build | Maven | — |
| Tests | JUnit 5, Mockito 5, Testcontainers, REST-Assured | — |
**Package**: `dev.lions.user.manager.server.api`
## Modules
#### 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)
### `server-api`
Contrats partagés entre serveur et client :
- **DTOs** : `UserDTO`, `RoleDTO`, `AuditLogDTO`, `RealmAssignmentDTO`, etc.
- **Interfaces Service** : `UserService`, `RoleService`, `AuditService`, `SyncService`, `RealmAuthorizationService`
- **Enums** : `StatutUser`, `TypeRole`, `TypeActionAudit`
- **Validations** : `ValidationConstants`
**Package**: `dev.lions.user.manager.server`
### `server-impl-quarkus`
API REST backend :
- **Resources** : `UserResource`, `RoleResource`, `AuditResource`, `RealmAssignmentResource`, `SyncResource`, `RealmResource`
- **Services** : Implémentations complètes avec gestion d'erreurs et audit
- **Keycloak Admin Client** : Gestion des utilisateurs, rôles, realms via Keycloak Admin API
- **Health & Metrics** : `/health`, `/metrics` (Prometheus), `/q/swagger-ui`
- **Audit** : Traçabilité des actions sur table PostgreSQL
#### 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
### `client-quarkus-primefaces-freya`
Interface web admin :
- **Pages** : Dashboard, Gestion Utilisateurs (CRUD), Rôles, Audit, Synchronisation, Realm Assignment
- **Beans JSF** : `DashboardBean`, `UserListBean`, `UserCreationBean`, `UserProfilBean`, `RoleGestionBean`, `AuditConsultationBean`, etc.
- **REST Clients** : Communication type-safe avec le serveur via MicroProfile REST Client
- **Thème** : PrimeFaces Freya (enterprise dark/light)
**Package**: `dev.lions.user.manager.client`
## Prérequis
## 🚀 Stack Technique
- **Java 17+**
- **Maven 3.9+**
- **Docker Desktop** (pour Keycloak et PostgreSQL)
- **Keycloak** accessible sur `localhost:8180`
- **PostgreSQL** accessible sur `localhost:5432`
| 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 |
## Démarrage Rapide
## 📂 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)
```properties
# 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)
```properties
# 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`:
### 1. Démarrer l'infrastructure
```bash
#!/bin/bash
# Keycloak
docker run -d --name keycloak -p 8180:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:26.0.4 start-dev
# 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"
# PostgreSQL
docker run -d --name postgres -p 5432:5432 \
-e POSTGRES_USER=skyfile \
-e POSTGRES_PASSWORD=skyfile \
-e POSTGRES_DB=lions_user_manager_dev \
postgres:16
```
## 🧪 Tests
### Tests unitaires
### 2. Configurer Keycloak
```bash
mvn clean test
# Utiliser les scripts dans scripts/
pwsh scripts/setup-keycloak-client.ps1
```
### Tests d'intégration (avec Testcontainers)
### 3. Compiler le projet
```bash
mvn clean verify
mvn clean install -DskipTests
```
### Couverture de code (minimum 80%)
```bash
mvn clean test jacoco:report
# Rapport: target/site/jacoco/index.html
```
## 📦 Build & Run
### Build complet
```bash
mvn clean install
```
### Run server
### 4. Lancer le serveur (port 8081)
```bash
cd lions-user-manager-server-impl-quarkus
mvn quarkus:dev
mvn quarkus:dev -Dquarkus.profile=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
### 5. Lancer le client (port 8082)
```bash
cd lions-user-manager-client-quarkus-primefaces-freya
mvn quarkus:dev
mvn quarkus:dev -Dquarkus.profile=dev
```
Accès:
- UI: http://localhost:8081
## Ports
## 🐳 Docker
| Service | Port | URL |
|---------|------|-----|
| Keycloak | 8180 | http://localhost:8180 |
| Serveur API | 8081 | http://localhost:8081 |
| Client Web | 8082 | http://localhost:8082 |
| Swagger UI | 8081 | http://localhost:8081/q/swagger-ui |
| PostgreSQL | 5432 | — |
### Build images
## Configuration
Chaque module utilise 3 fichiers de configuration Quarkus :
| Fichier | Rôle |
|---------|------|
| `application.properties` | Propriétés communes (tous environnements) |
| `application-dev.properties` | Surcharges développement (ports, logging verbeux, Keycloak local) |
| `application-prod.properties` | Surcharges production (env vars, TLS, logging minimal) |
## Tests
```bash
# 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 .
# Tests unitaires seuls
mvn test
# 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 .
# Tests d'intégration
mvn verify
# Avec couverture JaCoCo
mvn verify -Pjacoco
```
## ☸️ Déploiement Kubernetes (Helm)
## Production
### Variables d'environnement requises
```bash
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
# Keycloak
KEYCLOAK_AUTH_SERVER_URL=https://security.lions.dev/realms/lions-user-manager
KEYCLOAK_SERVER_URL=https://security.lions.dev
KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=<secret>
KEYCLOAK_CLIENT_ID=lions-user-manager-client
# Base de données
DB_HOST=<host>
DB_PORT=5432
DB_NAME=lions_user_manager
DB_USERNAME=<user>
DB_PASSWORD=<secret>
# Sécurité
OIDC_ENCRYPTION_SECRET=<32-char-secret>
CORS_ORIGINS=https://users.lions.dev
# Backend URL (pour le client)
LIONS_USER_MANAGER_BACKEND_URL=https://api.users.lions.dev
```
## 📊 Métriques & Observabilité
### Docker
### Métriques disponibles (Prometheus format)
Chaque module déployable contient un `Dockerfile.prod` :
- `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
```bash
# Build natif
mvn package -Pnative -DskipTests
### Health checks
# Build Docker
docker build -f Dockerfile.prod -t lions-user-manager-server:1.0.0 .
```
- `/health/ready`: Readiness probe
- `/health/live`: Liveness probe
## Licence
## 📚 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éé
- [x] Structure des répertoires
- [x] POMs (parent + 3 modules)
- [x] Configuration de base
- [x] 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**
Propriétaire — Lions Dev Team © 2025