權杖類型

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

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

權杖是什麼

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

權杖類型

不同環境會使用不同類型的權杖。本頁面說明下列權杖類型：

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

本頁面不會討論 API 金鑰或用戶端 ID， 這些都屬於憑證。

存取權杖

存取權杖是不透明的權杖，符合 OAuth 2.0 架構。這類權杖包含用於建立權杖的主體類型資訊，以及授權資訊。這些權杖可用於向 Google API 驗證身分及提供授權資訊。存取權杖不含主體的身分。

如果您使用應用程式預設憑證 (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": "[e-mail]",
  "email_verified": "true"
}

下表列出最重要的欄位，方便您瞭解：

欄位	說明
azp	要求權杖的應用程式專案、電子郵件或服務帳戶 ID。只有在範圍清單中指定 https://www.googleapis.com/auth/userinfo.email 時，才會包含這個值。
scope	已新增至這個存取權杖的 OAuth 範圍。對於 Google Cloud 服務，建議使用 https://www.googleapis.com/auth/cloud-platform 範圍 (包含所有 Google Cloud API)，以及 Identity and Access Management (IAM)， 可提供精細的存取權控管。
expires_in	權杖失效前的秒數。詳情請參閱「存取權杖生命週期」。

存取權杖效期

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

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

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

聯盟存取權杖

聯合存取權杖是安全權杖服務 API 傳回的存取權杖，用來交換由工作負載身分聯盟和員工身分聯盟從聯合身分產生的外部憑證。除了下列差異外，同盟存取權杖與標準存取權杖類似：

• 請注意，並非所有 Google Cloud 服務都支援使用同盟存取權杖。如需有關聯邦存取權權杖的限制清單，請參閱「身分同盟：產品和限制」。
• 聯合存取權杖會聲明外部聯合身分。

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

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

ID 權杖

ID 權杖是符合 OpenID Connect (OIDC) 規格的 JSON Web Token (JWT)。這類權杖是由一組稱為「聲明」的鍵/值組合所組成。

與應用程式無法檢查的不透明物件存取權杖不同，應用程式可檢查及使用 ID 權杖。應用程式可使用權杖中的資訊，例如權杖簽署者或核發 ID 權杖的對象。

如要進一步瞭解 Google 在 Google Cloud中使用的 OIDC 實作方式，請參閱 Google Identity 說明文件中的「OpenID Connect」。如需使用 JWT 的最佳做法，請參閱 JSON Web Token 現行最佳做法。

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": "[e-mail]",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

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

領取	說明
iss	權杖的簽發者或簽署者。如果是 Google 簽署的 ID 權杖，這個值為 https://accounts.google.com。
azp	(選用步驟) 權杖核發對象。
aud	權杖的目標對象。這項聲明的價值必須與使用權杖驗證要求的應用程式或服務相符。詳情請參閱「ID 權杖 aud 聲明」。
sub	主體：代表提出要求主體的 ID。
iat	權杖核發時的 Unix Epoch 時間。
exp	權杖到期的 Unix Epoch 時間。

視發行者和應用程式而定，可能會有其他聲明。

ID 權杖 aud 聲明

aud 聲明會說明這個權杖是為呼叫哪個服務而建立。 如果服務收到 ID 權杖，就必須驗證權杖的完整性 (簽章)、有效性 (是否已過期)，以及 aud 聲明是否與預期名稱相符。如果不相符，服務應拒絕符記，因為這可能是要用於其他系統的重播。

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

ID 權杖效期

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

驗證 ID 權杖

當服務或應用程式使用 Cloud Run、Cloud Run 函式或 Identity-Aware Proxy 等 Google 服務時，Google 會為您驗證 ID 權杖；在這些情況下，ID 權杖必須由 Google 簽署。

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

自行簽署的 JSON Web Token (JWT)

您可以使用自行簽署的 JWT 向部分 Google API 進行驗證，不必從授權伺服器取得存取權杖。

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

更新權杖

根據預設，存取權杖和 ID 權杖的有效期限為 1 小時。更新權杖是一種特殊權杖，用於取得額外的存取權杖或 ID 權杖。應用程式首次進行驗證時，會收到存取權杖或 ID 權杖，以及更新權杖。之後，如果應用程式需要再次存取資源，且先前提供的權杖已過期，應用程式就會使用重新整理權杖要求新權杖。重新整理權杖僅用於使用者驗證，例如 Cloud Identity 或 Google Workspace。

如果您的使用者帳戶是由外部識別資訊提供者 (IdP) 管理，則該 IdP 會管理長期權杖的生命週期。例外狀況是本機 ADC 檔案，其中包含驗證程式庫使用的更新權杖，可自動更新用戶端程式庫的存取權杖。

重新整理權杖沒有設定生命週期，可能會過期，但除此之外，權杖會持續可用。

如果是 Google Workspace 或 Cloud Identity 進階版的使用者存取權，您可以設定工作階段長度，確保使用者必須定期登入，才能繼續存取 Google Cloud 服務。 如果應用程式會自行建立及管理權杖，也需要管理重新整理權杖。

詳情請參閱 Google Identity 說明文件中的下列頁面：

• 伺服器對伺服器應用程式的 OAuth 2.0
• 網路伺服器應用程式的 OAuth 2.0。
• 用戶端網頁應用程式的 OAuth 2.0
• 行動與電腦版應用程式的 OAuth 2.0
• 電視和有限輸入裝置應用程式的 OAuth 2.0

不記名憑證

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

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

如果不記名權杖無法為您的用途提供足夠的安全性，請考慮新增另一層加密，或使用相互傳輸層安全 (mTLS) 解決方案，例如 Chrome Enterprise Premium，這項服務會限制只有通過驗證的使用者才能在信任的裝置上存取。

後續步驟

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