Google Sign-In：什么是它、通过 Google 登录与 OAuth 2.0 SDK

什么是 Google Sign-In？

Google Sign-In 是谷歌提供的单点登录（Single Sign-On）服务，用于在第三方应用中验证用户身份。开发者可通过该 SDK 集成 Google 账户登录，而无需自建注册系统。该技术基于 OAuth 2.0 协议和 OpenID Connect，可获取用户的身份信息：姓名、邮箱、头像和唯一标识符。

与传统的邮箱加密码认证不同，Google Sign-In 免去了用户记忆密码和填写注册流程的麻烦。用户只需在设备上选择 Google 账户、确认授权，应用即可获得访问令牌。根据 Google Identity Platform (2025) 的数据，使用 Google Sign-In 的应用相比邮箱/密码表单，成功注册数量多出 52%。

Google Sign-In 支持三种使用场景：用户身份验证（获取 ID Token）、Google API 访问授权（获取 Access Token）以及针对已授权用户的无缝认证（Silent Sign-In）。每种场景都需要不同的权限集（scopes）并返回不同类型的令牌。

Google Sign-In 中的 OAuth 2.0 如何工作

OAuth 2.0 是一种授权协议，允许应用在无需公开用户凭据的情况下获得对用户资源的受限访问。在 Google Sign-In 的语境下，该协议的运作方式如下：应用通过 Google 向用户请求授权，获取临时授权码，将其换取访问令牌，并使用这些令牌调用 Google API。

OAuth 2.0 与早期协议的关键区别在于对角色进行了划分：资源所有者（用户）、客户端（应用）、授权服务器（Google）和资源服务器（Google API）各司其职。应用永远不会获得用户密码，只会获得一个可被撤销的令牌。Google Identity Platform 在 OAuth 2.0 之上采用 OpenID Connect 规范，增加了标准化的 JWT 格式 ID Token。

ID Token 与 Access Token 的区别

// 通过 Credential Manager 获取 ID Token 的示例
val googleIdOption = GoogleIdCredentialOption.Builder()
    .setServerClientId(serverClientId)
    .build()

val credentialManager = CredentialManager.create(this)
val request = GetCredentialRequest.Builder()
    .addCredentialOption(googleIdOption)
    .build()

credentialManager.getCredential(request)
    .addOnSuccessListener { result ->
        val credential = result.credential as GoogleIdCredential
        Log.d("登录", credential.idToken)
    }

ID Token (JWT) 包含三个部分：包含签名算法的头部、包含用户数据的负载（sub、email、name、picture）以及用于验证的签名。应用的服务端使用 Google 的公钥验证 ID Token 的签名，并提取用户标识符。这种方法可以保证，即使客户端应用被入侵，攻击者也无法在未获取 Google 私钥的情况下伪造令牌。

Credential Manager：Android 上新的登录方式

Credential Manager 是谷歌于 2023 年推出的现代 Android API，它将所有认证方式（Google Sign-In、密码登录、Passkeys）整合到统一的用户界面中。与旧的 GoogleSignInClient 不同，Credential Manager 无需 WebView 即可登录，而是使用原生 Bottom Sheet，从而加快认证速度并改善用户体验。

Credential Manager 的主要优势是所有类型凭据都能获得统一 UX。用户只需看到一个对话框，即可选择：通过 Google 登录、使用 Passkey 或输入密码。开发者无需管理不同的认证流程——Credential Manager 抽象了与 Google Sign-In、Smart Lock 和 Passkeys 的交互。Google 推荐将 Credential Manager 作为 Android 14 及以上版本集成 Google Sign-In 的主要方式。

从 GoogleSignInClient 迁移到 Credential Manager

迁移从 GoogleSignInClient 到 Credential Manager 需要修改客户端逻辑：用 GoogleIdCredentialOption 代替 GoogleSignInOptions，用 GetCredentialResponse 的结果处理代替 GoogleSignIn.getSignedInAccountFromIntent。服务端无需改动，因为 ID Token 仍保持相同的 JWT 格式。根据 Google I/O 2024 的数据，Google Play 中约 40% 的应用已经迁移到 Credential Manager。

在 Android 项目中配置 Google Sign-In

在 Android 应用中集成 Google Sign-In 首先要从在 Google Cloud Console 中配置项目开始。第一步是为 Android 创建 OAuth 2.0 Client ID：需要指定应用的 package name 和签名证书的 SHA-1。Google 会利用这些数据验证认证请求确实来自你的应用，而非伪造客户端。

在 Google Cloud Console 创建客户端后，开发者需要在 build.gradle 中添加 Credential Manager 依赖，并配置带 serverClientId 的 GoogleIdCredentialOption。注意：serverClientId 是同一 Google Cloud 项目中 Web 应用的 Client ID，服务端用它来验证 ID Token。客户端应用不验证令牌，它只是获取令牌并传递给服务器。

// build.gradle（应用）依赖
implementation("androidx.credentials:credentials:1.5.0")
implementation("androidx.credentials:credentials-play-services-auth:1.5.0")
implementation("com.google.android.libraries.identity.googleid:googleid:1.1.0")

// 通过 Credential Manager 请求 Google Sign-In
suspend fun requestGoogleSignIn(context: Context): String? {
    val credentialManager = CredentialManager.create(context)
    val googleIdOption = GoogleIdCredentialOption.Builder()
        .setServerClientId(BuildConfig.SERVER_CLIENT_ID)
        .setAutoSelectEnabled(true)
        .build()

    val result = credentialManager.getCredential(
        context as Activity,
        GetCredentialRequest.Builder()
            .addCredentialOption(googleIdOption)
            .build()
    )
    return (result.credential as GoogleIdCredential).idToken
}

客户端获取 ID Token 后，应用会将其发送到自己的服务器进行验证。服务器使用 Google 的公钥（可通过 https://www.googleapis.com/oauth2/v3/certs 获取）验证 JWT 签名、令牌有效期（exp）以及 aud 字段的值——它必须与 serverClientId 一致。验证完成后，服务器会创建自己的会话，例如签发内部 JWT 或 Session Token。

iOS 上的 Google Sign-In：配置与特点

在 iOS 上集成 Google Sign-In 需要通过 GoogleSignIn-iOS SDK 实现，该 SDK 可通过 CocoaPods 或 Swift Package Manager 获取。配置流程包括：在 Google Cloud Console 中创建 iOS Client ID（并指定 Bundle Identifier）、添加用于回调的 URL Scheme，以及在 AppDelegate 中配置对 Google 认证后返回的 URL 的处理。

Google Sign-In 的 iOS 版本与 Android 的一个重要区别是需要配置 URL Scheme 和 Info.plist。GoogleSDK 使用通用链接（Universal Links）进行回调，但为了兼容性还需要 `com.googleusercontent.apps.[CLIENT_ID]` 形式的 URL Scheme。此外还需要配置 Keychain Sharing，以便在应用启动之间保存 refresh token。根据 Google Identity 文档，iOS SDK 支持 iOS 15 及以上版本。

// 在 iOS 上配置 Google Sign-In
import GoogleSignIn

class SignInManager: ObservableObject {
    func signIn(presenting viewController: UIViewController) {
        GIDSignIn.sharedInstance.signIn(
            withPresenting: viewController
        ) { signInResult, error in
            guard let result = signInResult else {
                print("登录失败：\(error)")
                return
            }
            let idToken = result.user.idToken.tokenString
            // 将 ID Token 发送到服务器
            sendTokenToBackend(idToken)
        }
    }
}

在 iOS 上，Google Sign-In 支持针对之前已授权用户的 Silent Sign-In。如果 refresh token 已保存在 Keychain 中，restorePreviousSignIn 方法会自动恢复会话。这对于用户不应在每次启动时重复登录的应用尤为重要。根据 Google 的数据，在存在活跃 Google 会话的设备上，Silent Sign-In 的成功率为 85%。

令牌处理与安全

安全性 Google Sign-In 的安全性建立在三个层面：客户端验证（应用 SHA-1 签名）、传输加密（HTTPS/TLS）以及 JWT 的加密签名。从 Google 获得的 ID Token 使用 RS256（RSA with SHA-256）算法签名。应用的服务端必须验证令牌签名、有效期以及 issuer（iss）——只能是 accounts.google.com。

Access Token 是临时令牌（有效期为 1 小时），用于访问 Google API（Google Drive、Google Calendar、YouTube 等）。与 ID Token 不同，Access Token 不包含用户信息，它是一个 opaque 字符串，Google API 服务器用它来授权请求。Refresh Token 是长期有效的令牌，可在用户不重新登录的情况下获取新的 Access Token。Refresh Token 仅在首次登录时发放，用户可在 Google 账户设置中将其撤销。

// 在服务器上处理 ID Token 的示例（伪代码）
fun verifyGoogleToken(idToken: String): User? {
    val verifier = GoogleIdTokenVerifier.Builder(
        NetHttpTransport(), GsonFactory.getDefaultInstance()
    ).setAudience(listOf(CLIENT_ID))
     .build()

    val token = verifier.verify(idToken) ?: return null
    val payload = token.payload

    return User(
        id = payload.subject,
        email = payload.email,
        name = payload.get("name") as String
    )
}

Refresh Token 与会话管理

安全建议：切勿通过不安全的渠道传输 ID Token，所有发送到服务器的请求都应使用 HTTPS，并检查令牌有效期（exp 字段）和 issuer（iss）。在客户端，不要将令牌明文存储在 SharedPreferences 中，应使用 EncryptedSharedPreferences 或 Android Keystore。Google Sign-In 不用于服务器对服务器的认证——这种情况下应使用服务账户（Service Accounts）。

代码示例：使用 Kotlin 集成 Google Sign-In

在 Android 应用中使用 Credential Manager 和 ViewModel 集成 Google Sign-In 的完整示例。应用显示登录按钮，认证成功后向服务器发送 ID Token 并展示用户信息。代码使用协程与 Credential Manager 进行异步交互。

class SignInViewModel: ViewModel() {
    private val cm = CredentialManager.create(getApplication())

    private val googleOption = GoogleIdCredentialOption.Builder()
        .setServerClientId(BuildConfig.SERVER_CLIENT_ID)
        .build()

    suspend fun signIn(): SignInResult {
        return try {
            val response = cm.getCredential(
                GetCredentialRequest.Builder()
                    .addCredentialOption(googleOption)
                    .build()
            )
            val credential = response.credential as GoogleIdCredential
            SignInResult.Success(credential.idToken)
        } catch (e: GetCredentialCancellationException) {
            SignInResult.Cancelled
        }
    }
}

sealed class SignInResult {
    data class Success(val idToken: String) : SignInResult()
    data class Error(val message: String) : SignInResult()
    data class Cancelled : SignInResult()
}

认证成功后，应用应向自己的服务器发送 ID Token 以进行验证并创建会话。建议使用 HTTPS，并在 POST 请求体中传递令牌。服务器返回自己的会话令牌，客户端将其保存在 EncryptedSharedPreferences 中。此后每次向服务器的请求都使用内部令牌，而不是 Google 的 ID Token。

集成时的常见错误及解决方法

第一个常见错误是 SHA-1 证书不匹配。Google Cloud Console 将 OAuth 2.0 Client ID 绑定到签名证书的 SHA-1 指纹。如果应用使用 debug 密钥构建，而 Client ID 是为 release 密钥创建的，Google Sign-In 将返回错误 12501 (SIGN_IN_FAILED)。解决办法：在 Google Cloud Console 中添加两个 SHA-1（debug 和 release），或者为开发使用一个 Client ID、为生产环境使用另一个。

第二个常见问题是 serverClientId 错误。开发者经常在 Credential Manager 的 serverClientId 参数中使用 Android Client ID，而不是 Web 应用的 Client ID。Google 要求使用 Web 客户端 ID 来生成用于服务器验证的 ID Token。Android Client ID 仅用于在认证过程中标识应用。请检查 serverClientId 是否与 Google Cloud Console 中的 Web 应用对应。

第三个错误是忽略取消处理。用户可能关闭 Google Sign-In 对话框而未完成认证。Credential Manager 会抛出 GetCredentialCancellationException，需要与其他错误分开处理。许多开发者将所有异常都当作错误处理，向用户显示“登录失败”的消息，但实际上用户只是取消了操作。正确的做法是：遇到 Cancelled 时不显示任何内容，直接返回初始状态。