透過後端伺服器驗證

如果您使用 Google 登入的應用程式或網站會與後端伺服器通訊,您可能需要在伺服器上識別目前登入的使用者。為安全地完成這項程序,請在使用者成功登入後,透過 HTTPS 將使用者的 ID 權杖傳送至伺服器。接著,在伺服器上驗證 ID 權杖的完整性,並使用權杖包含的使用者資訊來建立工作階段或建立新帳戶。

將 ID 權杖傳送至伺服器

使用者成功登入後,取得使用者的 ID 權杖:

Swift

GIDSignIn.sharedInstance.signIn(withPresenting: self) { signInResult, error in
    guard error == nil else { return }
    guard let signInResult = signInResult else { return }

    signInResult.user.refreshTokensIfNeeded { user, error in
        guard error == nil else { return }
        guard let user = user else { return }

        let idToken = user.idToken
        // Send ID token to backend (example below).
    }
}

Objective-C

[GIDSignIn.sharedInstance signInWithPresentingViewController:self
                                              completion:^(GIDSignInResult * _Nullable signInResult,
                                                           NSError * _Nullable error) {
      if (error) { return; }
      if (signInResult == nil) { return; }

      [signInResult.user refreshTokensIfNeededWithCompletion:^(GIDGoogleUser * _Nullable user,
                                                               NSError * _Nullable error) {
          if (error) { return; }
          if (user == nil) { return; }

          NSString *idToken = user.idToken;
          // Send ID token to backend (example below).
      }];
}];

接著,使用 HTTPS POST 要求將 ID 權杖傳送至伺服器:

Swift

func tokenSignInExample(idToken: String) {
    guard let authData = try? JSONEncoder().encode(["idToken": idToken]) else {
        return
    }
    let url = URL(string: "https://yourbackend.example.com/tokensignin")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let task = URLSession.shared.uploadTask(with: request, from: authData) { data, response, error in
        // Handle response from your backend.
    }
    task.resume()
}

Objective-C

NSString *signinEndpoint = @"https://yourbackend.example.com/tokensignin";
NSDictionary *params = @{@"idtoken": idToken};

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:signinEndpoint];
[request setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
[request setHTTPMethod:@"POST"];
[request setHTTPBody:[self httpBodyForParamsDictionary:params]];

NSOperationQueue *queue = [[NSOperationQueue alloc] init];
[NSURLConnection sendAsynchronousRequest:request
                                   queue:queue
                       completionHandler:^(NSURLResponse *response, NSData *data, NSError *error) {
                         if (error) {
                           NSLog(@"Error: %@", error.localizedDescription);
                         } else {
                           NSLog(@"Signed in as %@", data.bytes);
                         }
                       }];

驗證 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 ID 令牌时,建议使用一个 Google API 客户端库(例如 JavaNode.jsPHPPython)。

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 Auth 库。安装库:

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 the request specified a Google Workspace 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 the request specified a Google Workspace 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 the request specified a Google Workspace domain
    # if idinfo['hd'] != DOMAIN_NAME:
    #     raise ValueError('Wrong domain name.')

    # 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 帳戶安全有重大異動,並能對服務採取動作,保護帳戶安全。