5 步实现 OAuth2 在 Capacitor 应用程序中

想为您的__CAPGO_KEEP_0__应用添加安全的 OAuth2 认证？以下快速指南将帮助您开始。 Capacitor __CAPGO_KEEP_0__应用

__CAPGO_KEEP_0__ Capacitor apps 因为它可以在 iOS、Android 和 web 平台上工作。对于社交提供商, @capgo/capacitor 社交登录 处理 Google、Apple 和 Facebook 登录的原生流程。对于无密码认证, @capgo/capacitor-passkey 保持浏览器样式的 WebAuthn code ，同时原生 passkey 调用会被处理。另外，它通过使用令牌而不是存储敏感凭证来保持应用程序的安全。

以下是如何将 OAuth2 集成到您的 Capacitor 应用程序 上述步骤：

1. 设置 OAuth2 提供商: 选择提供商（例如 Google, Auth0），配置重定向 URI，并安全地管理客户端凭证。
2. 安装和配置 OAuth2 插件: 添加 @byteowls/capacitor-oauth2 插件，或者使用 @capgo/capacitor-社交登录 为 Google、Apple 和 Facebook，设置平台特定的设置（例如， Info.plist 对于 iOS， AndroidManifest.xml 对于 Android）。
3. 构建身份验证流程: 使用插件处理用户登录、令牌存储和安全注销。启用 PKCE 以获得额外的保护。
4. 在多个平台上进行测试: 验证流程在 iOS、Android 和 Web 浏览器中。修复常见问题，如重定向 URI 匹配错误或 PKCE 错误。
5. Secure Your Implementation: 在安全存储中存储令牌（如 Keychain/Keystore），使用 HTTPS，并设置强大的 内容安全策略.

快速比较：安全令牌存储选项

如何使用Google Sign In Capacitor 到您的 Ionic 应用

步骤1：设置您的 OAuth2 服务提供商

正确配置 OAuth2 服务提供商是实现 OAuth2 的第一步和最关键的步骤。它涉及选择与您的应用程序要求相匹配的提供商、配置技术细节，如重定向 URI、并安全地处理您的凭据。这些步骤为接下来安装 OAuth2 插件做好准备。

选择 OAuth2 服务提供商

首先选择一个与您的应用程序功能、安全需求和兼容性相匹配的 OAuth2 服务提供商。您正在构建的应用程序类型对确定使用的 OAuth 2.0 流程至关重要，这直接影响您的提供商选择。 [2]对于 Capacitor-基于的应用程序，建议使用 Authorization Code 流程与 PKCE - 这是移动应用程序的首选方法。

比较服务提供商时，应重点关注其安全功能。寻找像签名 cookie、CSRF token 验证和加密 JWT 等选项。如果您的应用程序处理敏感数据，则支持多因素认证是必不可少的。在评估时，应平衡成本和功能，根据您的需求而定，不要被繁琐的比较所困扰。 配置重定向 URI 重定向 URI 至关重要，它们告诉 OAuth2 服务提供商在用户完成身份验证后应该将用户发送到哪里。正确配置这些 URI 确保在移动和 web 平台上实现无缝体验。

对于移动应用程序，请使用自定义 URL 方案，通常以以下格式

，其中

__CAPGO_KEEP_0__ com.example.app://callback, where com.example.app 与您的应用程序包 ID 匹配。 在 Web 上，使用 window.location.origin 作为重定向 URI。 如果您正在测试本地环境，类似于 http://localhost:8100/callback 的 URL 很好。

对于 iOS 用户，请记住 Capacitor 的浏览器插件使用 SFSafariViewController。 在 iOS 11 和更高版本中，这不会与 Safari 共享 cookie，这可能会影响单点登录功能。 如果 SSO 是必需的，请考虑使用支持 ASWebAuthenticationSession [3].

管理客户端凭证

客户端凭证标识您的应用程序并由 OAuth2 提供商识别，包括客户端 ID 和客户端密钥。 想象客户端 ID 为公共标识符，而客户端密钥应像私钥一样处理。

不要将客户端密钥硬编码到您的应用程序中或提交到版本控制。 相反，使用环境变量或安全密钥管理系统来存储它们。 另外，优先选择短期令牌和最小权限以限制暴露并提高安全性。

步骤 2：安装和配置 OAuth2 插件

Now that your OAuth2 provider is ready, the next step is to add the plugin to your Capacitor app and set it up for iOS, Android, and web platforms.

安装插件

The @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

安装完成后，请运行同步命令（npx cap sync）来更新本机依赖项。这个步骤对于确保插件正确与iOS和Android项目集成至关重要。如果您跳过这个步骤，编译移动平台时可能会出现构建错误。

配置插件设置

安装后，您需要配置插件以匹配OAuth2提供商的设置。这可以通过在调用 oauth2Options 对象中进行 authenticate() 步骤。需要定义的关键参数包括:

• appId: OAuth2 服务提供商的客户端 ID。
• authorizationBaseUrl: OAuth2 服务提供商的授权端点。
• responseType: 通常设置为 "code" 适用于移动应用。
• redirectUrl: 必须与步骤 1 中配置的重定向 URL 匹配。

您还可以设置其他参数，如 accessTokenEndpoint, scope,以及针对特定平台的选项，以微调身份验证过程。

对于 Android，更新您的 AndroidManifest.xml 和 strings.xml 文件中使用正确的方案和主机信息。对于 iOS，修改 Info.plist 文件以注册您的重定向 URL 方案。这些平台特定的更改确保用户在身份验证后会被重定向回您的应用。

Check Capacitor Version Compatibility

确保插件版本与您的Capacitor版本匹配是非常重要的。版本不匹配可能会导致编译错误或运行时问题。 @byteowls/capacitor-oauth2 Capacitor 的插件严格遵循 Capacitor 的发布版本，因此在进行操作之前，请务必检查兼容性。

如果您正在开发 iOS 应用，请注意 Xcode 版本要求。使用不兼容的版本将阻止您的应用成功构建。插件文档包含详细的兼容性表格，这些表格是解决版本相关问题的宝贵资源。

如果您在安装后遇到问题，请卸载当前插件版本，安装适合您的 Capacitor 版本的正确插件，并再次运行同步命令。这比尝试强制不兼容版本工作更有效。

步骤 3：构建 OAuth2 认证流程

上下文：关于 Capgo 页面。角色：UI 标签。见于：关于 .astro 页面。消息键 `about_how_step_label` (关于如何步骤标签)。

设置好插件后，时刻准备好创建一个功能齐全的认证流程。这一步确保了安全的用户登录、令牌管理和注销，使您的应用能够在多个平台上管理用户会话。

创建登录流程 authenticate() 登录流程从调用 authorizationBaseUrl, redirectUrl和 responseType 和 'code' ，并将其设置为

用户直接在 OAuth2 提供商处输入凭证，这样您的应用程序就不会获得敏感信息。该方法返回一个包含访问令牌、刷新令牌和用户数据（如电子邮件或个人资料详细信息）的响应对象。

无论是在 iOS 和 Android 平台还是在 web 平台上，这个过程都使用安全的 web 视图共享 cookie 与系统浏览器。配置好重定向 URL 确保用户体验顺畅。

处理令牌存储和刷新

访问令牌

• 存储这些令牌在内存中以便快速和临时访问。刷新令牌
• 使用安全存储，例如 插件，使用 AES-256 加密令牌，通过 iOS Keychain 或 Android Keystore 保护令牌，即使设备被破坏也能保护令牌。 capacitor-secure-storage 当应用程序重新启动时，检查存储的令牌以便用户无需重新输入凭证即可登录。 存储这些令牌在内存中以便快速和临时访问。使用安全存储，例如

插件，使用 AES-256 加密令牌，通过 iOS Keychain 或 Android Keystore 保护令牌，即使设备被破坏也能保护令牌。

为了保持会话活动，刷新令牌在它们过期之前。 在进行API调用之前，检查访问令牌是否即将过期。如果是，使用刷新令牌从您的OAuth2提供商获取一个新的访问令牌。 为增加可靠性，包括逻辑以重试令牌刷新，当网络重新连接时。如果刷新令牌过期或被撤销，请将用户重定向到登录流以重新验证。

添加注销功能

安全有效的注销过程同样重要。首先通过提供商的端点撤销刷新令牌。然后清除令牌从安全存储并重置用户数据以确保所有会话都已终止。

仅仅删除本地令牌不足。 OAuth2提供商通常维护服务器端会话，这些会话可能自动重新验证用户。 撤销刷新令牌打断了与授权许可证链相关的令牌链，使存储的凭据不能被重用。

“JWT Access Tokens cannot be revoked. They are valid until they expire. Since they are bearer tokens, there is no way to invalidate them.” – lihua.zhang, Auth0 Employee [5]

为了撤销令牌，请在清除本地存储之前，使用刷新令牌调用提供者的令牌撤销端点。这项服务器端操作即使凭据被泄露，也能防止令牌滥用。撤销令牌后，应从安全存储中删除令牌、重置缓存用户数据，并将用户导回登录屏幕。

对于单点登录（SSO）设置，需要决定是否在注销时也结束其他使用同一提供者的应用程序的会话。此外，还应确保注销过程在网络中断时能顺利进行，通过本地存储注销请求并在连接恢复时重试它们。这确保了在提供者端进行了适当的清理。

步骤 4：测试 OAuth2 集成

在设置 OAuth2 配置并开发身份验证流程之后，下一步是进行彻底的测试。这确保了您的集成在设备和平台之间无缝工作，提供了可靠的用户体验。测试涉及在移动设备和浏览器上验证功能，同时也要识别并解决潜在问题，以便在发布应用程序之前进行发布。

测试 iOS 和 Android

首先在物理 iOS 和 Android 设备上测试整个身份验证过程。

• 对于 iOS: 确保 URL 方案在 iOS 设备上正确配置。 Info.plist file，确保您的应用程序正确处理OAuth2提供商的重定向。避免使用 WKWebView 用于授权请求，因为这可能导致 disallowed_useragent 错误。相反，使用像Google Sign-In for iOS或OpenID Foundation的AppAuth for iOS这样的库来有效地处理身份验证流 [6].

• Android: 检查您的 AndroidManifest.xml 包含了正确的意图过滤器来处理重定向URI。与iOS类似，避免使用 android.webkit.WebView 用于授权请求，因为这也可能导致 disallowed_useragent 错误。选择Google Sign-In或OpenID AppAuth for Android这样的库 [6].

在两种情况下测试错误场景，如不可用的授权服务器 [7]。如果您的应用程序请求多个权限（范围），请验证哪些已被授予，并处理某些可能被拒绝的情况 [6].

在Capacitor应用中测试

对于Web平台，使用开发者工具监控网络请求并确保令牌安全。工具如OAuth 2.0 Playground可以帮助您测试您的流程 [10]，而HTTP拦截代理如 ZAP 或 BurpSuite 提供更深入的见解 [11].

在测试中使用Authorization Code授权码与PKCE，作为公共客户端的推荐方法。确保通过POST参数或头值安全地传输机密，而不是URL参数。此外，实现安全头，如 Referrer-Policy 以增强保护 [11].

解决常见问题

在测试期间，您可能会遇到需要解决的问题:

• 错误的重定向URI:不匹配的重定向URI通常会导致“未经授权的客户端”错误。确保重定向URI在OAuth2提供者的设置、您的__CAPGO_KEEP_0__应用中的 capacitor.config.json file in your Capacitor app, and the native platform manifests.

  “需要支持的sso accepted路由需要支持iosScheme和hostname的 combination： ionic://com.myapp.mybundle” - LBopp [8]

• PKCE验证错误: 确认PKCE支持和配置正确，因为它对于保护您的应用程序至关重要 [9].

• 插件实现错误: 类似于“iOS上未实现插件”的错误通常表明缺少配置或Capacitor环境中的问题。启用OAuth2插件的日志以帮助识别和解决这些问题 [4].

• 状态不匹配错误: 如果授权请求中的状态参数与重定向响应中的状态参数不匹配，可能存在安全风险，尤其是在使用自定义OAuth处理程序（如Facebook）时。仔细检查您的自定义处理程序code以确保没有错误或配置错误 [4].

第五步：安全您的OAuth2实现

保护您的OAuth2集成至关重要，以保护敏感数据并最小化漏洞。以下是确保您的实现保持安全的关键实践

启用 PKCE 提高安全性

OAuth2授权流程安全的有效方法是启用PKCE（证明密钥Code交换）。 PKCE有助于防止未经授权的授权代码截取。以下是它是如何工作的：

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

如果您正在使用 capacitor-community/generic-oauth2 插件，启用PKCE非常方便。以下是示例配置：

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

该插件自动处理PKCE，并不支持Code流程。该 code_challenge_method 设置为“S256”以进行有效验证 [12].

使用安全存储保存令牌

为了防止未经授权的访问，安全存储OAuth2令牌至关重要。对于原生移动应用程序，利用操作系统提供的安全存储功能：

• 在iOS上，使用 Keychain 来实现硬件加密和操作系统级保护。
• 在Android上，使用 Keystore，它还可以支持 生物识别验证 来提高安全性。

对于Web应用程序，存储令牌在 HttpOnly安全cookie 中，使用 SameSite 防止跨站脚本攻击（XSS）风险的属性。

这里是一些安全存储选项的快速比较：

OAuth2 实现步骤 [13]OAuth2 实现步骤 [14].

设置内容安全策略

除了安全存储外，实施强大的内容安全策略（CSP）可以帮助保护您的应用程序免受跨站点脚本（XSS）和code注入攻击。您可以使用HTTP标头在服务器级别配置CSP，或者在HTML中添加一个 Content-Security-Policy 标签。 <meta> 关键指令包括：

default-src

• : 设置所有内容类型的默认规则。script-src
• script-srcconnect-src
• connect-src: 管理 API 调用和 OAuth2 交互。
• frame-ancestors: 防止点击劫持攻击，限制谁可以在 iframe 中嵌入您的应用。

为了获得最大程度的保护，请使用严格的非法令或散列代替广泛的允许列表，并避免像这样的指令： unsafe-inline 或 unsafe-eval或 upgrade-insecure-requests 或 frame-ancestors 'none'.

或

结论和下一步

You’ve successfully implemented OAuth2 authentication in your Capacitor app by following five core steps. These included setting up your OAuth2 provider, installing the required plugins, creating the authentication flow, testing across platforms, and securing your integration using PKCE and proper token storage. It’s important to remember that OAuth 2.0 is an 您已经成功在您的__CAPGO_KEEP_0__应用中实现了 OAuth2 身份验证，通过遵循五个核心步骤。这些步骤包括设置 OAuth2 提供商，安装所需的插件，创建身份验证流程，测试跨平台，使用 PKCE 和适当的令牌存储来安全地集成。请记住，OAuth 2.0 是一个授权协议 [1]，而不是身份验证协议

Security is crucial, especially for mobile apps. Organizations using OAuth 2.0 report a 34% drop in API access security incidents compared to those relying on basic authentication methods [19]通过采用最佳实践 - 如使用短期访问令牌、实现 PKCE 和安全存储令牌 - 你已经为你的应用程序的身份验证系统奠定了坚实的基础。

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

添加更多功能

通过 OAuth2 的实施，你有机会通过添加额外功能来增强你的应用程序。例如：

• OpenID Connect (OIDC):通过扩展 OAuth 2.0 来实现用户身份验证和单点登录 (SSO) 能力 [16].
• 多因素身份验证 (MFA):通过添加额外的保护层来提高安全性 [17].
• 渐进式资料收集:通过逐步收集用户资料来改善用户体验和注册流程 [15].

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

更多资源

为了进一步增强您的OAuth2实现，利用这些资源和策略:

• API Gateway安全:通过实施身份验证和授权措施、缓存、以及强大的日志和分析来加强您的部署 [20].

• 阿伦帕雷基的建议:根据阿伦帕雷基的著作 OAuth 2.0简化:

  “授权Code流是OAuth 2.0流中最安全的，并且在服务器端应用程序中应尽可能使用” [18].

下一步指南

保持领先，定期进行安全审计并保持您的实现最新。例如，OAuth 2.1 引入了改进，如要求 PKCE 对所有授权 code 请求和淘汰较少的安全流 [19].此外，Capacitor 文档和 OAuth2 插件仓库提供了持续的技术支持，以帮助维护和改进您的应用程序的身份验证系统

常见问题

::: faq

为什么我应该使用 Authorization Code 流程（PKCE）来 OAuth2 在移动应用程序中?

为什么使用授权Code流程（PKCE）来增强移动应用的安全性？

The 授权Code流程（PKCE） is a go-to choice for mobile apps because it boosts security by addressing risks like authorization code interception and man-in-the-middle attacks. PKCE (Proof Key for Code Exchange) works by adding an extra layer of protection: it requires a unique code challenge that the authorization server validates. This ensures that only the intended app can finalize the authentication process.

移动应用，作为公共客户端，无法安全地存储客户端密钥。PKCE就此而言，允许您安全地验证用户而不暴露敏感数据。结果？一个更安全、更可靠的登录过程，改善了整体用户体验。

::: faq

如何在iOS、Android和Web应用中安全地存储OAuth2令牌？

为了在不同平台上安全地存储OAuth2令牌，使用 针对每个平台的安全存储解决方案是必不可少的。对于iOS，Keychain Services是首选，而Android用户应该依赖Android Keystore系统。这些工具是专门设计来保护敏感数据，包括令牌的。对于Web，安全cookie或加密的浏览器存储可以作为有效的替代方案。

添加加密，如AES-256，提供了令牌的额外安全层。使用 短期令牌 并且在需要时安全地刷新它们可以进一步降低风险。实现 PKCE (Proof Key for Code Exchange) 在 OAuth2 过程中使用 PKCE（证明密钥）

::: faq

What are the most common issues when testing OAuth2 integration in Capacitor apps, and how can they be fixed?

在 Capacitor 应用中测试 OAuth2 集成时最常见的问题是什么？如何解决这些问题？

• 在 __CAPGO_KEEP_0__ 应用中测试 OAuth2 集成时，开发人员可能会遇到几个常见的问题。以下是需要注意的内容：无效的客户端凭证
• : 确保您的客户端 ID 和密钥设置正确，并与 OAuth 提供商的配置详细信息匹配。即使是小的拼写错误也可能导致问题。重定向 URI 不匹配
• : 应用程序中的重定向 URI 必须与 OAuth 提供商中注册的 URI 完全匹配。请仔细检查以避免不必要的头痛。令牌过期时间
• 步骤 5：在 __CAPGO_KEEP_0__ 应用中实现 OAuth2步骤 5：在 __CAPGO_KEEP_0__ 应用中实现 OAuth2

步骤 5：在 Capgo 应用中实现 OAuth2

步骤 5：在 Capacitor 应用中实现 OAuth2

步骤 5：在 __CAPGO_KEEP_0__ 应用中实现 OAuth2 步骤 5：在 Capacitor 应用中实现 OAuth2 步骤 5：在 __CAPGO_KEEP_0__ 应用中实现 OAuth2 Encryption 步骤 5：在 __CAPGO_KEEP_0__ 应用中实现 OAuth2 Compliance 步骤 5：在 __CAPGO_KEEP_0__ 应用中实现 OAuth2 步骤 5：在 Capgo 应用中实现 OAuth2 为 Capgo 安全扫描器产品工作流程 Capgo 安全 为 Capgo 安全和 Capgo 信任中心 为 Capgo 信任中心