lions-user-manager/PREPARATION_PRODUCTION.md

# 🚀 Guide de Préparation Production - Lions User Manager

**Date**: 2025-01-15  
**Version**: 1.0.0  
**Statut**: ⚠️ **OBLIGATOIRE AVANT DÉPLOIEMENT**

---

## ⚠️ IMPORTANT

**NE PAS DÉPLOYER** avant d'avoir complété toutes les étapes de ce guide. Le déploiement échouera si :
- ❌ Keycloak n'est pas configuré (clients, rôles, utilisateurs)
- ❌ La base de données PostgreSQL n'existe pas
- ❌ Les secrets et variables d'environnement ne sont pas configurés

---

## 📋 Table des Matières

1. [Prérequis](#prérequis)
2. [Configuration Keycloak Production](#configuration-keycloak-production)
3. [Configuration Base de Données PostgreSQL](#configuration-base-de-données-postgresql)
4. [Préparation des Secrets](#préparation-des-secrets)
5. [Vérification Pré-Déploiement](#vérification-pré-déploiement)
6. [Checklist Complète](#checklist-complète)

---

## 1. Prérequis

### Infrastructure Requise

- ✅ **Keycloak** : Accessible sur `https://security.lions.dev`
- ✅ **PostgreSQL** : Base de données disponible dans le cluster Kubernetes
- ✅ **Accès SSH** : Accès au VPS/cluster pour exécuter les commandes
- ✅ **kubectl** : Configuré et connecté au cluster de production
- ✅ **kcadm.sh** : Keycloak Admin CLI (optionnel, pour scripts)

### Accès Requis

- ✅ Accès admin à Keycloak (`master` realm)
- ✅ Accès admin au cluster Kubernetes
- ✅ Accès à la base de données PostgreSQL

---

## 2. Configuration Keycloak Production

### 2.1. Créer le Realm (si nécessaire)

Le realm `master` est utilisé par défaut pour gérer tous les autres realms.

**Vérification** :
```bash
# Via Keycloak Admin Console
https://security.lions.dev/admin
# Realm: master
# User: admin
```

### 2.2. Créer les Clients OIDC

#### Client Frontend (`lions-user-manager-client`)

**Configuration requise** :
- **Client ID** : `lions-user-manager-client`
- **Type** : `public` (ou `confidential` avec secret)
- **Realm** : `master`
- **Redirect URIs** :
  - `https://user-manager.lions.dev/*`
  - `https://admin.lions.dev/*`
  - `https://user-manager.lions.dev/auth/callback`
- **Web Origins** :
  - `https://user-manager.lions.dev`
  - `https://admin.lions.dev`
- **Standard Flow** : ✅ Activé
- **Direct Access Grants** : ❌ Désactivé (sécurité)
- **Service Accounts** : ❌ Désactivé
- **PKCE** : ✅ Activé (recommandé)

**Script PowerShell** : `scripts/setup-keycloak-production.ps1` (à créer)

#### Client Backend (`lions-user-manager`)

**Configuration requise** :
- **Client ID** : `lions-user-manager`
- **Type** : `confidential` (avec secret)
- **Realm** : `master`
- **Service Accounts** : ✅ Activé (OBLIGATOIRE)
- **Standard Flow** : ❌ Désactivé
- **Direct Access Grants** : ✅ Activé (pour service account)
- **Authorization** : ✅ Activé

**Rôles à assigner au Service Account** :
- `admin` (dans le realm `master`)
- Ou créer un rôle spécifique `lions-user-manager-service` avec les permissions nécessaires

**Script PowerShell** : `scripts/setup-keycloak-production.ps1` (à créer)

### 2.3. Créer les Rôles Realm

Les rôles suivants doivent exister dans le realm `master` :

| Rôle | Description | Utilisation |
|------|-------------|-------------|
| `admin` | Administrateur système | Accès complet à tous les endpoints |
| `user_manager` | Gestionnaire utilisateur | CRUD utilisateurs |
| `user_viewer` | Visualiseur utilisateur | Lecture seule utilisateurs |
| `auditor` | Auditeur | Consultation logs d'audit |
| `sync_manager` | Gestionnaire synchronisation | Gestion synchronisation |
| `role_manager` | Gestionnaire rôles | CRUD rôles |
| `role_viewer` | Visualiseur rôles | Lecture seule rôles |

**Script** : `scripts/setup-keycloak-roles-production.ps1` (à créer)

### 2.4. Configurer les Protocol Mappers

**Client Scope** : `roles` (déjà existant dans Keycloak)

**Vérifier que le mapper inclut** :
- ✅ `realm_access.roles` dans l'access token
- ✅ `roles` dans l'id token (optionnel)

**Configuration** :
1. Aller dans **Client Scopes** → `roles`
2. Onglet **Mappers**
3. Vérifier que `realm roles` existe et est configuré pour l'access token

### 2.5. Créer un Utilisateur de Test (Optionnel)

Pour tester l'application en production :

- **Username** : `admin-user-manager`
- **Email** : `admin-user-manager@lions.dev`
- **Password** : (générer un mot de passe fort)
- **Rôles** : Assigner `admin`, `user_manager`, `auditor`

---

## 3. Configuration Base de Données PostgreSQL

### 3.1. Créer la Base de Données

**Nom** : `lions_audit`

**Script PowerShell** : `scripts/setup-database-production.ps1` (à créer)

**Commandes manuelles** :
```bash
# Se connecter au pod PostgreSQL
kubectl exec -it -n postgresql <postgres-pod-name> -- psql -U <postgres-user> -d postgres

# Créer la base de données
CREATE DATABASE lions_audit OWNER <postgres-user>;

# Créer l'utilisateur (si nécessaire)
CREATE USER lions_audit_user WITH PASSWORD '<strong-password>';

# Octroyer les privilèges
GRANT ALL PRIVILEGES ON DATABASE lions_audit TO lions_audit_user;

# Se connecter à la nouvelle base
\c lions_audit

# Vérifier les privilèges
\l
```

### 3.2. Vérifier les Migrations Flyway

Les migrations Flyway seront exécutées automatiquement au démarrage du backend si :
- `quarkus.flyway.migrate-at-start=true` (déjà configuré dans `application-prod.properties`)

**Vérification** :
- Les fichiers de migration sont dans `lions-user-manager-server-impl-quarkus/src/main/resources/db/migration/`
- Flyway créera automatiquement les tables nécessaires

### 3.3. Configuration de Connexion

**Variables d'environnement requises** :
```bash
DB_HOST=lions-db.lions.svc.cluster.local  # Service Kubernetes
DB_PORT=5432
DB_NAME=lions_audit
DB_USERNAME=lions_audit_user
DB_PASSWORD=<strong-password>
```

---

## 4. Préparation des Secrets

### 4.1. Secrets Keycloak

#### Frontend Client Secret

**Où le trouver** :
1. Keycloak Admin Console → **Clients** → `lions-user-manager-client`
2. Onglet **Credentials**
3. Copier le **Secret** (si client confidential)

**Si client public** : Pas de secret nécessaire

#### Backend Service Account Secret

**Où le trouver** :
1. Keycloak Admin Console → **Clients** → `lions-user-manager`
2. Onglet **Credentials**
3. Copier le **Secret**

#### OIDC Encryption Secret

**Générer un secret de 32 caractères minimum** :
```bash
# Linux/Mac
openssl rand -base64 32

# PowerShell
-join ((48..57) + (65..90) + (97..122) | Get-Random -Count 32 | ForEach-Object {[char]$_})
```

**Stockage** : À stocker dans Kubernetes Secret

### 4.2. Secrets Base de Données

**Générer un mot de passe fort** :
```bash
# Linux/Mac
openssl rand -base64 24

# PowerShell
-join ((48..57) + (65..90) + (97..122) | Get-Random -Count 24 | ForEach-Object {[char]$_})
```

### 4.3. Créer les Kubernetes Secrets

**Namespace** : `lions-user-manager` (ou `applications`)

**Secret pour Frontend** :
```yaml
apiVersion: v1
kind: Secret
metadata:
  name: lions-user-manager-client-secrets
  namespace: lions-user-manager
type: Opaque
stringData:
  KEYCLOAK_CLIENT_SECRET: <frontend-client-secret>
  OIDC_ENCRYPTION_SECRET: <32-char-encryption-secret>
  LIONS_USER_MANAGER_BACKEND_URL: https://api.lions.dev/lions-user-manager
```

**Secret pour Backend** :
```yaml
apiVersion: v1
kind: Secret
metadata:
  name: lions-user-manager-server-secrets
  namespace: lions-user-manager
type: Opaque
stringData:
  KEYCLOAK_CLIENT_SECRET: <backend-service-account-secret>
  KEYCLOAK_ADMIN_USERNAME: <keycloak-admin-username>
  KEYCLOAK_ADMIN_PASSWORD: <keycloak-admin-password>
  DB_PASSWORD: <database-password>
  SSL_KEYSTORE_PASSWORD: <ssl-keystore-password>
```

---

## 5. Vérification Pré-Déploiement

### 5.1. Vérifier Keycloak

```bash
# Tester la connexion Keycloak
curl -k https://security.lions.dev/realms/master/.well-known/openid-configuration

# Tester l'obtention d'un token (service account)
curl -X POST https://security.lions.dev/realms/master/protocol/openid-connect/token \
  -d "client_id=lions-user-manager" \
  -d "client_secret=<secret>" \
  -d "grant_type=client_credentials"
```

### 5.2. Vérifier la Base de Données

```bash
# Tester la connexion PostgreSQL
kubectl exec -it -n postgresql <postgres-pod-name> -- psql -U lions_audit_user -d lions_audit -c "SELECT version();"
```

### 5.3. Vérifier les Secrets Kubernetes

```bash
# Lister les secrets
kubectl get secrets -n lions-user-manager

# Vérifier un secret (sans afficher les valeurs)
kubectl describe secret lions-user-manager-client-secrets -n lions-user-manager
```

---

## 6. Checklist Complète

### ✅ Configuration Keycloak

- [ ] Realm `master` accessible
- [ ] Client frontend `lions-user-manager-client` créé
- [ ] Client backend `lions-user-manager` créé avec service account
- [ ] Secret frontend récupéré (si client confidential)
- [ ] Secret backend (service account) récupéré
- [ ] Rôles créés : `admin`, `user_manager`, `user_viewer`, `auditor`, `sync_manager`, `role_manager`, `role_viewer`
- [ ] Rôles assignés au service account backend
- [ ] Protocol mapper `roles` configuré pour inclure `realm_access.roles`
- [ ] Utilisateur de test créé (optionnel)
- [ ] Test de connexion Keycloak réussi

### ✅ Configuration Base de Données

- [ ] Base de données `lions_audit` créée
- [ ] Utilisateur `lions_audit_user` créé
- [ ] Privilèges accordés
- [ ] Test de connexion réussi
- [ ] Migrations Flyway prêtes (fichiers dans `db/migration/`)

### ✅ Secrets et Configuration

- [ ] Secret OIDC encryption généré (32+ caractères)
- [ ] Secrets Kubernetes créés (frontend + backend)
- [ ] Variables d'environnement documentées
- [ ] ConfigMaps Kubernetes préparés (si nécessaire)

### ✅ Infrastructure

- [ ] Namespace Kubernetes créé
- [ ] Ingress configuré (si exposition externe)
- [ ] Certificats TLS/SSL préparés
- [ ] Health checks configurés

### ✅ Tests

- [ ] Test Keycloak : Obtenir un token service account
- [ ] Test Database : Connexion PostgreSQL
- [ ] Test Secrets : Vérifier les secrets Kubernetes

---

## 7. Scripts de Configuration

### 7.1. Script Keycloak Production

**Fichier** : `scripts/setup-keycloak-production.ps1` ✅ **CRÉÉ**

Ce script :
1. ✅ Se connecte à Keycloak production (`https://security.lions.dev`)
2. ✅ Crée les clients OIDC (frontend + backend)
3. ✅ Crée les rôles realm (admin, user_manager, user_viewer, auditor, sync_manager, role_manager, role_viewer)
4. ✅ Vérifie le protocol mapper `roles`
5. ✅ Assigne les rôles au service account backend
6. ✅ Affiche les secrets récupérés

**Utilisation** :
```powershell
.\scripts\setup-keycloak-production.ps1 `
    -AdminUsername "admin" `
    -AdminPassword "your-admin-password"
```

### 7.2. Script Base de Données Production

**Fichier** : `scripts/setup-database-production.ps1` ✅ **CRÉÉ**

Ce script :
1. ✅ Se connecte au cluster Kubernetes via SSH
2. ✅ Trouve le pod PostgreSQL
3. ✅ Crée la base de données `lions_audit`
4. ✅ Crée l'utilisateur `lions_audit_user`
5. ✅ Octroie les privilèges
6. ✅ Teste la connexion

**Utilisation** :
```powershell
.\scripts\setup-database-production.ps1 `
    -VpsHost "lions@176.57.150.2" `
    -DatabasePassword "strong-password-123"
```

### 7.3. Script Création Secrets Kubernetes

**Fichier** : `scripts/create-kubernetes-secrets-production.ps1` ✅ **CRÉÉ**

Ce script :
1. ✅ Crée le namespace si nécessaire
2. ✅ Crée le secret frontend (KEYCLOAK_CLIENT_SECRET, OIDC_ENCRYPTION_SECRET, LIONS_USER_MANAGER_BACKEND_URL)
3. ✅ Crée le secret backend (KEYCLOAK_CLIENT_SECRET, KEYCLOAK_ADMIN_PASSWORD, DB_PASSWORD)
4. ✅ Vérifie la création des secrets

**Utilisation** :
```powershell
.\scripts\create-kubernetes-secrets-production.ps1 `
    -VpsHost "lions@176.57.150.2" `
    -FrontendClientSecret "<frontend-secret>" `
    -BackendClientSecret "<backend-secret>" `
    -OidcEncryptionSecret "<32-char-secret>" `
    -KeycloakAdminPassword "<admin-password>" `
    -DatabasePassword "<db-password>"
```

---

## 8. Ordre d'Exécution

**IMPORTANT** : Respecter cet ordre :

1. ✅ **Configuration Keycloak** (clients, rôles, secrets)
2. ✅ **Configuration Base de Données** (création DB, utilisateur)
3. ✅ **Création Secrets Kubernetes** (secrets, configmaps)
4. ✅ **Vérification** (tests de connexion)
5. ✅ **Déploiement** (via lionsctl ou kubectl)

---

## 9. Commandes de Déploiement (APRÈS Configuration)

Une fois toutes les configurations terminées :

**Server (Backend)** :
```bash
cd ../lions-infrastructure-2025/lionsctl
./lionsctl.exe pipeline -u https://git.lions.dev/lionsdev/lions-user-manager-server-impl-quarkus -b main -j 17 -e production -c k2 -m gbanedahoud@gmail.com
```

**Client (Frontend)** :
```bash
cd ../lions-infrastructure-2025/lionsctl
./lionsctl.exe pipeline -u https://git.lions.dev/lionsdev/lions-user-manager-client-quarkus-primefaces-freya -b main -j 17 -e production -c k2 -m gbanedahoud@gmail.com
```

---

## 10. Troubleshooting

### Erreur : "401 Unauthorized" lors du démarrage

**Cause** : Secret Keycloak incorrect ou client non configuré
**Solution** : Vérifier les secrets dans Keycloak et Kubernetes

### Erreur : "Database connection failed"

**Cause** : Base de données non créée ou credentials incorrects
**Solution** : Vérifier la création de la DB et les credentials

### Erreur : "Roles not found in token"

**Cause** : Protocol mapper non configuré
**Solution** : Vérifier le mapper `roles` dans Keycloak

---

## ✅ Conclusion

**NE PAS DÉPLOYER** avant d'avoir complété toutes les étapes de ce guide.

**Ordre** :
1. ⚠️ Configuration Keycloak (OBLIGATOIRE)
2. ⚠️ Configuration Base de Données (OBLIGATOIRE)
3. ⚠️ Création Secrets Kubernetes (OBLIGATOIRE)
4. ✅ Vérification (OBLIGATOIRE)
5. 🚀 Déploiement (après vérification)

---

**Document généré le** : 2025-01-15  
**Dernière mise à jour** : 2025-01-15

**Scripts créés** :
- ✅ `scripts/setup-keycloak-production.ps1` : Configuration Keycloak
- ✅ `scripts/setup-database-production.ps1` : Configuration PostgreSQL
- ✅ `scripts/create-kubernetes-secrets-production.ps1` : Création secrets Kubernetes

**Prochaine étape** : Exécuter les scripts dans l'ordre indiqué ci-dessus