您可能是因为 Google Sign-In 应该是一个快速的集成，结果您却在凭据屏幕上发愁，为什么一个应用类型会给您一个客户密钥，而另一个却不会。这种困惑是正常的，尤其是当您正在使用 Capacitor、Ionic、Electron 或混合的 web 和本机堆栈时。
大多数教程都忽略了最关键的部分： Google 客户 ID 是平台特有的,并且非 web 应用类型通常 不 会
获得客户密钥。创建错误的凭据只是为了强制一个秘密进入流程，通常会导致一个更难调试的 OAuth 设置。
连接到 Google 生态系统
许多团队在同一时间遇到这个问题。他们需要 使用 Google 登录, 或者他们想要对某些东西（如Drive或日历）进行用户批准的访问，而一个 API 键 suddenly 不再足够。
,或者他们想要用户批准的访问某些东西，如 Drive 或 Calendar，一个 __CAPGO_KEEP_0__ key suddenly stops being enough. 您的应用API 的凭证。 ,而不是被称为的 __CAPGO_KEEP_0__。鉴于此的凭证是.
Google Client ID
OAuth 实践设置通常涉及几个实现问题：
- 一个实际的 OAuth 设置通常会归结为几个实现问题：
- 无论您需要客户端密钥
- 哪些重定向 URI 或起源必须完全匹配
- 如何在不混淆凭据的情况下将移动和 web 流程连接起来
- 为什么在浏览器中工作的流程在原生包装器中失败
实用规则： 如果您的应用程序要求用户权限或登录，请先以 OAuth 客户端类型思考，而不是 API 键。
这种区别会节省早期的时间。它还可以防止构建一个基于 web 凭据的移动登录流程的常见错误，因为控制台显示了更多的字段。如果您正在在 Capacitor 应用程序中实现此功能，则有关 在 Capacitor 应用程序中的 OAuth2 的指南是应用程序侧流程的有用伴侣。
什么是 Google 客户端 ID
一个 Google OAuth 2.0 客户端 ID 是 Google 认证系统中的应用程序的公共标识符。 Google 将其描述为在请求 Google 认证端点时向 Google 认证端点请求访问令牌时应用程序的唯一用户名，并指出它与 API 密钥不同，因为它用于 OAuth 流程中验证应用程序身份以交换令牌，正如 Google Cloud 的 OAuth 客户端文档中所解释的那样。 Google Cloud 的 OAuth 客户端文档.
简单的认知模型
想象一下 Google 客户端 ID 为您的应用程序 公共用户名.
它告诉 Google，“这次请求来自已注册的应用程序。”在登录、同意、令牌交换和任何流程中，您的应用程序要求代表用户行动时，这很重要。客户端 ID 旨在由您的应用程序和 Google 认证服务器引用。
人们容易混淆的是，这个凭证位于两个概念旁边，它们是不可互换的。
客户端 ID 用于 OAuth 中应用程序的标识
API 密钥 API
客户端密钥 是用於安全的流程和應用類型的機密對等項。
很多的破坏性整合都是因为有人把这些东西当作同一种东西来处理。它们不是。
在实践中，Google客户端ID的作用
如果您需要 使用 Google 登录 或 Google ID是用於啟動驗證握手的前端值。Google 的文件還指出，應用程式必須在專用 Cloud Console 項目中註冊，才能生成憑據，且 Web 應用程式需要配置授權的 JavaScript 原始碼或重定向 URI，包括完整的方案和主機名稱。
因此，設定過程比生成簡單密鑰更嚴格。Google 不僅僅是啟用訪問，它還將驗證請求綁定到已知應用程式身份。
对于构建混合应用的团队来说，最安全的认知模型是这样的:
- 使用客户端 ID来识别应用
- 使用同意屏幕来代表应用给用户
- 使用正确的应用类型来确定是否将密钥放入流程中
如果您想了解应用身份和委托访问如何结合在一起的更广泛的概述 应用授权指南 创建和查看您的客户端 ID
如何创建和查看您的客户端 ID
Google Auth Platform > Clients 路径和旧的 APIs & Services > Credentials 如何创建和查看您的客户端 ID 路径，详见 Google的设置文档.
从正确的控制台区域开始
打开Google Cloud控制台并选择或创建将拥有认证配置的项目。不要将认证分散到随机的项目中。稍后会使审计和支持更加痛苦。
从那里，去以下任何地方：
- Google身份平台>客户
- APIs & Services>凭证
如果您的团队看到不同的导航标签，这是正常的。Google已经将身份设置与API凭证表面其他部分分开。
创建凭证而不被限制
当您创建新OAuth客户端时，最大决策是 应用程序类型Google要求您选择一个具体的类型，如 Web, Android, iOS或 Desktop. 这个选择并非是外观上的选择，它定义了应用程序的识别方式以及所需的支持配置。
对于一个Web应用程序，预计您需要输入:
- 授权的JavaScript源
- 授权的重定向URI
这些值必须是精确的。对于一个Web凭证，Google期望完整的方案和主机名，如 https://www.example.com,而不是一个松散的域概念。
对于移动平台，形状是不同的。Android注册需要包级别身份和所有权验证，而iOS使用自己的平台标识符。如果您正在结合Google认证与另一个认证层, 这是一个使用Supabase的Capacitor社交登录设置的有用例子，展示了这些部分如何经常合并在一起。 如果您想比较UI并在点击时查看，这个教程是一个不错的可视化参考：
在哪里找到它
创建后，客户端ID会出现在项目的凭证列表中。同样的项目空间也是团队启用API和查看OAuth身份如何连接到同意屏幕的地方。注册应用程序的名称是用户在权限提示中看到的，这就是为什么准确命名应用程序很重要的原因。
Google会在长期内管理这些凭证。您可以返回到控制台来复制客户端ID、查看设置，并在适用时管理与该凭证相关的客户端密钥。
同意屏幕不是装饰。它是信任边界的一部分。用户在那里看到的应用程序名称，而不是内部项目的昵称。
平台特定的客户端ID配置
平台特定客户端 ID 配置
这个平台设置参考中提到 本地开发环境设置指南.
為什麼一個應用程式需要多個客戶端 ID
您的产品可能是用户看到的单个应用，但是在 Google 的 OAuth 客户端中，它是多个客户端。
A web 应用, an 安卓构建, an iOS 构建和一个 桌面应用 don’t present the same security properties. They don’t prove identity in the same way, and they don’t all store credentials in a trustworthy environment.
Google handles that by giving each platform its own app registration model.
以下是实用的分离方案：
- Web 使用 Web 客户端 ID 和严格的源和重定向 URI 匹配。
- Android 使用与包标识和 SHA1 指纹相关的 Android 客户端 ID。
- iOS 使用与应用程序包标识相关的 iOS 客户端 ID。
- 桌面或 Electron 通常使用安装或桌面式 OAuth 模式而不是基于秘密的浏览器流。
Google 客户端 ID 类型比较
| 应用程序类型 | 主要标识符 | 是否提供客户端密钥? | 关键用例 |
|---|---|---|---|
| Web | 授权的JavaScript源和重定向URI | 通常是的 | 浏览器应用和后端辅助Web OAuth |
| Android | 包标识符加SHA1指纹 | 通常不是 | 原生Android登录 |
| iOS | 应用程序包标识符 | 常常没有 | 原生iPhone和iPad登录 |
| 台式机 | 已安装应用程序身份 | 常常没有 | 桌面应用程序，包括Electron风格的原生流程 |
移动和台式机开发者常常期望每个OAuth客户端都带有一个
客户端ID
和一个 客户端密钥 客户端密钥的悖论 这就是许多教程所犯的错误然后他们创建一个 Web 应用 因为只有这样他们才能在控制台中看到一个秘密。流程看起来更完整，所以他们继续。后来，身份验证在令人困惑的方式中出现了问题。
根据 这个关于移动凭证不匹配的说明,非Web应用类型，如Android、iOS和安装程序通常会接收一个客户端ID，但没有客户端密钥的故意，因为Google不希望在客户端软件中嵌入一个机密的密钥，用户可以从中提取它。
这个设计选择是正确的。一个移动应用程序或Electron捆绑包不是一个安全的密钥存储器。
什么有效: 为公众客户端设计的原生或客户端OAuth流程。
什么无效: 为移动应用程序创建一个Web凭证，只是为了强制实施一个密钥到实现中。
对于Capacitor团队，这通常会在两个糟糕的模式中出现:
- 使用一个 web客户端 然后尝试像一个保密服务器一样行为。
- 应用程序发送一个 客户端密钥 从捆绑的code,这实际上破坏了密钥的保密性。
更好的方法是将移动和桌面应用程序视为 公共客户端.在现代OAuth中，这通常意味着使用不依赖于客户端内置密钥的流程。如果您的后端参与了，保持保密操作在后端，native应用程序仅限于公共客户端应该做的事情。
另一个细微差别对于Firebase-backed Android sign-in很重要。在这种设置中， web应用程序类型客户端ID 被用作后端服务器的OAuth客户端ID，而Android应用程序则保留自己的平台特定身份。这种分离会让团队感到困惑，因为他们会看到同一个项目中同时存在一个web凭证和一个移动凭证，认为它们互相替代。它们并不互相替代。它们各自扮演不同的角色。
如果你记住一个规则，那就是： 选择与code运行的客户端类型相匹配，而不是你希望拥有的凭据形状.
保护您的GoogleAPI凭据
大多数OAuth事件并不是由复杂的攻击引起的。团队泄露凭据、过度设置重定向设置或将机密放入不安全的地方
Google的OAuth指南强调，客户端ID和机密应该被视为私有数据，针对web应用程序，客户端ID会被强制与预注册的重定向URI进行匹配。如果重定向URI不严格匹配，Google会拒绝请求。该源绑定是保护令牌劫持的部分，正如在 OAuth.com的客户端注册指南.
立即锁定什么
如果你只做几件事正确，那就是这些：
- 不要将客户端机密在应用程序code中发送 Web包、移动二进制文件和Electron包都是可由用户检查的
- 注册准确的重定向URI 足够的并非足够。Google 验证严格匹配的 Web 流程。
- 保持源头紧凑。 不要仅为了减少设置阻力而授权广泛的域名。
- 分离平台凭据。 不要让便利性将 Android、iOS 和 Web 凭据合并为一个凭据。
一个操作细节容易被忽略。Google 允许团队为现有客户 ID 生成新密钥并禁用旧密钥。这在密钥被泄露时或您正在优化部署流程时很重要。
安全团队的实际做法
那些避免麻烦的团队对 OAuth 凭据的处理与对其他生产密钥的处理一样严格。
它们将 Web 客户端密钥保留在后端，通过环境管理注入它们，并审计谁有控制台访问权限。如果您正在清理发布管道，这篇关于 在 CI/CD 管道中管理密钥的指南 也值得应用到您的认证设置中。
它们还审计元数据，而不是仅仅审计密钥。OAuth 同意屏幕与用户看到的客户端标识相关联。如果应用名称模糊或误导性，用户更有可能不信任提示或批准错误应用。
安全性不仅仅是隐藏一个秘密。它还包括确保每次应用程序身份、重定向目标和批准屏幕都准确匹配。
常见的客户端 ID 错误排查
大多数 Google OAuth 失败都是由于设置错误引起的。错误信息可能不友好，但一旦你知道哪里去找问题，问题通常是很直接的。
解决大多数故障的修复
redirect_uri_mismatch
您的应用程序发送的重定向 URI 与注册的 Web 客户端不完全匹配。检查方案、主机、路径和任何尾随差异。对于 Web OAuth，精确匹配是安全模型的一部分。
invalid_client
这通常意味着应用程序发送了错误的客户端 ID、错误的密钥或在不同平台之间混合了凭据。常见的例子是 Android 或 iOS 流程意外使用了 Web 凭据的错误位置。
invalid_request
这一个问题很广泛，但在跨平台应用中，它经常指向 malformed auth 参数或流程不符合客户端类型。检查应用程序是否尝试在不应该的地方包含密钥，或者所选的 OAuth 流程是否期望不同的客户端类型。
Google Sign-In 在 Web 上工作但在移动设备上失败
首先要检查的是客户端类型。移动开发人员最常见的错误来源是创建一个 Web 应用程序客户端 ID 只为了获取客户端密钥，而实际上应该使用 Android 或 iOS 类型，这些类型通常省略密钥，正如在 这个客户端密钥不匹配的分解. 如果您的实现包含在登录后进行令牌生命周期工作，则该注销指南也很有用。
Android 登录失败后凭据创建
双重检查 Android 客户端附加的 SHA1 FingerPrint。如果签名身份与 Google 期望不符，应用程序就无法正确证明所有权。
Consent 屏幕看起来不正确
验证在控制台中设置的 OAuth 配置中的应用程序名称和品牌。用户授权的是他们在那里看到的内容，因此错误的元数据会导致信任问题和支持噪音。
实践调试顺序很简单： 首先检查客户端类型，然后检查重定向设置，接着检查平台标识符，最后检查是否在流程中需要密钥.
如果您的团队部署 Electron 应用程序或 Capacitor，认证错误很少会孤立。它们通常会在发布压力、回滚需求和环境特定修复中出现。 Capgo 帮助团队在不等待商店审核的情况下将目标更新推送到应用程序 code 和资产，使得更容易修复登录流程、回调处理和客户端认证问题。
