OpenID Connect

Google 的 OAuth 2.0 API 可用於驗證作業和授權作業。本文件說明用於驗證的 OAuth 2.0 實作，並遵循 OpenID Connect 規格，並已獲得 OpenID 認證。此外，「使用 OAuth 2.0 存取 Google API」一文中列出的說明文件也適用於這項服務。如果您想以互動方式探索這個通訊協定，建議您使用 Google OAuth 2.0 Playground。 如需 Stack Overflow 說明，請使用「##39;google-oauth'」標記您的問題。

設定 OAuth 2.0

您必須先在 Google API Console 中設定專案，才能取得 OAuth 2.0 憑證、設定重新導向 URI，以及 (選擇性) 自訂使用者同意聲明畫面中向使用者顯示的品牌宣傳資訊，您的應用程式才能使用 Google 的 OAuth 2.0 驗證系統。您也可以使用 API Console 建立服務帳戶、啟用計費功能、設定篩選及執行其他工作。詳情請參閱 Google API Console說明。

取得 OAuth 2.0 憑證

您必須取得 OAuth 2.0 憑證 (包括用戶端 ID 和用戶端密鑰) 來驗證使用者，才能存取 Google 的 API。

要查看給定OAuth 2.0憑據的客戶端ID和客戶端密鑰，請單擊以下文本： 選擇憑據 。在打開的窗口中，選擇您的項目和所需的憑證，然後單擊“ 查看” 。

或者，從API Console的“ 憑據”頁面中查看您的客戶端ID和客戶端密鑰：

1. Go to the Credentials page.
2. 單擊您的憑據名稱或鉛筆（ create ）圖標。您的客戶ID和機密位於頁面頂部。

設定重新導向 URI

您在 API Console 中設定的重新導向 URI 會決定 Google 將回應傳送至驗證要求的位置。

要創建，查看或編輯給定OAuth 2.0憑據的重定向URI，請執行以下操作：

1. Go to the Credentials page.
2. 在頁面的OAuth 2.0客戶端ID部分中，點擊一個憑據。
3. 查看或編輯重定向URI。

如果“憑據”頁面上沒有OAuth 2.0客戶端ID部分，則您的項目沒有OAuth憑據。要創建一個，點擊創建憑證 。

自訂使用者同意畫面

對使用者而言，OAuth 2.0 驗證體驗包含同意畫面，說明使用者釋出的資訊和適用的條款。舉例來說，使用者登入時，系統可能會請他們提供應用程式電子郵件地址和基本帳戶資訊的存取權。您可以使用 scope 參數要求這項資訊的存取權，因為應用程式包含在驗證要求中。您也可以使用範圍來要求存取其他 Google API。

使用者同意聲明畫面也會顯示品牌資訊，例如產品名稱、標誌和首頁網址。您可以透過 API Console控管品牌宣傳資訊。

要啟用項目的同意屏幕：

1. 在Consent Screen page中打開Google API Console 。
2. If prompted, select a project, or create a new one.
3. 填寫表格，然後點擊保存 。

下列同意聲明對話方塊會顯示使用者在要求中加入 OAuth 2.0 和 Google 雲端硬碟範圍時看到的內容。(這個一般對話方塊使用 Google OAuth 2.0 Playground 產生，因此不會包含 API Console中設定的品牌宣傳資訊)。

存取服務

Google 和第三方可以提供程式庫，讓您用來處理眾多驗證使用者的詳細資料，並取得 Google API 的存取權。例如 Google Identity 服務和 Google 用戶端程式庫 (適用於各種平台)。

如果您選擇不使用程式庫，請按照本文其餘章節中的指示操作，其中說明可用程式庫的基礎 HTTP 要求流程。

驗證使用者

驗證使用者涉及取得及驗證 ID 權杖。ID 權杖是 OpenID Connect 的標準功能，用於在網際網路上分享身分斷言。

「驗證伺服器」和「取得 ID」權杖時，最常用的方法稱為「伺服器」流程和「隱含」流程。伺服器流程可讓應用程式的後端伺服器透過瀏覽器或行動裝置驗證使用者身分。當用戶端應用程式 (通常在瀏覽器中執行 JavaScript) 必須直接存取 API (而非透過後端伺服器)，系統就會使用隱含流程。

本文說明如何執行伺服器流程來驗證使用者。由於用戶端在處理及使用權杖時的安全性風險，隱含流程會更為複雜。如果您需要實作隱含流程，強烈建議您使用 Google Identity 服務。

伺服器流程

請務必在 API Console中設定應用程式，讓應用程式使用這些通訊協定並驗證使用者。當使用者嘗試透過 Google 登入時，您必須：

1. 建立防偽造狀態權杖
2. 傳送驗證要求給 Google
3. 確認防偽造狀態權杖
4. 交換存取權杖和 ID 權杖的 code
5. 從 ID 權杖取得使用者資訊
6. 驗證使用者

1. 建立防偽造狀態權杖

藉由防止要求偽造攻擊，請務必保護使用者的安全。第一步是建立不重複的工作階段符記，用來保存應用程式和使用者用戶端之間的狀態。您稍後會將這個不重複工作階段符記與 Google OAuth 登入服務傳回的驗證回應進行比對，以驗證使用者提出要求，而非惡意攻擊。這些權杖通常稱為跨網站要求偽造 (CSRF) 權杖。

狀態權杖的一個很好的選擇，是利用 30 個以上的字串，使用高品質隨機號碼產生器來建構。另一個雜湊值則是使用部分密鑰狀態在後端進行簽署的產生的雜湊。

以下程式碼示範如何產生專屬工作階段符記。

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. 傳送驗證要求給 Google

下一步是使用適當的 URI 參數來建構 HTTPS GET 要求。請注意，在此程序中的所有步驟中，使用 HTTPS 而非 HTTP；HTTP 連線會遭到拒絕。您應使用 authorization_endpoint 中繼資料值從探索文件擷取基礎 URI。下列討論假設基礎 URI 為 https://accounts.google.com/o/oauth2/v2/auth。

如果是基本要求，請指定下列參數：

• client_id，您從 API Console Credentials page中取得的資訊
• response_type；在基本授權碼流程中，此要求應為 code。(詳情請參閱 response_type)。
• scope，基本要求中應為 openid email。(詳情請參閱 scope)。
• redirect_uri 應是伺服器用來接收 Google 回應的 HTTP 端點。這個值必須與您在 API ConsoleCredentials page中設定的 OAuth 2.0 用戶端授權重新導向 URI 完全相同。如果這個值與授權的 URI 不符，要求就會失敗並傳回 redirect_uri_mismatch 錯誤。
• state 應包含防偽不重複工作階段符記的值，以及當使用者返回應用程式時 (例如起始網址) 時所需的任何其他資訊，以復原內容。(詳情請參閱 state)。
• nonce 是應用程式產生的隨機值，會在啟用時保護重播功能。
• login_hint 可以是使用者的電子郵件地址或 sub 字串，等同於使用者的 Google ID。如果您未提供 login_hint 使用者，但使用者目前正登入，同意畫面會提出核准要求，以便向使用者更新使用者的電子郵件地址。(詳情請參閱 login_hint)。
• 使用 hd 參數來最佳化與 Google Cloud 機構相關聯的特定網域使用者的 OpenID Connect 流程。(詳情請參閱 hd)。

以下是完整的 OpenID Connect 驗證 URI 範例，其中含有可讀的斷行字元和空格：

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

如果您的應用程式會要求取得任何新的相關資訊，或是應用程式先前未事先取得帳戶存取權，您就必須提供使用者的同意聲明。

3. 確認防偽造狀態權杖

系統會將回應傳送至您在要求中指定的 redirect_uri。所有回應都會傳回查詢字串，如下所示：

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

您必須確認從 Google 收到的 state 與您在步驟 1 建立的工作階段符記相符。這項往返驗證可確保使用者 (而非惡意指令碼) 提出要求。

以下程式碼示範如何確認您在步驟 1 中建立的工作階段符記：

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. 透過 code 取得存取權杖和 ID 權杖

回應包含 code 參數，這是伺服器用來交換存取權杖和 ID 權杖的一次性授權碼。您的伺服器透過傳送 HTTPS POST 要求進行這項交換。系統會將 POST 要求傳送至權杖端點，您應該使用 token_endpoint 中繼資料值從探索文件中擷取相關資訊。以下討論假設端點為 https://oauth2.googleapis.com/token。要求必須在 POST 主體中加入下列參數：

實際要求可能如下所示：

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

要求成功回應包含 JSON 陣列中的下列欄位：

5. 從 ID 權杖取得使用者資訊

ID 權杖是 JWT (JSON Web Token)，也就是經過加密簽署的 Base64 編碼 JSON 物件。一般來說，請務必先驗證 ID 權杖，然後再使用該金鑰。不過，由於您是透過中介端的 HTTPS 管道直接與 Google 通訊，並使用用戶端密鑰向 Google 進行驗證，因此可以確定您收到的權杖確實來自 Google 且有效。如果您的伺服器會將 ID 權杖傳遞至應用程式的其他元件，則其他元件必須在使用權杖前進行驗證。

大多數 API 程式庫結合了驗證與解碼 Base64url 編碼值和剖析 JSON 作業的工作，因此當您存取 ID 權杖中的憑證要求時，最終可能還是會驗證權杖。

ID 權杖的酬載

ID 權杖是一種 JSON 物件，內含一組名稱/值組合。以下為可讀格式範例：

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Google ID 權杖可能包含下列欄位 (也稱為聲明)：

6. 驗證使用者

從 ID 權杖取得使用者資訊後，您應查詢應用程式的使用者資料庫。如果使用者在您的資料庫中已有使用者，且是由 Google API 回應符合所有登入規定時，您應該為該使用者啟動應用程式工作階段。

如果使用者資料庫中沒有使用者，請將使用者重新導向至新使用者的註冊流程。您可以根據自己從 Google 提供的資訊自動註冊使用者，或是至少在註冊表單中預先填入許多欄位。除了 ID 權杖中的資訊外，您還可以在使用者設定檔端點中找到額外的使用者個人資料資訊。

進階主題

以下各節提供了 Google OAuth 2.0 API 的詳細說明。開發人員請注意，這些資訊均適用於驗證和授權方面的進階要求。

其他 Google API 的存取權

使用 OAuth 2.0 進行驗證的好處之一是，您的應用程式可以在驗證使用者的同時，代表使用者 (例如 YouTube、Google 雲端硬碟、日曆或聯絡人) 使用其他 Google API。如要這麼做，請在傳送給 Google 的驗證要求中納入其他其他範圍。舉例來說，如要將驗證使用者的年齡層加入驗證要求，請傳遞 openid email https://www.googleapis.com/auth/profile.agerange.read 的範圍參數。使用者會在同意畫面中正確提示使用者。透過 Google 傳回的存取權杖，可讓您存取與所要求存取權和存取權範圍相關的所有 API。

重新整理權杖

您可以在要求 API 存取權時，要求在 code 交換期間傳回重新整理權杖。更新權杖則可讓應用程式持續存取 Google API，前提是使用者不在您的應用程式中。如要要求重新整理權杖，請在驗證要求中將 access_type 參數設為 offline。

注意事項：

• 請務必完整且永久地儲存更新權杖，因為第一次執行程式碼交換流程時才能獲得重新整理權杖。
• 核發的重新整理權杖數量設有上限：每個用戶端/使用者組合各一個，以及所有用戶端的每位使用者。如果您的應用程式要求更新重新整理權杖的次數過多，就有可能會達到這些限制，這時舊的更新權杖就會停止運作。

詳情請參閱重新整理存取權杖 (離線存取權)。

提示重新同意聲明

您可以在驗證要求中將 prompt 參數設為 consent，藉此提示使用者重新授權應用程式。如果包含 prompt=consent，每次應用程式要求存取存取權範圍時，系統仍會顯示同意畫面，即使您先前先前已授予 Google API 專案的所有範圍權限亦然。因此，請只在必要時加入 prompt=consent。

如要進一步瞭解 prompt 參數，請參閱「驗證 URI 參數」表格中的 prompt。

驗證 URI 參數

下表詳細說明 Google' OAuth 2.0 驗證 API 接受的參數。

驗證 ID 權杖

除非您知道 Google 的權杖是否直接來自 Google ，否則您必須驗證伺服器中的所有 ID 權杖。舉例來說，您的伺服器必須從用戶端應用程式收到的任何 ID 權杖進行驗證。

以下是您將 ID 權杖傳送至伺服器的常見原因：

• 傳送需要驗證的要求的 ID 權杖。ID 權杖會指出提出要求的使用者和取得該 ID 權杖的用戶端。

ID 權杖屬於機密資訊，可能會在攔截時遭到濫用。請務必透過 HTTPS 和要求標頭或透過 POST 資料，只將權杖透過 HTTPS 傳輸，以安全的方式處理。如果您將 ID 憑證儲存在伺服器上，您也必須妥善儲存權杖。

ID 權杖的其中一項優點是，您可以在應用程式的不同元件之間傳送 ID。這些元件可以使用 ID 權杖做為驗證應用程式和使用者的輕量驗證機制。但是，您「必須」使用 ID 權杖中的資訊，或將其視為使用者已通過驗證的宣告。

ID 權杖驗證需要幾個步驟：

1. 確認核發機構已正確簽署身分證件。系統會使用探索文件 jwks_uri 中繼資料值中指定的 URI 找到其中一個憑證，以簽署 Google 核發的權杖。
2. 確認 ID 權杖中的 iss 聲明值等於 https://accounts.google.com 或 accounts.google.com。
3. 確認 ID 權杖中的 aud 憑證值是否與應用程式的用戶端 ID 相同。
4. 確認身分證件的到期時間 (exp 聲明) 未過期。
5. 如果您在要求中指定了 hd 參數值，請確認 ID 權杖的 hd 聲明與與 Google Cloud 機構相關聯的接受網域相符。

步驟 2 到步驟 5 只比較字串與日期的比較結果，因此不會在這裡加以詳細說明。

第一個步驟較為複雜，涉及加密編譯簽名檢查。如要偵錯，您可以使用 Google 的 tokeninfo 端點，與伺服器或裝置實作的本機處理作業進行比較。假設 ID 權杖的值為 XYZ123，然後，您會取消 URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123。如果權杖簽章有效，則回應會使用其解碼的 JSON 物件形式的 JWT 酬載。

tokeninfo 端點對於偵錯而言非常實用，但請在實際工作環境中，從金鑰端點擷取 Google 的公開金鑰，並在本機執行驗證程序。您應使用 jwks_uri 中繼資料值從探索文件擷取金鑰 URI。傳送至偵錯端點的要求可能會受到限製或發生暫時性錯誤。

由於 Google 不會頻繁變更其公開金鑰，因此您可以使用 HTTP 回應的快取指令對金鑰進行快取，而且在多數情況下，使用 tokeninfo 端點更有效率地執行本機驗證。這項驗證需要擷取及剖析憑證，並發出適當的加密編譯呼叫來檢查簽名。幸好，我們提供多種語言版本的偵錯程式庫，支援多種語言，請參閱 jwt.io。

取得使用者個人資料

如要取得其他使用者的其他設定檔資訊，您可以使用存取權杖 (應用程式在驗證流程期間收到的應用程式) 和 OpenID Connect 標準：

1. 如要符合 OpenID 規定，必須在驗證要求中加入 openid profile 範圍值。

   如果您想納入使用者的電子郵件地址，可以指定 email 的其他範圍值。若要同時指定 profile 和 email，您可以在驗證要求 URI 中加入下列參數：

   scope=openid%20profile%20email

2. 將存取權杖新增至授權標頭，並向 userinfo 端點發出 HTTPS GET 要求，您應該使用 userinfo_endpoint 中繼資料值從探索文件擷取。如 OpenID Connect Standard Claims 和探索文件的 claims_supported 中繼資料值所述，userinfo 回應包含使用者的相關資訊。使用者或其機構可能會選擇提供或保留特定欄位，因此您可能無法針對已授權的存取權範圍取得每個欄位的資訊。

探索文件

OpenID Connect 通訊協定需要使用多個端點來驗證使用者，以及要求資源 (包括權杖、使用者資訊和公開金鑰)。

為了簡化導入作業並增加彈性，OpenID Connect 允許使用「探索文件」；JSON 文件位於已知位置/值組合的知名位置，可提供 OpenID Connect 供應商設定的詳細資料，包括授權、權杖、撤銷、使用者資訊及公開金鑰端點的 URI。您可以從下列位置擷取 Google' OpenID Connect 服務的探索文件：

https://accounts.google.com/.well-known/openid-configuration

如要使用 Google 的 OpenID Connect 服務，您應將探索文件 URI (https://accounts.google.com/.well-known/openid-configuration) 以硬式編碼至應用程式。應用程式會擷取文件，並在回應中套用快取規則，然後視需要從端點擷取端點 URI。舉例來說，如要驗證使用者，程式碼會擷取 authorization_endpoint 中繼資料值 (下方範例中的 https://accounts.google.com/o/oauth2/v2/auth) 做為傳送至 Google 的驗證要求基礎 URI。

以下是這類文件的範例；欄位名稱為 OpenID Connect Discovery 1.0 中指定的名稱 (請參閱該文件的意義)。這些值只是用來說明用途，因此可能會從最新版本的 Google 探索文件複製而來。

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

您可以快取探索文件的值，藉此避免發生 HTTP 往返流量。 系統會採用標準 HTTP 快取標頭，因此請參照該標頭。

用戶端程式庫

下列用戶端程式庫可與熱門架構整合，讓您輕鬆導入 OAuth 2.0：

• Java 的 Google API 用戶端程式庫
• Python 適用的 Google API 用戶端程式庫
• .NET 適用的 Google API 用戶端程式庫
• Ruby 適用的 Google API 用戶端程式庫
• PHP 適用的 Google API 用戶端程式庫
• Google Web Designer 專用 OAuth 2.0 程式庫
• Google OAuthbox (Mac OAuth 2.0 控制器)

OpenID Connect 法規遵循

Google 的 OAuth 2.0 驗證系統支援 OpenID Connect Core 規格的必要功能。任何可與 OpenID Connect 搭配使用的用戶端應與這項服務互通 (OpenID 要求物件除外)。