使用 ID 權杖透過後端進行驗證

當使用者選取 Google 帳戶時,One Tap 登入用戶端會擷取 Google ID 權杖。ID 權杖是一種已簽署的使用者身分聲明,其中還包含使用者的基本個人資料資訊,可能包括 Google 驗證的電子郵件地址。

有可用的 ID 權杖時,您可以使用這些權杖安全地透過應用程式的後端進行驗證,或自動為使用者註冊新帳戶,而不必驗證使用者的電子郵件地址。

如要以 ID 憑證登入或註冊使用者,請將權杖傳送至應用程式的後端。在後端使用 Google API 用戶端程式庫或一般用途 JWT 程式庫驗證權杖。如果使用者尚未以此 Google 帳戶登入您的應用程式,請建立新帳戶。

如果您選擇使用 Nonce 來協助避免重送攻擊,請使用 getNonce 將 ID 權杖和 ID 權杖傳送至後端伺服器,並檢查預期的值。我們強烈建議您使用 Nonce 以提升使用者的安全性和安全性。

從憑證物件取得 ID 權杖

擷取使用者憑證後,請檢查憑證物件是否包含 ID 權杖。如果相符,請將內容傳送到後端。

Java

public class YourActivity extends AppCompatActivity {

  // ...
  private static final int REQ_ONE_TAP = 2;  // Can be any integer unique to the Activity.
  private boolean showOneTapUI = true;
  // ...

  @Override
  protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
      super.onActivityResult(requestCode, resultCode, data);

      switch (requestCode) {
          case REQ_ONE_TAP:
              try {
                  SignInCredential credential = oneTapClient.getSignInCredentialFromIntent(data);
                  String idToken = credential.getGoogleIdToken();
                  if (idToken !=  null) {
                      // Got an ID token from Google. Use it to authenticate
                      // with your backend.
                      Log.d(TAG, "Got ID token.");
                  }
              } catch (ApiException e) {
                  // ...
              }
              break;
      }
  }
}

Kotlin

class YourActivity : AppCompatActivity() {

    // ...
    private val REQ_ONE_TAP = 2  // Can be any integer unique to the Activity
    private var showOneTapUI = true
    // ...

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)

        when (requestCode) {
             REQ_ONE_TAP -> {
                try {
                    val credential = oneTapClient.getSignInCredentialFromIntent(data)
                    val idToken = credential.googleIdToken
                    when {
                        idToken != null -> {
                            // Got an ID token from Google. Use it to authenticate
                            // with your backend.
                            Log.d(TAG, "Got ID token.")
                        }
                        else -> {
                            // Shouldn't happen.
                            Log.d(TAG, "No ID token!")
                        }
                    }
                } catch (e: ApiException) {
                    // ...
            }
        }
    }
    // ...
}

驗證 ID 權杖的完整性

透過 HTTPS POST 接收 ID 權杖之後,您必須驗證權杖的完整性。

如要驗證權杖是否有效,請確認符合下列條件:

  • Google 正確簽署 ID 權杖。使用 Google 的公開金鑰 (提供 JWKPEM 格式) 驗證權杖的簽名。這些金鑰會定期輪替;請檢查回應中的 Cache-Control 標頭,判斷何時應再次擷取這些金鑰。
  • ID 權杖中的 aud 值等於應用程式的其中一個用戶端 ID。必須進行這項檢查,以免核發至惡意應用程式的 ID 權杖,藉此存取應用程式後端伺服器上的相同使用者相關資料。
  • ID 權杖中的 iss 值等於 accounts.google.comhttps://accounts.google.com
  • ID 權杖的到期時間 (exp) 尚未超過。
  • 如果您需要驗證 ID 權杖代表 Google Workspace 或 Cloud 機構帳戶,可以查看 hd 憑證附加資訊,這就表示使用者的託管網域。將資源的存取權限制為僅限特定網域的成員存取時,必須使用這個屬性。缺少這項聲明,代表帳戶不屬於 Google 代管網域。

比起自行編寫程式碼來執行這些驗證步驟,我們強烈建議您使用適用於您平台的 Google API 用戶端程式庫,或一般用途的 JWT 程式庫。如要進行開發和偵錯,您可以呼叫我們的 tokeninfo 驗證端點。

使用 Google API 用戶端程式庫

建議您使用其中一種 Google API 用戶端程式庫 (例如 JavaNode.jsPHPPython),在實際工作環境中驗證 Google ID 權杖。

Java

如要在 Java 中驗證 ID 權杖,請使用 GoogleIdTokenVerifier 物件。例如:

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken.Payload;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;

...

GoogleIdTokenVerifier verifier = new GoogleIdTokenVerifier.Builder(transport, jsonFactory)
    // Specify the CLIENT_ID of the app that accesses the backend:
    .setAudience(Collections.singletonList(CLIENT_ID))
    // Or, if multiple clients access the backend:
    //.setAudience(Arrays.asList(CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3))
    .build();

// (Receive idTokenString by HTTPS POST)

GoogleIdToken idToken = verifier.verify(idTokenString);
if (idToken != null) {
  Payload payload = idToken.getPayload();

  // Print user identifier
  String userId = payload.getSubject();
  System.out.println("User ID: " + userId);

  // Get profile information from payload
  String email = payload.getEmail();
  boolean emailVerified = Boolean.valueOf(payload.getEmailVerified());
  String name = (String) payload.get("name");
  String pictureUrl = (String) payload.get("picture");
  String locale = (String) payload.get("locale");
  String familyName = (String) payload.get("family_name");
  String givenName = (String) payload.get("given_name");

  // Use or store profile information
  // ...

} else {
  System.out.println("Invalid ID token.");
}

GoogleIdTokenVerifier.verify() 方法會驗證 JWT 簽名、aud 憑證附加資訊、iss 憑證附加資訊,以及 exp 憑證附加資訊。

如果您需要驗證 ID 權杖是 Google Workspace 或 Cloud 機構帳戶,可以檢查 Payload.getHostedDomain() 方法傳回的網域名稱,藉此驗證 hd 憑證附加資訊。email 憑證附加資訊的網域不足,無法確保該帳戶是由網域或機構管理。

Node.js

如要在 Node.js 中驗證 ID 權杖,請使用 Node.js 適用的 Google 驗證程式庫。安裝程式庫:

npm install google-auth-library --save
,然後呼叫 verifyIdToken() 函式。例如:

const {OAuth2Client} = require('google-auth-library');
const client = new OAuth2Client();
async function verify() {
  const ticket = await client.verifyIdToken({
      idToken: token,
      audience: CLIENT_ID,  // Specify the CLIENT_ID of the app that accesses the backend
      // Or, if multiple clients access the backend:
      //[CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3]
  });
  const payload = ticket.getPayload();
  const userid = payload['sub'];
  // If request specified a G Suite domain:
  // const domain = payload['hd'];
}
verify().catch(console.error);

verifyIdToken 函式會驗證 JWT 簽名、aud 憑證附加資訊、exp 憑證附加資訊和 iss 憑證附加資訊。

如果您需要驗證 ID 權杖代表 Google Workspace 或 Cloud 機構帳戶,可以查看 hd 憑證附加資訊,這就表示使用者的託管網域。將資源的存取權限制為僅限特定網域的成員存取時,必須使用這個屬性。缺少這項聲明,代表帳戶不屬於 Google 代管網域。

PHP

如要以 PHP 驗證 ID 權杖,請使用 PHP 適用的 Google API 用戶端程式庫。安裝程式庫 (例如使用 Composer):

composer require google/apiclient
,然後呼叫 verifyIdToken() 函式。例如:

require_once 'vendor/autoload.php';

// Get $id_token via HTTPS POST.

$client = new Google_Client(['client_id' => $CLIENT_ID]);  // Specify the CLIENT_ID of the app that accesses the backend
$payload = $client->verifyIdToken($id_token);
if ($payload) {
  $userid = $payload['sub'];
  // If request specified a G Suite domain:
  //$domain = $payload['hd'];
} else {
  // Invalid ID token
}

verifyIdToken 函式會驗證 JWT 簽名、aud 憑證附加資訊、exp 憑證附加資訊和 iss 憑證附加資訊。

如果您需要驗證 ID 權杖代表 Google Workspace 或 Cloud 機構帳戶,可以查看 hd 憑證附加資訊,這就表示使用者的託管網域。將資源的存取權限制為僅限特定網域的成員存取時,必須使用這個屬性。缺少這項聲明,代表帳戶不屬於 Google 代管網域。

Python

如要在 Python 中驗證 ID 權杖,請使用 verify_oauth2_token 函式。例如:

from google.oauth2 import id_token
from google.auth.transport import requests

# (Receive token by HTTPS POST)
# ...

try:
    # Specify the CLIENT_ID of the app that accesses the backend:
    idinfo = id_token.verify_oauth2_token(token, requests.Request(), CLIENT_ID)

    # Or, if multiple clients access the backend server:
    # idinfo = id_token.verify_oauth2_token(token, requests.Request())
    # if idinfo['aud'] not in [CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3]:
    #     raise ValueError('Could not verify audience.')

    # If auth request is from a G Suite domain:
    # if idinfo['hd'] != GSUITE_DOMAIN_NAME:
    #     raise ValueError('Wrong hosted domain.')

    # ID token is valid. Get the user's Google Account ID from the decoded token.
    userid = idinfo['sub']
except ValueError:
    # Invalid token
    pass

verify_oauth2_token 函式會驗證 JWT 簽名、aud 憑證附加資訊和 exp 憑證附加資訊。您也必須檢查 verify_oauth2_token 傳回的物件,驗證 hd 憑證附加資訊 (如適用)。如有多個用戶端存取後端伺服器,也請手動驗證 aud 憑證附加資訊。

呼叫 Tokeninfo 端點

如要驗證偵錯所需的 ID 權杖簽章,最簡單的方法是使用 tokeninfo 端點。呼叫這個端點需要額外的網路要求,這類要求會為您執行大部分的驗證作業,同時在您自己的程式碼中測試適當的驗證與酬載擷取作業。不適用於實際工作環境程式碼中,因為要求可能會受到限製或發生間歇性錯誤。

如要使用 tokeninfo 端點驗證 ID 權杖,請向端點發出 HTTPS POST 或 GET 要求,並在 id_token 參數中傳遞 ID 權杖。 舉例來說,如要驗證權杖「XYZ123」,請提出下列 GET 要求:

https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123

如果權杖已正確簽署,且 issexp 憑證附加資訊含有預期值,您會收到「HTTP 200」回應,其中主體包含 JSON 格式的 ID 權杖憑證附加資訊。以下是回應範例:

{
 // These six fields are included in all Google ID Tokens.
 "iss": "https://accounts.google.com",
 "sub": "110169484474386276334",
 "azp": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
 "aud": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
 "iat": "1433978353",
 "exp": "1433981953",

 // These seven fields are only included when the user has granted the "profile" and
 // "email" OAuth scopes to the application.
 "email": "testuser@gmail.com",
 "email_verified": "true",
 "name" : "Test User",
 "picture": "https://lh4.googleusercontent.com/-kYgzyAWpZzJ/ABCDEFGHI/AAAJKLMNOP/tIXL9Ir44LE/s99-c/photo.jpg",
 "given_name": "Test",
 "family_name": "User",
 "locale": "en"
}

如果您需要驗證 ID 權杖是否代表 Google Workspace 帳戶,可以查看 hd 憑證附加資訊,這會指出使用者的代管網域。將資源的存取權限制為僅限特定網域的成員存取時,必須使用這個屬性。若缺少這項聲明,代表帳戶不屬於 Google Workspace 代管的網域。

建立帳戶或工作階段

驗證權杖後,請檢查使用者是否已在使用者資料庫中。如果是的話,請為使用者建立已驗證的工作階段。如果使用者還不在您的使用者資料庫中,請使用 ID 權杖酬載中的資訊建立新的使用者記錄,然後為使用者建立工作階段。偵測到應用程式新建立的使用者時,您可以提示使用者輸入任何其他必要的設定檔資訊。

使用跨帳戶防護功能確保使用者帳戶安全無虞

當你仰賴 Google 來登入使用者帳戶時,系統會自動發揮 Google 保護使用者資料的所有安全防護功能和基礎架構,不過,萬一使用者的 Google 帳戶遭到入侵,或是發生其他重大安全性事件,您的應用程式就可能容易遭受攻擊。如要進一步保護帳戶不受重大安全性事件影響,請使用跨帳戶防護功能接收 Google 的安全性警示。收到這些事件後,您可以掌握使用者的 Google 帳戶安全有重大異動,並能對服務採取動作,保護帳戶安全。