当您使用第三方应用连接到 Artifact Registry 代码库时，您必须进行 Artifact Registry 身份验证。本文档重点介绍 Maven 和 Gradle 的配置。
您无需为 Cloud Build 或 Google Cloud运行时环境（例如 Google Kubernetes Engine 和 Cloud Run）配置身份验证，但应验证是否已配置所需的权限。如需了解详情，请参阅有关 Cloud Build 和部署到 Google Cloud runtime 环境的信息。
准备工作
-
安装 Google Cloud CLI。 安装完成后，运行以下命令初始化 Google Cloud CLI：
gcloud init如果您使用的是外部身份提供方 (IdP)，则必须先 使用联合身份登录 gcloud CLI。
- （可选）为 gcloud 命令配置默认值。
如果您要配置标准代码库的身份验证，请验证版本政策，以便您可以根据可上传的 Java 软件包类型正确配置 Maven 项目。
控制台
在 Google Cloud 控制台中打开代码库页面。
点击要进行身份验证的代码库。
详细信息部分会显示版本政策。如果代码库具有快照版本政策，则允许快照覆盖字段会指明快照是否可以覆盖代码库中匹配的快照版本。
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 会改为按以下顺序搜索凭据：
应用默认凭据 (ADC) 是一种按以下顺序查找凭据的策略：
在
GOOGLE_APPLICATION_CREDENTIALS环境变量中定义的凭据。Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Run 函数的默认服务账号提供的凭据。
Google Cloud CLI 提供的凭据，包括来自命令
gcloud auth application-default login的用户凭据。
GOOGLE_APPLICATION_CREDENTIALS 变量明确指定了用于身份验证的账号，从而简化了问题排查过程。如果您不使用该变量，请验证 ADC 可能使用的任何账号是否具有所需的权限。例如，Compute Engine 虚拟机、Google Kubernetes Engine 节点和 Cloud Run 修订版本的默认服务账号对仓库具有只读权限。如果您打算使用默认服务账号从这些环境中上传，则必须修改权限。
为凭据帮助程序设置服务账号
如需创建服务账号并使用环境变量设置身份验证，请执行以下操作：
创建一个服务账号代表您的应用执行操作，或选择一个现有服务账号用于进行自动化。
您需要服务账号密钥文件所在的位置，才能使用 Artifact Registry 设置身份验证。对于现有账号，您可以在“服务账号”页面上查看密钥和创建新密钥。
向服务账号授予特定的 Artifact Registry 角色，以提供代码库访问权限。
将服务账号密钥文件分配给变量
GOOGLE_APPLICATION_CREDENTIALS，以便 Artifact Registry 凭据帮助程序可在与代码库连接时获取您的密钥。export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE其中，KEY-FILE 是服务账号密钥文件的路径。
配置 Maven
根据您使用的代码库类型配置 Maven。
标准
运行以下命令来输出要添加到 Java 项目的代码库配置。
gcloud artifacts print-settings mvn \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION地点
将返回的设置添加到 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的依赖项。
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 解析父级或插件依赖项。
- 子 Maven 项目中对父项目的引用（使用
您的身份验证配置已完成。
配置 Gradle
为所使用的代码库类型配置 Gradle。
标准
运行以下命令来输出要添加到 Java 项目的代码库配置。
gcloud artifacts print-settings gradle \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION地点
将代码库设置添加到
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部分中定义软件包的依赖项。如果您需要在
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.5" } } 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.5" } } apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
您的身份验证配置已完成。
配置密码身份验证
如果 Java 应用要求使用指定的用户名和密码进行身份验证，请使用此方法。
为密码身份验证设置服务账号
要创建服务账号，请执行以下操作：
创建一个服务账号代表您的应用执行操作，或选择一个现有服务账号用于进行自动化。
您需要服务账号密钥文件所在的位置，才能使用 Artifact Registry 设置身份验证。对于现有账号，您可以在“服务账号”页面上查看密钥和创建新密钥。
如果要在当前 gcloud CLI 会话中激活服务账号，请运行以下命令：
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE地点
- ACCOUNT 是用户账号或服务账号。
- KEY-FILE 是服务账号 JSON 密钥文件的路径。
配置 Maven
根据您使用的代码库类型配置 Maven。
标准
运行以下命令来输出要添加到 Java 项目的代码库配置。
gcloud artifacts print-settings mvn \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION \ --json-key=KEY-FILE地点
该命令会返回要包含在 Java 项目中的设置，包括私钥的 base64 编码版本。
- 将
<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>元素用于指明代码库存储的是发布软件包、快照软件包还是两者兼而有之。这些设置应与代码库的版本政策相对应。- 将
<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>远程或虚拟
将代码库设置添加到 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 的默认值。使用以下命令对密钥文件进行 Base64 编码。将 KEY-FILE 替换为您的密钥文件的名称。
base64 -w 0 KEY-FILE将
<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>示例：
<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
为所使用的代码库类型配置 Gradle。
标准
运行以下命令来输出要添加到 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 编码版本。
所返回配置中的以下行定义了您的服务账号密钥对应的
artifactRegistryMavenSecret变量。将此行添加到~/.gradle/gradle.properties文件中，使密钥在构建或源代码控制代码库中不可见。artifactRegistryMavenSecret = KEY在此行中，KEY 是服务账号密钥文件中的私钥。 对于
_json_key_base64，artifactRegistryMavenSecret设置为以 base64 编码的密钥作为密码。在
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 插件文档。
远程或虚拟
使用以下命令对密钥文件进行 Base64 编码。将 KEY-FILE 替换为您的密钥文件的名称。
base64 -w 0 KEY-FILE在
~/.gradle/gradle.properties文件中，添加以下行，使密钥在构建或源代码控制代码库中不可见。artifactRegistryMavenSecret = KEY在此行中，KEY 是 base64 编码的密钥文件的内容。
将代码库设置添加到
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部分中定义软件包的依赖项。
您的身份验证配置已完成。