5 步实现 OAuth2 在 Capacitor 应用中

想在您的 __CAPGO_KEEP_0__ 应用中添加安全的 OAuth2 认证？以下快速指南将帮助您开始 Capacitor OAuth2 是一种安全的认证协议，允许用户分享他们的数据而不共享密码。它是为此目的而设计的

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

以下是如何将 OAuth2 integrates 到您的 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. 构建身份验证流程: 使用插件安全处理用户登录、令牌存储和注销。启用 PKCE ，提供额外的保护。
4. 跨平台测试: 在 iOS、Android 和 web 浏览器上验证流程。修复常见问题，如重定向 URI 匹配错误或 PKCE 错误。
5. 安全实施: 在 (Keychain/Keystore) 中存储令牌，使用 HTTPS，并设置强大的 内容安全策略.

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

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

YouTube 视频播放器 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].

的插件。

管理客户端凭证

客户端凭证标识您的应用程序并向 OAuth2 提供商提供客户端 ID 和客户端密钥。 想象客户端 ID 是一个公共标识符，而客户端密钥应该像私钥一样对待。

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

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.

安装插件

这个 @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

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

安装后，您需要配置插件以匹配您的OAuth2提供商的设置。这是通过

__CAPGO_KEEP_0__ v5 oauth2Options object when calling the authenticate() 方法的关键参数包括：

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

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

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

检查Capacitor版本兼容性

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

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

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

步骤 3：构建 OAuth2 认证流程

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

创建登录流程

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

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

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

处理令牌存储和刷新

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

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

当应用程序重启时，检查存储的令牌以无需用户重新输入凭据即可重新登录用户。

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

添加注销功能

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

Simply deleting local tokens isn’t enough. OAuth2 providers often maintain server-side sessions that could re-authenticate users automatically. Revoking the refresh token breaks the token chain linked to the authorization grant, ensuring that stored credentials can’t be reused.

“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]

To revoke tokens, call the provider’s token revocation endpoint with the refresh token before clearing local storage. This server-side action prevents token misuse, even if credentials are compromised. After revocation, remove tokens from secure storage, reset cached user data, and navigate users back to the login screen.

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.

Step 4: Test Your OAuth2 Integration

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

在iOS和Android上进行测试

首先在物理iOS和Android设备上测试整个认证流程。

• 在iOS上：确保您的URL方案在 Info.plist 文件中正确配置，并确认您的应用程序正确处理OAuth2提供商的重定向。避免使用 WKWebView 来处理授权请求，因为这可能导致错误。相反，使用像Google Sign-In for iOS或OpenID Foundation的AppAuth for iOS这样的库来处理认证流程。 disallowed_useragent 在Android上： [6].

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

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

测试 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）时。仔细检查您的自定义处理器 __CAPGO_KEEP_0__ 以确保没有错误或配置错误: If the state parameter in the authorization request doesn’t match the one in the redirect response, it could signal a security risk. This is especially relevant when using custom OAuth handlers for providers like Facebook. Carefully review your custom handler code to ensure there are no errors or misconfigurations [4].

第 5 步：安全您的 OAuth2 实现

保护您的 OAuth2 集成至关重要，以 safeguarding sensitive 数据和减少漏洞。以下是确保您的实现保持安全的关键实践。

启用 PKCE 为更好的安全性

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

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

如果您正在使用该插件，启用 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 的 Backend for Frontend (BFF) 代理来增强安全性 [14].

设置内容安全策略

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

default-src

• : 设置所有内容类型的fallback规则http-header
• script-src:控制哪些JavaScript文件允许执行。
• connect-src:管理API调用和OAuth2交互。
• frame-ancestors:通过限制谁可以在iframe中嵌入您的应用程序来防止点击劫持。

为了获得最大保护，请使用严格的非法令或散列代替广泛的白名单，并避免像 unsafe-inline 或 unsafe-eval这样的指令。如果您的应用程序正在从HTTP切换到HTTPS，请考虑添加 upgrade-insecure-requests 指令。要确保您的OAuth2内容不能被嵌入到其他地方，请设置 frame-ancestors 'none'.

Conclusion and Next Steps

结论和下一步骤

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 授权协议, not an authentication protocol [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]安全性至关重要，尤其是对于移动应用。使用 OAuth 2.0 的组织报告了与依赖基本身份验证方法的组织相比，__CAPGO_KEEP_0__访问安全事件的 34% 降低

.

通过采用最佳实践 - 如使用短期访问令牌、实现 PKCE 和安全存储令牌 - 你已经为你的应用程序的身份验证系统奠定了坚实的基础。

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

• 添加更多功能 通过 OAuth2， 你有机会通过添加更多功能来增强你的应用程序。例如：OpenID Connect（OIDC）： [16].
• 多因素认证 (MFA): 增强安全性通过添加额外的保护层 [17].
• 渐进式资料收集: 逐步收集用户资料以改善注册和用户体验 [15].

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

更多资源

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

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

• 阿伦·帕雷基的建议: 根据 Aaron Parecki 的说法，OAuth 2.0 Simplified 的作者 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）？

为什么使用 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 访问令牌，使用__CAPGO_KEEP_0__是必不可少的。 针对每个平台的安全存储解决方案. 对于 iOS，Keychain Services 是首选选项，而 Android 用户则应依赖 Android Keystore 系统。这些工具专门设计用于保护敏感数据，包括令牌。 在 web 上，安全 cookie 或加密的浏览器存储可以作为有效的替代方案。

在添加加密功能，如 AES-256 时，可以为令牌提供额外的安全层。使用 __CAPGO_KEEP_0__ 可以进一步增强安全性。 临时令牌 并且在需要时安全地刷新它们进一步减少了风险。通过实施 PKCE (证明密钥用于Code交换) 在 OAuth2 流程中，阻止未经授权访问的另一个聪明的做法是。为了获得更强的保护，考虑将生物识别认证集成到应用中，确保只有真正的用户才能访问存储的令牌。

::: faq

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

当在Capacitor应用中测试OAuth2集成时，开发者可能会遇到几个常见的问题。以下是需要注意的关键点：

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

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

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

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