為 npm 設定 Artifact Registry 驗證機制

使用第三方應用程式連線至存放區時，必須對 Artifact Registry 進行驗證。

您不需要為 Cloud Build 或 Google Cloud執行階段環境 (例如 Google Kubernetes Engine 和 Cloud Run) 設定驗證程序，但應確認已設定必要的權限。

事前準備

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  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. Google Cloud CLI 提供的憑證，包括 gcloud auth application-default login 指令的使用者憑證。

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 位於同一目錄。

    請務必在 Node.js 專案中加入這些設定，以便發布套件，以及從 npm 存放區安裝依附元件的專案。

  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 設定檔 ~/.npmrc 中，有用來連線至公開 npm 登錄的憑證。

    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 指派給只下載構件服務帳戶。
  • 如果貴機構中的群組需要對特定存放區的不同存取層級，請在存放區層級 (而非專案層級) 授予存取權。
  • 請遵循憑證管理的最佳做法。

如要建立服務帳戶並設定驗證方法，請按照下列步驟操作：

  1. 建立服務帳戶，以便代表應用程式執行動作，或選擇用於自動化的現有服務帳戶。

    您需要服務帳戶金鑰檔案的位置，才能設定 Artifact Registry 的驗證機制。如要查看現有帳戶的金鑰，或建立新的金鑰，請前往「服務帳戶」頁面。

    前往「Service Accounts」(服務帳戶) 頁面

  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 位於同一目錄。請務必在 Node.js 專案中加入這些設定，以便發布套件，以及從 npm 存放區安裝依附元件的專案。

  6. 如果您有其他要連線的 Node.js 存放區，請重複執行上述步驟，取得設定並將其新增至 .npmrc 檔案。

後續步驟