btpxpress-frontend/OIDC_SECRETS_CONFIGURATION.md

Configuration des Secrets OIDC - BTPXpress Client JSF

✅ Solution définitive au problème "Secret key for encrypting state cookie is less than 16 characters long"

Problème identifié

Quarkus OIDC nécessite TROIS secrets différents pour fonctionner correctement avec PKCE et client confidential:

1. Client Secret - Pour l'authentification auprès de Keycloak
2. State Secret - Pour encrypter le PKCE code verifier dans le state cookie
3. Token Encryption Secret - Pour encrypter les tokens dans les cookies de session

❌ Erreur rencontrée

io.quarkus.runtime.configuration.ConfigurationException:
Secret key for encrypting state cookie is less than 16 characters long

🔍 Cause racine

Quand quarkus.oidc.authentication.pkce-required=true est activé, Quarkus a besoin d'un state-secret de 32 caractères pour encrypter le PKCE code verifier dans le state cookie.

Ce secret est:

• Auto-généré si le client secret fait au moins 32 caractères ET n'est pas explicitement configuré
• OBLIGATOIRE à configurer explicitement si le fallback au client secret ne fonctionne pas

✅ Configuration finale dans application.properties

# 1. Client Secret (32 caractères) - Récupéré depuis Keycloak
quarkus.oidc.credentials.secret=0Ph4e31lQQuonodmLQG3JycehbFL1Hei

# 2. PKCE avec State Secret (32 caractères) - OBLIGATOIRE
quarkus.oidc.authentication.pkce-required=true
# pkce-secret=false car on utilise un state-secret dédié (pas le client secret)
quarkus.oidc.authentication.pkce-secret=false
quarkus.oidc.authentication.state-secret=btpxpress-pkce-state-secret-32ch

# 3. Token Encryption Secret (32+ caractères) - Pour les cookies de session
quarkus.oidc.token-state-manager.split-tokens=true
quarkus.oidc.token-state-manager.strategy=id-refresh-tokens
quarkus.oidc.token-state-manager.encryption-secret=btpxpress-secure-cookie-encryption-key-32chars-2025
quarkus.oidc.token-state-manager.encryption-required=false

📊 Tableau récapitulatif des secrets

Secret	Propriété	Longueur	Valeur	Usage
Client Secret	quarkus.oidc.credentials.secret	32 chars	0Ph4e31lQQuonodmLQG3JycehbFL1Hei	Authentification avec Keycloak
State Secret	quarkus.oidc.authentication.state-secret	32 chars	btpxpress-pkce-state-secret-32c	Encryption PKCE code verifier
Token Encryption	quarkus.oidc.token-state-manager.encryption-secret	32+ chars	btpxpress-secure-cookie-encryption-key-32chars-2025	Encryption tokens dans cookies

🎯 Pourquoi ces 3 secrets?

1. Client Secret (credentials.secret)

• Rôle: Authentifie l'application auprès de Keycloak lors de l'échange du code d'autorisation
• Requis pour: Client confidential (non public)
• Source: Généré par Keycloak et récupéré via script get-client-secret.ps1

2. State Secret (authentication.state-secret)

• Rôle: Encrypte le PKCE code verifier stocké dans le state cookie pendant la redirection OIDC
• Requis pour: PKCE (pkce-required=true)
• Important: Si state-secret est défini, il faut mettre pkce-secret=false. Si pkce-secret=true, le client secret est utilisé et state-secret ne doit PAS être configuré
• Documentation: Quarkus OIDC Code Flow Authentication

3. Token Encryption Secret (token-state-manager.encryption-secret)

• Rôle: Encrypte les tokens ID, access et refresh stockés dans les cookies de session
• Requis pour: Déploiements multi-pods ou quand la taille des cookies dépasse 4096 bytes
• Documentation: Quarkus OIDC Expanded Configuration

🔐 Sécurité en production

⚠️ IMPORTANT: Ne jamais commiter les secrets en production!

Pour la production, utilisez des variables d'environnement:

# production-application.properties
quarkus.oidc.credentials.secret=${KEYCLOAK_CLIENT_SECRET}
quarkus.oidc.authentication.state-secret=${OIDC_STATE_SECRET}
quarkus.oidc.token-state-manager.encryption-secret=${OIDC_TOKEN_ENCRYPTION_SECRET}

Génération de secrets sécurisés

# Linux/Mac
openssl rand -base64 32

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

# Python
python -c "import secrets; print(secrets.token_urlsafe(32)[:32])"

📚 Références officielles

1. GitHub Issue #33532: Clarify startup warning: Secret key for encrypting
2. Quarkus Guide: OpenID Connect authorization code flow
3. Red Hat Documentation: OpenID Connect (OIDC) authentication - Quarkus 3.15

✅ Vérification de la configuration

Pour vérifier que tous les secrets sont correctement configurés:

# Démarrer l'application
mvn quarkus:dev

# Vérifier les logs - vous devriez voir:
# ✓ OIDC enabled
# ✓ Discovered OIDC endpoints from https://security.lions.dev/realms/btpxpress/.well-known/openid-configuration
# ✓ Aucune erreur "Secret key for encrypting state cookie"

🧪 Test du flux OIDC

1. Accéder à http://localhost:8081
2. → Redirection automatique vers https://security.lions.dev
3. → Connexion avec utilisateur existant (admin@btpxpress.dev, etc.)
4. → Validation PKCE code verifier (encrypté avec state-secret)
5. → Échange authorization code contre tokens (avec client secret)
6. → Stockage tokens dans cookies (encryptés avec token-encryption-secret)
7. → Redirection vers /dashboard.xhtml ✅

---

Date de résolution: 2025-11-07 Version Quarkus: 3.15.1 Configuration testée et validée: ✅