关联帐号登录 (Android)

如果用户的 Google 帐号已与您的服务相关联，则“关联的帐号登录”功能可为已将其 Google 帐号的用户启用一键登录 Google 服务。这提升了用户体验，因为用户只需点击一下，即可登录，而无需重新输入用户名和密码。这还可以降低用户在您的服务上重复创建帐号的几率。

关联的帐号登录功能是 Android 的一键登录流程的一部分。这意味着，如果您的应用已经启用一键快捷功能，则无需导入单独的库。

在本文档中，您将了解如何修改 Android 应用以支持关联的帐号登录。

运作方式

  1. 您可以在“一键登录”流程中选择显示关联的账号。
  2. 如果用户登录了 Google，并且已将其 Google 帐号与其在服务中的帐号相关联，那么我们会向您发送关联帐号的 ID 令牌。
  3. 系统会向用户显示“一键登录”提示，以便用户使用关联的帐号登录您的服务。
  4. 如果用户选择继续使用关联的帐号，系统会将用户的 ID 令牌返回给您的应用。您可以将其与在第 2 步中发送到服务器的令牌进行匹配，以识别已登录的用户。

初始设置

设置开发环境

在开发主机上获取最新的 Google Play 服务：

  1. 打开 Android SDK 管理器。

  1. 在 SDK Tools 下，找到 Google Play 服务。

  2. 如果这些软件包的状态为“未安装”，请同时选中它们并点击 Install Packages（安装软件包）。

配置您的应用

  1. 在项目级 build.gradle 文件中，同时在 buildscript 和 allprojects 部分添加 Google 的 Maven 制品库。

    buildscript {
    repositories {
        google()
    }
}

allprojects {
    repositories {
        google()
    }
}

  2. 将“Link with Google”API 的依赖项添加到模块的应用级 Gradle 文件（通常为 app/build.gradle）：

    dependencies {
  implementation 'com.google.android.gms:play-services-auth:20.7.0'
}

修改您的 Android 应用以支持关联的账号登录功能

在关联的帐号登录流程结束后，系统会向您的应用返回一个 ID 令牌。应先验证 ID 令牌的完整性，然后再让用户登录。

以下代码示例详细介绍了检索、验证 ID 令牌以及随后让用户登录的步骤。

  1. 创建 activity 以接收登录 intent 的结果

    Kotlin

      private val activityResultLauncher = registerForActivityResult(
    ActivityResultContracts.StartIntentSenderForResult()) { result ->
    if (result.resultCode == RESULT_OK) {
      try {
        val signInCredentials = Identity.signInClient(this)
                                .signInCredentialFromIntent(result.data)
        // Review the Verify the integrity of the ID token section for
        // details on how to verify the ID token
        verifyIdToken(signInCredential.googleIdToken)
      } catch (e: ApiException) {
        Log.e(TAG, “Sign-in failed with error code:”, e)
      }
    } else {
      Log.e(TAG, “Sign-in failed”)
    }
  }

    Java

      private final ActivityResultLauncher<IntentSenderResult>
    activityResultLauncher = registerForActivityResult(
    new ActivityResultContracts.StartIntentSenderForResult(),
    result -> {
    If (result.getResultCode() == RESULT_OK) {
        try {
          SignInCredential signInCredential = Identity.getSignInClient(this)
                         .getSignInCredentialFromIntent(result.getData());
          verifyIdToken(signInCredential.getGoogleIdToken());
        } catch (e: ApiException ) {
          Log.e(TAG, “Sign-in failed with error:”, e)
        }
    } else {
        Log.e(TAG, “Sign-in failed”)
    }
});

  2. 构建登录请求

    Kotlin

    private val tokenRequestOptions =
GoogleIdTokenRequestOptions.Builder()
  .supported(true)
  // Your server's client ID, not your Android client ID.
  .serverClientId(getString("your-server-client-id")
  .filterByAuthorizedAccounts(true)
  .associateLinkedAccounts("service-id-of-and-defined-by-developer",
                           scopes)
  .build()

    Java

     private final GoogleIdTokenRequestOptions tokenRequestOptions =
     GoogleIdTokenRequestOptions.Builder()
  .setSupported(true)
  .setServerClientId("your-service-client-id")
  .setFilterByAuthorizedAccounts(true)
  .associateLinkedAccounts("service-id-of-and-defined-by-developer",
                            scopes)
  .build()

  3. 启动登录待处理 intent

    Kotlin

     Identity.signInClient(this)
    .beginSignIn(
  BeginSignInRequest.Builder()
    .googleIdTokenRequestOptions(tokenRequestOptions)
  .build())
    .addOnSuccessListener{result ->
      activityResultLauncher.launch(result.pendingIntent.intentSender)
  }
  .addOnFailureListener {e ->
    Log.e(TAG, “Sign-in failed because:”, e)
  }

    Java

     Identity.getSignInClient(this)
  .beginSignIn(
    BeginSignInRequest.Builder()
      .setGoogleIdTokenRequestOptions(tokenRequestOptions)
      .build())
  .addOnSuccessListener(result -> {
    activityResultLauncher.launch(
        result.getPendingIntent().getIntentSender());
})
.addOnFailureListener(e -> {
  Log.e(TAG, “Sign-in failed because:”, e);
});

验证 ID 令牌的完整性

To verify that the token is valid, ensure that the following criteria are satisfied:

  • The ID token is properly signed by Google. Use Google's public keys (available in JWK or PEM format) to verify the token's signature. These keys are regularly rotated; examine the Cache-Control header in the response to determine when you should retrieve them again.
  • The value of aud in the ID token is equal to one of your app's client IDs. This check is necessary to prevent ID tokens issued to a malicious app being used to access data about the same user on your app's backend server.
  • The value of iss in the ID token is equal to accounts.google.com or https://accounts.google.com.
  • The expiry time (exp) of the ID token has not passed.
  • If you want to restrict access to only members of your G Suite domain, verify that the ID token has an hd claim that matches your G Suite domain name.

Rather than writing your own code to perform these verification steps, we strongly recommend using a Google API client library for your platform, or a general-purpose JWT library. For development and debugging, you can call our tokeninfo validation endpoint.

使用 Google API 客户端库

在生产环境中验证 Google ID 令牌时，建议使用 Java Google API 客户端库。

Java

  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 声明和 theyexp 声明。

如果您希望仅限 G Suite 网域中的成员访问文件，则还应通过检查 Payload.getHostedDomain() 方法返回的域名来验证 hd 声明。

调用 tokeninfo 端点

若要验证用于调试的 ID 令牌签名，一种简单的方法是使用 tokeninfo 端点。调用此端点涉及到一个额外的网络请求，该网络请求会为您执行大部分验证，而您在自己的代码中测试适当的验证和载荷提取时。它不适合在生产代码中使用，因为请求可能会受到限制或出现间歇性错误。

如需使用 tokeninfo 端点验证 ID 令牌，请向该端点发出 HTTPS POST 或 GET 请求，并在 id_token 参数中传递您的 ID 令牌。例如，要验证令牌“XYZ123”，可发出以下 GET 请求：

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

如果令牌已正确签名，并且 iss 和 exp 声明具有预期值，您会收到 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"
}

如果您是 G Suite 客户，可能还对 hd 声明感兴趣，该声明表示用户的托管网域。这可用于将对资源的访问权限限制为仅特定网域的成员。缺少此声明表示用户不属于 G Suite 托管网域。