配置对 Artifact Registry for Maven 和 Gradle 的身份验证

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

您无需为 Cloud Build 或 Google Cloud 配置身份验证 Google Kubernetes Engine 和 Cloud Run 等运行时环境，但您应该 验证所需的权限 配置。要了解详情，请参阅 Cloud Build 以及部署到 Google Cloud 运行时 环境

准备工作

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  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-managed 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.3</version>
    </extension>
  </extensions>
</build>

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

      <build> 元素将 Artifact Registry 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.3</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.3</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.3"
}

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.3"
  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 "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.3"
  }
}
apply plugin: com.google.cloud.artifactregistry.gradle.plugin.ArtifactRegistryGradlePlugin

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

    buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"              }
    }
  dependencies {
    classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.3"
  }
}
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. 将代码库设置添加到 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>

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

配置 Gradle

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

    标准

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

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

      地点

      • PROJECT 是项目 ID。
      • REPOSITORY 是 存储库如果您配置了 default 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 部分中为您的软件包定义依赖项。

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

后续步骤