驗證 gcloud CLI

本文僅說明如何透過 Google Cloud CLI 存取Google Cloud 資源時進行驗證。如要使用 Cloud 用戶端程式庫或 Google API 用戶端程式庫驗證工作負載，請參閱「應用程式預設憑證的運作方式」。

事前準備

如果您是 Google Cloud 新手，只想在本機開發環境中使用 gcloud CLI 指令，可以執行下列指令初始化 gcloud CLI：

gcloud init

初始化程序會引導您完成驗證流程、設定 gcloud CLI 設定，並授權 gcloud CLI 代表您執行動作。不必執行個別驗證步驟。

本文其餘內容將涵蓋更複雜的情境，例如搭配不同主體類型使用 gcloud CLI、適用於不同環境的適當驗證方法、切換主體，以及管理儲存的憑證。

驗證方法

所有 gcloud CLI 指令都必須通過 API 驗證。 Google Cloud 您可以透過下列方式進行驗證：

  • 授權及儲存憑證：適合在本地開發環境中使用。您可以使用 gcloud auth login 指令，授權 gcloud CLI 代表主體執行動作。完成初步驗證後，這項指令會將憑證儲存在 gcloud CLI 設定目錄中。gcloud CLI 會使用這些儲存的憑證，在工作階段到期或您撤銷授權之前，自動驗證後續指令。

  • 使用憑證檔案進行驗證：適用於在 Google Cloud外部執行的工作負載。您可以使用環境變數或 gcloud CLI 設定屬性，指定用於自動驗證的憑證檔案。這個檔案可以是下列其中之一：

    • Workload Identity 聯盟憑證設定檔。

    • 服務帳戶金鑰。

  • 提供存取權杖：適用於高度隔離的自動化工作流程，或共用電腦上的無狀態工作階段。您可以直接向 gcloud CLI 提供存取權杖，略過憑證儲存程序。您可以將特定環境變數設為原始存取權杖字串，或讓 gcloud CLI 指向含有存取權杖的檔案，藉此完成這項操作。

驗證後，您可以選擇提供服務帳戶的電子郵件地址，讓 gcloud CLI 模擬服務帳戶。

您可以在單一環境中使用多種驗證方法。不過，任何給定的 gcloud 指令只會使用一個主體。如要判斷要使用哪個主體，gcloud CLI 會依優先順序執行。

不需要驗證的情況

在下列情況中，您不需要驗證 gcloud CLI：

  • 初始化 gcloud CLI 後，請立即執行下列指令：初始化程序會驗證及授權 gcloud CLI 代表您執行動作。如果您需要使用其他主體存取不同資源，或是需要重新驗證主體，可能仍須再次驗證。
  • 從公開 Compute Engine 中繼資料伺服器的資源使用 gcloud CLI。 包括 Compute Engine VM 執行個體、Cloud Run 服務和 Cloud Build 建構作業等資源。gcloud CLI 會使用附加至 VM 的服務帳戶進行驗證，並在任何已套用的 存取範圍限制內，存取與該服務帳戶相同的資源。
  • 使用 Cloud Shell 時。gcloud CLI 會自動使用您登入 Google Cloud 控制台時的主體進行驗證。在新的 Cloud Shell 工作階段中首次執行 gcloud CLI 指令時，系統會提示您使用該主體 授權 Cloud Shell。

為工作選擇適當的主體

主體類型分為兩種，分別供人員和自動化工作負載使用。 您需要使用的主體類型會影響驗證方式。

  • 使用者帳戶：這些是供使用者執行互動式工作的 Google 帳戶，例如臨時管理工作、服務的非程式輔助設定、測試、實驗和可觀測性。 Google Cloud

    您會以使用者憑證 (例如密碼和一次性代碼) 驗證使用者帳戶。

  • 服務帳戶：這些是專屬帳戶，工作負載可透過這些帳戶存取服務或資源。 Google Cloud 您通常不會直接以服務帳戶進行驗證，而是將服務帳戶附加至 Compute Engine VM 等資源，或使用服務帳戶模擬。

  • 聯合主體：這些身分會參照外部身分提供者中的使用者或服務帳戶。 Google Cloud支援兩種同盟主體，名稱相似：

以人類身分使用 gcloud CLI

如果是互動式工作，通常會透過下列其中一種方式進行驗證：

  • 使用者帳戶

  • 使用員工身分聯盟的聯合使用者身分

使用者帳戶

使用使用者帳戶向 gcloud CLI 進行驗證的方式，取決於裝置上是否已安裝網頁瀏覽器。

我的裝置有網路瀏覽器

如要在搭載網頁瀏覽器的裝置上，透過使用者帳戶進行驗證，請完成下列步驟：

  1. 執行下列指令來啟動程序：

    gcloud auth login

  2. 按照瀏覽器式流程驗證並授權 gcloud CLI，以便日後代表您存取資源。

gcloud auth login 指令會將存取憑證儲存在主目錄中。經過驗證的主體會成為有效 gcloud CLI 設定中的有效主體。除非遭到覆寫，否則 gcloud CLI 會使用這些已儲存的憑證存取 Google Cloud。

我的裝置沒有網路瀏覽器

如果要在沒有網頁瀏覽器的裝置上使用 gcloud CLI，可以在其他信任的裝置上驗證使用者帳戶。這個程序會因其他信任裝置上安裝的軟體而異。

使用其他信任的裝置進行驗證

選取其他信任的裝置上可用的軟體。

gcloud CLI 和網路瀏覽器

使用 --no-browser 標記，在安裝 gcloud CLI 的其他裝置上，透過網路瀏覽器完成驗證程序：

  1. 在要使用 gcloud CLI 的原始裝置上執行下列指令：

    Linux 和 macOS 

    gcloud auth login \
    --no-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-browser

  2. 複製以 gcloud auth login --remote-bootstrap=" 開頭的 gcloud 指令，以便在其他裝置上使用。

  3. 前往其他受信任的裝置，該裝置必須安裝網頁瀏覽器和 gcloud CLI 372.0.0 以上版本。

  4. 在終端機中執行先前複製的指令 (開頭為 gcloud auth login --remote-bootstrap=")，然後完成瀏覽器流程。

  5. 在終端機中，複製以 https://localhost 開頭的網址，以便在原始裝置上使用。

  6. 返回原始裝置。

  7. 在終端機的提示中，貼上您先前複製的 https://localhost 網址。按下鍵盤上的 Enter 或 Return 鍵，即可完成程序。

gcloud auth login 指令會將存取憑證儲存在主目錄中。經過驗證的主體會成為有效 gcloud CLI 設定中的有效主體。除非遭到覆寫，否則 gcloud CLI 會使用這些已儲存的憑證存取 Google Cloud。

僅限網路瀏覽器

使用 --no-launch-browser 標記，透過其他裝置的網路瀏覽器完成驗證程序：

  1. 在要使用 gcloud CLI 的原始裝置上執行下列指令：

    Linux 和 macOS 

    gcloud auth login \
    --no-launch-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-launch-browser

  2. 複製開頭為 https://accounts.google.com/o/oauth2/auth 的網址，以便在其他裝置上使用。

  3. 前往已安裝網頁瀏覽器的其他信任裝置。

  4. 開啟網路瀏覽器，前往先前複製的網址，然後完成瀏覽器流程。

  5. 複製驗證碼，以便在原始裝置上使用。

  6. 返回原始裝置。

  7. 在終端機的提示字元中，貼上您先前複製的驗證碼。按下鍵盤上的 Enter 或 Return 鍵，完成程序。

gcloud auth login 指令會將存取憑證儲存在主目錄中。經過驗證的主體會成為有效 gcloud CLI 設定中的有效主體。除非遭到覆寫，否則 gcloud CLI 會使用這些已儲存的憑證存取 Google Cloud。

聯合使用者身分

您可以使用 gcloud CLI，搭配在外部識別資訊提供者 (IdP) 中管理的聯合使用者身分。您可以使用「員工身分聯盟」執行這項操作。

以下操作說明假設您已設定員工身分聯盟集區和提供者，可與 IdP 搭配運作。

如要透過聯合使用者身分使用 gcloud CLI，請建立登入設定檔，然後使用瀏覽器流程登入：

  1. 執行下列指令，建立登入設定檔：

    Linux 和 macOS

    gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_PATH

    Windows (PowerShell)

    gcloud iam workforce-pools create-login-config `
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
    --output-file=LOGIN_CONFIG_PATH

    更改下列內容：

    • WORKFORCE_POOL_ID：員工身分聯盟集區 ID。
    • WORKFORCE_PROVIDER_ID：員工身分聯盟提供者 ID。
    • LOGIN_CONFIG_PATH：登入設定檔的寫入路徑。例如：login-config.json。

    登入設定檔包含 gcloud CLI 啟動瀏覽器式驗證流程時使用的端點，並將對象設為工作團隊身分集區提供者中設定的 IdP。檔案不含機密資訊。

    登入設定檔內容類似於下列範例：

    {
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

  2. 使用環境變數或使用中 gcloud CLI 設定中的屬性，指向登入設定檔，或直接搭配 gcloud auth login 指令使用：

    環境變數

    如要搭配環境變數使用登入設定檔，請完成下列操作說明：

    1. 將 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境變數設為登入設定檔的路徑。

    2. 執行下列指令：

      gcloud auth login
    3. gcloud CLI 會參照環境變數，找出登入設定檔，然後啟動驗證程序。按照瀏覽器式流程驗證及授權 gcloud CLI，以便日後代表您存取資源。

    如要停止使用 gcloud auth login 指令的登入設定檔，請清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境變數。

    gcloud CLI 設定

    如要搭配使用登入設定檔和 gcloud CLI 設定屬性，請完成下列操作說明：

    1. 使用下列指令，將有效 gcloud CLI 設定的 auth/login_config_file 屬性設為登入設定檔的路徑：

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

    2. 執行下列指令：

      gcloud auth login
    3. gcloud CLI 會參照設定屬性來尋找登入設定檔，然後啟動驗證程序。按照瀏覽器式流程驗證及授權 gcloud CLI，以便日後代表您存取資源。

    如要停止使用登入設定檔執行 gcloud auth login 指令，請使用下列指令取消設定屬性： 

    gcloud config unset auth/login_config_file

    gcloud auth login

    如要直接使用登入設定檔搭配 gcloud auth login 指令，請完成下列操作說明：

    • 如果您在建立登入設定檔時使用 --activate 旗標，請執行下列指令： 

      gcloud