This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo AuthSession

一个通用库,提供 API 来处理基于浏览器的身份验证。

Android
iOS
Web
Included in Expo Go
Recommended version:
~58.0.10

AuthSession 通过使用 WebBrowser 和 Crypto 在你的应用中启用基于网络浏览器的身份验证(例如,基于浏览器的 OAuth 流程)。有关实现详情,请参阅此参考资料;有关使用方法,请参见 Authentication 指南。

安装

🌐 Installation

Terminal
- npx expo install expo-auth-session expo-crypto
- yarn expo install expo-auth-session expo-crypto
- pnpm expo install expo-auth-session expo-crypto
- bun expo install expo-auth-session expo-crypto

If you are installing this in an existing React Native app, make sure to install expo in your project.

配置

🌐 Configuration

Are you using this library in an existing React Native app?

要使用这个库,你需要在应用中通过设置 scheme 来配置深度链接。使用 uri-scheme 命令行接口 工具可以轻松添加、删除、列出和打开你的 URI。

🌐 To use this library, you need to set up deep linking in your app by setting up a scheme. Use the uri-scheme CLI utility to easily add, remove, list, and open your URIs.

例如,要让你的本地应用处理 mycoolredirect://,请运行:

🌐 For example, to make your native app handle mycoolredirect://, run:

Terminal
- npx uri-scheme add mycoolredirect

你现在应该能够通过运行以下命令来查看所有项目方案的列表:

🌐 You should now be able to see a list of all your project's schemes by running:

Terminal
- npx uri-scheme list

你可以测试它以确保它像这样工作:

🌐 You can test it to ensure it works like this:

Terminal
# Rebuild the native apps, be sure to use an emulator
- yarn android
- yarn ios

# Open a URI scheme
- npx uri-scheme open mycoolredirect://some/redirect

在独立应用中的使用

🌐 Usage in standalone apps

app.json
{ "expo": { "scheme": "mycoolredirect" } }

为了能够深度链接回你的应用,你需要在项目的应用配置中设置一个 scheme,然后构建你的独立应用(它无法通过更新来修改)。如果你没有包含一个 scheme,认证流程将会完成,但无法将信息传回你的应用,用户将需要手动退出认证弹窗(导致事件被取消)。

🌐 To be able to deep link back into your app, you will need to set a scheme in your project's app config, and then build your standalone app (it can't be updated with an update). If you do not include a scheme, the authentication flow will complete, but it will be unable to pass the information back into your application and the user will have to manually exit the authentication modal (resulting in a canceled event).

指南

🌐 Guides

基于 Web 浏览器的身份验证流程如何工作

🌐 How web browser based authentication flows work

移动应用中基于浏览器的身份验证的典型流程如下:

🌐 The typical flow for browser-based authentication in mobile apps is as follows:

  • 启动:用户按下登录按钮
  • 打开网页浏览器:该应用会打开一个网页浏览器,访问身份验证提供者的登录页面。用于登录页面的 URL 通常包含用于识别应用的信息,以及成功后重定向的 URL。注意:网页浏览器应与系统浏览器共享 Cookie,这样如果用户已在系统浏览器中完成身份验证,就无需再次登录 — Expo 的 WebBrowser API 会处理此问题。
  • 身份验证提供者重定向:在身份验证成功后,身份验证提供者应通过重定向到登录页面查询参数中应用提供的 URL 来返回应用(了解有关移动应用中链接工作原理的更多信息),前提是该 URL 在允许的重定向 URL 白名单中。将重定向 URL 列入白名单对于防止恶意行为者冒充你的应用非常重要。重定向会在 URL 中包含数据(例如用户 ID 和令牌),可以放在位置哈希、查询参数或两者中。
  • 应用处理重定向:重定向由应用处理,并从重定向 URL 中解析数据。

安全考虑

🌐 Security considerations

  • 永远不要将任何密钥放在应用代码中,没有安全的方法可以这样做! 相反,你应该将密钥存储在服务器上,并提供一个端点,让它为你的客户端进行 API 调用并返回数据。

应用接口

🌐 API

import * as AuthSession from 'expo-auth-session';

No API data file found, sorry!

高级用法

🌐 Advanced usage

过滤掉链接处理程序中的 AuthSession 事件

🌐 Filtering out AuthSession events in Linking handlers

有许多原因可能会让你希望处理进入你应用的入站链接,例如推送通知或普通的深度链接(你可以在 Linking 中了解更多);认证重定向只是深度链接的一种类型,而 AuthSession 为你处理这些特定的链接。在你自己的 Linking.addEventListener 处理器中,你可以通过检查 URL 是否包含 +expo-auth-session 字符串来过滤掉由 AuthSession 处理的深度链接——如果包含,你可以忽略它。这之所以可行,是因为 AuthSession 将 +expo-auth-session 添加到默认的 returnUrl;然而,如果你提供了自己的 returnUrl,你可能需要考虑添加类似的标识符,以便能够从其他处理器中过滤掉 AuthSession 事件。

🌐 There are many reasons why you might want to handle inbound links into your app, such as push notifications or just regular deep linking (you can read more about this in the Linking); authentication redirects are only one type of deep link, and AuthSession handles these particular links for you. In your own Linking.addEventListener handlers, you can filter out deep links that are handled by AuthSession by checking if the URL includes the +expo-auth-session string — if it does, you can ignore it. This works because AuthSession adds +expo-auth-session to the default returnUrl; however, if you provide your own returnUrl, you may want to consider adding a similar identifier to enable you to filter out AuthSession events from other handlers.

使用 React 导航

🌐 With React Navigation

如果你在使用 React Navigation 的深度链接,仅通过 Linking.addEventListener 进行过滤是不够的,因为深度链接是以不同方式处理的。相反,要过滤这些事件,请在你的链接配置中添加一个自定义的 getStateFromPath 函数,然后按上文所述的方式通过 URL 进行过滤。

🌐 If you are using deep linking with React Navigation, filtering through Linking.addEventListener will not be sufficient because deep linking is handled differently. Instead, to filter these events, add a custom getStateFromPath function to your linking configuration, and then filter by URL in the same way as described above.