为 Maven 和 Gradle 配置向 Artifact Registry 进行身份验证

当您使用第三方应用连接到 Artifact Registry 代码库时，您必须进行 Artifact Registry 身份验证。本文档重点介绍了 Maven 和 Gradle 的配置。

您无需为 Cloud Build 或 Google Kubernetes Engine 和 Cloud Run 等运行时环境配置身份验证，但应验证是否已配置所需的权限。 Google Cloud如需了解详情，请参阅有关 Cloud Build 和部署到 Google Cloud 运行时环境的信息。

准备工作

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. （可选）为 gcloud 命令配置默认值。

  3. 如果您要使用标准代码库配置身份验证，请验证版本政策，以便针对您可以上传的 Java 软件包类型正确配置 Maven 项目。

    控制台

    1. 在 Google Cloud 控制台中打开制品库页面。

      打开“代码库”页面

    2. 点击您要进行身份验证的代码库。

      详细信息部分会显示版本政策。如果代码库具有快照版本政策，允许快照覆盖字段会指明快照是否可以覆盖代码库中匹配的快照版本。

    gcloud

    运行以下命令可查看代码库的说明。

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

    地点

    • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
    • LOCATION 是代码库的单区域或多区域位置。

    该命令的输出包含 mavenConfig 下版本政策的相关信息。在此示例中，代码库具有快照版本政策，并且快照无法覆盖代码库中的相同版本。

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

    如果代码库没有版本政策，mavenConfig 的值为 {}。

概览

Artifact Registry 支持以下身份验证方法。

使用身份验证帮助程序
这是最灵活的方法。在 Maven 或 Gradle 配置中添加帮助程序时，Artifact Registry 会在环境中搜索服务账号凭据。
指定服务账号密钥作为凭据
如果应用不支持应用默认凭据，但支持使用用户名和密码进行身份验证，请使用此选项。

服务账号密钥是长期有效的凭据。请使用以下准则来限制对代码库的访问：

  • 请考虑使用专用服务账号与代码库进行交互。
  • 授予服务账号所需的最低 Artifact Registry 角色。例如，将 Artifact Registry Reader 分配给仅用于下载工件的服务账号。
  • 如果您组织中的群组需要不同级层的访问权限来访问特定代码库，请在代码库级层而不是项目级层授予访问权限。
  • 按照管理凭据的最佳做法操作。

使用凭据帮助程序进行身份验证

Artifact Registry 提供 Maven wagon 和 Gradle 插件作为凭据帮助程序。使用凭据帮助程序时，您的凭据不会存储在 Java 项目中。Artifact Registry 会改为按以下顺序搜索凭据：

  1. 应用默认凭据 (ADC) 是一种按以下顺序查找凭据的策略：

    1. 在 GOOGLE_APPLICATION_CREDENTIALS 环境变量中定义的凭据。

    2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Run 函数的默认服务账号提供的凭据。

  2. Google Cloud CLI 提供的凭据，包括来自命令 gcloud auth application-default login 的用户凭据。

GOOGLE_APPLICATION_CREDENTIALS 变量会明确指明用于身份验证的账号，从而简化问题排查。如果您不使用该变量，请验证 ADC 可能会使用的所有账号是否具有所需的权限。例如，Compute Engine 虚拟机、Google Kubernetes Engine 节点和 Cloud Run 修订版的默认服务账号对代码库拥有只读权限。如果您打算使用默认服务账号从这些环境中上传内容，则必须修改权限。

为凭据帮助程序设置服务账号

如需创建服务账号并使用环境变量设置身份验证，请执行以下操作：

  1. 创建一个服务账号代表您的应用执行操作，或选择一个现有服务账号用于进行自动化。

    您需要服务账号密钥文件所在的位置，才能使用 Artifact Registry 设置身份验证。对于现有账号，您可以在“服务账号”页面上查看密钥和创建新密钥。

    转到“服务账号”页面

  2. 向服务账号授予特定的 Artifact Registry 角色，以提供代码库访问权限。

  3. 将服务账号密钥文件分配给变量 GOOGLE_APPLICATION_CREDENTIALS，以便 Artifact Registry 凭据帮助程序可在与代码库连接时获取您的密钥。

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    其中，KEY-FILE 是服务账号密钥文件的路径。

配置 Maven

  1. 针对您使用的代码库类型配置 Maven。

    标准

    1. 运行以下命令来输出要添加到 Java 项目的代码库配置。

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

      地点

      • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
      • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
      • LOCATION 是代码库的单区域或多区域位置。

    2. 将返回的设置添加到 Maven 项目的 pom.xml 文件中的相应部分。如需详细了解文件的结构，请参阅 Maven 的 POM 参考文档。

      以下示例显示了同时存储快照版本和发布版本的代码库的设置。

      <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.2.5</version>
    </extension>
  </extensions>
</build>

      <release> 和 <snapshot> 元素用于指明代码库是存储版本软件包、快照软件包，还是同时存储这两者。这些设置应与代码库版本政策保持一致。

      <build> 元素将 Artifact Registry wagon 定义为扩展程序。如需了解 wagon 的相关信息，请参阅 Artifact Registry Maven 工具的相关文档。

    远程或虚拟

    修改项目中的 pom.xml 文件。如需详细了解文件的结构，请参阅 Maven 的 POM 参考文档。

    以下示例显示了同时存储快照版本和发布版本的远程代码库的设置。在此示例中，该项目依赖于某个版本的 Guava 软件包。

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.hello</groupId>
  <artifactId>repo-config</artifactId>
  <version>4.1-SNAPSHOT</version>
  <description>version 1 release</description>

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>28.0-jre</version>
    </dependency>
  </dependencies>

  <repositories>
    <repository>
      <id>central</id>
      <name>Maven Central remote repository</name>
      <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url>
      <layout>default</layout>
      <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.2.5</version>
      </extension>
    </extensions>
  </build>
</project>

    • <repositories> 部分定义了 Artifact Registry 代码库。对于远程代码库，<id> 元素必须设置为 central。此设置会覆盖从 Super POM 继承的 central 代码库 ID 的默认值。

    • <build> 部分将 Artifact Registry wagon 设置为扩展程序。如需了解 wagon 的相关信息，请参阅 Artifact Registry Maven 工具的相关文档。

    • 在此示例中，<dependencies> 部分会设置对 Guava 软件包版本 28.0-jre 的依赖项。

  2. Maven 会在应用 pom.xml 中定义的 wagon 之前解析一些依赖项，包括：

    • 子 Maven 项目中使用 <parent> 元素引用父项目。
    • 存储在 Artifact Registry 中的插件依赖项。

    如果您的项目需要解析这些依赖项，您必须使用核心扩展机制，以确保 Maven 能够找到父级 POM 文件和插件。

    在项目中创建包含以下内容的 ${maven.projectBasedir}/.mvn/extensions.xml 文件。<extension> 元素用于定义 wagon。

    <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.2.5</version>
  </extension>
</extensions>

    Maven 现在可以从 Artifact Registry 解析父级或插件依赖项。

您的身份验证配置已完成。

配置 Gradle

  1. 针对您使用的代码库类型配置 Gradle。

    标准

    1. 运行以下命令来输出要添加到 Java 项目的代码库配置。

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

      地点

      • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
      • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
      • LOCATION 是代码库的单区域或多区域位置。

    2. 将代码库设置添加到 build.gradle 文件中。以下示例显示了打印部分的相对位置。

      plugins {
  id "maven-publish"
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
}

publishing {
  publications {
    mavenJava(MavenPublication) {
      groupId 'maven.example.id'
      from components.java
     }
  }
  repositories {
    maven {
      url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
    }
  }
}
repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
  }
}

      • plugins 部分声明了 Artifact Registry 插件。如需了解插件，请参阅 Artifact Registry Maven 工具的相关文档。

      • publishing 部分定义了要上传的文件和目标 Artifact Registry 代码库。在准备好上传后，您可以更新 publications 部分中的文件列表。如需了解发布设置，请参阅 Maven Publish 插件文档。

    远程或虚拟

    将代码库设置添加到 build.gradle 文件中。

    以下示例展示了远程代码库的设置。在此示例中，该项目依赖于某个版本的 Guava 软件包。

    plugins {
  id 'java'
  id "maven-publish"
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
  id 'maven'
}

repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
  }
}
dependencies {
  compile "com.google.guava:guava:31.1-jre"
}

    • plugins 部分声明了 Artifact Registry 插件。如需了解插件，请参阅 Artifact Registry Maven 工具的相关文档。

    • repositories 部分定义了 Artifact Registry 代码库。

    • 在此示例中，dependencies 部分会设置对 Guava 软件包版本 31.1-jre 的依赖项。

    在 dependencies 部分中为您的软件包定义依赖项。

  2. 如果您需要在 init.gradle 或 settings.gradle 文件中使用代码库，则可以将插件配置添加到这些文件中。

    对于 init.gradle，请添加以下配置：

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

    对于 settings.gradle，请添加以下配置：

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

您的身份验证配置已完成。

配置密码身份验证

如果 Java 应用要求使用指定的用户名和密码进行身份验证，请使用此方法。

设置用于密码身份验证的服务账号

要创建服务账号，请执行以下操作：

  1. 创建一个服务账号代表您的应用执行操作，或选择一个现有服务账号用于进行自动化。

    您需要服务账号密钥文件所在的位置，才能使用 Artifact Registry 设置身份验证。对于现有账号，您可以在“服务账号”页面上查看密钥和创建新密钥。

    转到“服务账号”页面

  2. 如果要在当前 gcloud CLI 会话中激活服务账号，请运行以下命令：

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

    地点

    • ACCOUNT 是用户账号或服务账号。
    • KEY-FILE 是服务账号 JSON 密钥文件的路径。

配置 Maven

  1. 针对您使用的代码库类型配置 Maven。

    标准

    1. 运行以下命令来输出要添加到 Java 项目的代码库配置。

      gcloud artifacts print-settings mvn \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

      地点

      • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
      • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
      • LOCATION 是代码库的单区域或多区域位置。
      • KEY-FILE 是服务账号 JSON 密钥文件的路径。

    该命令会返回要添加到 Java 项目中的设置，包括 base64 编码的私钥版本。

    1. 将 <project> 元素中返回的代码库设置添加到 Maven 项目的 pom.xml 文件的相应部分。如需详细了解文件的结构，请参阅 Maven 的 POM 参考文档。
    <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>

    <release> 和 <snapshot> 元素用于指明代码库是存储版本软件包、快照软件包，还是同时存储这两者。这些设置应与代码库版本政策相符。

    1. 将 <settings> 元素中返回的身份验证设置添加到 ~/.m2/settings.xml 文件的 <servers> 部分。在以下示例中，KEY 是密钥文件中的 base64 编码密钥。

    如需了解详情，请参阅 Maven 的设置参考文档。

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

    远程或虚拟

    1. 将代码库设置添加到 Maven 项目的 pom.xml 文件的相应部分。如需详细了解文件的结构，请参阅 Maven 的 POM 参考文档。

      <repositories>
  <repository>
     <id>central</id>
     <name>Maven Central remote repository</name>
     <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url>
     <layout>default</layout>
     <releases>
       <enabled>true</enabled>
     </releases>
     <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

    <repositories> 部分定义了 Artifact Registry 代码库。对于远程代码库，<id> 元素必须设置为 central。此设置会覆盖从 Super POM 继承的 central 代码库 ID 的默认值。

    1. 使用以下命令对密钥文件进行 base64 编码。将 KEY-FILE 替换为密钥文件的名称。

      base64 -w 0 KEY-FILE

    2. 将 <settings> 元素中的身份验证设置添加到 ~/.m2/settings.xml 文件的 <servers> 部分。

    如需了解详情，请参阅 Maven 的设置参考文档。

    <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>
    1. 如果您使用的是 HTTP 端点，并且希望使用 Maven 原生连接进行身份验证，则可以在 settings.xml 中使用自定义 HTTP 标头传递身份验证标头。

    示例：

    <settings>
<servers>
  <server>
    <id>artifact-registry</id>
    <configuration>
      <httpHeaders>
        <property>
          <name>Authorization </name>
          <value>Bearer ${artifact.registry.token}</value>
        </property>
      </httpHeaders>
      <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>
  </server>
</servers>
</settings>

您的身份验证配置已完成。

配置 Gradle

  1. 针对您使用的代码库类型配置 Gradle。

    标准

    1. 运行以下命令来输出要添加到 Java 项目的代码库配置。

      gcloud artifacts print-settings gradle \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

      地点

      • PROJECT 是项目 ID。
      • REPOSITORY 是代码库的 ID 或完全限定标识符。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
      • KEY-FILE 是服务账号 JSON 密钥文件的路径。如果您运行了命令来激活服务账号，则可以省略此标志。

      该命令会返回要添加到 Java 项目中的设置，包括 base64 编码的私钥版本。

    2. 所返回配置中的以下行定义了您的服务账号密钥对应的 artifactRegistryMavenSecret 变量。将此行添加到 ~/.gradle/gradle.properties 文件中，使密钥在构建或源代码控制代码库中不可见。

      artifactRegistryMavenSecret = KEY

      在此行中，KEY 是服务账号密钥文件中的私钥。对于 _json_key_base64，artifactRegistryMavenSecret 会设置为以 base64 编码的密钥作为密码。

    3. 在 build.gradle 中指定代码库设置：

      plugins {
  id "maven-publish"
}

publishing {
  publications {
    mavenJava(MavenPublication) {
      groupId 'maven.example.id'
      from components.java
    }
  }
  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)
    }
  }
}
      • repositories 部分用于设置代码库网址和用于身份验证的凭据。
      • publishing 部分定义了要上传的文件和目标 Artifact Registry 代码库。在准备好上传后，您可以更新 publications 部分中的文件列表。如需了解发布设置，请参阅 Maven Publish 插件文档。

    远程或虚拟

    1. 使用以下命令对密钥文件进行 base64 编码。将 KEY-FILE 替换为密钥文件的名称。

      base64 -w 0 KEY-FILE

    2. 在 ~/.gradle/gradle.properties 文件中，添加以下行，使密钥在构建或源代码控制代码库中不可见。

      artifactRegistryMavenSecret = KEY

      在此行中，KEY 是 base64 编码的密钥文件的内容。

    3. 将代码库设置添加到 build.gradle 文件中。

    以下示例展示了远程代码库的配置。

    plugins {
  id 'java'
  id "maven-publish"
  id 'maven'
}

repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
    credentials {
    username = "_json_key_base64"
    password = "$artifactRegistryMavenSecret"
  }
  authentication {
    basic(BasicAuthentication)
  }
  dependencies {
    compile "com.google.guava:guava:31.1-jre"
  }

    • repositories 部分定义了 Artifact Registry 代码库。

    • 在此示例中，dependencies 部分会设置对 Guava 软件包版本 31.1-jre 的依赖项。

    在 dependencies 部分中为您的软件包定义依赖项。

您的身份验证配置已完成。

后续步骤