權杖類型

本頁面將說明用於驗證 Google API、Google Cloud 服務和客戶在 Google Cloud上代管的服務的權杖類型。

如果您是透過使用用戶端程式庫存取 Google API 和服務，可以設定應用程式預設憑證，用戶端程式庫會為您處理權杖。這是我們建議的做法。

符記

在驗證和授權程序中，符記是數位物件，其中包含有關提出要求的主體資訊，以及該主體獲授權的存取權類型。在大多數的驗證流程中，應用程式或應用程式使用的程式庫會將憑證換成權杖，而權杖會決定應用程式可存取哪些資源。

權杖類型

不同環境會使用不同類型的符記。本頁說明下列符記類型：

• 存取權杖
• ID 權杖
• 自行簽署的 JWT
• 更新權杖
• 不記名權杖

存取權杖

存取權杖是符合 OAuth 2.0 架構的不明確權杖。這些屬性包含用於建立權杖的實體類型資訊，以及授權資訊。這些資訊會用於向 Google API 驗證並提供授權資訊。存取權存取權杖不含主體的 ID。

如果您使用應用程式預設憑證 (ADC)和 Cloud 用戶端程式庫或 Google API 用戶端程式庫，就不需要管理存取權杖；程式庫會自動擷取憑證、兌換成存取權杖，並視需要重新整理存取權杖。

存取權杖內容

存取權杖是不可見的權杖，也就是說，它們採用專屬格式，應用程式無法檢查。

您可以使用 Google OAuth 2.0 tokeninfo 端點，從有效 (未到期或已撤銷) 的存取權杖取得資訊。

請將 ACCESS_TOKEN 替換為有效且未過期的存取權杖。

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

這個指令會傳回類似以下的內容：

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

下表列出最重要的欄位：

存取權杖的生命週期

根據預設，存取權杖的有效期間為 1 小時 (3,600 秒)。存取權杖到期時，您的權杖管理程式碼必須取得新的權杖。

如果您需要的是有效期限較長或較短的存取權杖，可以使用 serviceAccounts.generateAccessToken 方法建立權杖。您可以使用這個方法選擇權杖的生命週期，最多 12 小時。

如果您想將權杖生命週期延長至超過預設值，必須建立機構政策，啟用 iam.allowServiceAccountCredentialLifetimeExtension 限制。詳情請參閱「建立短期存取權權杖」一文。

聯合存取權杖

聯合存取權權杖是 Security Token Service API 傳回的存取權權杖，用於交換 Workload Identity Federation 和 Workforce Identity Federation 透過聯合身分產生的外部憑證。除了以下差異之外，聯合存取權杖與標準存取權杖相似：

• 聯合存取權存證無法用於所有 Google Cloud 服務。如需聯合式存取權權杖的限制清單，請參閱「身分識別聯合：產品和限制」。
• 聯合存取權權杖會宣告外部聯合身分。

如果您需要使用不支援聯合存取權杖的 API，可以使用聯合存取權杖模擬服務帳戶，並產生標準存取權杖。詳情請參閱「建立短期存取權權杖」一文。

如要進一步瞭解 Google Kubernetes Engine 應用程式如何向 Google API 進行驗證，請參閱「關於 GKE 適用的工作負載身分聯盟」。

ID 權杖

ID 權杖是符合 OpenID Connect (OIDC) 規格的 JSON Web Token (JWT)。這些資訊由一組稱為「宣告」的鍵/值組合組成。

與存取權存證金鑰不同，ID 權杖是應用程式可檢查及使用的透明物件。應用程式可使用憑證中的資訊，例如誰簽署了憑證，或是為誰核發 ID 權杖。

ID 權杖內容

您可以使用 tokeninfo 端點檢查有效的 ID 權杖 (未過期或撤銷)。

將 ID_TOKEN 替換為有效且未過期的 ID 權杖。

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

這個指令會傳回類似以下內容的輸出內容：

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

下表說明必要或常用的 ID 權杖宣告：

視發出者和應用程式而定，可能會出現其他權利聲明。

ID 權杖 aud 權杖

aud 驗證聲明會說明此憑證用於叫用的服務名稱。如果服務收到 ID 權杖，就必須驗證其完整性 (簽名)、有效性 (是否已過期)，以及 aud 驗證資料是否與預期名稱相符。如果不相符，服務應拒絕符記，因為這可能是另一個系統的回放。

一般來說，取得 ID 權杖時，您會使用服務帳戶提供的憑證，而非使用者憑證。這是因為使用者憑證產生的 ID 權杖 aud 宣告，會靜態繫結至使用者用於驗證的應用程式。使用服務帳戶取得 ID 權杖時，您可以為 aud 權杖指定不同的值。

ID 權杖的效期

ID 權杖的有效期間最長為 1 小時 (3,600 秒)。ID 權杖到期後，您必須取得新的 ID 權杖。

ID 權杖驗證

如果您的服務或應用程式使用 Google 服務 (例如 Cloud Run、Cloud Run 函式或身分識別 Proxy)，Google 會為您驗證 ID 權杖；在這種情況下，ID 權杖必須由 Google 簽署。

如果您需要在應用程式中驗證 ID 權杖，可以這麼做，但這是進階工作流程。詳情請參閱「驗證 ID 權杖」。

自行簽署的 JSON Web Token (JWT)

如果您要建立自有的用戶端程式庫來存取 Google API，建議您建立自行簽署的 JWT，但這是進階工作流程。如要進一步瞭解自行簽署的 JWT，請參閱「建立自行簽署的 JSON Web Token」。如要瞭解使用 JWT 的最佳做法，請參閱「JSON Web Token 現行最佳做法」。

重新整理權杖

您的 IdP 會管理長期權杖的有效期限。例外狀況是本機 ADC 檔案，其中包含更新權杖，可供驗證程式庫用於自動為用戶端程式庫更新存取權杖。

不記名憑證

不記名憑證是一種一般類別的權杖，可授予持有權杖的一方存取權。存取權杖、ID 權杖和自行簽署的 JWT 都是權杖。

使用權杖進行驗證時，需要仰賴加密通訊協定 (例如 HTTPS) 提供的安全性；如果權杖遭到攔截，惡意人士就能利用它取得存取權。

後續步驟

• 瞭解如何為 ADC 設定憑證。
• 請參閱取得 ID 權杖的相關資訊。
• 進一步瞭解驗證方法。