为 npm 设置身份验证

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

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

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

准备工作

  1. 如果目标代码库不存在,请创建新代码库
  2. 如果您要从 Windows 连接到代码库,请安装 PowerShell
  3. (可选)如果您要从 Windows 连接到 npm 代码库,请配置 gcloud 命令的默认值
  4. 创建一个服务帐号来代表您的应用执行操作。
  5. 如果您刚开始接触 npm,请参阅概览以了解限定范围的软件包以及身份验证设置的配置文件。

概览

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

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

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

使用凭据帮助程序时,您的凭据不会存储在 Node.js 项目中。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. 创建一个服务帐号代表您的应用执行操作,或选择一个现有服务帐号进行持续集成/持续交付自动化。

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

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

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

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

  4. 运行以下命令来输出要添加到 Node.js 项目的代码库配置。如果要将设置存储在 npm 全局配置文件或每个用户配置文件中,您必须添加一个范围

    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 注册表。

  5. 将返回的配置设置添加到项目的 .npmrc 配置文件中,该文件与 package.json 位于同一目录。

  6. 如果您有其他要连接的 npm 代码库,请重复前面的步骤以获取设置,并将其添加到 .npmrc 文件中。

  7. 如果您要连接到代码库,请在建立连接后的 60 分钟内刷新访问令牌以进行身份验证。google-artifactregistry-auth 是一个客户端库,用于更新 Artifact Registry 代码库的凭据。

    如需刷新凭据,请使用以下任一方法:

    • 直接使用 npx 来刷新访问令牌。如果您使用的是 npm 5.2.0 或更高版本,则凭据将包含在 npm 中。

      1. 确保用于连接到公共 npm 注册表的凭据位于用户的 npm 配置文件 ~/.npmrc 中。

      2. 在 Node.js 项目上方的文件夹中运行以下命令。

      npx google-artifactregistry-auth PROJECT-NPMRC
      

      其中 PROJECT-NPMRC 是项目目录中 .npmrc 文件的路径。

      您必须在项目目录之外运行该命令,以便 npx 使用 ~/.npmrc 中的公共 npm 注册表凭据来下载 google-artifactregistry-auth

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

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

      运行脚本:

      npm run artifactregistry-login PROJECT-NPMRC
      

      其中 PROJECT-NPMRC 是项目目录中 .npmrc 文件的路径。

    • 对于低于 5.2.0 的 npm 版本,请执行以下步骤:

      1. 运行以下命令:
      npm install google-artifactregistry-auth --save-dev --registry https://registry.npmjs.org/
      
      1. 将其添加到身份验证脚本中:
      "scripts": {
          "artifactregistry-login": "./node_modules/.bin/artifactregistry-auth",
      }
      

      运行脚本:

      npm run artifactregistry-login PROJECT-NPMRC
      

      其中 PROJECT-NPMRC 是项目目录中 .npmrc 文件的路径。

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

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

配置密码身份验证

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

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

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

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

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

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

    转到“服务帐号”页面

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

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

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

    其中

    • ACCOUNT 是用户帐号或服务帐号。
    • KEY-FILE 是服务帐号 JSON 密钥文件的路径。
  4. 运行以下命令来输出要添加到 Node.js 项目的代码库配置。如果要将设置存储在 npm 全局配置文件或每个用户配置文件中,您必须添加一个范围

    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 注册表。

    • KEY-FILE 是服务帐号 JSON 密钥文件的路径。

  5. 将返回的配置设置添加到项目的 .npmrc 配置文件中,该文件与 package.json 位于同一目录。

  6. 如果您有其他要连接的 npm 代码库,请重复前面的步骤以获取设置,并将其添加到 .npmrc 文件中。

后续步骤