本頁面說明 Google 如何實作 OpenID Connect 提供者，並提供 Google OIDC 端點的技術參考資料。OpenID Connect (OIDC) Core 1.0 規格定義了驗證使用者及取得身分資訊的通訊協定。
本參考資料並非提供 OIDC 實作方式的逐步說明，如需實作詳細資料，請參閱 OpenID Connect 指南。
探索文件
探索文件包含 Google OpenID Connect 設定的中繼資料，如 OpenID Connect Discovery 1.0 規格所定義。
網址： https://accounts.google.com/.well-known/openid-configuration
支援的要求方法： GET
回應主體
HTTP 回應主體中的 JSON 物件會傳回回應欄位，供要求者向 https://accounts.google.com/.well-known/openid-configuration 提出 GET 要求。
| 欄位 | 類型 | 說明 |
|---|---|---|
issuer |
string |
發卡機構識別碼。使用 https 配置的網址 (區分大小寫)。新版的值為 https://accounts.google.com，但舊版實作項目也會傳回 accounts.google.com。 |
authorization_endpoint |
string |
授權端點的網址。 |
device_authorization_endpoint |
string |
裝置授權端點的網址。 |
token_endpoint |
string |
權杖端點的網址。 |
userinfo_endpoint |
string |
UserInfo 端點的網址。 |
revocation_endpoint |
string |
撤銷端點的網址。 |
jwks_uri |
string |
JSON Web Key Set (JWKS) 文件的網址。 |
response_types_supported |
array |
支援的 response_type 值清單。 |
response_modes_supported |
array |
支援的 response_mode 值清單。 |
authorization_response_iss_parameter_supported |
boolean |
布林值，指出是否支援 RFC 9207。 |
subject_types_supported |
array |
支援的主體 ID 類型清單。 |
id_token_signing_alg_values_supported |
array |
用於簽署 ID 權杖的支援演算法清單。 |
scopes_supported |
array |
支援的範圍值清單。 |
claims_supported |
array |
支援的聲明清單。 |
token_endpoint_auth_methods_supported |
array |
權杖端點支援的驗證方法清單。 |
code_challenge_methods_supported |
array |
PKCE 支援的程式碼驗證方法清單。 |
grant_types_supported |
array |
支援的 OAuth 2.0 授權類型清單。 |
ID 權杖 (聲明)
回應中傳回的 id_token 值是已簽署的 JSON Web Token (JWT)，必須使用從導覽文件中 jwks_uri 取得的鍵控素材驗證。下表說明解碼後的 ID 權杖酬載內容。
| 權杖附加資訊 | 類型 | 說明 |
|---|---|---|
iss |
string |
必要。回覆核發者的核發者 ID。通常為 https://accounts.google.com，但舊版實作也會傳回 accounts.google.com。 |
sub |
string |
必要。使用者的專屬 ID，必須別於任何其他 Google 帳戶，且不得重複使用。Google 帳戶可在不同時間點使用多個電子郵件地址，但 sub 值一律維持不變。在應用程式中，請使用 sub 做為使用者的唯一識別碼。長度上限為 255 個區分大小寫的 ASCII 字元。 |
azp |
string |
授權簡報者的用戶端 ID，可從 Google Cloud 控制台取得。只有當 ID 權杖的要求者與 ID 權杖的目標對象不同時，才需要使用這項權杖附加資訊。 |
aud |
string |
必要。ID 權杖的目標對象。這是應用程式的用戶端 ID，可從 Google Cloud 控制台取得。 |
iat |
integer |
必要。ID 權杖的核發時間。以 Unix Epoch 紀元時間 (整數秒數) 表示。 |
exp |
integer |
必要。ID 權杖不得接受的到期時間。以 Unix Epoch 紀元時間 (整數秒數) 表示。 |
nonce |
string |
您的應用程式在驗證要求中提供的 nonce 值。您必須確保該 Nonce 值只會出現一次，以防範重送攻擊。 |
auth_time |
integer |
使用者驗證時間，以 JSON 數字表示，代表自 Unix 紀元 (1970 年 1 月 1 日 00:00:00 UTC) 經過的秒數。如果驗證要求 claims 參數中包含 auth_time 聲明，系統就會提供這個值。 |
at_hash |
string |
存取權杖雜湊值。驗證存取權杖是否與 ID 權杖相關聯。如果 ID 權杖是在伺服器流程中發放，且含有 access_token 值，系統一律會納入這項聲明。 |
email |
string |
使用者的電子郵件地址。只有在要求中加入 email 範圍時，才會提供這項資訊。這項聲明的價值可能不是這個帳戶獨有，而且可能會隨時間變更，因此不應將這個值做為連結至使用者記錄的主要 ID。您也無法依據 email 聲明中的網域，識別 Google Workspace 或 Cloud 機構的使用者，請改用 hd 聲明。警告：請勿使用電子郵件地址做為 ID，因為 Google 帳戶在不同時間點可能有多個電子郵件地址。請一律使用 sub 欄位做為使用者的 ID。 |
email_verified |
boolean |
如果使用者的電子郵件地址已完成驗證，則為 true；否則傳回 false。 |
name |
string |
以可顯示格式呈現的使用者全名。如果要求範圍包含 profile 字串，或 ID 權杖是從權杖更新作業傳回，則可能會提供這項資訊。 |
picture |
string |
使用者個人資料相片的網址。如果要求範圍包含 profile 字串，或 ID 權杖是從權杖更新作業傳回，則可能會提供這個值。 |
given_name |
string |
使用者的名字。如果存在 name 聲明，可能會提供此屬性。 |
family_name |
string |
使用者的姓氏。如果存在 name 聲明，可能會提供此屬性。 |
hd |
string |
與使用者 Google Workspace 或 Cloud 機構相關聯的網域。只有在使用者屬於 Google Cloud 機構時才提供。如要限制只有特定網域的成員可以存取資源，就必須檢查這項聲明。如果沒有這項聲明，表示帳戶不屬於 Google 代管網域。 |
授權端點
授權端點用於驗證使用者身分，並取得授權碼或權杖。
網址： https://accounts.google.com/o/oauth2/v2/auth
支援的要求方法： GET、POST
要求參數
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
client_id |
string |
必填 | 從 Google Cloud 控制台取得的用戶端 ID 字串。 |
nonce |
string |
選用 | 應用程式產生的隨機值，可啟用重送保護機制。只有在要求 ID 權杖時才需要 (當 response_type 包含 id_token 時)。 |
response_type |
string |
必填 | 決定要使用的流程。如果值為 code，系統會啟動授權碼流程，並要求向權杖端點發出 POST，以取得權杖。如果值為 token、id_token、token id_token 或 id_token token，系統會啟動隱含流程，因此必須在重新導向 URI 使用 JavaScript，從 URI 片段擷取權杖。強烈建議不要在任何表單中使用 token，因為這會將存取權杖曝露在網址中；OAuth 2.1 禁止使用這個值。 |
response_mode |
string |
選用 | 指定授權回應的傳送方式。如果 response_type 為 code，則預設值為 query。如果是其他回應類型，預設值為 fragment。支援的值：query、fragment、form_post。 |
redirect_uri |
string |
必填 | 決定回應的傳送位置。這個參數的值必須與您在 Google Cloud 控制台中設定的其中一個授權重新導向值完全相符 (包括 HTTP 或 HTTPS 通訊協定、大小寫和尾端「/」，如有)。重新導向 URI 和授權 JavaScript 來源必須遵守「OAuth 2.0 URI 驗證」文件中列出的驗證規則。 |
scope |
string |
必填 | 以空格分隔的範圍未排序清單。清單必須包含 openid 值，然後包含 profile 值、email 值或兩者。您也可以加入非 OIDC 範圍。如果存在 profile 範圍值，ID 權杖可能會 (但不保證) 包含使用者的預設 profile 權杖附加資訊。如果存在 email 範圍值，ID 權杖會包含 email 和 email_verified 聲明。詳情請參閱「OAuth 2.0 範圍」。 |
state |
string |
建議 | 在通訊協定中來回傳輸的不透明字串；也就是說，在授權碼流程中，系統會將其做為 URI 參數傳回，在隱含流程中，則會做為 URI 片段傳回。state 可用於關聯要求和回應。由於 redirect_uri 可能遭到猜測，使用 state 值可提高保證，確保連入連線是應用程式啟動的驗證要求所致。這可防範跨網站偽造要求等攻擊。 |
access_type |
string |
選用 | 允許的值為 offline 和 online。如果應用程式需要在使用者不在瀏覽器時重新整理存取權杖，請使用 offline。這是取得重新整理權杖的必要值。 |
hd |
string |
選用 | 簡化 Google Cloud 機構所擁有帳戶的登入程序。加入 Google Cloud 機構網域 (例如 mycollege.edu) 後，您就能指出帳戶選取 UI 應針對該網域的帳戶進行最佳化。如要針對一般 Google Cloud 組織帳戶 (而非單一 Google Cloud 組織網域) 進行最佳化，請將值設為星號 (*)：hd=*。 |
login_hint |
string |
選用 | 如果應用程式知道要驗證的使用者是誰，就可以提供這個參數做為驗證伺服器的提示。傳遞這項提示會停用帳戶選擇工具，並預先填寫登入表單上的電子郵件方塊，或選取適當的工作階段，有助於避免應用程式登入錯誤使用者帳戶時發生的問題。這個值可以是電子郵件地址或 sub 字串，後者等同於使用者的 Google ID。 |
prompt |
string |
選用 | 以空格分隔的字串值清單，用於指定授權伺服器是否提示使用者重新驗證及同意。可能的值包括：none (無 UI)、consent (提示使用者同意) 和 select_account (提示使用者選取帳戶)。 |
hl |
string |
選用 | 用來指定登入、帳戶選擇器和同意畫面顯示語言的 BCP 47 語言標記。不建議使用這個參數，因為瀏覽器設定和 Google 帳戶偏好設定通常更能反映使用者的語言偏好設定。 |
include_granted_scopes |
boolean |
選用 | 如果這個參數的值為 true，且授權要求已獲准，授權會包含先前授予這個使用者/應用程式組合的其他範圍授權；請參閱增量授權。 |
claims |
object |
選用 | claims 參數可用來指定要在 UserInfo 回應或 ID 權杖中加入的一或多個選用欄位。如要要求 auth_time 聲明，請使用 claims={\"id_token\":{\"auth_time\":{\"essential\":true}}}。 |
回應參數
授權回應會使用 HTTP GET 重新導向，傳送至用戶端的重新導向 URI (redirect_uri)。視 response_type 和 response_mode 而定，回應參數會附加至查詢字串或網址片段中的重新導向 URI。
| 參數 | 類型 | 說明 |
|---|---|---|
iss |
string |
發卡機構 ID。根據 RFC 9207，系統一律會傳回這個參數，並設為 https://accounts.google.com。 |
code |
string |
授權碼，可交換存取權杖和 ID 權杖。 |
state |
string |
與要求中的 state 參數值相同。 |
id_token |
string |
內含使用者身分資訊的 JSON Web Token (JWT)。 |
access_token |
string |
可傳送至 Google API 的存取權杖。 |
token_type |
string |
傳回的權杖類型。一律 Bearer。 |
expires_in |
integer |
存取權杖的生命週期 (以秒為單位)，相對於權杖核發時間。 |
scope |
string |
code 或 access_token 授予的存取權範圍，以空格分隔的字串清單表示，且區分大小寫。 |
error |
string |
如果要求失敗，則為錯誤代碼。 |
error_description |
string |
如果要求失敗，則會顯示錯誤說明。 |
錯誤回應
授權端點會將錯誤以查詢字串或網址片段中的參數形式，傳回給用戶端的 redirect_uri，或以 Google 代管的錯誤網頁形式向使用者顯示。
重新導向錯誤
系統可能會將下列錯誤代碼傳回至 redirect_uri：
| 錯誤 | 說明 |
|---|---|
access_denied |
使用者或授權伺服器拒絕要求。 |
invalid_request |
要求缺少必要參數、內含無效的參數值、內含重複的參數，或格式有誤。 |
unauthorized_client |
用戶端無權使用此方法要求授權碼。 |
unsupported_response_type |
授權伺服器不支援使用這個方法取得授權碼。 |
invalid_scope |
要求的範圍無效、不明或格式錯誤。 |
面向使用者的錯誤
在某些情況下 (例如 client_id 或 redirect_uri 無效)，授權伺服器無法安全地將使用者重新導向至您的應用程式。在這些情況下，系統會直接向使用者顯示錯誤頁面。
| 錯誤 | 說明 |
|---|---|
admin_policy_enforced |
由於 Google Workspace 管理員的政策，Google 帳戶無法授權一或多個要求範圍。如要進一步瞭解管理員如何限制存取權，直到明確授予 OAuth 用戶端 ID 存取權為止，請參閱 Google Workspace 管理員說明文章。 |
disallowed_useragent |
授權端點顯示在 Google 的 OAuth 2.0 政策禁止使用的內嵌使用者代理程式中。 |
org_internal |
要求中的 OAuth 用戶端 ID 屬於專案，該專案限制只能存取特定 Google Cloud 機構中的 Google 帳戶。 |
deleted_client |
用來提出要求的 OAuth 用戶端已遭刪除。如果用戶端未使用，系統可能會手動或自動刪除。 |
invalid_grant |
使用 PKCE 時，code_challenge 參數無效或遺失。重新整理存取權權杖或使用增量授權時，權杖可能已過期或失效，也可能是使用者帳戶已遭刪除或停用。 |
redirect_uri_mismatch |
要求中傳遞的 redirect_uri 與用戶端 ID 的授權重新導向 URI 不符。在 Google Cloud 控制台中查看已授權的重新導向 URI。如果要求使用已淘汰的 OAuth 頻外 (OOB) 流程，也可能發生這個錯誤。 |
invalid_client |
提出要求的來源未獲授權使用這個用戶端、用戶端設定有誤，或 OAuth 用戶端密鑰不正確。 |
origin_mismatch |
發出授權要求的 JavaScript 的結構定義、網域和/或通訊埠，與為 OAuth 用戶端 ID 註冊的授權 JavaScript 來源 URI 不符。在 Google Cloud 控制台中查看已授權的 JavaScript 來源。 |
invalid_request |
要求有誤，這可能是因為要求格式有誤、缺少必要參數，或是使用 Google 不支援的授權方法。 |
權杖端點
權杖端點用於交換授權碼，以取得存取權杖和 ID 權杖。
網址： https://oauth2.googleapis.com/token
支援的要求方法： POST
要求參數 (授權碼授予)
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
code |
string |
必填 | 從授權端點收到的授權碼。 |
client_id |
string |
必填 | 應用程式的用戶端 ID，可從 Google Cloud 控制台取得。 |
client_secret |
string |
必填 | 應用程式的用戶端密鑰，可從 Google Cloud 控制台取得。 |
redirect_uri |
string |
必填 | 初始授權要求中使用的重新導向 URI。重新導向 URI 和授權 JavaScript 來源必須遵守「OAuth 2.0 URI 驗證」文件中列出的驗證規則。 |
grant_type |
string |
必填 | 必須設為「authorization_code」。 |
要求參數 (裝置流程)
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
client_id |
string |
必填 | 應用程式的用戶端 ID，可從 Google Cloud 控制台取得。 |
client_secret |
string |
必填 | 應用程式的用戶端密鑰，可從 Google Cloud 控制台取得。 |
device_code |
string |
必填 | 裝置授權端點傳回的 device_code。 |
grant_type |
string |
必填 | 必須設為「urn:ietf:params:oauth:grant-type:device_code」。 |
要求參數 (重新整理存取權杖)
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
client_id |
string |
必填 | 應用程式的用戶端 ID，可從 Google Cloud 控制台取得。 |
client_secret |
string |
必填 | 應用程式的用戶端密鑰，可從 Google Cloud 控制台取得。 |
grant_type |
string |
必填 | 必須設為 refresh_token，如 OpenID Connect 重新整理權杖規格中所定義。 |
refresh_token |
string |
必填 | 授權碼交換作業傳回的重新整理權杖。 |
scope |
string |
選用 | 以空格分隔的新存取權杖要求範圍清單。要求的範圍必須是原始授權要求中授予範圍的子集。 |
回應主體
HTTP 回應主體中的 JSON 物件會傳回回應欄位，供要求者向 https://oauth2.googleapis.com/token 提出 POST 要求。
| 欄位 | 類型 | 說明 |
|---|---|---|
access_token |
string |
可傳送至 Google API 的存取權杖。 |
expires_in |
integer |
存取權杖的生命週期 (以秒為單位)，相對於權杖核發時間。 |
id_token |
string |
內含使用者身分資訊的 JSON Web Token (JWT)。這個權杖會在初始授權碼交換期間傳回，如果已授予 openid 範圍，也會在重新整理權杖要求期間傳回。 |
scope |
string |
access_token授予的存取範圍，以不區分大小寫的字串清單表示，並以空格分隔。 |
token_type |
string |
傳回的權杖類型。一律 Bearer。 |
refresh_token |
string |
(選用) 可用於取得新存取權杖的權杖。如果要求了 access_type=offline，這個欄位只會在授權碼的初始交換中傳回。 |
refresh_token_expires_in |
integer |
(選用) 重新整理權杖的剩餘生命週期 (以秒為單位)。只有在使用者授予時間限制存取權時，系統才會設定這個值。 |
錯誤回應
如果要求失敗，授權伺服器會傳回具有下列欄位的 JSON 物件：
| 欄位 | 類型 | 說明 |
|---|---|---|
error |
string |
錯誤代碼。 |
error_description |
string |
如果要求失敗，則會顯示錯誤說明。 |
下表說明可能的錯誤代碼和相關聯的 HTTP 狀態碼：
| 錯誤 | HTTP 狀態碼 | 說明 |
|---|---|---|
invalid_request |
400 |
要求缺少必要參數、包含無效參數值，或格式有誤。 |
invalid_client |
401 |
用戶端驗證失敗。例如 client_id 或 client_secret 無效，或是用戶端類型不正確。 |
invalid_grant |
400 |
提供的授權碼、重新整理權杖或裝置代碼無效、已過期、已遭撤銷，或與授權要求中使用的重新導向 URI 不符。 |
unauthorized_client |
400 |
經驗證的用戶端無權使用這項授權 Grant Type。 |
unsupported_grant_type |
400 |
授權伺服器不支援授權 Grant Type。 |
invalid_scope |
400 |
要求的範圍無效、不明或格式錯誤。 |
authorization_pending |
428 |
(裝置流程) 使用者尚未完成授權流程。 |
slow_down |
429 |
(裝置流程) 裝置傳送輪詢要求的頻率過高。 |
access_denied |
403 |
(裝置流程) 使用者拒絕授予裝置存取權。 |
expired_token |
400 |
(裝置流程) device_code已過期。 |
admin_policy_enforced |
400 |
由於 Google Workspace 管理員強制執行的政策，使用者無法授權所要求的範圍。 |
org_internal |
403 |
用戶端 ID 屬於專案的一部分，可限制特定 Google Cloud 機構的存取權。 |
裝置授權端點
OAuth 2.0 裝置流程會使用裝置授權端點，為輸入功能有限的裝置取得使用者代碼和驗證網址。
網址： https://oauth2.googleapis.com/device/code
支援的要求方法： POST
要求參數
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
client_id |
string |
必填 | 應用程式的用戶端 ID，可從 Google Cloud 控制台取得。 |
scope |
string |
必填 | 以空格分隔的範圍清單，可識別應用程式可代表使用者存取的資源。 |
回應主體
回覆為 JSON 物件，內含下列欄位：
| 欄位 | 類型 | 說明 |
|---|---|---|
device_code |
string |
Google 專屬指派的值，用於識別執行應用程式的裝置，並要求授權。 |
user_code |
string |
這個值會區分大小寫，可向 Google 說明應用程式要求存取的範圍。使用者介面會指示使用者在輸入功能較豐富的裝置上輸入這個值。 |
verification_url |
string |
使用者必須在其他裝置上前往這個網址，輸入 user_code 並授予或拒絕應用程式存取權。 |
expires_in |
integer |
device_code 和 user_code 的有效時間長度 (以秒為單位)。 |
interval |
integer |
裝置在輪詢要求之間應等待的時間長度 (以秒為單位)。 |
撤銷端點
應用程式可透過撤銷端點撤銷存取權杖或更新權杖。
網址： https://oauth2.googleapis.com/revoke
支援的要求方法： POST
要求參數
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
token |
string |
必填 | 要撤銷的存取權杖或更新權杖。 |
回應主體
如果撤銷成功，回應會是空白的 HTTP 200 OK。如果撤銷失敗，系統會以 JSON 物件傳回錯誤回應。
| 欄位 | 類型 | 說明 |
|---|---|---|
error |
string |
如果要求失敗，則為錯誤代碼。 |
error_description |
string |
如果要求失敗，則會顯示錯誤說明。 |
下表說明可能的錯誤代碼：
| 錯誤 | 說明 |
|---|---|
invalid_token |
要求中提供的權杖已過期或遭到撤銷。 |
invalid_request |
要求缺少必要參數、包含無效參數值，或格式有誤。 |
UserInfo 端點
UserInfo 端點會傳回已驗證使用者的個人資料資訊。
網址： https://openidconnect.googleapis.com/v1/userinfo
支援的要求方法： GET、POST
要求標頭
| 標頭 | 說明 |
|---|---|
Authorization |
必要。必須設為「Bearer: access_token」。 |
回應主體
HTTP 回應主體中的 JSON 物件會傳回回應欄位，以回應要求者對 https://openidconnect.googleapis.com/v1/userinfo 提出的 GET 或 POST 要求。
| 欄位 | 類型 | 說明 |
|---|---|---|
sub |
string |
必要。使用者的專屬 ID，必須別於任何其他 Google 帳戶，且不得重複使用。區分大小寫的字串，不得超過 255 個字元。 |
name |
string |
以可顯示格式呈現的使用者全名。 |
given_name |
string |
使用者的名字。 |
family_name |
string |
使用者的姓氏。 |
picture |
string |
使用者個人資料相片的網址。 |
email |
string |
使用者的電子郵件地址。 |
email_verified |
boolean |
使用者的電子郵件地址是否已通過驗證。 |
hd |
string |
與使用者 Google Workspace 或 Cloud 機構相關聯的代管網域。 |
Tokeninfo 端點
tokeninfo 端點是 Google 專用的實作方式，用於偵錯驗證 ID 權杖。
網址： https://oauth2.googleapis.com/tokeninfo
支援的要求方法： GET、POST
要求參數
| 參數 | 類型 | 必要 | 說明 |
|---|---|---|---|
id_token |
string |
必填 | 要驗證的 ID 權杖。 |
回應主體
HTTP 回應主體中的 JSON 物件會傳回回應欄位，以回應要求者對 https://oauth2.googleapis.com/tokeninfo 提出的 GET 或 POST 要求。
| 欄位 | 類型 | 說明 |
|---|---|---|
iss |
string |
發卡機構 ID。一律 https://accounts.google.com。 |
sub |
string |
使用者的專屬 ID，必須別於任何其他 Google 帳戶，且不得重複使用。 |
aud |
string |
ID 權杖的目標對象。這是應用程式的用戶端 ID，可從 Google Cloud 控制台取得。 |
iat |
integer |
JWT 的簽發時間。以從 1970-01-01T0:0:0Z 算起的秒數表示 (以世界標準時間測量)。 |
exp |
integer |
ID 權杖的到期時間，在此時間之後不得接受該權杖進行處理。以從 1970-01-01T0:0:0Z 算起的秒數表示，測量單位為世界標準時間。 |
email |
string |
使用者的電子郵件地址。 |
email_verified |
string |
使用者的電子郵件地址是否已通過驗證。值為字串 "true" 或 "false"。 |
access_type |
string |
原始授權要求中要求的存取權類型。 |
azp |
string |
授權表示器的用戶端 ID，可從 Google Cloud 控制台取得。 |
scope |
string |
以空格分隔的權杖授權範圍清單。 |
alg |
string |
用於簽署 ID 權杖的演算法。 |
kid |
string |
用於簽署 ID 權杖的金鑰 ID。 |
typ |
string |
權杖類型。一律 JWT。 |