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

想添加安全的 OAuth2 对您的 Capacitor Capacitor

应用程序？以下是快速入门指南。 Capacitor apps __CAPGO_KEEP_0__ @capgo/capacitor-social-login 因为它可以在 iOS、Android 和 web 平台上工作。对于社交提供者， @capgo/capacitor-social-login keeps browser-style WebAuthn code while native passkey calls are handled for you. Plus, it keeps your app secure by using tokens instead of storing sensitive credentials.

@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-passkey 保持浏览器风格的 WebAuthn Capacitor，同时原生 passkey 调用将为您处理。另外，它通过使用令牌而不是存储敏感凭据来保持您的应用程序安全。 在 5 步之内:

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

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

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

步骤 1：设置您的 OAuth2 提供者

正确设置 OAuth2 提供者是确保一切顺利的第一步和最关键的步骤。这涉及选择与您的应用需求相符的提供者，配置技术细节，如重定向 URI，安全地处理您的凭据。这些步骤为接下来安装 OAuth2 插件做好准备。

选择 OAuth2 提供者

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

比较提供者时，重点关注其安全功能。寻找像签名 cookie、CSRF token 验证和加密 JWT 等选项。如果您的应用处理敏感数据，则应支持 多因素身份验证 在Capacitor应用中实施OAuth2需要遵循一定的步骤。评估时，应权衡成本和功能，根据您的需求进行比较，而不是陷入繁琐的比较中。

配置重定向URI

重定向URI至关重要，它们告诉OAuth2提供者在用户完成身份验证后应该将用户发送到哪里。正确配置这些URI确保在移动和Web平台上都能实现顺畅的体验。

对于移动应用，应使用自定义URL方案，通常以 com.example.app://callback为格式。其中 com.example.app 匹配您的应用包ID。对于Web应用，应使用 window.location.origin 作为重定向URI。如果您正在测试本地环境，URL http://localhost:8100/callback 会很好地工作。

对于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.

安装插件

该插件与大多数 OAuth2 提供商兼容。为了避免兼容性问题，您需要安装与您的应用程序设置匹配的版本。 @byteowls/capacitor-oauth2 plugin works with most OAuth2 providers. To avoid compatibility issues, you’ll need to install the version that matches your Capacitor setup.

Here are the installation commands based on your Capacitor version:

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

安装完成后，运行同步命令（”，”）来更新您的本机依赖项。这一步骤对于确保插件与您的iOS和Android项目正确集成至关重要。忽略此步骤可能导致在编译移动平台时出现编译错误。npx cap sync配置插件设置

安装完成后，您需要配置插件以匹配OAuth2提供者的设置。这是通过在调用”方法中的”对象中完成的。需要定义的关键参数包括：

appId oauth2Options :您的OAuth2提供者的客户端ID。 authenticate() authorizationBaseUrl

• :OAuth2提供者的授权端点。responseType
• :通常设置为__CAPGO_KEEP_0__
• __CAPGO_KEEP_1____CAPGO_KEEP_2__ "code" 对于移动应用程序.
• 重定向 URL: 这必须与步骤 1 中配置的重定向 URL 匹配.

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

对于 Android，更新您的 AndroidManifest.xml 和 strings.xml context Info.plist Page/area: Capgo marketing website. Role: Short UI label or navigation item. Seen in: page trust.astro. Message key `and` (And).

Check Capacitor Version Compatibility

It’s essential to verify that the plugin version matches your Capacitor version. Mismatched versions can cause build errors or runtime issues. The @byteowls/capacitor-oauth2 检查Capacitor版本兼容性.

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

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

步骤 3：构建 OAuth2 认证流程

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

创建登录流程

登录过程从调用 authenticate() 使用一个选项对象。这个对象应该包含你的 authorizationBaseUrl, redirectUrl和 responseType 设置为 'code' 以符合PKCE要求。该插件安全地打开提供者的登录页面，用户可以输入他们的凭据。登录成功后，提供者会将用户重定向回你的应用程序，带有令牌和用户详细信息。

最好的部分是：用户直接在OAuth2提供者中输入凭据，所以你的应用程序永远不会访问敏感信息。该方法返回一个响应对象，包括访问令牌、刷新令牌和用户数据，如电子邮件或个人资料详细信息。

在iOS和Android上，这个过程使用一个安全的网页视图，共享cookie与系统浏览器。在web平台上，它依赖于标准的浏览器重定向。正确配置你的重定向URL确保无论平台如何都能提供smooth用户体验。

处理令牌存储和刷新

用户登录后，安全地管理令牌是你的下一个优先事项。这包括安全地存储令牌并自动刷新令牌以避免会话中断。这里是如何处理它的:

• 访问令牌: 在内存中存储这些令牌，以便快速和临时访问。
• 刷新令牌: 使用安全存储，例如 capacitor-secure-storage 插件，使用AES-256加密令牌，通过iOS Keychain或 Android Keystore。 这样令牌即使设备被破坏，也会得到保护。

当您的应用程序重新启动时，检查存储的令牌以便用户在不需要重新输入凭据的情况下重新登录。

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

添加注销功能

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

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

“JWT访问令牌无法被撤销。它们有效直到过期。由于它们是持有者令牌，因此无法无效它们。” – lihua.zhang，Auth0员工 [5]

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

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

步骤 4：测试 OAuth2 集成

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

在 iOS 和 Android 设备上测试

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

• 对于 iOS: 确保 URL 方案在文件中正确配置，并确认您的应用程序能够从 OAuth2 提供者正确处理重定向。避免使用 Info.plist ，因为这可能导致错误。相反，使用 Google Sign-In for iOS 或 OpenID Foundation 的 AppAuth for iOS 等库来有效地处理身份验证流程。 WKWebView 对于 Android disallowed_useragent : 检查您的 [6].

• For Android: Check that your AndroidManifest.xml 包括了正确的意图过滤器来处理重定向 URI。与 iOS 类似，避免使用 android.webkit.WebView 用于授权请求，因为这也可能导致 disallowed_useragent 错误。对于 Android，优先使用 Google Sign-In 或 OpenID AppAuth 等库 [6].

In both cases, test for error scenarios, such as an unavailable authorization server [7]. 如果您的应用程序请求多个权限（范围），请验证哪些已被授予，并处理某些可能被拒绝的情况 [6].

Test on Web

对于 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.

  PKCE 验证错误 [8]

• :确认PKCE是否支持并正确配置，因为它对于安全您的应用至关重要插件实现错误 [9].

• :错误，如“iOS上未实现插件”通常表明缺少配置或__CAPGO_KEEP_0__环境中的问题。启用OAuth2插件的日志，以帮助识别和解决这些问题: Errors like “Plugin is not implemented on iOS” typically indicate missing configurations or issues within the Capacitor environment. Enable logging in your OAuth2 plugin to help identify and resolve these problems [4].

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

步骤 5：安全实施 OAuth2

保护 OAuth2 集成至关重要，以 safeguardSensitive 数据并降低漏洞。以下是确保实施安全的关键实践

启用 PKCE 提高安全性

One of the most effective ways to secure your authorization flow is by enabling PKCE (Proof Key for Code Exchange). PKCE helps prevent unauthorized interception of authorization codes. Here’s how it works:

• 首先生成一个随机 code_verifier 长度在 43 到 128 个字符之间
• 然后创建一个 code_challenge 通过使用SHA-256并将结果以base64 URL格式编码 code_verifier 如果您正在使用

插件，启用PKCE非常简单。以下是示例配置： capacitor-community/generic-oauth2 此插件自动处理PKCE，并且不支持__CAPGO_KEEP_0__流程。

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

This plugin automatically handles PKCE and does not support the Code Flow without it. The code_challenge_method 使用安全存储存储令牌 [12].

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

在iOS上使用

• Keychain 以硬件加密和OS级别保护 在Android上使用
• KeyStore 密钥库, 也可以支持 生物识别验证 提高安全性。

对于 Web 应用程序， HttpOnly 安全 cookie 属性 SameSite 降低跨站脚本攻击 (XSS) 风险。

以下是安全存储选项的快速比较：

为了提高安全性，请考虑使用短期令牌和加密存储。例如，Auth0 将活跃刷新令牌限制为每个用户每个应用程序200个，以减少风险 [13]您还可以通过使用 HttpOnly cookie 的后端前端代理来增强安全性 [14].

设置内容安全策略

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

Key directives to focus on include:

• default-src: Sets fallback rules for all content types.
• script-src: Controls which JavaScript files are allowed to execute.
• connect-src: Manages API calls and OAuth2 interactions.
• frame-ancestors: Prevents clickjacking by restricting who can embed your app in an iframe.

为了获得最大保护，使用严格的非对称或散列值替代广泛的白名单，并避免使用指令，如 unsafe-inline 或 unsafe-eval（HTML文本片段来自更长的Capgo UI字符串（父级键 `alternatives_cta_questions`）。页面/区域：Capacitor live-update alternatives比较页面。角色：长期营销或法律段落。见于：页面alternatives.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键 `alternatives_cta_questions`（Alternatives CTA Questions）。| HTML文本片段来自更长的Capgo UI字符串（父级键 `appflow_cta_questions`）。页面/区域：Appflow比较/迁移营销复制。角色：长期营销或法律段落。见于：页面ionic-appflow.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键 `appflow_cta_questions`（Appflow CTA Questions）。| HTML文本片段来自更长的Capgo UI字符串（父级键 `capwesome_cta_questions`）。页面/区域：Capawesome比较页面。角色：长期营销或法律段落。见于：页面capwesome.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键 `capwesome_cta_questions`（Capwesome CTA Questions）。| HTML文本片段来自更长的Capgo UI字符串（父级键 `consulting_faq_subtitle`）。页面/区域：咨询服务页面。角色：段落标题或标语。见于：页面consulting.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键 `consulting_faq_subtitle`（Consulting FAQ Subtitle）。| 页面/区域：Appflow比较/迁移营销复制。角色：短UI标签或导航项。见于：页面ionic-appflow.astro，页面ionic-enterprise-plugins.astro，页面解决方案/ionic-enterprise-plugins.astro。消息键 `appflow_plugins_or`（Appflow Plugins Or）。 upgrade-insecure-requests . 如果您的应用程序正在从HTTP转换为HTTPS，请考虑添加指令。要确保您的OAuth2内容不能被嵌入到其他地方，请设置 frame-ancestors 'none'.

结论和下一步

关键点

您已经成功在您的Capacitor应用中实现了OAuth2身份验证，通过遵循五个核心步骤。这些步骤包括设置OAuth2提供商、安装所需插件、创建身份验证流程、在多个平台上测试以及使用PKCE和适当的令牌存储来安全地集成。请记住，OAuth 2.0是一个 授权协议而不是身份验证协议 [1]。它的主要重点是授予访问权限，而不是验证用户身份。

安全性至关重要，尤其是在移动应用中。使用OAuth 2.0的组织报告了与依赖基本身份验证方法的组织相比，API访问安全事件的34%降低 [19]。通过采用最佳实践，例如使用短期访问令牌、实现PKCE和安全存储令牌，您已经为应用的身份验证系统奠定了坚实的基础。

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

添加更多功能

通过OAuth2的实施，您有机会在保持安全框架的同时增强应用的功能。例如:

• OpenID Connect OIDC): OAuth 2.0 的扩展，支持用户身份验证和单点登录（SSO）功能 [16].
• Multi-Factor Authentication (MFA): 增强安全性，添加额外的保护层 [17].
• Progressive Profiling: 逐步收集用户数据，改善用户体验和注册流程 [15].

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

更多资源

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

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

• Aaron Parecki的建议: 根据Aaron Parecki的建议， OAuth 2.0简化:

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

以下是您的下一步指南:

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

常见问题

::: faq

为什么我应该使用 OAuth2 在移动应用中使用 Authorization Code 流程和 PKCE?

为什么使用 Authorization Code 流程和 PKCE 在移动应用中?

The Authorization 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 等加密提供令牌的额外安全层。使用短期令牌，并在需要时安全刷新令牌进一步降低风险。实现 OAuth2 过程中的 PKCE (Proof Key for __CAPGO_KEEP_0__ Exchange) 是阻止未经授权访问的聪明做法。为了获得更强的保护，请考虑集成生物识别验证，确保只有合法用户才能访问存储的令牌。 :::

::: faq 在 __CAPGO_KEEP_0__ 应用中测试 OAuth2 整合时最常见的问题是什么，如何解决? __CAPGO_KEEP_0__ Code __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

Capacitor

当测试Capacitor中的OAuth2集成时，开发人员可能会遇到几个常见的问题。以下是需要注意的内容：

• 无效的客户端凭证: 确保您的客户端ID和密钥设置正确，并与OAuth提供商的配置详细信息匹配。即使是小小的拼写错误也会导致问题。
• 重定向URI不匹配: 应用程序中的重定向URI必须与OAuth提供商中注册的重定向URI完全匹配。请仔细检查以避免不必要的头痛。
• 令牌过期: 令牌不会永远存在。设置可靠的令牌刷新系统来处理过期令牌，保持用户体验不受影响。
• 权限配置不正确: 应用程序中请求的权限需要与OAuth提供商中配置的权限匹配。权限不匹配可能会导致意外错误。

要解决这些问题，请仔细检查应用程序的OAuth设置。实现强大的错误处理来捕获和解决问题，测试您的身份验证流程在不同场景下。工具如Capgo可以使开发更高效，用户更满意，通过允许您直接将更新和修复推送到应用程序，而无需等待应用商店批准。

继续阅读：5步实现Capacitor中的OAuth2

如果您正在使用 5 步实现 OAuth2 在 Capacitor 应用中 为了规划安全性和合规性，连接它 加密 加密的实现细节 合规 合规的实现细节 Capgo 安全扫描器 Capgo 安全扫描器的产品工作流 Capgo 安全 Capgo 安全的产品工作流 Capgo 信任中心 Capgo 信任中心的产品工作流