为 Maven 和 Gradle 设置身份验证

本页面介绍如何配置 Maven 或 Gradle 以进行身份验证。

当您使用第三方应用连接到代码库时,您必须进行 Artifact Registry 身份验证。

与 Google Cloud 服务集成(例如 Cloud Build 或 Google Kubernetes Engine 服务)不需要进行身份验证。但是,您应该验证代表这些服务的身份是否具有访问代码库所需的权限

软件包管理目前为 Alpha 版。它仅适用于 Alpha 版用户,可能不包含容器管理可用的所有特性。若要申请 Alpha 版,请填写注册表单

准备工作

  1. 如果目标代码库不存在,请创建新代码库
  2. (可选)为 gcloud 命令配置默认值

概览

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 Functions 的默认服务帐号提供的凭据。

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

GOOGLE_APPLICATION_CREDENTIALS 变量设置为您希望帮助程序在进行身份验证时使用的服务帐号密钥。当 ADC 使用默认服务帐号凭据时,您的代码库访问权限取决于授予该帐号的权限

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

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

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

    转到“服务帐号”页面

  2. 向服务帐号授予适当的 Artifact Registry 角色,以提供代码库访问权限。

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

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

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

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

    Maven

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

    其中

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

    Gradle

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

    其中

    • PROJECT 是项目 ID。
    • REPOSITORY 是代码库的 ID 或完全限定标识符。如果您配置了默认 Artifact Registry 代码库,则在命令中省略此标志时,系统将会使用该代码库。
  5. 配置 Java 项目。

    Maven

    1. 将返回的设置添加到 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.1.1</version>
        </extension>
      </extensions>
    </build>
    

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

    1. 如果您的 pom.xml 文件引用了包含 <parent> 元素的父项目,请在该项目中添加核心扩展程序文件。

    Maven 会在应用 wagon 之前解析父级关系。核心扩展程序机制可让子项目解析父级依赖项,然后再在 pom.xml 文件中应用 wagon。

    在项目中创建包含以下内容的 ${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.1.1</version>
      </extension>
    </extensions>
    

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

    Gradle

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

      plugins {
        id "maven-publish"
        id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.1"
      }
      
      publishing {
        publications {
             mavenJava(MavenPublication) {
                groupId 'maven.example.id'
                from components.java
             }
        }
        repositories {
          maven {
            url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          }
        }
      }
      
      • plugins 部分声明了 Artifact Registry 插件。如需了解插件,请参阅 Artifact Registry Maven 工具的相关文档。

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

    2. 如果您的构建内容包含任何依赖项,请确保在构建内容中声明这些依赖项。

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

      对于 init.gradle,请添加以下配置:

      initscript {
        repositories {
          maven {
            url "https://plugins.gradle.org/m2/"
          }
        }
        dependencies {
          classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.1.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.1.1"
        }
      }
      apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
      

配置密码身份验证

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

如需创建服务帐号并配置身份验证,请执行以下操作:

  1. 创建一个服务帐号代表您的应用执行操作,或选择一个现有服务帐号用于进行持续集成/持续交付自动化。

  2. 向服务帐号授予适当的 Artifact Registry 角色,以提供代码库访问权限。

  3. 如果要在当前 Cloud SDK 会话中激活服务帐号,请运行以下命令:

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

    其中

    • ACCOUNT 是用户帐号或服务帐号。
    • KEY-FILE 是服务帐号 JSON 密钥文件的路径。
  4. 运行以下命令来输出要添加到 Java 项目的代码库配置。

    Maven

    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 密钥文件的路径。

    Gradle

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

    其中

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

    Maven

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

    Gradle

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

      def artifactRegistryMavenSecret = "KEY"
      

      其中,KEY 是您的服务帐号的 base64 编码版本。

    2. build.gradle 中指定代码库设置:

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

    您的身份验证配置已完成。在发布文件之前,请确保在 publishing 下的 publications 部分中定义了要上传的文件。例如:

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

    如需了解发布设置,请参阅 Maven Publish 插件文档。

后续步骤