你可能会来这里，因为Google Sign-In应该是一个快速的集成，但你却在一个凭证屏幕上徘徊，困惑于为什么一个应用类型会给你一个客户端密钥，而另一个却不会。这种困惑是正常的，尤其是当你使用Capacitor、Ionic、Electron或混合的web和native堆栈时。
最常被指南忽略的部分是破坏真正实现的东西： Google Client IDs 是平台相关的, 并且非 web 应用类型通常 不 通过设计就不会获得客户端密钥。如果您创建错误的凭证仅为了强制秘密进入流程，通常会导致 OAuth 配置出现问题，难以调试。
目录
连接您的应用到Google生态系统
许多团队在同一时间遇到这个问题。他们需要 使用 Google 登录, 或者他们想要对某些东西如 Drive 或 Calendar 的用户批准访问，而一个 API 键 suddenly 不再足够。
因为用户登录和委托访问通过 OAuth 运行。 Google 需要一种方法来识别 你的应用, 不仅仅是被调用的 API 。 那个识别应用的凭证是 Google Client ID.
如果你在一个跨平台的代码库中工作，混淆会迅速加剧。 你可能有一个 web 前端，一个 Android 外壳，一个 iOS 应用，和可能的 Electron 构建用于桌面。 他们可能共享产品品牌和后端逻辑，但他们不应该共享一个 OAuth 身份。
一个实际的 OAuth 设置通常会归结为几个实现问题：
- 你应该创建哪种应用类型
- 是否需要一个客户端密钥
- 哪些重定向 URI 或起源必须完全匹配
- 如何在不混淆凭证的情况下连接移动和 web 流程
- 为什么在浏览器中工作的流程在原生包装器中会失败
实用规则： 如果您的应用程序要求用户权限或登录，请先考虑OAuth客户端类型，而不是API密钥。
这种区分可以节省早期时间。它还可以防止常见的错误，即在控制台显示更多字段时，仅仅因为它是基于Web凭证而构建一个移动登录流程。如果您正在在Capacitor应用程序中实现此功能，则有关 在Capacitor应用程序中的OAuth2 的指南是应用程序侧流程的有用附件。
什么是Google Client ID
A Google OAuth 2.0客户端ID是Google身份验证系统中的应用程序的公共标识符。Google将其描述为在请求Google身份验证端点时向Google访问令牌的唯一用户名，并指出它与__CAPGO_KEEP_0__密钥不同，因为它用于OAuth流程中验证应用程序身份以交换令牌，正如 is the public identifier for your application in Google’s auth system. Google describes it as the unique username for an application when requesting access tokens from Google authentication endpoints, and notes that it’s distinct from API keys because it’s used in OAuth flows to verify the app’s identity during token exchange, as explained in 中所述的那样。.
简易的心理模型
考虑到Capgo的开发者 客户端 ID Google 应用中的问题 公共用户名.
在登录、同意、令牌交换以及任何流程中，用户授权应用程序操作用户账户时，应用程序会告诉 Google，“这个请求来自这个已注册的应用程序。”这很重要。客户端 ID 应该被应用程序和 Google 的认证服务器都引用。
是什么让人们感到困惑的是，这个凭证位于两个彼此不可互换的概念旁边。
客户端 ID 在 OAuth 中，用于标识应用的信息。
API 键 识别某些不涉及委托用户授权的API调用所对应的项目。
客户端密钥 是用来在可以安全保留机密信息的流程和应用类型中使用的机密对等体。
很多破碎的集成都是因为有人把这些东西当作同一种东西来处理的。它们不是的。
在实践中，Google客户端ID的位置
如果您需要 使用Google登录 或 一键登录,
,
,
- ,
- ,
- 使用正确的应用类型来确定一个密钥是否属于流程
如果您想了解应用身份和委派访问的更多信息，请参阅 应用授权指南 这是一个很好的复习资料。
如何创建和查看您的客户 ID
控制台路径已经发生了变化，开发者经常认为自己在错误的地方。他们通常不是。Google目前暴露了两个导航路线来显示这些凭据：新的 Google Auth Platform > Clients 路径和旧的 APIs & Services > Credentials 路径，正如 Google 设置文档.
在正确的控制台区域开始
打开 Google Cloud 控制台，选择或创建将拥有认证配置的项目。不要将认证分散到随机的项目中。这样做会使后期的审计和支持变得痛苦。
从那里，前往以下任何一个地方：
- Google 身份验证平台 > 客户
- APIs & Services > 凭据
如果您的团队看到不同的导航标签，这是预期的。Google 已经将身份设置与其他API凭据表面分开。
创建凭据而不限制自己
当您创建新 OAuth 客户端时，最大决策是 应用程序类型. Google 会要求您选择特定的类型，如 Web, Android, iOS, 或 Desktop. 这个选择并非是外观上的问题。它决定了应用程序的识别方式以及所需的支持配置。
对于一个网页应用，预计需要输入：
- 授权的 JavaScript 源
- 授权的重定向 URI
这些值必须是精确的。对于一个网页凭证，Google 期望完整的方案和主机名，例如 https://www.example.com,而不是一个松散的域概念。
对于移动平台，形状是不同的。Android 注册需要包级别的身份和所有权验证，而 iOS 使用自己的平台标识符。如果您正在结合 Google 认证与另一个认证层， 这个 Capacitor 社交登录设置与 Supabase 是这些部分如何常常结合在一起的有用例子。
如果您想在点击浏览时比较 UI 的话，这个教程是一个不错的视觉参考。
稍后在哪里找到它
创建后，客户 ID 将出现在项目的凭据列表中。同样的项目空间也是团队启用 API 和查看 OAuth 身份如何连接到同意屏幕的地方。注册应用程序的名称是用户在权限提示中看到的，这是为什么准确命名应用程序很重要的一个原因。
Google 会在长期内对这些凭据进行管理。您可以返回到控制台来复制客户 ID、查看设置，并在适用时管理与该凭据相关的客户机密。
同意屏幕并不是装饰。它是信任边界的一部分。用户在那里看到的是您的应用程序名称，而不是您的内部项目昵称。
平台特定的客户端 ID 配置
破坏 Google 登录设置的最快方法是假设一个客户端 ID 可以覆盖所有平台。它不能。 对于多平台应用程序，每个平台必须注册自己的独特 OAuth 2.0 客户端 ID，并且 Android 设置特别需要 SHA1 指纹来验证所有权，正如.
为什么一个应用程序需要多个客户端 ID
您的产品可能是用户看到的一个应用程序，但它是多个 OAuth 客户端给 Google。
A web app, an 安卓构建, an iOS构建, 和一个 桌面应用 它们不表现出相同的安全性特性。它们不证明身份的方式相同，而且它们不存储凭证的可信环境中。Google通过为每个平台提供自己的应用注册模型来处理这一点。
这种分离是好的安全卫生习惯。如果一个平台的凭证设置被破坏或配置不当，其他平台不会自动暴露。
以下是实用的分离方案：
- Web 使用Web客户端ID和严格的源和重定向URI匹配。
- 安卓 使用一个与包标识和SHA1指纹相关联的Android客户端ID。
- iOS 使用一个与应用程序包标识相关联的iOS客户端ID。
- 桌面或Electron 通常使用安装或桌面样式的OAuth模式，而不是基于秘密的浏览器流程。
Google Client ID类型比较
| 应用程序类型 | 主要标识符 | 是否提供客户端密钥? | 关键用例 |
|---|---|---|---|
| Web | 授权JavaScript源和重定向URI | 通常是的 | 浏览器应用和后端辅助Web OAuth |
| 安卓 | 包标识符加SHA1指纹 | 通常不是 | 原生安卓登录 |
| iOS | 应用程序包标识符 | 通常不是 | 原生iPhone和iPad登录 |
| 桌面 | 已安装应用程序标识符 | 常常没有 | 桌面应用程序，包括Electron风格的本机流 |
移动和桌面应用程序的客户端秘密悖论
很多教程都在这里犯错。
移动和桌面开发人员经常期望每个OAuth客户端都带有一个 客户ID 和一个 客户端秘密。然后他们创建一个 Web应用程序 凭证，因为他们只能在控制台中看到一个秘密。流程看起来更完整，所以他们继续前进。后来，身份验证会以令人困惑的方式中断。
根据 移动凭证不匹配的说明, 非Web应用类型，如Android、iOS和安装程序，通常会接收到客户端ID，但不接收客户端密钥，这是因为Google不希望在客户端软件中嵌入一个保密的密钥，用户可以从中提取它。
这种设计选择是正确的。移动应用或Electron包不是安全的密钥存储。
有效的解决方案: 针对公共客户端的本机或客户端OAuth流程。
不起作用的解决方案: 为移动应用创建一个Web凭证，只是为了强制实施一个密钥到实现中。
对于Capacitor团队，这通常会出现在两个糟糕的模式中:
- 应用程序启动一个基于浏览器的流程，使用一个 web客户端 然后尝试像保密服务器一样行为。
- 应用程序发送一个 client secret 从打包的 code 中，破坏了使用机密的目的。
更好的方法是将移动和桌面应用程序视为 公共客户端。在现代 OAuth 中，这通常意味着使用不依赖于客户端中隐藏的机密的流程。如果您的后端涉及，请在后端保留机密操作，并将本机应用程序限制为公共客户端应执行的操作。
另一个细微点对于 Firebase 支持的 Android 登录很重要。在这种设置中， web 应用程序类型客户端 ID 用于后端服务器的 OAuth 客户端 ID，而 Android 应用程序保留自己的平台特定身份。这种分离会使团队困惑，因为他们会看到同一个项目中一个 web 凭证和一个移动凭证，并假设一个取代了另一个。它并没有。它们服务于不同的角色。
如果您记住一个规则，请使用这个： 选择与 code 运行的客户端类型匹配，而不是您希望拥有的凭证形状.
Google API 凭证安全
大多数 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 pipeline 中管理密钥的指南 也值得应用到您的身份验证设置中。
他们还会审查元数据，而不是仅仅关注密钥。OAuthConsent 屏幕与用户看到的客户端身份相关。如果应用名称模糊或误导性，用户更有可能不信任提示或批准错误的应用。
安全不仅仅是隐藏一个密钥。它还要确保每次都有正确的应用身份、重定向目标和批准屏幕。
常见的客户 ID 错误排查
大多数 Google OAuth 失败都是由于设置错误引起的。错误文本可能不友好，但一旦您知道哪里看，问题通常是简单的。
解决大多数失败的修复
redirect_uri_mismatch
您的应用程序正在发送一个不完全匹配已注册的 Web 客户端的重定向 URI。检查方案、主机、路径和任何尾随差异。对于 Web OAuth，精确匹配是安全模型的一部分。
invalid_client
这通常意味着应用程序发送了错误的客户端 ID、错误的客户端密钥或混合了不同平台的凭据。一个常见的例子是 Android 或 iOS 流程意外地在错误的地方使用 Web 凭据。
invalid_request
这一个很宽泛，但在跨平台应用中经常指向的是不良的认证参数或不适合客户端类型的流程。检查应用程序是否试图在不应该的地方包含密钥，还是所选的 OAuth 流程期望的客户端类型不同。
Google Sign-In 在 Web 上工作但在移动设备上失败
首先要检查的是客户端类型。移动开发人员最常见的错误来源是创建一个 Web 应用程序客户端 ID 只为了获取客户端密钥，而实际上应该使用 Android 或 iOS 类型的客户端，这些类型通常会故意省略密钥，如 中解释的那样。如果您的实现包含在登录后进行令牌生命周期工作，那么该令牌撤销指南也是很有用的。
Android 登录失败后创建凭据
双重检查 Android 客户端附加的 SHA1 指纹。如果签名身份不匹配 Google 期望的，那么应用程序就无法正确证明所有权。
Consent 屏幕看起来不正确
验证应用程序名称和与控制台 OAuth 设置相关的品牌信息。用户授权的是他们在那里看到的内容，因此错误的元数据会导致信任问题和支持噪音。
调试顺序很简单： 首先检查客户端类型，然后检查重定向设置，接着检查平台标识符，最后检查是否在流程中需要一个密钥.
如果您的团队部署 Capacitor 或 Electron 应用程序，授权错误很少会孤立。它们通常会在发布压力、回滚需求和环境特定修复中出现。 Capgo 帮助团队在不等待商店审核的情况下将针对性的更新推送到应用程序 code 和资产，这使得更容易修复登录流程、回调处理和客户端授权问题。
