授權 gcloud CLI

如要存取 Google Cloud，通常必須授權 Google Cloud CLI。本頁面會說明可用的授權選項，並示範如何管理用於授權的帳戶。如果您使用 Compute Engine 執行個體或 Cloud Shell，則不需要授權 gcloud CLI。

帳戶類型

如要授予 gcloud CLI 存取Google Cloud的權限，您可以使用使用者帳戶或服務帳戶。

使用者帳戶是 Google Cloud 一種帳戶，可供使用者向應用程式驗證身分。在最常見的使用情況下，特別是互動式使用 gcloud CLI 時，最好使用使用者帳戶。

「服務帳戶」是與 Google Cloud 專案相關聯的帳戶Google Cloud ，而非特定使用者。使用 Cloud Run 函式、App Engine、Compute Engine 或 Google Kubernetes Engine 時，您可以運用內建的服務帳戶。建議使用服務帳戶在多部機器上執行 gcloud CLI 指令碼。

選擇授權類型

您必須授權 Google Cloud CLI 管理資源。 Google CloudGoogle Cloud CLI 和 Google Cloud 都使用 OAuth2 進行驗證和授權。

選擇下列其中一種授權種類：

類型 說明
使用者帳戶 如果您要從指令列使用 gcloud CLI，或是要使用 gcloud CLI 編寫指令碼，在單一機器上使用，建議採用這種方法。
服務帳戶 如果您要在正式環境中安裝及設定 gcloud CLI，做為機器部署程序的一部分，或在所有使用者都能存取 root 的 Compute Engine 虛擬機器執行個體上使用，建議採用這種方法。

如要進一步瞭解驗證和 Google Cloud，請參閱驗證總覽。

使用使用者帳戶授權

本節說明如何使用使用者帳戶授權。

使用 Google 帳戶進行驗證

您可以使用下列 gcloud CLI 指令，透過使用者帳戶授權存取：

指令 說明
gcloud init 授予存取權並執行其他常見的設定步驟。
gcloud auth login 僅授權存取。

在授權期間，這些指令會從Google Cloud 取得帳戶憑證，然後將其儲存於本機系統。指定的帳戶會變成設定中的使用中帳戶。 gcloud CLI 會使用儲存的憑證存取Google Cloud。您可以在單一 gcloud CLI 安裝上擁有已儲存的憑證帳戶，不限數量，但不論何時，您都只能有一個使用中的帳戶。

執行 gcloud init

gcloud init 可授權存取並執行其他常見的設定步驟。gcloud init 會使用網頁式授權流程驗證使用者帳戶，並授予存取權限。

如要授權存取權並執行其他常見設定步驟，請按照下列步驟操作：

  1. 執行 gcloud init：

    gcloud init

    或是，如要預防指令自動開啟網路瀏覽器：

    gcloud init --console-only

    如果您使用 ssh 在遠端系統上執行指令，但無法存取該系統上的瀏覽器，使用 --console-only 標記就非常實用。您必須在本機系統的瀏覽器中手動開啟提供的網址，才能完成授權程序。

  2. 按照瀏覽器式授權流程來驗證帳戶並授予存取權限。

如要進一步瞭解 gcloud init，請參閱「初始化 gcloud CLI」。

執行 gcloud auth login

執行 gcloud auth login 只會授權使用者帳戶。 如要授權存取權而不執行其他設定步驟，請使用下列任一選項。

  • 如要在有瀏覽器的機器上授權 gcloud CLI，請按照下列步驟操作。

    1. 授權 gcloud CLI：

      gcloud auth login

    2. 按照瀏覽器式授權流程來驗證帳戶並授予存取權限。

  • 如要在沒有瀏覽器的機器上授權 gcloud CLI，但您可以在有瀏覽器的另一部機器上安裝 gcloud CLI，請使用 --no-browser 標記。

    1. 授權 gcloud CLI：

      gcloud auth login --no-browser

    2. 複製開頭為 gcloud auth login --remote-bootstrap=" 的長指令。

    3. 在其他受信任的電腦上，貼上並執行這個指令。這部電腦必須在本機安裝網頁瀏覽器和 gcloud CLI 工具 372.0 以上版本。

    4. 在有網路瀏覽器的電腦上，複製輸出的長網址。

    5. 在「Enter the output of the above command」(輸入上述指令的輸出內容) 提示下方，將長網址貼回第一部電腦，然後按下 Enter 鍵完成授權。

  • 如要在沒有瀏覽器的電腦上授權 gcloud CLI，且無法在有瀏覽器的其他電腦上安裝 gcloud CLI，請使用 --no-launch-browser 標記。--no-launch-browser 標記可防止指令自動開啟網頁瀏覽器。

    1. 授權 gcloud CLI：

      gcloud auth login --no-launch-browser

    2. 複製開頭為 https://accounts.google.com/o/oauth2/auth... 的長網址

    3. 將這個網址貼到其他信任裝置的瀏覽器中。

    4. 從有網路瀏覽器的電腦複製授權碼。

    5. 在第一個機器的提示「Enter verification code」(輸入驗證碼) 中，貼回授權碼並按下 Enter 鍵，完成授權。

  • 如果您已有存取權杖，請使用下列其中一種方法，將存取權杖傳遞至 gcloud CLI：

    • 將存取權杖儲存在檔案中，並透過 --access-token-file 標記設定路徑。
    • 將存取權杖儲存在檔案中，並在 auth/access_token_file 屬性中設定路徑。
    • 將 CLOUDSDK_AUTH_ACCESS_TOKEN 環境變數設為存取權杖值。

使用員工身分聯盟進行驗證

本節說明如何使用 Workforce Identity Federation 登入 gcloud CLI。

透過瀏覽器登入 gcloud CLI

如要使用瀏覽器登入流程登入 gcloud CLI，請執行下列操作：

  1. 建立登入設定檔。

    如要建立登入設定檔，請執行下列指令。您可以視需要新增 --activate 標記，將檔案設為 gcloud CLI 的預設設定。這樣一來，您之後執行 gcloud auth login 時，就不必每次都指定設定檔路徑。

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

    更改下列內容：

    • WORKFORCE_POOL_ID：工作團隊集區 ID
    • PROVIDER_ID：供應商 ID
    • LOGIN_CONFIG_FILE_PATH：您指定的設定檔路徑，例如 login.json

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

    輸出看起來類似以下內容：

    {
  "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",
}

    如要停止讓 gcloud auth login 自動使用這個設定檔，可以執行 gcloud config unset auth/login_config_file 取消設定。

  2. 使用瀏覽器型驗證登入。

    如要使用瀏覽器型登入驗證進行驗證，可以採用下列其中一種方法：

    • 如果您在建立設定檔時使用 --activate 標記，或使用 gcloud config set auth/login_config_file 啟用設定檔，gcloud CLI 會自動使用您的設定檔：

      gcloud auth login

    • 如要指定設定檔位置來登入，請執行下列指令：

      gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
    • 如要使用環境變數指定設定檔位置，請將 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 設為設定路徑。

如要停止使用登入設定檔，請按照下列步驟操作：

  • 如果您在建立設定檔時使用了 --activate 旗標，或是使用 gcloud config set auth/login_config_file 啟用了設定檔，則必須執行下列指令來取消設定：

    gcloud config unset auth/login_config_file
  • 清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境變數 (如果已設定)。

gcloud CLI 無頭登入

如要使用無頭流程登入 gcloud CLI，請執行下列操作：

OIDC

  1. 讓使用者登入 IdP 應用程式，並取得 OIDC 權杖。

    如要瞭解如何取得權杖，請參閱 IdP 的 OIDC 說明文件。

  2. 將 IdP 傳回的 OIDC 權杖儲存在本機電腦的安全位置。

  3. 執行下列指令來產生設定檔：

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
    --credential-source-file="PATH_TO_OIDC_ID_TOKEN" \
    --workforce-pool-user-project="WORKFORCE_POOL_USER_PROJECT" \
    --output-file="config.json"

更改下列內容：

  • WORKFORCE_POOL_ID：工作團隊集區 ID
  • PROVIDER_ID：供應商 ID
  • PATH_TO_OIDC_TOKEN：OIDC IdP 憑證檔案的路徑
  • WORKFORCE_POOL_USER_PROJECT：與工作團隊集區使用者專案相關聯的專案編號

主體必須具備這項專案的 serviceusage.services.use 權限。

執行指令後，系統會產生 OIDC IdP 設定檔，格式類似於下列範例：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

SAML

  1. 讓使用者登入 IdP 應用程式，並取得 SAML 聲明。

    如要瞭解如何從 IdP 取得 SAML 聲明，請參閱 IdP 的 SAML 說明文件。

  2. 將 IdP 傳回的 SAML 回應儲存在本機電腦的安全位置，然後儲存路徑，如下所示：

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. 如要產生設定檔，請執行下列指令：

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:saml2" \
    --credential-source-file="SAML_ASSERTION_PATH"  \
    --workforce-pool-user-project="PROJECT_ID"  \
    --output-file="config.json"

    更改下列內容：

    • WORKFORCE_PROVIDER_ID：您在本指南中稍早建立的工作團隊提供者 ID。
    • WORKFORCE_POOL_ID：您在本指南中稍早建立的工作團隊集區 ID。
    • SAML_ASSERTION_PATH：SAML 聲明檔案的路徑。
    • PROJECT_ID：專案 ID

    產生的設定檔類似於下列內容：

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "SAML_ASSERTION_PATH"
  },
  "workforce_pool_user_project": "PROJECT_ID"
}

如要使用權杖交換登入 gcloud，請執行下列指令：

gcloud auth login --cred-file="config.json"

gcloud 接著會以 IdP 憑證換取臨時 Google Cloud 存取權杖，讓您對 Google Cloud發出其他 gcloud 呼叫。

輸出結果會與下列內容相似：

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

如要列出已通過驗證的帳戶和目前使用中的帳戶，請執行下列指令：

gcloud auth list

使用服務帳戶授權

gcloud auth login 指令可使用儲存在本機檔案系統的憑證檔案，透過服務帳戶授權存取權。這項憑證可以是具備服務帳戶模擬權限的使用者憑證、Workload Identity Federation 的憑證設定檔，或是服務帳戶金鑰。

使用服務帳戶模擬功能授權服務帳戶

如要授權 gcloud CLI 使用模擬服務帳戶憑證，請執行下列操作：

  1. 前往 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面。

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

  2. 選擇現有帳戶，或按一下「建立服務帳戶」建立新帳戶。

  3. 如要取得模擬服務帳戶所需的權限，請要求管理員授予您服務帳戶的「服務帳戶權杖建立者」 (roles/iam.serviceAccountTokenCreator) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    這個預先定義的角色包含 iam.serviceAccounts.getAccessToken權限，這是模擬服務帳戶時的必要權限。

    您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

  4. 執行 gcloud auth login，使用使用者身分授權 gcloud CLI。

  5. 如要設定 gcloud CLI，使其預設使用服務帳戶提供的身分和存取權，請使用 gcloud CLI config 指令：

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. 如要停止預設使用 gcloud CLI 模擬的服務帳戶憑證，請使用 gcloud CLI config 指令取消設定旗標：

    gcloud config unset auth/impersonate_service_account

使用 Workload Identity Federation 授權服務帳戶

如要使用 Workload Identity Federation 的外部憑證，透過服務帳戶授權 gcloud CLI，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面。

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

  2. 選擇現有帳戶，或按一下「建立服務帳戶」建立新帳戶。

  3. 按照支援的識別資訊提供者指示，為 Workload Identity 聯盟建立憑證設定檔。

  4. 如要啟用服務帳戶，請使用 --cred-file 旗標執行 gcloud auth login：

    gcloud auth login --cred-file=CONFIGURATION_FILE

    將 CONFIGURATION_FILE 替換為 Workload Identity Federation 的憑證設定檔路徑。

使用服務帳戶金鑰授權服務帳戶

如要使用服務帳戶金鑰，透過服務帳戶授權 gcloud CLI，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面。

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

  2. 選擇現有帳戶，或按一下「建立服務帳戶」建立新帳戶。

  3. 如要建立服務帳戶金鑰，請參閱 IAM 說明中的建立服務帳戶金鑰。

  4. 如要啟用服務帳戶，請使用 --cred-file 旗標執行 gcloud auth login：

    gcloud auth login --cred-file=KEY_FILE

    將 KEY_FILE 替換為服務帳戶金鑰檔案的路徑。

列出帳戶

如要列出將憑證儲存在本機系統上的帳戶，請執行 gcloud auth list：

gcloud auth list

gcloud CLI 會列出帳戶並顯示使用中的帳戶：

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

切換使用中帳戶

如要切換使用中帳戶，請執行 gcloud config set：

gcloud config set account ACCOUNT

其中 [ACCOUNT] 是帳戶的完整電子郵件地址。

您也能透過建立指定不同帳戶的個別配置來切換帳戶，並在不同配置之間切換：

gcloud config configurations activate CONFIGURATION

如要在每次叫用時切換 gcloud CLI 使用的帳戶，請使用 --account 標記覆寫使用中的帳戶。

設定授權工作階段長度

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

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

撤銷帳戶憑證

當您要禁止特定帳戶使用 gcloud CLI 存取時，可以撤銷憑證。您不需要為了切換帳戶而撤銷憑證。

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

gcloud auth revoke ACCOUNT

如要在所有機器上撤銷所有用於 gcloud CLI 的存取權，請從可存取您帳戶的應用程式清單上移除 gcloud CLI。

使用憑證檔案

尋找憑證檔案

如要尋找憑證檔案的位置，請執行 gcloud info：

gcloud info

gcloud CLI 會輸出安裝相關資訊。憑證檔案會儲存於使用者配置目錄中：

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

設定應用程式預設憑證

gcloud CLI 支援使用 gcloud auth application-default 指令群組管理應用程式預設憑證 (ADC)。如要讓 ADC 使用者憑證，請執行 gcloud auth application-default login：

gcloud auth application-default login

gcloud CLI 不會使用這些憑證。如要瞭解設定 ADC 的其他方式，請參閱「設定應用程式預設憑證」。

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

後續步驟

  • 如要進一步瞭解驗證和 Google Cloud，請參閱驗證總覽。
  • 如要進一步瞭解如何自訂 gcloud CLI，請參閱 gcloud CLI 屬性。
  • 如要進一步瞭解如何管理 gcloud CLI 屬性的命名集，請參閱「gcloud CLI 設定」。