为 npm 配置向 Artifact Registry 的身份验证

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

您无需为 Cloud Build 或 Google Cloud 运行时环境（例如 Google Kubernetes Engine 和 Cloud Run）配置身份验证，但应验证是否已配置所需权限。

准备工作

安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI：
```
gcloud init
```
注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 获得最新版本。
（可选）为 gcloud CLI 命令配置默认值。
如果您要从 Windows 连接到代码库，请安装 PowerShell。
创建一个服务账号来代表您的应用执行操作。
如果您刚开始接触 npm，请参阅概览以了解限定范围的软件包以及身份验证设置的配置文件。

概览

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

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

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

google-artifactregistry-auth 是一个客户端库，用于获取 Artifact Registry 代码库的凭据。

Artifact Registry 会按以下顺序搜索凭据：

应用默认凭据 (ADC) 是一种按以下顺序查找凭据的策略：
1. 在 GOOGLE_APPLICATION_CREDENTIALS 环境变量中定义的凭据。
2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Functions 的默认服务账号提供的凭据。
Google Cloud CLI 提供的凭据，包括命令 gcloud auth application-default login 中的用户凭据。

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

如需创建服务帐号并设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，请执行以下操作：

创建一个服务账号代表您的应用执行操作，或选择一个现有服务账号进行持续集成/持续交付自动化。
向服务帐号授予特定的 Artifact Registry 角色，以提供代码库访问权限。
将服务账号密钥文件分配给变量 GOOGLE_APPLICATION_CREDENTIALS，以便 Artifact Registry 凭据帮助程序可在与代码库连接时获取您的密钥。
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
其中，KEY-FILE 是服务账号密钥文件的路径。

如需配置身份验证，请执行以下操作：

运行以下命令以输出代码库配置：
```
gcloud artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] \
    [--location=LOCATION] \
    --scope=@SCOPE-NAME \
```
地点
- PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
- REPOSITORY 是代码库的 ID。如果您配置了默认的 Artifact Registry 代码库，则当命令中省略此标志时，系统会使用该代码库。
- LOCATION 是代码库的单区域或多区域位置。
- SCOPE-NAME 是要与代码库关联的 npm 范围的名称。
  
  使用范围可确保您始终从正确的代码库发布和安装软件包。
  
  未限定作用域的软件包与您的默认 npm 注册表（通常是 npm 公共注册表）相关联。如果您未指定范围，返回的配置会将您的 Artifact Registry 代码库设置为默认注册表。如果您的 Node.js 项目需要同时从公共 npm 注册表和 Artifact Registry 代码库安装软件包，则可能会出现问题。
将返回的配置设置添加到 Node.js 项目的 .npmrc 配置文件中。此文件通常与 package.json 位于同一目录中。

请确保您发布的软件包以及将从 npm 代码库安装依赖项的项目包含在 Node.js 项目中。
如果您要连接其他 Node.js 代码库，请重复前面的步骤获取设置并将其添加到相应的 .npmrc 文件中。
准备好连接代码库时，请获取访问令牌以进行身份验证。

每个 Artifact Registry Node.js 软件包代码库都与一个注册表端点 https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY 相关联

如果您未使用 print-settings 命令指定范围，则可以运行以下命令，将范围与 Artifact Registry 代码库相关联。

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY/

获取访问令牌

访问令牌的有效期为 60 分钟。在运行与代码库交互的命令之前，请不久生成访问令牌。

如需获取令牌，请使用以下某个选项：

使用 npx 命令刷新访问令牌。
1. 确保用于连接到公共 npm 注册表的凭据位于用户的 npm 配置文件 ~/.npmrc 中。
2. 在 Node.js 项目目录中运行以下命令。
```
npx google-artifactregistry-auth
```
  如果您的 Artifact Registry 代码库已设置为全局注册表，并且软件包没有限定范围，请改为使用以下命令，以便该命令可以从公共 npm 注册表（而不是 Artifact Registry 代码库）下载凭据帮助程序。
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```

将脚本添加到项目的 package.json 文件中。

"scripts": {
 "artifactregistry-login": "npx google-artifactregistry-auth"
}

在 Node.js 项目目录中运行该脚本。

npm run artifactregistry-login

Artifact Registry 会读取项目 .npmrc 文件中的 Artifact Registry 代码库设置，并使用这些设置将令牌凭据添加到您的用户 .npmrc 文件中。将令牌存储在用户 .npmrc 文件中，可将凭据与源代码和源代码控制系统隔离开来。

--repo-config 是包含代码库设置的 .npmrc 文件。如果您未指定此标志，则默认位置是当前目录。
--credential-config 是要将访问令牌写入到的 .npmrc 文件的路径。默认目录为您的用户 .npmrc 文件。

配置密码身份验证

当 Node.js 应用需要使用指定的用户名和密码进行身份验证时，请使用此方法。

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

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

如需创建服务账号并配置身份验证，请执行以下操作：

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

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

转到“服务账号”页面

注意：如果服务账号密钥未正确管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性以及管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。
向服务帐号授予特定的 Artifact Registry 角色，以提供代码库访问权限。
如果要在当前 gcloud CLI 会话中激活服务帐号，请运行以下命令：
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
地点
- ACCOUNT 是用户账号或服务账号。
- KEY-FILE 是服务账号 JSON 密钥文件的路径。
运行以下命令以输出代码库配置：
```
gcloud artifacts print-settings npm [--project=PROJECT] \
[--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --json-key=KEY-FILE
```
地点
- PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
- REPOSITORY 是代码库的 ID。如果您配置了默认的 Artifact Registry 代码库，则当命令中省略此标志时，系统会使用该代码库。
- LOCATION 是代码库的单区域或多区域位置。
- SCOPE-NAME 是要与代码库关联的 npm 范围的名称。
  
  使用范围可确保您始终从正确的代码库发布和安装软件包。
  
  未限定作用域的软件包与您的默认 npm 注册表（通常是 npm 公共注册表）相关联。如果您未指定范围，返回的配置会将您的 Artifact Registry 代码库设置为默认注册表。如果您的 Node.js 项目需要同时从公共 npm 注册表和 Artifact Registry 代码库安装软件包，则可能会出现问题。
- KEY-FILE 是服务账号 JSON 密钥文件的路径。
注意：返回的配置设置包含占位符电子邮件地址。必须在 npm 配置中提供电子邮件地址才能发布 npm 软件包。Artifact Registry 不使用占位符电子邮件地址进行身份验证。
将返回的配置设置添加到 Node.js 项目的 .npmrc 配置文件中。此文件通常与 package.json 位于同一目录中。请确保您发布的软件包以及将从 npm 代码库安装依赖项的项目包含在 Node.js 项目中。
如果您要连接其他 Node.js 代码库，请重复前面的步骤获取设置并将其添加到 .npmrc 文件中。