Aller au contenu

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 — générer la clé de chiffrement côté serveur, 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.
  • Un accès shell au conteneur applicatif pour l'étape 1 (génération du secret de vault).
  • 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 vit dans le vault Symfony Secrets, jamais en clair. Voir CLAUDE_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 service App\Service\Security\ClaudeApiKeyCipher (src/Service/Security/ClaudeApiKeyCipher.php).
  • Seul le ciphertext (base64) est persisté, dans le champ encryptedClaudeApiKey de l'entité singleton App\Entity\Setting (src/Entity/Setting.php).
  • La clé de chiffrement (32 octets) vit dans le vault Symfony Secrets sous le nom CLAUDE_API_KEY_CIPHER_KEY — 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 — Générer la clé de chiffrement dans le vault

Cette étape est à faire une seule fois par environnement (et n'a pas à être refaite tant que vous ne régénérez pas le secret).

  1. Si le vault n'existe pas encore, générez les paires de clés :

    bin/console secrets:generate-keys

    Les clés publiques générées (config/secrets/<env>/*.encrypt.public.php) sont versionnables. La clé privée de déchiffrement de prod (*.decrypt.private.php) ne doit jamais être commitée — elle est déjà ignorée par Git.

  2. Déclarez la clé de chiffrement : 32 octets aléatoires encodés en base64, injectés 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:set de lire la valeur sur l'entrée standard, ce qui évite de l'écrire dans un fichier ou l'historique du shell.

  3. Pour la production, répétez la déclaration dans l'environnement prod :

    APP_RUNTIME_ENV=prod php -r 'echo base64_encode(random_bytes(32));' \
    | APP_RUNTIME_ENV=prod bin/console secrets:set CLAUDE_API_KEY_CIPHER_KEY -

Jamais committée en clair

La valeur de CLAUDE_API_KEY_CIPHER_KEY n'est jamais écrite dans un fichier versionné en clair. Le secret stocké par le vault est chiffré (illisible sans la clé privée), donc commitable pour dev. La variable n'est pas définie dans .env (une valeur dans .env masquerait le vault). 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.

Confirmer la déclaration sans révéler la valeur

bin/console secrets:list
confirme que CLAUDE_API_KEY_CIPHER_KEY est déclaré, sans afficher sa valeur en clair.

Étape 2 — Saisir la clé API Claude dans les Réglages

  1. Rendez-vous sur /admin/reglages (route app_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 »).

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

  3. Saisissez votre clé API Claude dans le champ « Clé API Claude » (champ masqué, type mot de passe : les caractères ne s'affichent pas).

  4. Cliquez sur « Enregistrer la clé ».
  5. 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 : sans CLAUDE_API_KEY_CIPHER_KEY valide dans le vault, le chiffrement ne peut pas s'initialiser. Confirmez la déclaration avec bin/console secrets:list.

Voir aussi