Authentification Composer pour les dépôts privés Magento : la configuration qui fonctionne

La plupart des guides d'installation de modules Magento omettent l'étape d'authentification Composer. Ensuite, un développeur se retrouve avec une erreur 401 Non autorisé lors de composer require, fait des recherches pendant une heure et atterrit ici.

Voici la configuration qui fonctionne, rédigée à partir du flux de travail que nous utilisons sur des centaines d'installations.

Le modèle à deux jetons

Magento nécessite deux ensembles de credentials configurés dans Composer :

1. Credentials Adobe Commerce pour repo.magento.com. Le registre Adobe qui contient les paquets de base de Magento.
2. Credentials spécifiques au fournisseur pour tout registre privé tiers. Par exemple, le registre de votre fournisseur de module.

Vous avez besoin des deux. Les credentials Adobe proviennent de votre compte Adobe Commerce. Les credentials du fournisseur proviennent de l'email de livraison de commande.

Où se trouvent les credentials

Deux emplacements sont importants.

Par projet : auth.json à la racine du magasin.

{
  "http-basic": {
    "repo.magento.com": {
      "username": "votre-clé-publique",
      "password": "votre-clé-privée"
    },
    "repo.example-vendor.com": {
      "username": "votre-id-client",
      "password": "votre-clé-de-licence"
    }
  }
}

Global : ~/.composer/auth.json sur la machine du développeur. Même structure. Composer lit d'abord le fichier du projet, puis revient au global.

Pour la production : conservez les credentials dans des variables d'environnement et modélisez auth.json au moment du déploiement. Ne jamais commettre auth.json dans le dépôt. Cela semble évident. C'est aussi l'erreur la plus courante que nous voyons.

Le bloc des dépôts

Dans composer.json sous repositories, ajoutez le registre du fournisseur :

{
  "repositories": {
    "magento": {
      "type": "composer",
      "url": "https://repo.magento.com/"
    },
    "example-vendor": {
      "type": "composer",
      "url": "https://repo.example-vendor.com/"
    }
  }
}

L'ordre est important. Composer scanne les dépôts dans l'ordre déclaré. Si deux registres fournissent le même nom de paquet, le premier l'emporte.

Les trois modes d'échec

Lorsque composer require échoue, la cause est presque toujours l'une de celles-ci.

1. Mauvais type de jeton. La paire de clé publique et de clé privée d'Adobe va uniquement à repo.magento.com. Si vous les avez collées dans l'emplacement du registre du fournisseur, le fournisseur répond avec 401. Correction : vérifiez à nouveau quel credential appartient où.

2. L'URL du registre a changé. Les fournisseurs migrent parfois les domaines de registre. Votre composer.json vieux de six mois pointe vers l'ancienne URL, qui redirige maintenant vers une adresse que Composer ne suit pas. Correction : vérifiez la documentation actuelle du fournisseur pour l'URL du registre.

3. Le pare-feu bloque le registre. Les serveurs de production dans des environnements réseau restrictifs ne peuvent parfois pas atteindre repo.example-vendor.com. Correction : ajoutez le domaine du registre à la liste d'autorisation sortante. Certains fournisseurs offrent une IP statique pour cela.

La variante CI

Dans CI, le modèle de travail est :

COMPOSER_AUTH='{"http-basic":{"repo.magento.com":{"username":"'"$MAGENTO_USERNAME"'","password":"'"$MAGENTO_PASSWORD"'"}}}' composer install

Passez les credentials via des variables d'environnement, construisez le JSON en ligne, exécutez l'installation. Aucun fichier sur le disque, aucun risque de commit accidentel.

Rotation des jetons

Faites tourner les jetons tous les trimestres. La plupart des fournisseurs exposent un bouton "régénérer" dans les paramètres de votre compte. Après rotation :

1. Mettez à jour ~/.composer/auth.json sur chaque machine de développeur et chaque exécuteur CI.
2. Mettez à jour les secrets de production dans le pipeline de déploiement.
3. Exécutez un test composer install sur chaque environnement pour confirmer.

Si un jeton fuit (commit accidentel, capture d'écran dans un ticket de bug, un tiers voyant la console de production), faites tourner immédiatement et auditez le journal d'accès si le fournisseur en expose un.

Quand cela échoue encore

Si vous avez vérifié tout ce qui précède et que Composer rejette toujours l'authentification, demandez au fournisseur d'inspecter ses journaux de serveur pour votre IP. Le 401 cache parfois un 403 d'une règle WAF que le fournisseur d'hébergement a ajoutée sans les en informer. Nous avons débogué ce cas exact trois fois au cours de l'année dernière.