5步实现Capacitor应用中的OAuth2

想在应用中添加安全的OAuth2认证吗 Want to add secure OAuth2 authentication to your __CAPGO_KEEP_0__ app? 在您的 Capacitor 应用程序中进行身份验证？以下是快速入门指南.

OAuth2 是一个协议，允许用户分享他们的数据而不共享密码。它适用于 Capacitor 应用程序 因为它可以在 iOS、Android 和 web 平台上工作。对于社交提供商， @capgo/capacitor-social-login 处理 Google、Apple 和 Facebook 登录的原生流程。对于无密码认证， @capgo/capacitor-passkey 保持浏览器风格的 WebAuthn code，同时原生 passkey 调用由其处理。另外，它通过使用令牌而不是存储敏感凭证来保持应用程序的安全。

以下是如何将 OAuth2 集成到您的 Capacitor 应用程序中 在 5 步之内:

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

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

如何使用 Google Sign In Capacitor 添加到您的 Ionic App

Step 1: 设置您的 OAuth2 服务提供商

正确设置 OAuth2 服务提供商是确保一切顺利运行的第一步和最关键的步骤。 这涉及选择与您的应用程序要求相符的提供商、配置技术细节，如重定向 URI、并安全地处理您的凭据。 这些步骤为安装 OAuth2 插件奠定了基础，下一阶段将进行。

选择 OAuth2 服务提供商

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

比较服务提供商时，应重点关注其安全功能。 搜索像签名 cookie、CSRF token 验证和加密 JWT 等选项。 如果您的应用程序处理敏感数据，则应支持 多因素身份验证 是必须的。 在评估时，根据您的需求平衡成本和功能，而不被繁琐的比较所困扰。

配置重定向 URI

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

对于移动应用程序，使用自定义 URL 方案，通常以 com.example.app://callback的格式呈现， com.example.app 匹配您的应用程序的包 ID。 在 web 上，使用 window.location.origin 作为重定向 URI。 如果您正在测试本地环境，一个类似 http://localhost:8100/callback 的 URL 很好。

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

管理客户凭证

客户凭证通过客户 ID 和客户密钥来识别您的应用程序，并且由 OAuth2 提供商提供。您可以将客户 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 提供商兼容。为了避免兼容性问题，您需要安装与您的 Capgo 设置匹配的版本。 @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 v3: npm i @byteowls/capacitor-oauth2@3

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

配置插件设置

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

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

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

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

检查Capacitor版本兼容性

验证插件版本与Capacitor版本匹配至关重要。版本不匹配可能会导致编译错误或运行时问题。Capacitor插件严格遵循Capacitor发布版本，因此在继续之前，请务必检查兼容性。 @byteowls/capacitor-oauth2 plugin strictly aligns with Capacitor releases, so double-check compatibility before proceeding.

如果您正在开发 iOS 应用，请密切关注 Xcode 版本要求。使用不兼容的版本会阻止您的应用成功构建。插件文档包含详细的兼容性表格，这是一个很好的资源，用于解决版本相关问题。

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

步骤 3：构建 OAuth2 认证流程

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

创建登录流程

The login process starts by calling __CAPGO_KEEP_0__ with an options object. This object should include your __CAPGO_KEEP_1__, and the __CAPGO_KEEP_2__ set to __CAPGO_KEEP_3__ to comply with PKCE requirements. The plugin securely opens the provider’s login page, where users can enter their credentials. After a successful login, the provider redirects users back to your app with tokens and user details. authenticate() Here’s the best part: users enter their credentials directly with the OAuth2 provider, so your app never has access to sensitive information. The method returns a response object that includes the access token, refresh token, and user data like email or profile details. authorizationBaseUrl, redirectUrlOn iOS and Android, this process uses a secure web view that shares cookies with the system browser. On web platforms, it relies on standard browser redirects. Properly configuring your redirect URL ensures a smooth user experience no matter the platform. responseType Handle Token Storage and Refresh 'code' Once users are logged in, securely managing tokens is your next priority. This includes storing tokens safely and refreshing them automatically to avoid session interruptions. Here’s how you can handle it:

Access Tokens

: 在内存中存储这些，以便快速和临时访问。

Refresh Tokens

: 在安全的存储中存储这些，以便在会话中断时自动刷新。

• Store these in memory for quick and temporary access.Store these in secure storage for automatic refresh when sessions are interrupted.
• Store these in secure storage for automatic refresh when sessions are interrupted.: 使用安全存储，例如通过 iOS Keychain 或 Android Keystore 使用 AES-256 加密令牌的插件。这样即使设备被破坏，令牌也会得到保护。 capacitor-secure-storage When your app restarts, check for stored tokens to log users back in without requiring them to re-enter credentials. 存储方法安全级别

性能

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

添加注销功能

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

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

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

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

For single sign-on (SSO) setups, decide whether logging out should also end sessions for other apps using the same provider. Additionally, make sure the logout process works smoothly during network interruptions by storing logout requests locally and retrying them when the connection is restored. This ensures proper cleanup on the provider’s end.

第 4 步：测试您的 OAuth2 集成

After setting up your OAuth2 configuration and developing the authentication flow, the next step is testing it thoroughly. This ensures your integration works seamlessly across devices and platforms, providing a reliable experience for your users. Testing involves verifying functionality on mobile devices and web browsers, while also identifying and resolving potential issues before launching your app.

在 iOS 和 Android 设备上测试

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

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

• Test on iOS and AndroidStart by testing the entire authentication process on physical iOS and Android devices. AndroidManifest.xml 包含了正确的意图过滤器来处理重定向 URI。类似于 iOS，避免使用 android.webkit.WebView __CAPGO_KEEP_0__ disallowed_useragent 用于授权请求，因为这也可能导致 [6].

错误。对于 Android，优先选择类似 Google Sign-In 或 OpenID AppAuth 的库 [7]在两种情况下，测试错误场景，如不可用的授权服务器 [6].

。如果您的应用程序请求多个权限（范围），请验证哪些已授予并处理某些可能被拒绝的情况

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

在测试时，使用授权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.

  需要支持的combination是： ionic://com.myapp.mybundle [8]

• PKCE 验证错误：:确认PKCE是否支持并正确配置，因为它对于安全您的应用程序至关重要。 [9].

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

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

第 5 步：安全您的 OAuth2 实现

保护您的 OAuth2 整合至关重要，以 safeguarding sensitive 数据和最小化漏洞。以下是确保您的实现保持安全的关键实践

启用 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 __CAPGO_KEEP_0____CAPGO_KEEP_1__ __CAPGO_KEEP_2__ __CAPGO_KEEP_3__

__CAPGO_KEEP_4__ __CAPGO_KEEP_5__ __CAPGO_KEEP_6__ SameSite __CAPGO_KEEP_7__

__CAPGO_KEEP_8__

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

设置内容安全策略

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

Key directives to focus on include:

• default-src: 为所有内容类型设置默认规则。
• <script-src>:控制哪些JavaScript文件可以执行。
• 安全源连接管理API调用和OAuth2交互。
• frame-ancestors防止点击劫持攻击，通过限制谁可以在 iframe 中嵌入您的应用。

为了获得最大程度的保护，请使用严格的非法令或散列取代广泛的允许列表，并避免指令，如__CAPGO_KEEP_0__。 unsafe-inline 或 unsafe-eval如果您的应用从 HTTP 迁移到 HTTPS，考虑添加 Cloudflare 的 SSL 证书。 upgrade-insecure-requests directive. 为确保您的 OAuth2 内容不能被其他地方嵌入，请设置 frame-ancestors 'none'.

结论和下一步

关键点

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

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

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

添加更多功能

在OAuth2的基础上，您有机会通过添加更多功能来增强应用。例如：

• OpenID Connect (当前帮心): 执有 OAuth 2.0 为用户登录和 Single Sign-On (SSO) 起始常式 [16].
• Multi-Factor Authentication (MFA): 券安端常式中心端常式使用 [17].
• Progressive Profiling: 此式提产用户数据券式使用当則上端常式和用户用。 [15].

For ongoing maintenance and updates, consider tools like Capgo, 起安端常式为端常式使用。当則端常式和新券式当則上端常式。当則上端常式不很得帮当則端常式的端常式。起安端常式为端常式使用。当則端常式和新券式当則上端常式。

More Resources

To further enhance your OAuth2 implementation, take advantage of these resources and strategies:

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

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

  “The Authorization Code Flow is the most secure of the OAuth 2.0 flows and should be used whenever possible for server-side applications” [18].

以下是快速参考表格，指导您的下一步行动：

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

常见问题

::: faq

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

为什么使用 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 Code Exchange) 可以阻止未经授权的访问。 为了获得更强的保护，请考虑集成生物识别验证，确保只有合法的用户才能访问存储的令牌。 :::

::: faq

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

When testing OAuth2 integration in Capacitor apps, developers might run into a few common roadblocks. Here’s a quick rundown of what to watch out for:

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

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

Keep going from 5 Steps to Implement OAuth2 in Capacitor Apps

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