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

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

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

始める前に

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 のデフォルトサービスアカウントによって指定される認証情報。
コマンド gcloud auth application-default login からのユーザー認証情報など、Google Cloud CLI によって提供される認証情報。

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

サービスアカウントを作成して GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定するには:

アプリケーションに代わって動作するサービスアカウントを作成するか、CI/CD の自動化に使用する既存のサービスアカウントを選択します。
適切な 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 \
```
Where
- 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 リポジトリがグローバルレジストリとして設定され、パッケージのスコープが設定されていない場合は、次のコマンドを使用すると、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 の読み取り権を割り当てます。
組織内のグループが特定のリポジトリに対する異なるレベルのアクセス権を必要とする場合は、プロジェクトレベルではなくリポジトリレベルでアクセス権を付与します。
認証情報管理のおすすめの方法に従います。

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

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

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

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

注: サービスアカウントキーが正しく管理されていない場合は、セキュリティリスクが発生します。可能であれば、サービスアカウントキーよりも安全な代替手段を選択してください。サービスアカウントキーで認証する必要がある場合は、秘密鍵のセキュリティと、サービスアカウントキーを管理するためのベストプラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービスアカウントキーを作成できない場合は、組織でサービスアカウントキーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。
適切な Artifact Registry のロールをサービスアカウントに付与して、リポジトリへのアクセスを許可します。
現在の gcloud CLI セッションでサービスアカウントを有効にする場合は、次のコマンドを実行します。
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
Where
- ACCOUNT は、ユーザーまたはサービスアカウントです。
- KEY-FILE はサービスアカウントの JSON キーファイルのパスです。
次のコマンドを実行して、リポジトリ構成を出力します。
```
gcloud artifacts print-settings npm [--project=PROJECT] \
[--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --json-key=KEY-FILE
```
Where
- 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 ファイルに追加します。