Accenture Japan (有志)
📚

npmのArtifact Registryに対する認証を構成する方法：実践ガイドと注意点解説

Chao K. Zhang
に公開
Google Cloud
npm
Artifact Registry
アクセンチュア
アクセンチュア
tech

はじめに

Google CloudのArtifact Registryは、npmパッケージを含むさまざまなアーティファクトを管理するフルマネージドサービスです。社内・プロジェクト限定のプライベートパッケージを安全に管理したい場合に特に有用です。本記事では公式ドキュメントの要点を整理し、実践的なnpm認証設定手順を分かりやすく解説します。また、開発現場に実際にはまっていた難点と対策も重点的に説明します。

なぜ認証が必要か？

Artifact Registryのnpmリポジトリにアクセスするには、Google Cloudの認証情報が必要です。特に以下の操作時に必須となります：

  • プライベートパッケージのnpm publish
  • プライベートパッケージのnpm install
  • CI/CD環境での自動ビルド・デプロイ

主要な認証方法（認証情報ヘルパー編）

Google推奨のgoogle-artifactregistry-auth（認証情報ヘルパー）を使用する方法です。60分間有効なアクセストークンを自動生成し、セキュアに認証します。

認証手順の目次:

Artifact Registryのnpm認証は4つの手順で構成されます：

前提条件

Artifact Registryでnpm認証を構成するための4つの手順を実行する前に、以下の前提条件を満たす必要があります：

  1. 環境要件
    OS: Linux/macOS/Windows（Windowsの場合はWSL推奨）
    Node.js: v14以上（LTS推奨）
    npm: v7以上
    Google Cloud CLI: gcloud コマンドが利用可能な状態
    公式サイトのインストール方法を参照してgcloudをインストールしてから、下記コマンドでバージョン情報が表示されたらインストールが成功です。
gcloud version

コマンド実行結果の例：

  1. Google Cloud権限
    ユーザー/サービスアカウントに以下のいずれかのロールを持っていること：
    roles/artifactregistry.writer（パッケージ公開用）
    roles/artifactregistry.reader（パッケージ取得用）
    roles/artifactregistry.admin（フルアクセス）

  2. 事前設定
    ・npmリポジトリ作成済みであること：
    　GCPコンソールから確認する例：

  3. ネットワーク要件
    アウトバウンドアクセス許可：
    https://REGION-npm.pkg.dev へのアクセス許可

ステップ1-GoogleCloudのユーザ認証

  • 手動でユーザ認証をする場合：
gcloud auth login  # ユーザー認証（手動）
gcloud config set project PROJECT_ID  # デフォルトプロジェクト設定、すでにターゲットプロジェクトに向いている場合はスキップ

実行例：（ブラウザで一番目のリンクにアクセスし、案内された手順に従って認証を実施すればOK）

  • 自動でユーザ認証をさせたい場合：
    • Google Cloud環境内（GCE/GKE）でCI/CDパイプラインを実行する場合は、メタデータサーバーから自動認証されるため、明示的なログイン不要になります。（例：gitlab ci パイプライン実行時のrunnerサーバをGKEコンテナとしてGoogle Cloud環境上に起動する場合は、自動認証されます）

ステップ2-リポジトリ情報の取得

  • npmプロジェクト直下で実行：
　gcloud artifacts print-settings npm \
  --project=PROJECT_ID \
  --repository=REPOSITORY_NAME \
  --location=REGION \
  --scope=@SCOPE_NAME

実行例：

  • エディタで出力された2行の構成設定をプロジェクト（※落とし穴注意）の .npmrc ファイルに保存します。ユーザの ~/.npmrc ではないので要注意です。
    • プロジェクト.npmrcファイル(package.jsonと同じ階層)が存在しない場合は、「touch ./.npmrc」などで作成してから、「vi/vim」などのエディタで追記する必要があります。
    • 出力された構成設定の例：
@SCOPE_NAME:registry=https://REGION-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME/
//REGION-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME/:always-auth=true
  • 保存済み.npmrcファイルの例：

※落とし穴の詳細： 公式サイトの手順では、「アクセス トークンの取得」の章に、「認証スクリプトの使用」と「npx コマンドの使用」という2種類のトークン取得方法が記載されています。取得方法によって、参照されるnpmrcファイルが違ってくるので、要注意です。筆者は対象ファイルを間違えて3時間ほど沼にはまっておりました。

  • 「認証スクリプトの使用」の場合、プロジェクトルートの.npmrc ファイルの設定が参照されますので、上記2行の構成設定をプロジェクトの .npmrc ファイルに保存すべきです。本手順は認証スクリプトのほうを選んでおります。
  • 「npx コマンドの使用」の場合、ユーザの「~/.npmrc」が参照されますので、上記2行の構成設定をユーザの ~/.npmrc ファイルに保存すべきです。

npxコマンドのほうが好ましいと思われる方は、下記ボタンをクリックしてnpxコマンドの手順をご参照ください。そうでなければ、ステップ3へお進みください。

npxコマンドでの認証手順
  1. [touch ~/.npmrc]でユーザ用ファイルを作成してから、下記のようにコマンド実行結果の構成設定を「~/.npmrc」にリダイレクト（>>）で追記する。
touch ~/.npmrc  #ファイル作成

gcloud artifacts print-settings npm \
  --project=PROJECT_ID \
  --repository=REPOSITORY_NAME \
  --location=REGION \
  --scope=@SCOPE_NAME >> ~/.npmrc

cat ~/.npmrc  #中身確認

実行例：

  1. 下記二つのコマンドを実行すれば認証が完了することになります。本手順のステップ3と4は実施不要です。
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
npx google-artifactregistry-auth

実行例：

ステップ3-認証スクリプトの追加

package.json に以下を追記：

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

追加例：

ステップ4-認証実行

npm run artifactregistry-login

成功時の出力例：

Retrieving application default credentials...
Retrieving credentials from gcloud...
Success!

実行例：

これで60分間有効なトークンが~/.npmrcに保存され、npm publishなどが操作可能になります。

代替認証方法（サービスアカウントキー編）

長期間有効な認証が必要な場合の方法です。セキュリティ上、上記認証情報ヘルパーでのトークン認証を優先的に利用すべきです。

設定手順
1.サービスアカウント作成：

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

2.権限付与：

gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
  --location=REGION \
  --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/artifactregistry.reader # 必要に応じてadminまたはwriterに変更

3.キーファイル生成：

gcloud iam service-accounts keys create KEY_FILE.json \
  --iam-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

4.環境変数設定：

export GOOGLE_APPLICATION_CREDENTIALS=./KEY_FILE.json

絶対パスでの設定を推奨します。

これでキーファイルと環境変数をクリアしない限りは、長期間有効な認証が維持でき、npm publishなどが操作可能になります。

認証成功後の実践的な使用例

・プライベートパッケージの公開

npm publish

実行例：（ログが長いので、最後の成功部分のみ添付）

GARにパッケージ確認：

・プライベートパッケージのインストール

npm install @SCOPE_NAME/package-name@X.X.X

実行例：(X.X.Xの部分はバージョンまたはlatestタグを指定)

結果確認：

・CI環境（GitHub Actions）での設定例

- name: Artifact Registry 認証
  run: |
    npm run artifactregistry-login
    npm ci
    npm run build  #buildスクリプトが定義されている場合
    npm publish

トラブルシューティング

  • 認証エラー発生時：
    • gcloud auth application-default loginで再認証
    • サービスアカウントに適切なIAMロールが付与されているか確認
  • スコープ未設定エラー：
    • ユーザの.npmrcにスコープ定義（@SCOPE_NAME:registry=...）があるかどうかを確認

まとめ

Artifact Registryのnpm認証において、4つの手順で実現できます。

  1. gcloud auth loginで事前にユーザ認証
  2. .npmrcにリポジトリ情報を定義
  3. package.jsonに認証スクリプトを追加
  4. トークン取得コマンドを実行

これにより、社内限定ライブラリの安全な共有や設定ファイルの一元管理が可能になり、npm publishでnpmパッケージをGARにアップロードできます。本記事をご参照いただき、ぜひ実環境でお試しください！

Accenture Japan (有志)
Accenture Japan (有志)

アクセンチュア株式会社に所属する社員有志による運営です。アクセンチュアの社員による様々な発信をまとめています。なお、投稿内容は社員個人の見解であり、所属する組織を代表するものではありません。

Discussion