在 Capacitor 应用中实现 OAuth2 的 5 个步骤

想添加安全的 OAuth2 身份验证到你的 Capacitor 应用吗？这份快速指南将助你入门。

OAuth2 是一种让用户无需共享密码就能共享数据访问权限的协议。它非常适合 Capacitor 应用 因为它支持 iOS、Android 和 Web 等跨平台环境。对于社交登录提供商， @capgo/capacitor-social-login 它能通过原生流程处理 Google、Apple 和 Facebook 登录。对于无密码认证， @capgo/capacitor-passkey 它在为你处理原生 passkey 调用时，仍保留浏览器风格的 WebAuthn code。此外，它通过使用 token 而非存储敏感凭据来确保应用安全。

以下是将 OAuth2 集成到你的 Capacitor 应用 只需 5 个步骤：

1. 配置你的 OAuth2 提供商：选择一个提供商（例如 Google、 Auth0), 配置重定向 URI，并安全地管理客户端凭据。
2. 安装并配置 OAuth2 插件：添加 @byteowls/capacitor-oauth2 插件，或使用 @capgo/capacitor-social-login 来处理 Google、Apple 和 Facebook 登录，并配置平台特定设置（例如， Info.plist iOS 版， AndroidManifest.xml Android 版)。
3. 构建身份验证流程：使用插件安全地处理用户登录、token 存储和注销。启用 PKCE 以获得额外保护。
4. 跨平台测试: 在 iOS、Android 和 Web 浏览器上验证流程。修复重定向 URI 不匹配或 PKCE 错误等常见问题。
5. 确保实现安全: 将 token 存入安全存储（Keychain/Keystore），使用 HTTPS，并设置严格的 内容安全策略.

快速对比：安全 Token 存储方案

How to add Google Sign In using Capacitor 其添加到你的 Ionic 应用

第 1 步：设置您的 OAuth2 提供商

正确设置 OAuth2 提供商是确保一切顺利运行的第一步，也是最关键的一步。这包括选择符合应用需求的提供商、配置重定向 URI 等技术细节，以及安全地处理凭据。这些步骤为下一阶段安装 OAuth2 插件铺平了道路。

选择 OAuth2 提供商

首先，选择符合应用功能、安全需求和兼容性的 OAuth2 提供商。你构建的应用类型会决定所用的 OAuth 2.0 流程，这直接影响提供商的选择 [2]。对于基于 Capacitor 的应用，建议使用带 PKCE 的 Authorization Code Flow——这是移动应用的首选方式。

在对比提供商时，请重点关注其安全功能。留意签名 Cookie、CSRF token 校验和加密 JWT 等选项。如果你的应用涉及敏感数据，那么对这类功能的支持 多因素认证 (MFA) 是必须的。评估时，请根据需求权衡成本与功能，不要陷入冗长的对比中。

配置重定向 URI

重定向 URI 非常关键——它们告诉 OAuth2 提供商在用户完成身份验证后把用户送到哪里。正确配置这些 URI 能确保移动端和 Web 端都有流畅的体验。

对于移动应用，请使用自定义 URL scheme，通常格式为： com.example.app://callback，其中 com.example.app 必须与您应用的 package ID 一致。在 Web 端，请使用 window.location.origin 作为重定向 URI。如果您在本地进行测试，使用类似 http://localhost:8100/callback 的 URL 即可。

对于 iOS 用户，请注意 Capacitor 的 Browser plugin 使用的是 SFSafariViewController。在 iOS 11 及更高版本中，它不会与 Safari 共享 cookie，这可能会影响单点登录 (SSO) 功能。如果 SSO 对您至关重要，请考虑使用支持 ASWebAuthenticationSession [3].

管理客户端凭据

的插件。Client credentials 用于向 OAuth2 提供商标识您的应用，由 client ID 和 client secret 组成。您可以将 client ID 视为公开标识符，而 client secret 则应被视为私钥。

切勿将 client secrets 直接硬编码到应用中，或将其提交到版本控制系统中。相反，应使用环境变量或安全的 secrets 管理系统进行存储。此外，建议选择具有最小 scope 的短效 token，以减少暴露风险并增强安全性。

第 2 步：安装并配置 OAuth2 插件

既然您的 OAuth2 提供商已准备就绪，下一步就是将插件添加到您的 Capacitor 应用中，并完成 iOS、Android 和 Web 平台的配置。

安装插件

本指南中介绍的 @byteowls/capacitor-oauth2 该插件支持大多数 OAuth2 提供商。为避免兼容性问题，您需要安装与您的 Capacitor 环境相匹配的版本。

以下是根据您的 Capacitor 版本提供的安装命令：

• Capacitor v5: npm i @byteowls/capacitor-oauth2
• Capacitor v4: npm i @byteowls/capacitor-oauth2@4
• Capacitor v3: npm i @byteowls/capacitor-oauth2@3

安装完成后，请运行 sync 命令 (npx cap sync) 以更新您的原生依赖。这一步对于确保插件正确集成到 iOS 和 Android 项目中至关重要。如果跳过此步骤，在编译移动端平台时可能会导致 build 错误。

配置插件设置

安装完成后，您需要根据 OAuth2 提供商的设置来配置插件。您可以通过 oauth2Options 调用方法时传入的对象 authenticate() 。需要定义的关键参数包括：

• appId：OAuth2 提供商提供的 Client ID。
• authorizationBaseUrl：提供商的授权端点。
• responseType：通常设置为 "code" ，适用于移动端应用。
• redirectUrl：必须与第 1 步中配置的重定向 URL 一致。

你还可以设置其他参数，例如 accessTokenEndpoint, scope，以及用于微调身份验证流程的平台特定选项。

对于 Android，请更新您的 AndroidManifest.xml 以及 strings.xml 文件，填入正确的 scheme 和 host 信息。在 iOS 上，请修改 Info.plist 文件以注册您的重定向 URL scheme。这些平台特定的配置可确保用户在身份验证后能正确跳转回您的 App。

检查 Capacitor 版本兼容性

务必确认插件版本与您的 Capacitor 版本一致。版本不匹配可能会导致 build 错误或运行时问题。 @byteowls/capacitor-oauth2 该插件与 Capacitor 的发布版本严格对齐，因此在继续操作前请务必检查兼容性。

如果你正在进行 iOS 开发，请务必留意 Xcode 的版本要求。使用不兼容的版本会导致 App 构建失败。插件文档中提供了详细的兼容性表格，是排查版本相关问题的绝佳资源。

如果在安装后遇到问题，请卸载当前插件版本，安装与你的 Capacitor 版本相匹配的版本，然后重新运行 sync 命令。这种方法比强行尝试运行不兼容的版本要有效得多。

第 3 步：构建 OAuth2 认证流程

插件配置完成后，就可以开始构建完整的身份验证流程了。这一步将确保用户登录、token 管理和登出的安全性，使你的 App 具备跨平台管理用户会话的能力。

构建登录流程

登录流程从调用以下方法开始： authenticate() 并传入一个 options 对象。该对象应包含你的 authorizationBaseUrl, redirectUrl，以及 responseType 并将其设置为 'code' 以符合 PKCE 要求。该 plugin 会安全地打开服务商的登录页，用户可在其中输入凭据。登录成功后，服务商会将用户重定向回你的 App，并带上 token 和用户信息。

最棒的是：用户直接在 OAuth2 服务商处输入凭据，因此你的 App 始终不会接触到敏感信息。该方法会返回一个 response 对象，其中包含 access token、refresh token 以及邮箱、个人资料等用户数据。

在 iOS 和 Android 上，此过程使用与系统浏览器共享 cookie 的安全 WebView。在 Web 平台上，它依赖标准的浏览器重定向。正确配置 redirect URL 可确保无论哪个平台都有流畅的用户体验。

处理 Token 存储与刷新

用户登录后，安全管理 token 就是你的下一个重点。这包括安全存储 token 并自动刷新，以避免会话中断。你可以这样处理：

• Access Token：将其存储在内存中，以便快速、临时访问。
• Refresh Token：使用安全存储，例如 capacitor-secure-storage plugin，它通过 iOS Keychain 或 Android Keystore 使用 AES-256 加密 token。这样即使设备被攻破，token 仍能受到保护。

应用重启时，检查是否存在已存储的 token，以便让用户无需重新输入凭据即可自动登录。

为了保持会话活跃，请在 refresh token 过期前进行刷新。在发起 API 调用之前，先检查 access token 是否接近过期。如果已接近过期，请使用 refresh token 从你的 OAuth2 提供商处获取新的 access token。为了提高可靠性，建议加入在网络重连时重试刷新 token 的逻辑。如果 refresh token 已过期或被撤销，请引导用户返回登录流程重新进行身份验证。

添加登出功能

安全且有效的登出流程同样重要。首先，通过提供商的 endpoint 撤销 refresh token。然后，清除安全存储中的 token 并重置用户数据，以确保所有会话均已终止。

只删除本地 token 还不够。OAuth2 提供商通常会维护服务端会话，可能自动重新认证用户。撤销 refresh token 会切断与 authorization grant 关联的 token 链，确保已存储的凭据无法被复用。

“JWT Access Token 无法撤销。它们在过期前一直有效。由于它们是 bearer token，无法使其失效。” —— lihua.zhang，Auth0 员工 [5]

要撤销 token，请在清除本地存储前，使用 refresh token 调用提供商的 token revocation endpoint。即使凭据泄露，这种服务端操作也能防止 token 被滥用。撤销后，从安全存储中移除 token，重置缓存的用户数据，并把用户带回登录页。

对于单点登录（SSO）设置，要决定退出登录时是否也结束使用同一提供商的其他应用的会话。另外，把登出请求存到本地，并在连接恢复后重试，确保网络中断时退出登录流程也能顺利进行。这样能确保提供商侧完成妥善清理。

第 4 步：测试 OAuth2 集成

在配置好 OAuth2 并开发完身份验证流程后，下一步就是进行彻底测试。这能确保你的集成在不同设备和平台上的无缝运行，为用户提供可靠的体验。测试包括在移动设备和 Web 浏览器上验证功能，并在应用发布前识别并解决潜在问题。

在 iOS 和 Android 上测试

首先，在 iOS 和 Android 真机上测试整个身份验证流程。

• 针对 iOS: 请确保你的 URL scheme 已在 Info.plist 文件中正确配置，并确认你的应用能妥善处理来自 OAuth2 提供商的重定向。避免使用 WKWebView 进行授权请求，因为这可能导致 disallowed_useragent 错误。相反，应使用 Google Sign-In for iOS 或 OpenID Foundation 的 AppAuth for iOS 等库来高效处理身份验证流程。 [6].

• 针对 Android: 检查你的 AndroidManifest.xml 是否包含正确的 intent filters 以处理重定向 URI。与 iOS 类似，避免使用 android.webkit.WebView 进行授权请求，因为这也会导致 disallowed_useragent 错误。Android 端建议使用 Google Sign-In 或 OpenID AppAuth 等库 [6].

在这两种情况下，都要测试错误场景，例如授权服务器不可用的情况 [7]。如果应用请求多个权限（scopes），请确认哪些已授予，并处理部分权限被拒绝的情况 [6].

在 Web 端测试

对于 Web 平台，请使用开发者工具监控网络请求并确保 token 安全。OAuth 2.0 Playground 等工具可以帮助您测试流程 [10]，而像以下这类 HTTP 拦截代理 ZAP 或 BurpSuite 可以在测试期间提供更深入的洞察 [11].

测试时，请使用带有 PKCE 的 Authorization Code grant，这是针对公共客户端的推荐做法。确保通过 POST 参数或 Header 值安全地传输密钥，而不是使用 URL 参数。此外，还应实现如下安全 Header Referrer-Policy 以增强安全性 [11].

修复常见问题

在测试过程中，你可能会遇到一些需要处理的常见问题：

• 重定向 URI 错误：重定向 URI 不匹配通常会导致“unauthorized client”错误。请确保重定向 URI 在 OAuth2 提供商设置、 capacitor.config.json 你的 Capacitor 应用中的文件，以及原生平台 manifest 中完全一致。

  “SSO 接受的路由需要支持 iosScheme 和 hostname 的组合：ionic://com.myapp.mybundle” —— LBopp [8]

• PKCE 验证错误：请确认 PKCE 已受支持且配置正确，这对保障应用安全至关重要。 [9].

• 插件实现错误：诸如“Plugin is not implemented on iOS”之类的错误，通常意味着配置缺失或 Capacitor 环境中存在问题。在 OAuth2 插件中启用日志，以帮助定位并解决这些问题。 [4].

• State 不匹配错误：如果授权请求中的 state 参数与重定向响应中的不匹配，可能预示着安全风险。在使用 Facebook 等提供商的自定义 OAuth handler 时，这一点尤为重要。请仔细检查你的自定义 handler code，确保没有错误或配置问题。 [4].

第 5 步：确保 OAuth2 实现安全

保护你的 OAuth2 集成对保障敏感数据安全、减少漏洞至关重要。以下是确保你的实现保持安全的关键做法。

启用 PKCE 提升安全性

保护授权流程安全最有效的方式之一，就是启用 PKCE（Proof Key for Code Exchange）。PKCE 有助于防止授权码遭未经授权拦截。其工作原理如下：

• 首先生成一个随机的 code_verifier 长度在 43 到 128 个字符之间。
• 然后，创建一个 code_challenge 通过对 code_verifier 使用 SHA-256 进行哈希，并将结果编码为 base64 URL 格式。

如果您正在使用 capacitor-community/generic-oauth2 对于该 plugin，启用 PKCE 非常简单。以下是配置示例：

{
  responseType: "code",
  pkceEnable: true,
  redirectUrl: "com.companyname.appname:/"
}

该 plugin 会自动处理 PKCE，并且不支持不使用 PKCE 的 Code Flow。该 code_challenge_method 默认设置为 “S256” 以确保正确验证 [12].

使用安全存储存放 Token

安全存储 OAuth2 token 对于防止未经授权的访问至关重要。对于原生移动应用，请利用操作系统提供的安全存储：

• 在 iOS 上，使用 Keychain 来实现硬件级加密和 OS 级保护。
• 在 Android 上，使用 Keystore，它还可以支持 生物识别认证 以增强安全性。

对于 Web 应用，请将 token 存储在 HttpOnly 安全 Cookie 配合 SameSite 属性中，以降低跨站脚本 (XSS) 风险。

以下是安全存储方案的快速对比：

为了提高安全性，建议使用短效 access token 和加密存储。例如，Auth0 将每个应用中每个用户的活跃 refresh token 限制在 200 个以内，以降低风险 [13]。您还可以通过使用 HttpOnly cookie 的 Backend for Frontend (BFF) 代理来增强安全性 [14].

配置内容安全策略

除了安全存储，实施严格的内容安全策略 (CSP) 也有助于保护您的应用免受跨站脚本 (XSS) 和 code 注入等攻击。您可以通过以下方式在服务器端配置 CSP： Content-Security-Policy HTTP header，或者在 HTML 中添加 <meta> 标签。

需要重点关注的核心指令包括：

• default-src：为所有内容类型设置回退规则。
• script-src：控制允许执行哪些 JavaScript 文件。
• connect-src：管理 API 调用和 OAuth2 交互。
• frame-ancestors：通过限制哪些页面可以将您的应用嵌入 iframe 来防止点击劫持。

为了获得最高级别的保护，请使用严格的 nonce 或 hash，而不是宽泛的白名单，并避免使用如下指令： unsafe-inline 或 unsafe-eval。如果您的应用正从 HTTP 过渡到 HTTPS，请考虑添加 upgrade-insecure-requests 指令。为了确保您的 OAuth2 内容无法被嵌入到其他地方，请设置 frame-ancestors 'none'.

总结与后续步骤

核心要点

通过遵循这五个核心步骤，您已成功在 Capacitor 应用中实现了 OAuth2 身份验证。这些步骤包括设置 OAuth2 提供商、安装必要的 plugin、创建身份验证流程、进行跨平台测试，以及使用 PKCE 和正确的 token 存储来保障集成安全性。请务必记住，OAuth 2.0 是一种 授权协议，而非身份验证协议 [1]。它的核心重点在于授予访问权限，而非验证用户身份。

安全性至关重要，对于移动应用尤其如此。与依赖基础身份验证方法的组织相比，使用 OAuth 2.0 的组织在 API 访问安全事件方面减少了 34%。 [19]通过结合最佳实践——例如使用短效 access token、实现 PKCE 以及安全地存储 token——您已为应用的身份验证系统奠定了坚实的基础。

现在，您可以在保持这一安全框架的同时，探索扩展应用功能的方法。

添加更多功能

有了 OAuth2 的支持，您有机会为应用增加更多功能。例如：

• OpenID Connect (OIDC)：通过用户身份验证和单点登录 (SSO) 功能来扩展 OAuth 2.0 [16].
• 多因素身份验证 (MFA): 通过增加一层额外保护来提升安全性 [17].
• 渐进式用户画像: 逐步收集用户数据，以改善 onboarding 和用户体验 [15].

对于持续的维护和更新，可以考虑使用以下工具： Capgo，它让你可以即时推送实时更新、修复和新功能，无需等待应用商店审核。这在处理安全补丁或快速推出新的身份验证功能时尤其有用。

更多资源

要进一步完善你的 OAuth2 实现，可以利用以下资源和策略：

• API 网关安全: 通过实施身份验证和授权措施、缓存以及可靠的日志记录与分析来强化部署 [20].

• Aaron Parecki 的建议: 根据《OAuth 2.0 Simplified》作者 Aaron Parecki 的观点 OAuth 2.0 简化指南:

  “Authorization Code 流程是 OAuth 2.0 各流程中最安全的，服务端应用应尽可能使用它” [18].

以下是快速参考表，帮你规划下一步：

通过定期进行安全审计并保持实现方案的更新来保持领先。例如，OAuth 2.1 引入了多项改进，如要求所有授权 code 请求都必须使用 PKCE，并淘汰了安全性较低的流程 [19]。此外，Capacitor 文档和 OAuth2 插件仓库也提供持续的技术支持，帮助您维护并优化应用的身份验证系统。

常见问题

::: 常见问题

为什么在移动应用中使用 OAuth2 时，应该选择带 PKCE 的授权 Code 流程？

为什么移动应用要使用带 PKCE 的授权 Code 流程？

本指南中介绍的 带 PKCE 的授权 Code 流程 是移动应用的理想选择，因为它通过应对授权 code 拦截和中间人攻击等风险来提升安全性。PKCE（用于 Code 交换的证明密钥）通过增加一层额外的保护来发挥作用：它需要一个由授权服务器验证的唯一 code 挑战。这确保了只有预期的应用才能完成身份验证过程。

移动应用被归类为公共客户端，无法安全地存储 client secrets。这正是 PKCE 的用武之地——它允许您在不暴露敏感数据的情况下安全地验证用户。结果如何？一个更安全、更可靠的登录流程，从而提升整体用户体验。 :::

::: 常见问题

在 iOS、Android 和 Web 应用中，安全存储 OAuth2 token 的最佳方式是什么？

为了在不同平台间安全地存储 OAuth2 token，必须使用 针对各平台定制的安全存储方案。对于 iOS，首选方案是 Keychain Services；而 Android 用户则应依赖 Android Keystore 系统。这些工具专为保护包括 token 在内的敏感数据而设计。在 Web 端，使用 secure cookies 或加密的浏览器存储也是有效的替代方案。

引入 AES-256 等加密算法可以为 token 提供额外的安全保障。通过使用 短效 token 并在需要时进行安全刷新，可以进一步降低风险。在 OAuth2 流程中实现 PKCE (Code 交换证明密钥) 是防止未经授权访问的另一种明智做法。为了获得更强的保护，可以考虑集成生物识别身份验证，确保只有合法用户才能访问存储的 token。 :::

::: 常见问题

在 Capacitor 应用中测试 OAuth2 集成时，最常见的问题有哪些？该如何解决？

在 Capacitor 应用中测试 OAuth2 集成时，开发者可能会遇到一些常见的障碍。以下是需要注意的要点：

• 无效的 Client Credentials：请确保您的 Client ID 和 Secret 配置正确，并与 OAuth 提供商中的配置信息一致。哪怕是一个微小的拼写错误都可能导致问题。
• Redirect URI 不匹配：应用中的 Redirect URI 必须与 OAuth 提供商中注册的 URI 完全一致。请务必仔细检查，以免产生不必要的麻烦。
• Token 过期：Token 不会永久有效。请建立一套可靠的 Token 刷新机制，以平滑处理过期 Token，确保用户体验不中断。
• Scope 配置错误：应用中请求的 Scope 需要与 OAuth 提供商中配置的 Scope 保持一致。Scope 不匹配可能会导致意料之外的错误。

要解决这些问题，请花时间彻底检查应用的 OAuth 设置。实现完善的错误处理机制，以便及早发现并解决问题，并在不同场景下测试您的身份验证流程。使用 Capgo 等工具可以让开发变得更轻松，您可以直接向应用推送更新和修复，无需等待应用商店审核，从而保持高效开发并提升用户满意度。 :::

继续阅读：在 Capacitor 应用中实现 OAuth2 的 5 个步骤

如果你正在使用 在 Capacitor 应用中实现 OAuth2 的 5 个步骤 来规划安全与合规，请结合 加密 了解 Encryption 的实现细节， 合规性 了解合规部分的实现细节， Capgo 安全扫描器 了解 Capgo Security Scanner 的产品工作流， Capgo 安全 用于 Capgo 安全的产品工作流，以及 Capgo 信任中心 用于 Capgo 信任中心的产品工作流。