跳转至正文

Google Client ID:是什么以及如何创建

了解 Google OAuth 客户端 ID 是什么、在 Google Cloud Console 中哪里找到它,以及如何为 Web、Android 和 iOS 创建凭据。修复常见登录错误。

在 Google Cloud Console 中为 Web、Android 和 iOS 应用配置 Google OAuth 客户端 ID

一套 Google OAuth 客户端 ID 是 Google 显示的公开应用标识符,是一个以 .apps.googleusercontent.com结尾的字符串。你在 Google Cloud Console 在……下 Google Auth Platform > 客户端 或 API 和服务 > 凭据中创建和管理它。该值告诉 Google 是哪个已注册应用在发起 Google 登录或请求 OAuth 令牌。

你大概会来到这里,是因为 Google 登录本该是个快速集成,结果却盯着凭据页面,纳闷为什么一种应用类型有客户端密钥,另一种却没有。这种困惑很正常,尤其是当你使用 Capacitor、Ionic、Electron 或 Web 与原生混合技术栈时。

大多数指南跳过的那部分,恰恰是会让实际实现出问题的地方: Google 客户端 ID 因平台而异,且非 Web 应用类型通常 不会 在设计上获取客户端密钥。如果你为了强行在流程中引入密钥而创建了错误的凭据,最终往往会得到一个难以调试的损坏 OAuth 配置。

目录

在 Google 允许你创建 OAuth 客户端之前,项目必须先为 Google Auth 注册应用。当你打开 Google Auth Platform > 客户端 时,Google 会提示你完成此操作。

典型步骤:

  1. 打开 Google Cloud Console 并选择将拥有登录功能的项目。
  2. 前往 Google 身份验证平台 (或 API 和服务 > OAuth 同意屏幕 (在旧版导航中)。
  3. 选择 外部 或 内部 用户类型,然后填写应用名称、支持邮箱和开发者联系方式。
  4. 添加应用将请求的 scope(对于基础登录, email 以及 profile 这些是常用的)。
  5. 保存并继续走完同意屏幕流程,直到应用注册完成。

此界面上的应用名称就是用户在 Google 权限提示中看到的名称。它应与用户安装的应用一致,而不是内部代号。

如何创建 OAuth 2.0 client ID

Google 在以下文档中记录了该流程: 管理 OAuth 客户端 帮助页面。这两个入口都可以使用:

  1. Google Auth Platform > 客户端 (然后 创建客户端)
  2. API 和服务 > 凭据 (然后 创建凭据 > OAuth 客户端 ID)

请先选择或创建一个 Cloud 项目。不要把认证凭据分散到不相关的项目中。

一个人正在笔记本电脑上打字,屏幕上显示着用于创建 OAuth 2.0 客户端凭据的 Google Cloud 控制台。

Web 应用客户端

浏览器应用以及以下场景请使用此类型: Web 客户端 ID 许多移动 SDK 将其作为服务器受众。

  1. 点击 创建客户端 (或创建一个 OAuth 客户端 ID ,来自凭据)。
  2. 选择 Web 应用 作为应用类型。
  3. 设置 已获授权的 JavaScript 来源 到每个运行登录 UI 的源(scheme、host 和 port 必须完全匹配)。使用 http://localhost:<port> 用于本地开发。根据 Google 的规则,生产环境的源必须使用 HTTPS,localhost 除外。
  4. 设置 已授权的重定向 URI 到 Google 重定向回来后你的服务器或 SPA 使用的每个回调 URL。
  5. 点击 创建. 复制 客户端 ID 并安全存储 客户端密钥 。Google 可能只显示一次该密钥。

对于 Capacitor 混合应用,即使登录通过原生 SDK 进行,Web 客户端 ID 通常也用于令牌验证。参见 如何使用 Capacitor 进行 Google 登录 了解完整的移动端配置。

Android 客户端(包名与 SHA-1)

Android OAuth 客户端将 Google 登录关联到您的 包名 以及 SHA-1 签名证书的

  1. 点击 创建客户端 并选择 Android.

  2. 输入 包名 从你的应用中(例如 com.example.app,匹配 applicationId 在 Gradle 中)。

  3. 获取 SHA-1 证书指纹 用于签署您正在测试的 build 的 keystore:

    keytool -list -v -keystore path-to-debug-or-production-keystore -alias your-key-alias

    对于默认的 debug keystore,Google 指出密码通常是 android 而路径通常为 ~/.android/debug.keystore.

  4. 将 SHA-1 粘贴到表单中并点击 创建.

  5. 复制 Android 客户端 ID。Google 通常不会 不会 为此类型签发 client secret。

如果应用已上架 Google Play,还需注册 Play 应用签名 Play 控制台的 SHA-1 应用完整性. Play 会使用与上传 keystore 不同的密钥对发布版本进行重新签名。

iOS 客户端(Bundle ID)

  1. 点击 创建客户端 并选择 iOS.
  2. 输入 Bundle ID (来自 Xcode,需与 CFBundleIdentifier 中的 Info.plist,例如 com.example.app).
  3. 可选添加 App Store ID 以及 团队 ID 当 Google 要求提供时。
  4. 点击 创建 并复制 iOS 客户端 ID.

将此客户端用于原生 iOS Google 登录,或与 @capgo/capacitor-social-login 为 Capacitor 配置 Apple 和 Google 提供商时。

如果你想边点击边对比 UI,这个图文教程是个不错的视觉参考:

如何查找现有的 Client ID

创建完成后,打开 Google Auth Platform &gt; 客户端 或 API 和服务 &gt; 凭据。每一行按名称和类型列出 OAuth 2.0 客户端 ID。打开某个客户端以复制其 客户端 ID 字符串(xxxx.apps.googleusercontent.com)。Web 客户端也会显示 客户端密钥 管理功能位于同一详情页。

同意屏幕并非装饰,而是信任边界的一部分。用户在那里看到的是你的应用名称,而非内部项目昵称。

Client ID 与 Client Secret 的区别

凭据 可见范围 典型用途
客户端 ID 公开。可安全嵌入应用和前端。 在所有 OAuth 流程中向 Google 标识你的应用。
客户端密钥 机密。仅限服务器或 CI 使用。 在 code-for-token 交换过程中,证明您的后端拥有 Web OAuth 客户端。

Google 将 Web 应用 在您的服务器上运行的客户端归类为 私有 可能使用密钥的客户端。 Android, iOS以及其他 已安装 客户端是 公开 客户端。Google 故意不提供 secret,因为用户可以从 APK 或 IPA 中提取任何随包发布的内容。

不要只为获取 secret 就给移动应用创建 Web 客户端。这种不匹配会导致 invalid_clientDEVELOPER_ERROR,以及之后令人困惑的 token audience 错误。

什么是 Google Client ID

一套 Google OAuth 2.0 Client ID 是你的应用在 Google 认证系统中的公开标识符。Google 将其描述为应用向 Google 认证端点请求 access token 时使用的唯一用户名,并指出它不同于 API 密钥,因为它在 OAuth 流程中用于在 token 交换期间验证应用身份,详见 Google Cloud 的 OAuth client 文档.

该图表解释了 Google Client ID 如何作为应用的唯一标识符和安全层。

可以把 Google 签发的 client id 视为你应用的 公开用户名.

它告诉 Google:“此请求来自该已注册应用。”这在登录、授权、token 交换以及任何应用代表用户执行操作的流程中都很重要。Client ID 旨在被你的应用和 Google 的认证服务器共同引用。

让人困惑的是,这个凭据旁边还有两个概念,它们并不通用。

客户端 ID 用于在 OAuth 中标识应用。
API 密钥 用于某些不涉及委托用户授权的 API 调用中标识项目。
客户端密钥 是与之配对的机密值,仅用于能安全保存密钥的流程和应用类型。

许多集成出问题,都始于有人把它们当成同一事物的不同变体。其实并非如此。

如果你需要 使用 Google 登录 或 一键登录,client ID 是前端用来发起认证握手的值。Google 文档还指出,必须先在一个专用的 Cloud Console 项目中注册应用,才能生成凭据;此外,Web 应用需要配置已获授权的 JavaScript 来源,或包含完整 scheme 和主机名的重定向 URI。

对于构建混合应用的团队,最稳妥的心智模型是:

  • 用 client ID 标识应用
  • 用同意屏幕向用户展示应用
  • 用正确的应用类型判断流程中是否需要 secret

如果你想更全面地了解应用身份与委托访问如何配合, 这份应用授权指南 是一个很好的回顾。关于 Capacitor 的 OAuth2 端到端流程,请参阅 Capacitor 应用中的 OAuth2.

平台专属的 Client ID 配置

搞坏 Google 登录配置最快的方式,就是以为一个 client ID 能覆盖所有平台。其实不能。对于多平台应用,每个平台都必须注册各自独立的 OAuth 2.0 client ID,而 Android 配置尤其需要 SHA1 指纹来验证所有权,正如 Google 的 Android 客户端说明.

对用户来说,你的产品可能只是一个应用,但对 Google 而言,它是多个 OAuth 客户端。

一套 Web 应用,一个 Android 构建,一个 iOS 构建,以及一个 桌面应用 并不具备相同的安全特性。Google 通过为每个平台提供独立的应用注册模型来处理这一点。

以下是实际操作中的划分方式:

  • Web 端 使用 Web Client ID,并严格匹配 Origin 和 Redirect URI。
  • Android 使用与包标识和 SHA1 指纹绑定的 Android Client ID。
  • iOS 使用与应用的 bundle 标识绑定的 iOS 客户端 ID。
  • 桌面端或 Electron 通常采用已安装或桌面风格的 OAuth 模式,而非基于密钥的浏览器流程。

Google Client ID 类型对比

应用类型 主要标识符 提供 Client Secret? 关键用例
Web 端 授权的 JavaScript 源和重定向 URI 通常是 浏览器应用与后端辅助的 Web OAuth
Android 包名加 SHA1 指纹 通常不需要 Android 原生登录
iOS App Bundle ID 通常不需要 iPhone 和 iPad 原生登录
桌面端 已安装应用的标识 通常不需要 桌面应用,包括 Electron 风格的原生流程

移动端与桌面端的 Client Secret 悖论

移动端和桌面端开发者通常期望每个 OAuth 客户端都同时附带一个 客户端 ID 以及 客户端密钥。然后他们创建一个 Web 应用 凭据,因为这是他们在控制台中查看密钥的唯一方式。

根据 Google 的 OAuth 客户端指南,Android、iOS 和已安装应用等非 Web 应用类型通常只会收到客户端 ID 而没有客户端密钥,这是有意为之,因为 Google 不希望将机密密钥嵌入到用户可提取的客户端软件中。

对于 Capacitor 团队来说,这通常表现为以下两种错误模式之一:

  1. 应用会通过使用 Web 客户端 启动基于浏览器的流程,然后试图表现得像机密服务器。
  2. 应用会发送 客户端密钥 来自捆绑的 code,这违背了使用密钥的初衷。

更好的做法是将移动和桌面应用视为 公共客户端。如果涉及后端,就把机密操作留在后端,并让原生应用只做公共客户端该做的事。

对于基于 Firebase 的 Android 登录,还有一个细微但重要的点。在这种配置中, Web 应用类型的客户端 ID 用作后端服务器的 OAuth 客户端 ID,而 Android 应用保留自己平台专属的身份。两者角色不同。

如果只记一条规则,就记这条: 选择与 code 运行位置相匹配的客户端类型,而不是你希望拥有的凭据形态.

保护您的 Google API 凭据

大多数 OAuth 事故并不是复杂攻击造成的。团队会泄露凭据、把重定向设置放得过宽,或把密钥放到本来就不安全的地方。

Google 的 OAuth 指南将 客户端密钥 视为应存放在你控制的服务器上的机密凭据。 客户端 ID 是公开标识符,但仍应谨慎注册。对于 Web 应用,Google 会按预注册的 redirect URI 校验客户端 ID。如果 redirect URI 没有严格匹配,Google 会拒绝请求。

一位专业开发者坐在办公室的办公桌前,用双显示器查看安全凭证。

如果只能做对几件事,就做这些:

  • 切勿在应用 code 中打包客户端密钥。 Web bundle、移动端二进制文件和 Electron 包都可被用户检查。
  • 注册精确的 redirect URI。 “差不多”可不够。Google 会严格校验 Web 流程的匹配。
  • 收紧 origin 范围。 不要为了省去配置麻烦就授权宽泛域名。
  • 分离平台凭证。 不要为了图方便,就把 Android、iOS 和 Web 合并到同一个凭证。

那些能避免麻烦的团队会将 OAuth 凭证视为其他生产环境密钥一样对待。他们会在后端保留 Web 客户端密钥,通过环境管理注入,并审计谁拥有控制台访问权限。如果你正在清理发布流水线,这篇关于 在 CI/CD pipeline 中管理 secrets 的指南也值得应用到你的认证配置中。

常见 Client ID 错误排查

大多数 Google OAuth 失败源于少数几个配置错误。错误信息可能并不友好,但一旦知道该看哪里,根本问题通常都很直接。

redirect_uri_mismatch

你的应用发送的 redirect URI 与该 Web 客户端注册的完全不一致。请检查 scheme、host、path 以及任何尾部差异。

invalid_client

这通常意味着应用发送了错误的 client ID、该客户端错误的 secret,或者在不同平台间混用了凭证。

origin_mismatch (JavaScript 流程)

页面 origin 未列在 已获授权的 JavaScript 来源 Web 客户端的

启用 Google 登录时,至少需要一个 client id(Supabase、Firebase 及类似 dashboard)

提供商开关已开启,但 Web 客户端 ID 字段为空,或从错误的项目粘贴而来。请在 Google Cloud Console 中创建 OAuth 客户端。使用 Supabase 时,发布这些平台需以逗号分隔列表输入 Web、Android 和 iOS 客户端 ID,并将 Web 客户端 ID 放在最前面。配置好原生客户端后保存。Supabase 搭配 Capacitor 时,请按照 使用 Supabase 配置 Capacitor Social Login.

DEVELOPER_ERROR、错误 10,或 Android 上调试时可登录、生产环境却失败

Android OAuth 客户端缺失,或 包名 / SHA-1 组合与用户所运行 APK 的签名 keystore 不匹配。对于商店构建,请添加 Play App Signing 证书指纹。确认你的插件使用的是 Web 客户端 ID SDK 需要服务器客户端 ID 的位置,详见 Capgo Social Login 文档.

Google Sign-In 在 Web 上正常,但在移动端失败

首先检查客户端类型。Web 凭据无法替代原生流程中的 Android 或 iOS 客户端。

同意屏幕显示异常

在 Google Cloud Console 中验证 OAuth 同意屏幕上的应用名称和品牌信息。

实用的调试顺序很简单: 先检查客户端类型,然后是重定向设置,接着是平台标识符,最后确认流程中是否真的需要 secret.

常见问题

Web 客户端 ID 和 Android 客户端 ID 必须在同一个 Google Cloud 项目中吗?

是的。对于 Android 上的 Google Sign-In,请在同一个 Google Cloud 项目中创建 Android 客户端(包名和 SHA-1)和 Web 应用客户端。应用将 Web 客户端 ID 作为服务器客户端 ID 传递,Google 会检查 Android 客户端是否属于同一项目。不匹配是 DEVELOPER_ERROR 的常见原因。 Capgo 社交登录插件 文档中展示了设置方法。

什么是 Google client ID?

这是 Google 在为您创建应用凭据时分配的公开 OAuth 2.0 标识符。它通常看起来像 123456789012-abcdefg.apps.googleusercontent.com。当您的应用启动 Sign in with Google 或交换授权码以获取令牌时,Google 都会使用它。

在哪里可以找到我的 Google client ID?

在 Google Cloud Console 中,打开 Google Auth Platform &gt; 客户端 或 API 和服务 &gt; 凭据,然后打开您的 OAuth 2.0 客户端。 客户端 ID 字段包含需要复制的完整字符串。

Android 和 iOS 客户端包含 client secret 吗?

通常不需要。已安装的应用是公开的 OAuth 客户端。仅在您控制的服务器上(通常配合使用)使用客户端密钥。 Web 应用 OAuth 客户端。

为什么我的后端提示至少需要一个 client id?

Dashboard 中已启用 Google 登录,但未保存客户端 ID。请在 Google Cloud Console 中创建 OAuth 客户端,并在向用户启用该功能前,至少将 Web 客户端 ID 粘贴到 provider 配置中。

Android 上的 DEVELOPER_ERROR 该如何修复?

使用正确的包名和设备上签名密钥的 SHA-1 注册 Android OAuth 客户端。如果通过 Google Play 分发,请包含 Play App Signing SHA-1。确保 Web 客户端 ID 与您的 auth SDK 预期一致。

我可以在所有平台上复用同一个 Client ID 吗?

不行。请为 Web、Android 和 iOS 分别创建独立的 OAuth 客户端。Capacitor 应用通常都会配置全部三个,即使用户看到的是同一个产品。


如果您的团队发布 Capacitor 或 Electron 应用,auth bug 很少是孤立的。它们通常会和发布压力、回滚需求以及特定环境的修复一起出现。 Capgo 帮助团队向应用 code 和资源发布定向更新,无需等待商店审核,这让登录流程、回调处理和客户端 auth 问题一旦流入生产环境,也能更容易修正。

为 Capacitor 应用提供 Live Updates

当 Web 层出现线上 Bug 时,通过 Capgo 发布修复,而不用等 App Store 审核好几天。用户会在后台收到更新,原生变更则仍走正常审核流程。

博客最新动态

Capgo 为你提供打造真正专业的移动应用所需的最有价值的洞察。