Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

驗證 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 後，請立即執行下列指令：初始化程序會包含驗證和授權。如果您需要使用其他主體存取不同資源，或是需要重新驗證主體，可能仍須再次驗證。
從公開 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支援兩種同盟主體，名稱相似：
- 員工身分聯盟：允許使用者透過外部識別資訊提供者管理的身分登入 Google Cloud 。如果貴機構已設定單一登入 (SSO)，您可以使用這類身分驗證 Google Cloud。
  
  如要使用員工身分聯盟，您的識別資訊提供者必須支援 OpenID Connect (OIDC) 或 SAML 2.0。
- Workload Identity Federation：允許在 Google Cloud 外部執行的工作負載對 Google Cloud 資源執行作業。
  
  您可以搭配使用 Workload Identity Federation 與下列工作負載：使用 X.509 用戶端憑證驗證身分的工作負載；在 Amazon Web Services (AWS) 或 Azure 上執行的工作負載；在地端部署 Active Directory 上執行的工作負載；部署服務 (例如 GitHub 和 GitLab)；以及支援 OpenID Connect (OIDC) 或安全宣告標記語言 (SAML) V2.0 的任何識別資訊提供者。

以人類身分使用 gcloud CLI

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

使用者帳戶
使用員工身分聯盟的聯合使用者身分

使用者帳戶

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

裝置有網路瀏覽器

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

執行下列指令來啟動程序：
```
gcloud auth login
```
按照瀏覽器式流程驗證並授權 gcloud CLI，以便日後代表您存取資源。

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

我的裝置沒有網路瀏覽器

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

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

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

gcloud CLI 和網路瀏覽器

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

在要使用 gcloud CLI 的原始裝置上執行下列指令：
Linux 和 macOS
gcloud auth login \ --no-browser
Windows (PowerShell)
gcloud auth login ` --no-browser
複製以 gcloud auth login --remote-bootstrap=" 開頭的 gcloud 指令，以便在其他裝置上使用。
前往其他受信任的裝置，該裝置必須安裝網頁瀏覽器和 gcloud CLI 372.0.0 以上版本。
在終端機中執行先前複製的指令 (開頭為 gcloud auth login --remote-bootstrap=")，然後完成瀏覽器流程。
在終端機中，複製以 https://localhost 開頭的網址，以便在原始裝置上使用。
返回原始裝置。
在終端機的提示中，貼上您先前複製的 https://localhost 網址。按下鍵盤上的 Enter 或 Return 鍵，即可完成程序。

僅限網路瀏覽器

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

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

Linux 和 macOS

gcloud auth login \
    --no-launch-browser

Windows (PowerShell)

gcloud auth login `
    --no-launch-browser

複製開頭為 https://accounts.google.com/o/oauth2/auth 的網址，以便在其他裝置上使用。
前往已安裝網頁瀏覽器的其他信任裝置。
開啟網路瀏覽器，前往先前複製的網址，然後完成瀏覽器流程。
複製驗證碼，以便在原始裝置上使用。
返回原始裝置。
在終端機的提示字元中，貼上您先前複製的驗證碼。按下鍵盤上的 Enter 或 Return 鍵，完成程序。

聯合使用者身分

您可以使用 gcloud CLI，透過外部識別資訊提供者 (IdP) 管理的聯合使用者身分進行操作。方法是使用員工身分聯盟。

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

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

執行下列指令，建立登入設定檔：
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
注意：您可以選擇新增 --activate 旗標，將登入設定檔設為 gcloud CLI 的預設設定檔。接著，您就可以執行 gcloud auth login 來授權 gcloud CLI，不必每次都指定登入設定檔路徑。

更改下列內容：
- 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"
}
```
注意：建議您先確認這個檔案的內容正確無誤，然後保護檔案，例如設為唯讀，並使用 ACL 限制存取權。系統不會驗證檔案，如果惡意行為人擁有這個檔案的寫入權，就能變更端點並攔截憑證。
使用環境變數或使用中 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 auth login
- 如果您在建立登入設定檔時未使用 --activate 旗標，請執行下列指令：
  
  Linux 和 macOS
  
  gcloud auth login \ --login-config=LOGIN_CONFIG_PATH
  
  Windows (PowerShell)
  
  gcloud auth login ` --login-config=LOGIN_CONFIG_PATH
  
  請將 LOGIN_CONFIG_PATH 替換為登入設定檔的路徑。
gcloud auth login 指令會將存取憑證儲存在主目錄中。通過驗證的主體會成為有效 gcloud CLI 設定中的有效主體。除非遭到覆寫，否則 gcloud CLI 會使用這些已儲存的憑證存取 Google Cloud。

注意：任何有權存取檔案系統的使用者，都能使用 gcloud auth login 建立的儲存存取憑證。為減少系統遭入侵的後果，請嚴格區隔人員和工作負載的使用情形，且不要在具有持續性儲存空間的遠端系統上，為自動化工作負載使用 gcloud auth login。請盡可能搭配使用密鑰管理工具和環境變數，

如需強化遠端系統的更多指引，請參閱「防範 Google Cloud CLI 的 OAuth 權杖遭盜用」。

搭配工作負載使用 gcloud CLI

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

使用 Workload Identity 聯盟的聯合工作負載身分
使用模擬功能的服務帳戶

聯合工作負載身分

您可以搭配聯合工作負載身分使用 gcloud CLI。方法是使用 Workload Identity Federation。

工作負載可以做為工作負載身分集區定義的主體，直接存取 Google Cloud 資源，也可以模擬附加至工作負載身分集區的服務帳戶。

建議您使用直接存取方法，避免服務帳戶權限過多，並使用聯盟主體的 ID 記錄資源存取權。只有在 Google Cloud API 不支援 Workload Identity Federation 時，才使用服務帳戶模擬功能。

以下操作說明假設您已設定好 Workload Identity Federation 集區和提供者，可與 IdP 搭配使用。

請按照支援的識別資訊提供者操作說明，為 Workload Identity Federation 建立憑證設定檔。
在環境變數中、有效 gcloud CLI 設定的屬性中，或使用 gcloud auth login 指令，定義憑證設定檔的路徑：
環境變數
將 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 環境變數設為憑證設定檔的路徑。gcloud CLI 每次執行指令時都會參照這個檔案，並從 IdP 取得憑證。這個憑證會換取 Google Cloud的存取權杖。

如要停止使用憑證設定檔，請清除 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 環境變數。
gcloud CLI 設定
使用下列指令，將有效 gcloud CLI 設定的 auth/credential_file_override 屬性設為憑證設定檔的路徑：
gcloud config set auth/credential_file_override CONFIGURATION_PATH
將 CONFIGURATION_PATH 替換為憑證設定檔的路徑。

如要停止預設使用憑證設定檔執行 gcloud 指令，請使用下列指令取消設定屬性：
gcloud config unset auth/credential_file_override
gcloud auth login
使用 --cred-file 旗標執行下列指令：
Linux 和 macOS
gcloud auth login \ --cred-file=CONFIGURATION_PATH

Windows (PowerShell)
gcloud auth login ` --cred-file=CONFIGURATION_PATH
將 CONFIGURATION_PATH 替換為憑證設定檔的路徑。

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

注意：任何有權存取檔案系統的使用者，都能使用 gcloud auth login 建立的儲存存取憑證。為減少系統遭入侵的後果，請嚴格區隔人員和工作負載的使用情形，且不要在具有持續性儲存空間的遠端系統上，為自動化工作負載使用 gcloud auth login。請盡可能搭配使用密鑰管理工具和環境變數，

如需強化遠端系統的更多指引，請參閱「防範 Google Cloud CLI 的 OAuth 權杖遭盜用」。

服務帳戶

您可以使用 gcloud CLI 和服務帳戶執行下列操作：

在公開 Compute Engine 中繼資料伺服器的資源上，例如 Compute Engine VM 執行個體或 Cloud Run 服務。根據預設，gcloud CLI 會使用附加至資源的服務帳戶進行驗證。
使用其他主體模擬服務帳戶。
使用服務帳戶金鑰。

服務帳戶模擬

如果主體通常無法存取資源，建議您使用 Privileged Access Manager 管理提權，而非使用服務帳戶模擬。

如果 Privileged Access Manager 不符合您的用途，請完成下列步驟，透過服務帳戶使用 gcloud CLI：

如要模擬服務帳戶，請確認專案已啟用 Service Account Credentials API。

啟用 API 時所需的角色
如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 API
選擇要用來模擬服務帳戶的主體。
如要確保主體具備模擬服務帳戶的必要權限，請要求管理員在服務帳戶中，將「服務帳戶權杖建立者」 (roles/iam.serviceAccountTokenCreator) IAM 角色授予主體。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 iam.serviceAccounts.getAccessToken 權限，可模擬服務帳戶。
管理員或許還可透過自訂角色或其他預先定義的角色，授予主體這項權限。
使用您先前選擇的主體 ( 使用者帳戶、聯合使用者身分、聯合工作負載身分或其他服務帳戶)，向 gcloud CLI 進行驗證。
選擇要模擬的服務帳戶。找出現有服務帳戶，或建立新的服務帳戶。
複製服務帳戶的「電子郵件」地址。
選擇要模擬所有指令的服務帳戶，還是只模擬單一指令：
所有指令
如要在日後的指令中，透過 gcloud CLI 使用服務帳戶模擬功能，可以設定環境變數，或在有效 gcloud CLI 設定中設定屬性：
- 環境變數：將 CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 環境變數設定為服務帳戶電子郵件地址。
  
  如要停止使用服務帳戶，請清除 CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 環境變數。
- gcloud CLI 設定：使用下列指令設定有效 gcloud CLI 設定的 auth/impersonate_service_account 屬性：
  
  gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL
  
  將 SERVICE_ACCOUNT_EMAIL 替換成服務帳戶的電子郵件地址。
  
  如要停止對 gcloud 指令預設使用服務帳戶模擬功能，請執行下列指令取消設定屬性：
  
  gcloud config unset auth/impersonate_service_account
單一指令
如要透過 gcloud CLI 對單一指令使用服務帳戶模擬功能，請將 --impersonate-service-account 旗標新增至 gcloud CLI 服務指令。

舉例來說，如要使用服務帳戶模擬功能列出 Compute Engine VM 執行個體，請執行下列指令：
Linux 和 macOS
gcloud compute instances list \ --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

Windows (PowerShell)
gcloud compute instances list ` --impersonate-service-account=SERVICE_ACCOUNT_EMAIL
將 SERVICE_ACCOUNT_EMAIL 替換成服務帳戶的電子郵件地址。

服務帳戶金鑰

建議您針對在 Google Cloud外部執行的多數工作負載，使用 Workload Identity 聯盟。只有在工作負載於不支援 Workload Identity 聯盟的獨立外部環境中執行時，才使用服務帳戶金鑰。

Workload Identity 聯盟具有下列優點：

資源存取權是透過 Identity and Access Management (IAM) 授予，工作負載則視為個別主體。這表示您不需要為多個用途過度授權服務帳戶。
您可以稽核哪些工作負載正在執行哪些工作，動作不會隱藏在服務帳戶電子郵件地址後方。
Workload Identity Federation 會使用短期存取權杖，降低外洩風險。服務帳戶金鑰不會過期，除非手動撤銷。

如要在日後的指令中，透過 gcloud CLI 使用服務帳戶，請執行下列操作：

建立服務帳戶金鑰，並將其儲存為環境中安全位置的檔案。
在環境變數中定義服務帳戶金鑰檔案的路徑、做為有效 gcloud CLI 設定中的屬性，或使用 gcloud auth login 指令：
- 環境變數：將 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 環境變數設為服務帳戶金鑰檔案的路徑。
  
  如要停止使用服務帳戶金鑰，請清除 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 環境變數。
- gcloud CLI 設定：使用下列指令，將有效 gcloud CLI 設定的 auth/credential_file_override 屬性設為服務帳戶金鑰的路徑：
```
gcloud config set auth/credential_file_override KEY_PATH
```
  將 KEY_PATH 替換為服務帳戶金鑰檔案的路徑。
  
  如要停止預設使用服務帳戶金鑰執行 gcloud 指令，請執行下列指令取消設定屬性：
```
gcloud config unset auth/credential_file_override
```
- gcloud auth login：使用 --cred-file 旗標執行下列指令：
  Linux 和 macOS
  gcloud auth login \ --cred-file=KEY_PATH
  Windows (PowerShell)
  gcloud auth login ` --cred-file=KEY_PATH
  將 KEY_PATH 替換為服務帳戶金鑰檔案的路徑。
  
  gcloud auth login 指令會將存取憑證儲存在主目錄中。通過驗證的主體會成為有效 gcloud CLI 設定中的有效主體。除非遭到覆寫，否則 gcloud CLI 會使用這些已儲存的憑證存取 Google Cloud。
  
  注意：任何有權存取檔案系統的使用者，都能使用 gcloud auth login 建立的儲存存取憑證。為減少系統遭入侵的後果，請嚴格區隔人員和工作負載的使用情形，且不要在具有持續性儲存空間的遠端系統上，為自動化工作負載使用 gcloud auth login。請盡可能搭配使用密鑰管理工具和環境變數，
  
  如需強化遠端系統的更多指引，請參閱「防範 Google Cloud CLI 的 OAuth 權杖遭盜用」。
  
  注意： 如為 P12 舊版格式的服務帳戶金鑰，請使用 gcloud auth activate-service-account 指令。

使用存取權杖搭配 gcloud CLI

如果您已在其他裝置上驗證 gcloud CLI，可以執行下列指令，為該裝置的有效主體取得存取權杖：

gcloud auth print-access-token

然後在其他裝置上使用這個存取權杖，存取 Google Cloud資源。使用存取權杖時，不需要設定有效主體，且會覆寫有效 gcloud CLI 設定中設定的任何有效主體。

使用者帳戶的存取權杖預設效期為一小時。

您可以在 gcloud CLI 中使用存取權杖，執行後續指令或單一指令。

所有指令

如要在日後的指令中使用存取權杖搭配 gcloud CLI，可以設定環境變數，或在有效的 gcloud CLI 設定中設定屬性：

環境變數：將 CLOUDSDK_AUTH_ACCESS_TOKEN 環境變數設為存取權杖字串。

如要停止使用存取權杖，請清除 CLOUDSDK_AUTH_ACCESS_TOKEN 環境變數。
gcloud CLI 設定：將存取權杖儲存在檔案中，然後使用下列指令，將有效 gcloud CLI 設定的 auth/access_token_file 屬性設為檔案路徑：
```
gcloud config set auth/access_token_file ACCESS_TOKEN_PATH
```
將 ACCESS_TOKEN_PATH 替換為存取權杖檔案的路徑。

如要停止預設使用存取權杖執行 gcloud 指令，請使用下列指令取消設定屬性：
```
gcloud config unset auth/access_token_file
```

單一指令

如要透過 gcloud CLI 對單一指令使用存取權杖，請將 --access-token-file 標記新增至 gcloud CLI 服務指令：

將存取權杖儲存到檔案中。
搭配任何 gcloud 服務指令使用 --access-token-file 旗標。

舉例來說，如要使用存取權杖列出 Compute Engine VM 執行個體，請執行下列指令：
Linux 和 macOS
gcloud compute instances list \ --access-token-file ACCESS_TOKEN_PATH
Windows (PowerShell)
gcloud compute instances list ` --access-token-file ACCESS_TOKEN_PATH
將 ACCESS_TOKEN_PATH 替換為存取權杖檔案的路徑。

憑證優先順序

由於一個環境中可能會使用多種驗證方法，因此 gcloud CLI 會依特定順序評估這些方法，判斷要使用哪個主體。gcloud CLI 會先使用提供的憑證，然後評估是否已要求服務帳戶模擬。

系統會依下列順序評估提供的憑證：

CLOUDSDK_AUTH_ACCESS_TOKEN 環境變數，設為存取權杖字串。
存取權杖檔案。系統會依下列順序評估用於定義存取權杖檔案路徑的方法：
1. --access-token-file 指令列旗標，可搭配任何 gcloud CLI 指令使用。
2. CLOUDSDK_AUTH_ACCESS_TOKEN_FILE 環境變數。
3. gcloud CLI 有效設定中的 auth/access_token_file 屬性。
憑證檔案。系統會依下列順序評估用於定義憑證檔案路徑的方法：
1. CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 環境變數。
2. gcloud CLI 有效設定中的auth/credential_file_override屬性。
由 gcloud auth login 指令設定的有效主體，或由設定 core/account 屬性設定的有效主體。

服務帳戶模擬優先順序

如果要求服務帳戶模擬，gcloud CLI 會在為執行模擬作業的主體提供憑證後，檢查要模擬的服務帳戶。系統會依下列順序評估用於定義模擬服務帳戶的方法：

--impersonate-service-account 指令列旗標。
CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 環境變數。
由有效設定中的 auth/impersonate_service_account 屬性定義的服務帳戶。

將 Google 雲端硬碟新增至範圍

除了 Google Cloud之外，gcloud CLI 範圍還可擴大，納入 Google 雲端硬碟存取權。這表示您可以使用 Google Cloud 存取權杖 Google Cloud 存取 Google 雲端硬碟。

如要將範圍擴大到 Google 雲端硬碟，請在授權 gcloud CLI 時新增 --enable-gdrive-access 旗標：

Linux 和 macOS

gcloud auth login \
    --enable-gdrive-access

Windows (PowerShell)

gcloud auth login `
    --enable-gdrive-access

然後，您可以使用 gcloud CLI 呼叫 Google 雲端硬碟 API，提供存取權杖。舉例來說，如要列出 Google 雲端硬碟中的所有檔案，可以發出下列要求：

Linux 和 macOS

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows (PowerShell)

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

舉例來說，您可以使用先前指令回應中的檔案 ID，從 Google 文件檔案擷取文字：

Linux 和 macOS

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows (PowerShell)

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Google 雲端硬碟存取權的常見用途是搭配 BigQuery 使用儲存在 Google 試算表中的資料。

如要進一步瞭解 Google Drive API，請參閱「Google Drive API 總覽」。

將 gcloud CLI 新增為 Docker 的憑證輔助程式

如要從 Artifact Registry 容器登錄檔提取內容，可以將 gcloud CLI 新增為 Docker 設定的憑證輔助程式。

如要進行這項操作，請執行 gcloud auth configure-docker 指令：

gcloud auth configure-docker REGION-docker.pkg.dev

管理主體和憑證

您可以使用 gcloud auth login 指令在相同環境中驗證多個主體，並授權 gcloud CLI 代表這些主體存取資源。不過，一次只能啟用一個主體。以下各節說明如何透過 gcloud CLI 設定管理主體，包括列出主體、在主體之間切換，以及撤銷主體憑證。

列出主體

如要列出存取憑證儲存在本機系統中的主體 (也就是已使用 gcloud auth login 驗證身分的主體)，請執行 gcloud auth list 指令：

gcloud auth list

gcloud CLI 會列出主體，並顯示哪個主體處於啟用狀態：

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

這個清單不包含有效主體的覆寫項目，包括下列環境變數：

CLOUDSDK_AUTH_ACCESS_TOKEN
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

如要檢查是否已設定這些環境變數，請為您的作業系統執行下列指令：

Linux 和 macOS

echo "$ENVIRONMENT_VARIABLE"

Windows (PowerShell)

echo $env:ENVIRONMENT_VARIABLE

將 ENVIRONMENT_VARIABLE 替換成要檢查的環境變數。

有效主體的覆寫項目也包含下列設定屬性：

auth/access_token_file
auth/credential_file_override
auth/impersonate_service_account

如要檢查是否已設定這些設定屬性，請執行下列指令：

gcloud config list

切換有效主體

如要切換至已儲存憑證的有效主體 (也就是先前已完成 gcloud auth login 流程的主體)，請執行 gcloud config set：

gcloud config set account PRINCIPAL_IDENTIFIER

將 PRINCIPAL_IDENTIFIER 替換為主體的完整 ID。

您也可以透過下列方式切換主體：

建立個別設定，指定不同的有效主體，然後啟用該設定。
使用 --account 指令列標記，為單一指令指定主體。
使用覆寫，例如指令列旗標、環境變數或設定屬性。

設定工作階段時間長度

管理員可以控管不同使用者每次使用 gcloud CLI 的時間，決定他們必須在使用多久後重新驗證。舉例來說，您可以強制進階權限的使用者比一般使用者更頻繁地重新驗證。

詳情請參閱「設定 Google Cloud 服務的工作階段時間長度」。

撤銷主體的憑證

您可以撤銷已透過 gcloud auth login 驗證的主體憑證，讓 gcloud CLI 無法代表主體執行動作。撤銷作業會使 Google 授權伺服器上的憑證失效，並從有效的 gcloud CLI 設定中移除主體。

如要撤銷憑證，請執行 gcloud auth revoke：

gcloud auth revoke PRINCIPAL_IDENTIFIER

將 PRINCIPAL_IDENTIFIER 替換為主體的完整 ID。

如要撤銷所有與 Google 帳戶相關聯裝置的 gcloud CLI 存取權，請前往 Google 帳戶設定中的「第三方應用程式和服務」，然後刪除與 Google Cloud SDK 的所有連結。

管理已儲存的憑證

gcloud CLI 會將使用的憑證檔案儲存在 gcloud CLI 設定目錄中。如要尋找憑證檔案的位置，請執行 gcloud info：

gcloud info

gcloud CLI 會輸出關於安裝作業的相關資訊。憑證檔案會儲存在輸出內容中定義的使用者設定目錄中：

User Config Directory: [/home/USERNAME/.config/gcloud]

在 Linux 和 macOS 中，gcloud CLI 設定目錄通常是 /home/USERNAME/.config/gcloud。如果是 Windows，則為 %APPDATA%\gcloud。

後續步驟

如要進一步瞭解如何自訂 gcloud CLI，請參閱「gcloud CLI 屬性」。
如要進一步瞭解如何管理 gcloud CLI 屬性的命名集，請參閱 gcloud CLI 設定。
如要驗證使用 Cloud 用戶端程式庫或 Google API 用戶端程式庫的程式碼型工作負載，請參閱「應用程式預設憑證的運作方式」。

驗證 gcloud CLI 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

驗證方法

不需要驗證的情況

為工作選擇適當的主體

以人類身分使用 gcloud CLI

使用者帳戶

裝置有網路瀏覽器

我的裝置沒有網路瀏覽器

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

gcloud CLI 和網路瀏覽器

Linux 和 macOS

Windows (PowerShell)

僅限網路瀏覽器

Linux 和 macOS

Windows (PowerShell)

聯合使用者身分

Linux 和 macOS

Windows (PowerShell)

環境變數

gcloud CLI 設定

gcloud auth login

Linux 和 macOS

Windows (PowerShell)

搭配工作負載使用 gcloud CLI

聯合工作負載身分

環境變數

gcloud CLI 設定

gcloud auth login

Linux 和 macOS

Windows (PowerShell)

服務帳戶

服務帳戶模擬

所有指令

單一指令

Linux 和 macOS

Windows (PowerShell)

服務帳戶金鑰

Linux 和 macOS

Windows (PowerShell)

使用存取權杖搭配 gcloud CLI

所有指令

單一指令

Linux 和 macOS

Windows (PowerShell)

憑證優先順序

服務帳戶模擬優先順序

將 Google 雲端硬碟新增至範圍

Linux 和 macOS

Windows (PowerShell)

Linux 和 macOS

Windows (PowerShell)

Linux 和 macOS

Windows (PowerShell)

將 gcloud CLI 新增為 Docker 的憑證輔助程式

管理主體和憑證

列出主體

Linux 和 macOS

Windows (PowerShell)

切換有效主體

設定工作階段時間長度

撤銷主體的憑證

管理已儲存的憑證

後續步驟

驗證 gcloud CLI