排解 ADC 設定問題

本頁面說明使用應用程式預設憑證 (ADC) 時,可能遇到的常見問題。

如要瞭解 ADC 的運作方式 (包括憑證的位置),請參閱「應用程式預設憑證的運作方式」。

使用者憑證無效

如果 API 要求傳回錯誤訊息,指出這個 API 不支援使用者憑證、API 未在專案中啟用,或未設定配額專案,請參閱下列資訊。

Google Cloud API 有兩種:

  • 資源導向 API:使用與所存取資源相關聯的專案,進行計費和配額。

  • 用戶端 API:使用與用戶端相關聯的專案,存取帳單和配額資源。

提供使用者憑證,向用戶端 API 進行驗證時,必須指定要用於計費和配額的專案。這項專案稱為「配額專案」。

指定配額專案的方法有很多種,包括下列選項:

  • 更新 ADC 檔案,使用其他專案做為配額專案:

    gcloud auth application-default set-quota-project YOUR_PROJECT
    
  • 如果您使用 gcloud CLI 呼叫 API,可以在 gcloud CLI 設定中設定配額專案:

    gcloud config set billing/quota_project YOUR_PROJECT
    
  • 如果您直接呼叫 REST 或 RPC API,請使用 x-goog-user-project HTTP 標頭,在每項要求中指定配額專案。詳情請參閱「使用 REST 要求設定配額專案」。

您必須具備專案的 serviceusage.services.use IAM 權限,才能將其指定為計費專案。serviceusage.services.use 權限包含在 Service Usage Consumer IAM 角色中。如果您沒有任何專案的 serviceusage.services.use 權限,請與安全性管理員或專案擁有者聯絡,請對方在專案中授予您「服務使用情形消費者」角色。

如要進一步瞭解配額專案,請參閱「配額專案總覽」。如要瞭解設定配額專案的其他方式,請參閱「設定配額專案」。

憑證不正確

如果憑證似乎未提供預期的存取權,或找不到憑證,請檢查下列事項:

  • 如果您使用 gcloud CLI 在本機環境中存取 Google Cloud ,請務必瞭解您使用的憑證。使用 gcloud CLI 時,您會使用透過 gcloud auth login 指令提供給 gcloud CLI 的憑證。您並未使用提供給 ADC 的憑證。如要進一步瞭解這兩組憑證,請參閱「gcloud CLI 驗證設定和 ADC 設定」。

  • 請務必「僅」在使用服務帳戶金鑰或其他 JSON 檔案進行 ADC 時,設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數。環境變數指向的憑證優先於其他憑證,包括 Workload Identity Federation for GKE 的憑證。

  • 確認提出要求的主體具備必要的 IAM 角色。如果您使用的是使用者憑證,則必須將角色授予與使用者帳戶相關聯的電子郵件地址。如果您使用的是服務帳戶,該服務帳戶必須具備必要角色。

  • 如果您在 API 要求中提供 API 金鑰,則無論在任何位置,API 金鑰的優先順序都高於 ADC。如果您已設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數,且使用 API 金鑰,API 可能會傳回警告,指出您提供給 ADC 的憑證遭到忽略。如要停止顯示警告,請取消設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數。

驗證範圍不足

如果 API 要求傳回 Request had insufficient authentication scopes,且原因為 ACCESS_TOKEN_SCOPE_INSUFFICIENT,表示存取權杖不含 API 所需的範圍。授予 IAM 角色無法修正這項錯誤。

如要解決錯誤,請執行下列任一操作:

  1. 從錯誤詳細資料的 service 和 method 欄位中找出 API。

  2. 在方法的 API 參考資料或 Google API 的 OAuth 2.0 範圍中,找出 API 所需的範圍。大多數 Google Cloud API 都接受 https://www.googleapis.com/auth/cloud-platform 範圍。Google Workspace API 需要專屬範圍。

  3. 查看權杖具有哪些範圍。在發生錯誤的環境中執行下列指令,並查看 scope 欄位:

    curl "https://oauth2.googleapis.com/tokeninfo?access_token=$(gcloud auth application-default print-access-token)"
  4. 在憑證取得範圍的位置,新增缺少的範圍:

無法辨識的憑證類型

如果 API 要求傳回的錯誤包含 Error creating credential from JSON. Unrecognized credential type,請確認您使用的是有效憑證。用戶端 ID 檔案不支援為 ADC 提供憑證。