Configurer la clé API Claude pour l'analyse IA¶
Vous êtes administrateur·ice d'une instance Kirexo et vous voulez activer l'analyse IA des articles : pour cela, il faut renseigner une clé API Claude. Ce guide couvre les deux opérations nécessaires — fournir la clé de chiffrement, puis saisir la clé API dans les Réglages admin.
Prérequis¶
- Un compte porteur de
ROLE_ADMIN. Pour en provisionner un, voir Créer un compte utilisateur en CLI. - Être connecté·e à l'espace d'administration (
/admin/login). Si ce n'est pas le cas, commencez par vous connecter. - Pour l'étape 1 (fournir la clé de chiffrement) : un accès shell au conteneur
phpen développement, un accès au serveur de production (son environnement de déploiement) en production. - Une clé API Claude valide (obtenue auprès d'Anthropic).
Deux clés à ne pas confondre
- La clé API Claude : le secret fourni par Anthropic qui autorise les appels au modèle. C'est elle que vous saisissez dans les Réglages.
- La clé de chiffrement (
CLAUDE_API_KEY_CIPHER_KEY) : une clé locale à votre instance qui sert uniquement à chiffrer la clé API Claude avant de la stocker en base. Elle vient du vault Symfony Secrets en développement et d'une variable d'environnement du serveur, injectée parcompose.prod.yaml, en production — jamais en clair dans Git. VoirCLAUDE_API_KEY_CIPHER_KEY.
Comment la clé API est protégée¶
La clé API Claude n'est jamais stockée en clair :
- À la saisie, elle est chiffrée applicativement (libsodium,
sodium_crypto_secretbox) par le serviceApp\Service\Security\ClaudeApiKeyCipher(src/Service/Security/ClaudeApiKeyCipher.php). - Seul le ciphertext (base64) est persisté, dans le champ
encryptedClaudeApiKeyde l'entité singletonApp\Entity\Setting(src/Entity/Setting.php). - La clé de chiffrement (32 octets, nommée
CLAUDE_API_KEY_CIPHER_KEY) vient du vault Symfony Secrets en développement et d'une variable d'environnement du serveur, injectée parcompose.prod.yaml, en production — jamais en base, jamais en clair dans Git. - Le champ de saisie est write-only : une fois enregistrée, la clé n'est jamais réaffichée. Pour la changer, on en saisit une nouvelle.
Étape 1 — Fournir la clé de chiffrement¶
La clé de chiffrement est une valeur de 32 octets aléatoires encodés en base64. Elle se fournit une seule fois par environnement, par un mécanisme différent en développement et en production.
En développement (vault dev)¶
-
Si le vault n'existe pas encore, générez les paires de clés :
Les clés publiques générées (
config/secrets/dev/*.encrypt.public.php) sont versionnables. -
Déclarez la clé de chiffrement sans passer par un fichier en clair :
php -r 'echo base64_encode(random_bytes(32));' | bin/console secrets:set CLAUDE_API_KEY_CIPHER_KEY -Le tiret final (
-) indique àsecrets:setde lire la valeur sur l'entrée standard, ce qui évite de l'écrire dans un fichier ou l'historique du shell.
Confirmer la déclaration sans révéler la valeur (dev)
confirme queCLAUDE_API_KEY_CIPHER_KEY est déclaré dans le vault dev, sans afficher sa valeur en clair.
En production (variable d'environnement)¶
En production, la clé ne passe par aucun coffre Symfony Secrets : c'est une variable d'environnement du serveur, injectée dans le conteneur php par compose.prod.yaml, comme APP_SECRET.
-
Générez la valeur une seule fois, sur une machine de confiance :
ou, de façon équivalente :
-
Conservez-la dans le gestionnaire de secrets ou l'environnement de déploiement du serveur, au même endroit que
APP_SECRET. Jamais dans un fichier versionné, jamais dans.env. -
Exportez-la avant de lancer Compose :
export CLAUDE_API_KEY_CIPHER_KEY='<valeur conservée à l’étape 2>' docker compose -f compose.yaml -f compose.prod.yaml pull docker compose -f compose.yaml -f compose.prod.yaml up -dLe déroulé complet du déploiement est décrit dans Déployer Kirexo en production.
-
Si la variable est absente ou vide, Compose refuse de démarrer et affiche le message
CLAUDE_API_KEY_CIPHER_KEY manquante ou vide : …. C'est l'effet de la déclaration obligatoire danscompose.prod.yaml: -
Contrôlez la valeur injectée sans la révéler :
docker compose -f compose.yaml -f compose.prod.yaml exec php \ php -r 'echo strlen(base64_decode((string) getenv("CLAUDE_API_KEY_CIPHER_KEY"), true)), PHP_EOL;'La commande doit afficher
32.
Jamais committée en clair, jamais dans .env
La valeur de CLAUDE_API_KEY_CIPHER_KEY n'est jamais écrite dans un fichier versionné en clair. Le secret stocké par le vault dev est chiffré (illisible sans la clé privée), donc commitable. La variable n'est pas définie dans .env, pour deux raisons :
- en développement, une valeur dans
.envmasquerait le vault ; - en production, Compose lit
.envpour l'interpolation decompose.prod.yaml: une valeur versionnée y satisferait silencieusement la déclaration obligatoire.
Si la clé fuite, considérez la clé API Claude qu'elle protège comme compromise : régénérez la clé de chiffrement et la clé API.
Rotation de la clé de chiffrement
- Changer
CLAUDE_API_KEY_CIPHER_KEYrend illisible la clé API déjà stockée : le ciphertext en base ne se déchiffre plus, etClaudeApiKeyCipher::decrypt()lève une exception au moment de l'analyse. - L'écran des Réglages indique toujours « Une clé est configurée » et le bouton « Analyser la conformité » reste actif :
Setting::hasClaudeApiKey()(src/Entity/Setting.php) ne teste que la présence d'un ciphertext. - Après toute rotation, ressaisissez la clé API dans
/admin/reglages(voir Remplacer une clé existante). La nouvelle saisie est chiffrée avec la nouvelle clé et écrase l'ancienne. - Corollaire : la valeur doit rester stable entre déploiements. N'en régénérez jamais une nouvelle à chaque release.
Étape 2 — Saisir la clé API Claude dans les Réglages¶
- Rendez-vous sur
/admin/reglages(routeapp_admin_settings). L'accès aux Réglages se fait depuis le menu utilisateur de l'en-tête (le corps du dashboard n'expose plus de bouton « Réglages »). -
Repérez la rubrique « Clé API Claude », sous le réglage d'accent. Tant qu'aucune clé n'est configurée, elle affiche :
Aucune clé configurée. L'analyse IA des articles est désactivée tant qu'aucune clé n'est saisie.
-
Saisissez votre clé API Claude dans le champ « Clé API Claude » (champ masqué, type mot de passe : les caractères ne s'affichent pas).
- Cliquez sur « Enregistrer la clé ».
- La page se recharge (motif Post/Redirect/Get) avec le message « Clé API Claude enregistrée. ». Le champ revient vide : la clé n'est jamais réaffichée.
Une fois la clé enregistrée, la rubrique indique :
Une clé est configurée. Saisissez-en une nouvelle pour la remplacer.
Remplacer une clé existante¶
La clé stockée ne se modifie pas : pour la changer, saisissez simplement une nouvelle valeur dans le même champ et cliquez sur « Enregistrer la clé ». La nouvelle clé est chiffrée et écrase l'ancienne.
Vérifier que l'analyse de conformité est activée¶
Le bouton « Analyser la conformité » présent dans le panneau « Analyse de conformité » de la page de détail d'un article publié (/admin/articles/{id}) est désactivé tant qu'aucune clé n'est configurée, avec le message :
Configurez la clé API Claude dans les Réglages pour activer l'analyse.
Une fois la clé enregistrée, ce bouton devient actif. C'est le signe que la configuration est complète. Pour la suite — déclencher une analyse et lire le rapport —, voir Analyser un article avec l'IA (Claude).
L'administration ne voit que le contenu publié
L'espace admin liste et détaille uniquement les articles publiés, sans aucune capacité de rédaction ni de publication. La page de détail où apparaît le bouton d'analyse n'expose donc aucun bouton d'édition. Cette restriction est portée par le ArticleVoter (« Admin ≠ publication »). Voir Espaces utilisateur et admin.
En cas de problème¶
- Erreur 403/404 sur
/admin/reglages. L'accès est réservé àROLE_ADMIN. Pour un visiteur connecté à l'espace utilisateur, l'admin se masque (404) ; connectez-vous sur/admin/login. Voir Architecture des firewalls. - Le formulaire refuse une valeur vide. Le champ est obligatoire : un envoi vide ne change rien et réaffiche le formulaire en erreur. C'est volontaire — on ne « vide » pas une clé via ce champ.
- Le bouton « Analyser la conformité » reste désactivé après enregistrement. Vérifiez que l'étape 1 a bien été faite dans le bon environnement :
- en développement, sans
CLAUDE_API_KEY_CIPHER_KEYvalide dans le vaultdev, le chiffrement ne peut pas s'initialiser. Confirmez la déclaration avecbin/console secrets:list; - en production, un conteneur qui ne démarre pas signale une variable non exportée : Compose affiche
CLAUDE_API_KEY_CIPHER_KEY manquante ou vide : …. Exportez-la puis relancezup -d.
- en développement, sans
- Erreur 500 à l'enregistrement de la clé API. La valeur de
CLAUDE_API_KEY_CIPHER_KEYne décode pas en 32 octets : libsodium refuse une clé de mauvaise taille. Contrôlez-la avec la commande de l'étape 1 (elle doit afficher32) et fournissez une valeur générée comme indiqué. - L'analyse échoue alors qu'une clé est configurée. La clé de chiffrement a changé depuis la saisie de la clé API : voir l'avertissement Rotation de la clé de chiffrement et ressaisissez la clé API.
Voir aussi¶
- Analyser un article avec l'IA (Claude) — déclencher l'analyse et lire le rapport, une fois la clé configurée.
- Référence —
CLAUDE_API_KEY_CIPHER_KEY— rôle, origine (vault en dev, variable d'environnement en prod), format de la clé de chiffrement. - Espaces utilisateur et admin — l'accueil
/u, le dashboard/admin, la page Réglages et la vue admin des articles publiés. - Définir la couleur d'accent de la plateforme — l'autre réglage d'instance de la même page.