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

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

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

准备工作

  1. 安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI： 

    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 旅行车和 Gradle 插件作为凭据帮助程序。使用凭据帮助程序时，您的凭据不会存储在 Java 项目中。Artifact Registry 会按以下顺序搜索凭据：

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

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

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

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

      <release> 和 <snapshot> 元素指示代码库是存储发布包和/或快照软件包。这些设置应与代码库版本政策相对应。

      <build> 元素将 Artifact Registry 货车定义为扩展程序。如需了解车，请参阅 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.1</version>
      </extension>
    </extensions>
  </build>
</project>

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

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

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

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

    • 子级 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.1</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.1"
}

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.1"
  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.1"
  }
}
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.1"
  }
}
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。此设置会覆盖从超级 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 是代码库的 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 中添加以下代码行，让您的密钥不会显示在 build 或源代码控制代码库中。

      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 部分中为您的软件包定义依赖项。

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

后续步骤