lions-user-manager-server-api/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)

```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`:

```bash
#!/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

```bash
mvn clean test
```

### Tests d'intégration (avec Testcontainers)

```bash
mvn clean verify
```

### 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

```bash
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

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

Accès:
- UI: http://localhost:8081

## 🐳 Docker

### Build images

```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 .

# 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)

```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
```

## 📊 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éé
- [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**