Migration complète vers PrimeFaces Freya - Corrections des incompatibilités et intégration de primefaces-freya-extension
This commit is contained in:
lionsdev
325
CONFIGURATION_GUIDE.md
Normal file
325
CONFIGURATION_GUIDE.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# Guide de Configuration - Lions User Manager
|
||||
|
||||
## 📋 Structure des fichiers de configuration
|
||||
|
||||
Les fichiers de configuration ont été restructurés selon les **best practices Quarkus** :
|
||||
|
||||
```
|
||||
lions-user-manager/
|
||||
├── lions-user-manager-client-quarkus-primefaces-freya/
|
||||
│ └── src/main/resources/
|
||||
│ ├── application.properties # Configuration commune
|
||||
│ ├── application-dev.properties # Configuration DEV
|
||||
│ └── application-prod.properties # Configuration PROD
|
||||
│
|
||||
├── lions-user-manager-server-impl-quarkus/
|
||||
│ └── src/main/resources/
|
||||
│ ├── application.properties # Configuration commune
|
||||
│ ├── application-dev.properties # Configuration DEV
|
||||
│ └── application-prod.properties # Configuration PROD
|
||||
│
|
||||
└── lions-user-manager-server-api/
|
||||
└── (pas de configuration - module DTOs uniquement)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Principe de séparation
|
||||
|
||||
### ✅ Avant (ancien système avec préfixes)
|
||||
```properties
|
||||
# application.properties
|
||||
quarkus.http.port=8080
|
||||
%dev.quarkus.http.port=8082
|
||||
%prod.quarkus.http.port=8080
|
||||
```
|
||||
|
||||
### ✅ Après (nouveau système avec fichiers séparés)
|
||||
|
||||
**application.properties** (commun)
|
||||
```properties
|
||||
quarkus.http.host=0.0.0.0
|
||||
```
|
||||
|
||||
**application-dev.properties**
|
||||
```properties
|
||||
quarkus.http.port=8082
|
||||
```
|
||||
|
||||
**application-prod.properties**
|
||||
```properties
|
||||
quarkus.http.port=8080
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Détail des configurations
|
||||
|
||||
### 1️⃣ lions-user-manager-client-quarkus-primefaces-freya
|
||||
|
||||
#### `application.properties` - Configuration commune
|
||||
Contient :
|
||||
- Configuration HTTP de base (host, session, cookies)
|
||||
- Configuration MyFaces (JSF)
|
||||
- Configuration PrimeFaces (thème, options)
|
||||
- Configuration REST Client (timeouts, scope)
|
||||
- Configuration OIDC de base (redirect path, scopes, rôles)
|
||||
- Chemins publics/protégés
|
||||
- Health checks et Metrics
|
||||
|
||||
#### `application-dev.properties` - Développement
|
||||
Contient :
|
||||
- **Port** : `8082`
|
||||
- **Debug port** : `5006`
|
||||
- **Logging** : DEBUG/TRACE
|
||||
- **OIDC** : Keycloak local `http://localhost:8180/realms/lions-user-manager`
|
||||
- **Backend URL** : `http://localhost:8081`
|
||||
- **CORS** : Permissif (`localhost:8080,8081,8082`)
|
||||
- **Cookies** : Non sécurisés (HTTP autorisé)
|
||||
|
||||
#### `application-prod.properties` - Production
|
||||
Contient :
|
||||
- **Port** : `8080`
|
||||
- **Logging** : WARN/INFO
|
||||
- **OIDC** : Keycloak production `https://security.lions.dev/realms/master`
|
||||
- **Backend URL** : Variable d'environnement `${LIONS_USER_MANAGER_BACKEND_URL}`
|
||||
- **CORS** : Restrictif (via `${CORS_ORIGINS}`)
|
||||
- **Cookies** : Sécurisés (HTTPS uniquement)
|
||||
- **TLS** : Vérification requise
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ lions-user-manager-server-impl-quarkus
|
||||
|
||||
#### `application.properties` - Configuration commune
|
||||
Contient :
|
||||
- Configuration HTTP de base (CORS headers, methods)
|
||||
- Type d'application OIDC : `service`
|
||||
- Configuration Keycloak Admin (pool, timeouts, retry)
|
||||
- Configuration Audit
|
||||
- Configuration Logging (format, rotation)
|
||||
- OpenAPI/Swagger metadata
|
||||
- Health checks et Metrics
|
||||
- Jackson (JSON)
|
||||
|
||||
#### `application-dev.properties` - Développement
|
||||
|
||||
**🔑 Point important : OIDC DÉSACTIVÉ en DEV**
|
||||
|
||||
Contient :
|
||||
- **Port** : `8081`
|
||||
- **Logging** : DEBUG/TRACE
|
||||
- **OIDC** : `quarkus.oidc.enabled=false` ⚠️
|
||||
- Simplifie le développement
|
||||
- Le client JSF reste sécurisé
|
||||
- Commentaires fournis pour réactiver si nécessaire
|
||||
- **Security** : Désactivée (`quarkus.security.auth.enabled=false`)
|
||||
- **Keycloak Admin** : Local `http://localhost:8180/realms/lions-user-manager`
|
||||
- **CORS** : Permissif (`*`)
|
||||
- **Realms autorisés** : `lions-user-manager,btpxpress,master,unionflow`
|
||||
|
||||
#### `application-prod.properties` - Production
|
||||
|
||||
**🔐 Point important : OIDC OBLIGATOIRE en PROD**
|
||||
|
||||
Contient :
|
||||
- **Port** : `8080`
|
||||
- **Logging** : INFO/WARN
|
||||
- **OIDC** : `quarkus.oidc.enabled=true` ✅
|
||||
- Vérification TLS requise
|
||||
- Token validation stricte
|
||||
- Extraction des rôles
|
||||
- **Security** : Activée et stricte
|
||||
- `quarkus.security.auth.enabled=true`
|
||||
- `quarkus.security.jaxrs.deny-unannotated-endpoints=true`
|
||||
- **Keycloak Admin** : Production `https://security.lions.dev/realms/master`
|
||||
- **Database** : PostgreSQL pour audit
|
||||
- **Swagger** : Désactivé
|
||||
- **Performance** : Thread pool optimisé (4-32 threads)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Utilisation
|
||||
|
||||
### Démarrage en mode DEV
|
||||
|
||||
```bash
|
||||
# Backend (port 8081, OIDC désactivé)
|
||||
cd lions-user-manager/lions-user-manager-server-impl-quarkus
|
||||
mvn quarkus:dev
|
||||
|
||||
# Client (port 8082, OIDC activé vers Keycloak local)
|
||||
cd lions-user-manager/lions-user-manager-client-quarkus-primefaces-freya
|
||||
mvn quarkus:dev
|
||||
```
|
||||
|
||||
**Accès** : http://localhost:8082
|
||||
|
||||
### Démarrage en mode PROD
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
mvn clean package -Pprod
|
||||
java -jar target/quarkus-app/quarkus-run.jar
|
||||
|
||||
# Client
|
||||
mvn clean package -Pprod
|
||||
java -jar target/quarkus-app/quarkus-run.jar
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Architecture de sécurité
|
||||
|
||||
### Mode DEV (simplifié)
|
||||
```
|
||||
[Navigateur] → [Client JSF:8082] → [Backend API:8081]
|
||||
↓ OIDC ✗ Pas d'OIDC
|
||||
[Keycloak local]
|
||||
```
|
||||
|
||||
**Avantages** :
|
||||
- ✅ Développement rapide sans configuration Keycloak backend
|
||||
- ✅ Client reste sécurisé (authentification utilisateur)
|
||||
- ✅ Pas de conflit de realms
|
||||
|
||||
**Inconvénients** :
|
||||
- ⚠️ Backend non sécurisé (localhost uniquement)
|
||||
- ⚠️ Différent de la production
|
||||
|
||||
---
|
||||
|
||||
### Mode PROD (sécurisé)
|
||||
```
|
||||
[Navigateur] → [Client JSF:8080] → [Backend API:8080]
|
||||
↓ OIDC ↓ OIDC
|
||||
[Keycloak Production]
|
||||
```
|
||||
|
||||
**Avantages** :
|
||||
- ✅ Défense en profondeur (double validation)
|
||||
- ✅ Traçabilité (qui a fait quoi)
|
||||
- ✅ Zero-trust (backend ne fait confiance à personne)
|
||||
- ✅ Best practice microservices
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Variables d'environnement requises en PROD
|
||||
|
||||
### Client
|
||||
|
||||
```bash
|
||||
LIONS_USER_MANAGER_BACKEND_URL=https://api.lions.dev/user-manager
|
||||
KEYCLOAK_AUTH_SERVER_URL=https://security.lions.dev/realms/master
|
||||
KEYCLOAK_CLIENT_ID=lions-user-manager-client
|
||||
KEYCLOAK_CLIENT_SECRET=<secret-du-client>
|
||||
OIDC_ENCRYPTION_SECRET=<secret-32-chars-minimum>
|
||||
CORS_ORIGINS=https://lions.dev,https://app.lions.dev
|
||||
```
|
||||
|
||||
### Serveur
|
||||
|
||||
```bash
|
||||
KEYCLOAK_CLIENT_SECRET=<secret-du-backend>
|
||||
KEYCLOAK_ADMIN_USERNAME=admin
|
||||
KEYCLOAK_ADMIN_PASSWORD=<mot-de-passe-admin>
|
||||
KEYCLOAK_AUTHORIZED_REALMS=btpxpress,master,unionflow
|
||||
DB_USERNAME=audit_user
|
||||
DB_PASSWORD=<mot-de-passe-db>
|
||||
DB_HOST=lions-db.lions.svc.cluster.local
|
||||
DB_NAME=lions_audit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Réactiver OIDC en DEV (optionnel)
|
||||
|
||||
Si vous voulez tester le flow complet en développement :
|
||||
|
||||
### Étape 1 : Modifier `application-dev.properties` du serveur
|
||||
|
||||
```properties
|
||||
# Commenter cette ligne:
|
||||
# quarkus.oidc.enabled=false
|
||||
|
||||
# Décommenter ces lignes:
|
||||
quarkus.oidc.enabled=true
|
||||
quarkus.oidc.auth-server-url=http://localhost:8180/realms/lions-user-manager
|
||||
quarkus.oidc.tls.verification=none
|
||||
quarkus.oidc.token.issuer=http://localhost:8180/realms/lions-user-manager
|
||||
quarkus.oidc.discovery-enabled=true
|
||||
quarkus.oidc.token.audience=account
|
||||
quarkus.oidc.verify-access-token=true
|
||||
quarkus.oidc.roles.role-claim-path=realm_access/roles
|
||||
quarkus.security.auth.enabled=true
|
||||
```
|
||||
|
||||
### Étape 2 : Configurer Keycloak
|
||||
|
||||
Suivre le guide : `KEYCLOAK_DEV_SETUP.md`
|
||||
|
||||
---
|
||||
|
||||
## ✅ Vérification de la configuration
|
||||
|
||||
### Compilationdes modules
|
||||
|
||||
```bash
|
||||
# Client
|
||||
cd lions-user-manager/lions-user-manager-client-quarkus-primefaces-freya
|
||||
mvn compile -DskipTests
|
||||
|
||||
# Serveur
|
||||
cd lions-user-manager/lions-user-manager-server-impl-quarkus
|
||||
mvn compile -DskipTests
|
||||
```
|
||||
|
||||
### Test rapide
|
||||
|
||||
```bash
|
||||
# Backend health check
|
||||
curl http://localhost:8081/health
|
||||
|
||||
# Client (via navigateur)
|
||||
http://localhost:8082
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Résumé des ports
|
||||
|
||||
| Module | DEV | PROD |
|
||||
|--------|-----|------|
|
||||
| **Client** | 8082 | 8080 |
|
||||
| **Serveur** | 8081 | 8080 |
|
||||
| **Keycloak** | 8180 | 443 |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Erreur : "Propriété non trouvée"
|
||||
✅ Vérifier que le profil est correct : `-Dquarkus.profile=dev` ou `-Pprod`
|
||||
|
||||
### Erreur : "Port already in use"
|
||||
✅ Vérifier qu'un seul module tourne sur chaque port
|
||||
|
||||
### Erreur HTTP 405 en DEV
|
||||
✅ Vérifier que OIDC est désactivé sur le backend DEV
|
||||
|
||||
### Erreur 401 en PROD
|
||||
✅ Vérifier que les secrets Keycloak sont corrects
|
||||
✅ Vérifier que les realms correspondent (client et serveur)
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation complémentaire
|
||||
|
||||
- `KEYCLOAK_DEV_SETUP.md` - Configuration Keycloak pour DEV
|
||||
- `test-keycloak-config.sh` - Script de vérification (Linux/Mac)
|
||||
- `test-keycloak-config.ps1` - Script de vérification (Windows)
|
||||
|
||||
---
|
||||
|
||||
**Dernière mise à jour** : 2025-12-25
|
||||
**Version** : 1.0.0
|
||||
Reference in New Issue
Block a user