Composer-Authentifizierung für private Magento-Repositories: die funktionierende Einrichtung

Die meisten Installationsanleitungen für Magento-Module überspringen den Schritt zur Composer-Authentifizierung. Dann erhält ein Entwickler einen 401 Unauthorized bei composer require, googelt eine Stunde lang und landet hier.

Dies ist die funktionierende Einrichtung, basierend auf dem Workflow, den wir bei Hunderten von Installationen verwenden.

Das Zwei-Token-Modell

Magento benötigt zwei Sätze von Anmeldeinformationen, die in Composer konfiguriert sind:

1. Adobe Commerce-Anmeldeinformationen für repo.magento.com. Das Adobe-Register, das die Magento-Kernpakete enthält.
2. Anmeldeinformationen des Anbieters für jedes private Drittanbieter-Register. Zum Beispiel das Register Ihres Modul-Lieferanten.

Sie benötigen beide. Die Adobe-Anmeldeinformationen stammen von Ihrem Adobe Commerce-Konto. Die Anbieter-Anmeldeinformationen erhalten Sie vom Lieferanten mit der Bestellbestätigungs-E-Mail.

Wo die Anmeldeinformationen gespeichert sind

Zwei Standorte sind wichtig.

Pro Projekt: auth.json im Stammverzeichnis des Shops.

{
  "http-basic": {
    "repo.magento.com": {
      "username": "your-public-key",
      "password": "your-private-key"
    },
    "repo.example-vendor.com": {
      "username": "your-customer-id",
      "password": "your-license-key"
    }
  }
}

Global: ~/.composer/auth.json auf der Entwicklermaschine. Gleiche Struktur. Composer liest zuerst die Projektdatei und greift dann auf die globale Datei zurück.

Für die Produktion: Halten Sie die Anmeldeinformationen in Umgebungsvariablen und erstellen Sie auth.json zur Bereitstellungszeit. Niemals auth.json in das Repository einpflegen. Das klingt offensichtlich. Es ist auch der häufigste Fehler, den wir sehen.

Der Repositories-Block

Fügen Sie in composer.json unter repositories das Register des Anbieters hinzu:

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

Die Reihenfolge ist wichtig. Composer durchsucht die Repositories in der deklarierten Reihenfolge. Wenn zwei Registries denselben Paketnamen bereitstellen, gewinnt die erste.

Die drei Fehlerarten

Wenn composer require fehlschlägt, ist die Ursache fast immer eine dieser drei.

1. Falscher Token-Typ. Adobes Public-Key plus Private-Key-Paar gehört nur zu repo.magento.com. Wenn Sie diese in das Register des Anbieters eingefügt haben, antwortet der Anbieter mit 401. Lösung: Überprüfen Sie, welche Anmeldeinformationen wo hingehören.

2. Die URL des Registers hat sich geändert. Anbieter migrieren manchmal die Registrierungsdomänen. Ihr sechs Monate altes composer.json verweist auf die alte URL, die jetzt eine Weiterleitung bereitstellt, die Composer nicht folgt. Lösung: Überprüfen Sie die aktuelle Dokumentation des Anbieters für die URL des Registers.

3. Firewall blockiert das Register. Produktionsserver in restriktiven Netzwerkumgebungen können manchmal repo.example-vendor.com nicht erreichen. Lösung: Fügen Sie die Registrierungsdomäne zur ausgehenden Erlaubenliste hinzu. Einige Anbieter bieten dafür eine statische IP an.

Die CI-Variante

In CI ist das Arbeitsmuster:

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

Geben Sie Anmeldeinformationen über Umgebungsvariablen an, erstellen Sie das JSON inline und führen Sie die Installation aus. Keine Datei auf der Festplatte, kein Risiko eines versehentlichen Commits.

Token-Rotation

Rotieren Sie die Tokens vierteljährlich. Die meisten Anbieter bieten einen "regenerieren"-Button in Ihren Kontoeinstellungen an. Nach der Rotation:

1. Aktualisieren Sie ~/.composer/auth.json auf jeder Entwicklermaschine und jedem CI-Runner.
2. Aktualisieren Sie die Produktionsgeheimnisse in der Bereitstellungspipeline.
3. Führen Sie einen Test composer install in jeder Umgebung durch, um dies zu bestätigen.

Wenn ein Token durchdringt (versehentlicher Commit, Screenshot in einem Bug-Ticket, ein Dritter sieht die Produktionskonsole), rotieren Sie sofort und überprüfen Sie das Zugriffsprotokoll, falls der Anbieter eines bereitstellt.

Wenn dies immer noch fehlschlägt

Wenn Sie alles oben Genannte überprüft haben und Composer die Authentifizierung immer noch ablehnt, bitten Sie den Anbieter, seine Serverprotokolle für Ihre IP zu überprüfen. Der 401 verbirgt manchmal einen 403 von einer WAF-Regel, die der Hosting-Anbieter des Anbieters hinzugefügt hat, ohne ihn darüber zu informieren. Wir haben diesen genauen Fall im letzten Jahr dreimal debuggt.