npm の Artifact Registry に対する認証を構成する

サードパーティのアプリケーションを使用してリポジトリに接続する場合は、Artifact Registry に対して認証する必要があります。

Cloud Build または Google Cloud ランタイム環境（Google Kubernetes Engine、Cloud Run など）に対する認証を構成する必要はありませんが、必要な権限が構成されていることを確認する必要があります。

始める前に

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  2. （省略可）gcloud CLI コマンドのデフォルトを構成します。
  3. Windows からリポジトリに接続する場合は、PowerShell をインストールします。
  4. アプリケーションに代わって動作するサービス アカウントを作成します。
  5. npm を初めて使用される場合は、概要をお読みいただき、スコープ設定されたパッケージと認証設定の構成ファイルを確認してください。

概要

Artifact Registry では、次の認証方法がサポートされています。

認証情報ヘルパーの使用
このオプションは非常に柔軟性に優れています。npm の構成にヘルパーを含めると、Artifact Registry で環境内のサービス アカウントの認証情報を検索します。
認証情報としてサービス アカウント キーを指定
このオプションは、アプリケーションがアプリケーションのデフォルト認証情報に対応していないものの、ユーザー名とパスワードによる認証をサポートしている場合に使用します。

認証情報ヘルパーによる認証

google-artifactregistry-auth は、Artifact Registry リポジトリの認証情報を取得するクライアント ライブラリです。

Artifact Registry では次の順序で認証情報を検索します。

  1. アプリケーションのデフォルト認証情報（ADC）。次の順序で認証情報を検索する戦略です。

    1. GOOGLE_APPLICATION_CREDENTIALS 環境変数で定義された認証情報。

    2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine、Cloud Run 関数のデフォルト サービス アカウントによって指定される認証情報。

  2. コマンド gcloud auth application-default login からのユーザー認証情報など、Google Cloud CLI によって提供される認証情報。

GOOGLE_APPLICATION_CREDENTIALS 変数によって、アカウントの認証が明示的になるため、トラブルシューティングが容易になります。この変数を使用しない場合は、ADC が使用するアカウントに必要な権限があることを確認します。たとえば、Compute Engine VM、Google Kubernetes Engine ノード、Cloud Run リビジョン用のデフォルトのサービス アカウントには、リポジトリへの読み取り専用権限が付与されています。デフォルトのサービス アカウントを使用して、これらの環境からアップロードする場合は、権限を変更する必要があります。

サービス アカウントを作成し、GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定する手順は次のとおりです。

  1. アプリケーションに代わって動作するサービス アカウントを作成するか、CI/CD の自動化に使用する既存のサービス アカウントを選択します。

  2. 適切な Artifact Registry のロールをサービス アカウントに付与して、リポジトリへのアクセスを許可します。

  3. サービス アカウント キー ファイルの場所を変数 GOOGLE_APPLICATION_CREDENTIALS に割り当てて、Artifact Registry の認証情報ヘルパーがリポジトリとの接続時にキーを取得できるようにします。

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    KEY-FILE はサービス アカウント キーファイルのパスです。

以下により認証を構成します。

  1. 次のコマンドを実行して、リポジトリ構成を出力します。

    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 リポジトリの両方からパッケージをインストールする必要がある場合に発生する可能性があります。

  2. 返された構成設定を、Node.js プロジェクトの .npmrc 構成ファイルに追加します。このファイルは通常、package.json と同じディレクトリにあります。

    公開するパッケージと、npm リポジトリから依存関係をインストールするプロジェクトに対して、Node.js プロジェクトにこれらの設定を含めます。

  3. 接続できる他の Node.js リポジトリがある場合は、前述の手順を繰り返して設定を取得し、適切な .npmrc ファイルに追加します。

  4. リポジトリを接続する準備ができたら、認証用のアクセス トークンを取得します。

各 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 リポジトリがグローバル レジストリとして設定され、パッケージのスコープが設定されていない場合は、次のコマンドを使用すると、Artifact Registry リポジトリではなく公開 npm レジストリから認証情報ヘルパーをダウンロードできます。

      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 の読み取り権を割り当てます。
  • 組織内のグループが特定のリポジトリに対する異なるレベルのアクセス権を必要とする場合は、プロジェクト レベルではなくリポジトリ レベルでアクセス権を付与します。
  • 認証情報管理のおすすめの方法に従います。

サービス アカウントを作成して認証を構成するには:

  1. アプリケーションに代わって動作するサービス アカウントを作成するか、自動化に使用する既存のサービス アカウントを選択します。

    Artifact Registry で認証を設定するには、サービス アカウントのキーファイルの場所が必要です。既存のアカウントの場合は、[サービス アカウント] ページで鍵を表示し、新しい鍵を作成できます。

    [サービス アカウント] ページに移動

  2. 適切な Artifact Registry のロールをサービス アカウントに付与して、リポジトリへのアクセスを許可します。

  3. 現在の gcloud CLI セッションでサービス アカウントを有効にする場合は、次のコマンドを実行します。

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

    ここで

    • ACCOUNT は、ユーザーまたはサービス アカウントです。
    • KEY-FILE はサービス アカウントの JSON キーファイルのパスです。

  4. 次のコマンドを実行して、リポジトリ構成を出力します。

    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 キーファイルのパスです。

  5. 返された構成設定を、Node.js プロジェクトの .npmrc 構成ファイルに追加します。このファイルは通常、package.json と同じディレクトリにあります。公開するパッケージと、npm リポジトリから依存関係をインストールするプロジェクトに対して、Node.js プロジェクトにこれらの設定を含めます。

  6. 接続できる他の Node.js リポジトリがある場合は、前述の手順を繰り返して設定を取得し、.npmrc ファイルに追加します。

次のステップ