Authentifizierung für Maven und Gradle einrichten

Auf dieser Seite wird beschrieben, wie Sie Maven oder Gradle für die Authentifizierung konfigurieren.

Sie müssen sich bei Artifact Registry authentifizieren, wenn Sie eine Drittanbieteranwendung für die Verbindung mit einem Repository verwenden.

Die Authentifizierung für Cloud Build- oder Google Cloud-Laufzeitumgebungen wie Google Kubernetes Engine und Cloud Run muss nicht konfiguriert werden. Sie sollten jedoch prüfen, ob die erforderlichen Berechtigungen konfiguriert wurden. aus. Weitere Informationen finden Sie unter Cloud Build und Bereitstellen in Google Cloud-Laufzeitumgebungen.

Hinweis

  1. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
  2. Installieren und initialisieren Sie das Cloud SDK.
  3. (Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.

Übersicht

Artifact Registry unterstützt die folgenden Authentifizierungsmethoden.

Authentifizierungshelfer verwenden
Diese Option bietet die größte Flexibilität. Wenn Sie den Helper in die Maven- oder Gradle-Konfiguration aufnehmen, sucht Artifact Registry nach Dienstkonto-Anmeldedaten in der Umgebung.
Dienstkontoschlüssel als Anmeldedaten angeben
Verwenden Sie diese Option, wenn eine Anwendung die Standardanmeldedaten für Anwendungen nicht unterstützt, jedoch die Authentifizierung mit einem Nutzernamen und Passwort unterstützt.

Dienstkontoschlüssel sind langlebige Anmeldedaten. Verwenden Sie die folgenden Richtlinien, um den Zugriff auf Ihre Repositories einzuschränken:

  • Verwenden Sie ein dediziertes Dienstkonto für die Interaktion mit Repositories.
  • Erteilen Sie die vom Dienstkonto erforderliche Artifact Registry-Mindestrolle. Weisen Sie z. B. Artifact Registry-Reader einem Dienstkonto zu, das nur Artefakte herunterlädt.
  • Wenn Gruppen in Ihrer Organisation verschiedene Zugriffsebenen für bestimmte Repositories benötigen, erteilen Sie den Zugriff auf Repository-Ebene und nicht auf Projektebene.
  • Folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.

Mit Credential Helper authentifizieren

Artifact Registry bietet einen Maven-Wagen und ein Gradle-Plug-in als Credential Helper. Wenn Sie den Credential Helper verwenden, werden Ihre Anmeldedaten nicht in Ihrem Java-Projekt gespeichert. Stattdessen sucht Artifact Registry in der folgenden Reihenfolge nach Anmeldedaten:

  1. Standardanmeldedaten für Anwendungen (ADC), eine Strategie, die in der folgenden Reihenfolge nach Anmeldedaten sucht:

    1. In der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS definierte Anmeldedaten.

    2. Anmeldedaten, die das Standarddienstkonto für Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine oder Cloud Functions bietet.

  2. Vom Cloud SDK bereitgestellte Anmeldedaten, einschließlich Nutzeranmeldedaten aus dem Befehl gcloud auth application-default login.

Die Variable GOOGLE_APPLICATION_CREDENTIALS macht das Konto für die Authentifizierung explizit, was die Fehlerbehebung vereinfacht. Wenn Sie die Variable nicht verwenden, prüfen Sie, ob alle Konten, die von ADC verwendet werden könnten, die erforderlichen Berechtigungen haben. Das Standarddienstkonto für Compute Engine-VMs, Google Kubernetes Engine-Knoten und Cloud Run-Überarbeitungen hat beispielsweise Lesezugriff auf Repositories. Wenn Sie Uploads aus diesen Umgebungen mit dem Standarddienstkonto vornehmen möchten, müssen Sie die Berechtigungen ändern.

So erstellen Sie ein Dienstkonto und richten die Authentifizierung mithilfe der Umgebungsvariable ein:

  1. Erstellen Sie ein Dienstkonto, das im Namen Ihrer Anwendung agieren soll, oder wählen Sie ein vorhandenes Dienstkonto für die Automatisierung aus.

    Sie benötigen den Speicherort der Dienstkonto-Schlüsseldatei, um damit die Authentifizierung bei Artifact Registry einzurichten. Auf der Seite „Dienstkonten“ können Sie die Schlüssel vorhandener Konten aufrufen und neue Schlüssel erstellen.

    Zur Seite „Dienstkonten“

  2. Gewähren Sie dem Dienstkonto die entsprechende Artifact Registry-Rolle, um den Zugriff auf das Repository zu ermöglichen.

  3. Weisen Sie der Variablen GOOGLE_APPLICATION_CREDENTIALS den Speicherort des Dienstkontoschlüssels zu, damit die Artifact Registry-Credential Helper Ihren Schlüssel beim Herstellen einer Verbindung zu Repositories abrufen können.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    Dabei ist KEY-FILE der Pfad zur Schlüsseldatei des Dienstkontos.

  4. Prüfen Sie die Versionsrichtlinie des Maven-Repositorys.

    Console

    1. Öffnen Sie in der Cloud Console die Seite Repositories.

    Zur Seite „Repositories“

    1. Klicken Sie auf das Repository, bei dem Sie sich authentifizieren möchten.

    Im Abschnitt Details wird die Versionsrichtlinie angezeigt. Wenn das Repository eine Snapshot-Versionsrichtlinie hat, gibt das Feld Snapshot-Überschreibungen zulassen an, ob Snapshots übereinstimmende Snapshot-Versionen im Repository überschreiben können.

    gcloud

    Führen Sie den folgenden Befehl aus, um sich die Beschreibung eines Repositorys anzusehen.

    gcloud artifacts repositories describe REPOSITORY \
         [--project=PROJECT] \
         [--location=LOCATION]
    

    Wo

    Die Ausgabe des Befehls enthält Informationen zur Versionsrichtlinie unter mavenConfig. In diesem Beispiel hat das Repository eine Snapshot-Versionsrichtlinie und Snapshots können keine identischen Versionen im Repository überschreiben.

    Encryption: Google-managed key
    createTime: '2021-10-04T19:39:10.897404Z'
    format: MAVEN
    mavenConfig:
      allowSnapshotOverwrites: false
      versionPolicy: SNAPSHOT
    

    Wenn ein Repository keine Versionsrichtlinie hat, ist der Wert von mavenConfig {}.

  5. Führen Sie den folgenden Befehl aus, um die Repository-Konfiguration zu drucken und sie dem Java-Projekt hinzuzufügen.

    Maven

    gcloud artifacts print-settings mvn \
        [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION]
    

    Wo

    Gradle

    gcloud artifacts print-settings gradle \
        [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION]
    

    Dabei gilt:

    • PROJECT ist die Projekt-ID.
    • REPOSITORY ist die ID oder die vollständig qualifizierte Kennzeichnung für das Repository. Wenn Sie ein Standard-Artifact Registry-Repository konfiguriert haben, wird es verwendet, wenn dieses Flag im Befehl ausgelassen wird.
  6. Java-Projekt konfigurieren

    Maven

    1. Fügen Sie die zurückgegebenen Einstellungen in die entsprechenden Abschnitte der Datei pom.xml für Ihr Maven-Projekt ein. Weitere Informationen zur Struktur der Datei finden Sie in der POM-Referenz zu Maven.

      Das folgende Beispiel gilt für ein Repository, das sowohl Snapshot- als auch Release-Versionen speichert.

      <distributionManagement>
        <snapshotRepository>
          <id>artifact-registry</id>
          <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </snapshotRepository>
        <repository>
          <id>artifact-registry</id>
          <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </repository>
      </distributionManagement>
      
      <repositories>
        <repository>
          <id>artifact-registry</id>
          <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      
      <build>
        <extensions>
          <extension>
            <groupId>com.google.cloud.artifactregistry</groupId>
            <artifactId>artifactregistry-maven-wagon</artifactId>
            <version>2.1.4</version>
          </extension>
        </extensions>
      </build>
      

      Im Abschnitt <build> wird der Artifact Registry-Wagon als Erweiterung deklariert. Informationen zu Wagon finden Sie in der Dokumentation zu den Maven-Tools für Artifact Registry.

    2. Maven löst einige Abhängigkeiten auf, bevor ein in pom.xml definierter Wagen angewendet wird, darunter:

    • Verweise in einem untergeordneten Maven-Projekt auf ein übergeordnetes Projekt mithilfe des <parent>-Elements.
    • In Artifact Registry gespeicherte Plug-in-Abhängigkeiten.

    Wenn Ihr Projekt diese Abhängigkeiten auflösen muss, müssen Sie den Kernerweiterungsmechanismus verwenden, damit Maven übergeordnete POM-Dateien und Plug-ins finden kann.

    Erstellen Sie in Ihrem Projekt die Datei ${maven.projectBasedir}/.mvn/extensions.xml mit folgendem Inhalt. Das Element <extension> definiert den Wagen.

     <extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
       <extension>
         <groupId>com.google.cloud.artifactregistry</groupId>
         <artifactId>artifactregistry-maven-wagon</artifactId>
         <version>2.1.4</version>
       </extension>
     </extensions>
    

    Maven kann jetzt Abhängigkeiten von übergeordneten oder Plug-ins aus Artifact Registry auflösen.

    Gradle

    1. Fügen Sie die Repository-Einstellungen der Datei build.gradle hinzu. Das folgende Beispiel zeigt die relative Position der gedruckten Abschnitte.

      Dieses Beispiel gilt für ein Repository, das sowohl Snapshot- als auch Release-Versionen speichert.

      plugins {
        id "maven-publish"
        id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.4"
      }
      
      publishing {
        publications {
          mavenJava(MavenPublication) {
            groupId 'maven.example.id'
            from components.java
           }
        }
        repositories {
          maven {
            url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          }
        }
      }
      
      • Im Abschnitt plugins wird das Artifact Registry-Plug-in deklariert. Informationen zum Plug-in finden Sie in der Dokumentation zu den Maven-Tools für Artifact Registry.

      • Im Abschnitt publishing werden die hochzuladenden Dateien und das Ziel-Artifact Registry-Repository deklariert. Sie können die Dateiliste im Abschnitt publications aktualisieren, wenn Sie die Datei hochladen können. Informationen zu den Veröffentlichungseinstellungen finden Sie in der Dokumentation zum Maven-Publish-Plug-in.

    2. Wenn Ihr Build Abhängigkeiten enthält, sollten Sie sie in Ihrem Build deklarieren.

    3. Wenn Sie Repositories in der Datei init.gradle oder settings.gradle verwenden möchten, können Sie die Plug-in-Konfiguration in diese Dateien einfügen.

      Fügen Sie für init.gradle die folgende Konfiguration hinzu:

      initscript {
        repositories {
          maven {
            url "https://plugins.gradle.org/m2/"
          }
        }
        dependencies {
          classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.1.4"
        }
      }
      apply plugin: com.google.cloud.artifactregistry.gradle.plugin.ArtifactRegistryGradlePlugin
      

      Fügen Sie für „settings.gradle” die folgende Konfiguration hinzu:

      buildscript {
        repositories {
          maven {
            url "https://plugins.gradle.org/m2/"              }
          }
        dependencies {
          classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.1.4"
        }
      }
      apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
      

Passwortauthentifizierung konfigurieren

Verwenden Sie diesen Ansatz, wenn Ihre Java-Anwendung eine Authentifizierung mit einem angegebenen Nutzernamen und Passwort erfordert.

So erstellen Sie ein Dienstkonto und konfigurieren die Authentifizierung:

  1. Erstellen Sie ein Dienstkonto, das im Namen Ihrer Anwendung agieren soll, oder wählen Sie ein vorhandenes Dienstkonto für die CI/CD-Automatisierung aus.

  2. Gewähren Sie dem Dienstkonto die entsprechende Artifact Registry-Rolle, um den Zugriff auf das Repository zu ermöglichen.

  3. Prüfen Sie die Versionsrichtlinie des Maven-Repositorys.

    1. Öffnen Sie in der Cloud Console die Seite Repositories.

      Zur Seite „Repositories“

    2. Klicken Sie auf das Repository, bei dem Sie sich authentifizieren möchten.

      Im Abschnitt Details wird die Versionsrichtlinie angezeigt. Wenn das Repository eine Snapshot-Versionsrichtlinie hat, gibt das Feld Snapshot-Überschreibungen zulassen an, ob Snapshots übereinstimmende Snapshot-Versionen im Repository überschreiben können.

  4. Wenn Sie das Dienstkonto in der aktuellen Cloud SDK-Sitzung aktivieren möchten, führen Sie den folgenden Befehl aus:

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
    

    Dabei gilt:

    • ACCOUNT ist das Nutzer- oder Dienstkonto.
    • KEY-FILE ist der Pfad zur JSON-Schlüsseldatei des Dienstkontos.
  5. Führen Sie den folgenden Befehl aus, um die Repository-Konfiguration zu drucken und sie dem Java-Projekt hinzuzufügen.

    Maven

    gcloud artifacts print-settings mvn \
        [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION] \
        --json-key=KEY-FILE \
        [--version-policy=VERSION-POLICY] \
        [--allow-snapshot-overwrites]
    

    Wo

    • PROJECT ist die Projekt-ID. Wenn dieses Flag nicht angegeben ist, wird das aktuelle Projekt oder das Standardprojekt verwendet.
    • REPOSITORY ist die ID des Repositorys. Wenn Sie ein Standard-Artifact Registry-Repository konfiguriert haben, wird es verwendet, wenn dieses Flag im Befehl ausgelassen wird.
    • LOCATION ist der regionale oder multiregionale Standort für das Repository.
    • KEY-FILE ist der Pfad zur JSON-Schlüsseldatei des Dienstkontos.
    • VERSION-POLICY Die Versionsrichtlinie des Repositorys.

      • None – Keine Versionsrichtlinie. Das Repository speichert sowohl Snapshot- als auch Release-Pakete.
      • Release: Das Repository hat eine Release-Versionsrichtlinie.
      • Snapshot: Das Repository hat eine Snapshot-Versionsrichtlinie.
    • --allow-snapshot-overwrites gibt an, dass das Repository das Überschreiben vorhandener Snapshot-Versionen unterstützt.

    Gradle

    gcloud artifacts print-settings gradle \
        [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION] \
        --json-key=KEY-FILE \
        [--version-policy=VERSION-POLICY] \
        [--allow-snapshot-overwrites]
    

    Dabei gilt:

    • PROJECT ist die Projekt-ID.
    • REPOSITORY ist die ID oder die vollständig qualifizierte Kennzeichnung für das Repository. Wenn Sie ein Standard-Artifact Registry-Repository konfiguriert haben, wird es verwendet, wenn dieses Flag im Befehl ausgelassen wird.
    • KEY-FILE ist der Pfad zur JSON-Schlüsseldatei des Dienstkontos. Wenn Sie den Befehl zur Aktivierung Ihres Dienstkontos ausgeführt haben, können Sie dieses Flag weglassen.
    • VERSION-POLICY Die Versionsrichtlinie des Repositorys.

      • None – Keine Versionsrichtlinie. Das Repository speichert sowohl Snapshot- als auch Release-Pakete.
      • Release: Das Repository hat eine Release-Versionsrichtlinie.
      • Snapshot: Das Repository hat eine Snapshot-Versionsrichtlinie.
    • --allow-snapshot-overwrites gibt an, dass das Repository das Überschreiben vorhandener Snapshot-Versionen unterstützt.

  6. Konfigurieren Sie Ihr Java-Projekt mit den vom Befehl zurückgegebenen Einstellungen.

    Maven

    1. Fügen Sie die zurückgegebenen Repository-Einstellungen im Element <project> den entsprechenden Abschnitten der Datei pom.xml für Ihr Maven-Projekt hinzu. Weitere Informationen zur Struktur der Datei finden Sie in der POM-Referenz zu Maven.
    <project>
      <distributionManagement>
        <snapshotRepository>
          <id>artifact-registry</id>
          <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </snapshotRepository>
        <repository>
          <id>artifact-registry</id>
          <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </repository>
      </distributionManagement>
    
      <repositories>
        <repository>
          <id>artifact-registry</id>
          <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </project>
    
    1. Fügen Sie die zurückgegebenen Authentifizierungseinstellungen im Element <settings> zum Abschnitt <servers> der Datei ~/.m2/settings.xml hinzu. Im folgenden Beispiel ist KEY der private Schlüssel in der Dienstkontoschlüsseldatei.

    Weitere Informationen finden Sie in der Referenz zu Maven-Einstellungen.

    <settings>
      <servers>
        <server>
          <id>artifact-registry</id>
          <configuration>
            <httpConfiguration>
              <get>
                <usePreemptive>true</usePreemptive>
              </get>
              <head>
                <usePreemptive>true</usePreemptive>
              </head>
              <put>
                <params>
                  <property>
                    <name>http.protocol.expect-continue</name>
                    <value>false</value>
                  </property>
                </params>
              </put>
            </httpConfiguration>
          </configuration>
          <username>_json_key_base64</username>
          <password>KEY</password>
        </server>
      </servers>
    </settings>
    

    Gradle

    1. Die folgende Zeile aus der zurückgegebenen Konfiguration definiert eine Variable mit dem Namen artifactRegistryMavenSecret für Ihren Dienstkontoschlüssel. Fügen Sie diese Zeile der Datei ~/.gradle/gradle.properties hinzu, damit der Schlüssel in den Builds oder Ihrem Quellkontroll-Repository nicht sichtbar ist.

      artifactRegistryMavenSecret = KEY
      

      In dieser Zeile ist KEY der private Schlüssel in der Dienstkontoschlüsseldatei. Für _json_key_base64 enthält das artifactRegistry MavenSecret das base64-verschlüsselte Passwort. Beispiel: base64 -w 0 KEY.

    2. Geben Sie in build.gradle die Repository-Einstellungen an:

      plugins {
        id "maven-publish"
      }
      
      publishing {
        repositories {
          maven {
            url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
            credentials {
              username = "_json_key_base64"
              password = "$artifactRegistryMavenSecret"
            }
            authentication {
              basic(BasicAuthentication)
            }
          }
        }
      }
      repositories {
        maven {
          url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          credentials {
            username = "_json_key_base64"
            password = "$artifactRegistryMavenSecret"
          }
          authentication {
            basic(BasicAuthentication)
          }
        }
      }
      

    Die Authentifizierungskonfiguration ist abgeschlossen. Prüfen Sie vor dem Veröffentlichen von Dateien, ob die hochzuladenden Dateien in einem publications-Abschnitt unter publishing definiert sind. Beispiel:

    publishing {
    publications {
         mavenJava(MavenPublication) {
            groupId 'maven.example.id'
            from components.java
         }
    }
    repositories {
    ...
    }
    }
    

    Informationen zu den Veröffentlichungseinstellungen finden Sie in der Dokumentation zu [Maven-Veröffentlichungs-Plug-in][maven-publish-plugin]{:class="external"}.

Nächste Schritte