Expo AuthSession

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

AuthSession 通过利用 WebBrowser 和 加密 在你的应用中启用基于 Web 浏览器的身份验证（例如，基于浏览器的 OAuth 流）。有关实现细节，请参阅此参考，有关使用方法，请参阅 验证 指南。

¥AuthSession enables web browser-based authentication (for example, browser-based OAuth flows) in your app by utilizing WebBrowser and Crypto. For implementation details, refer to this reference, and for usage, see the Authentication guide.

安装

¥Installation

expo-crypto 是对等依赖，必须与 expo-auth-session 一起安装。

¥expo-crypto is a peer dependency and must be installed alongside expo-auth-session.

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

在独立应用中的使用

¥Usage in standalone apps

{
  "expo": {
    "scheme": "mycoolredirect"
  }
}

为了能够深层链接回你的应用，你需要在项目 app.config.js 或 app.json 中设置 scheme，然后构建独立应用（无法通过更新进行更新）。如果你不包含方案，则身份验证流程将完成，但无法将信息传回你的应用，并且用户必须手动退出身份验证模式（导致事件取消）。

¥to be able to deep link back into your app, you will need to set a scheme in your project app.config.js, or app.json, 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

指南已移动：认证指南。

¥The guides have moved: Authentication Guide.

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

¥How web browser based authentication flows work

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

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

• 引发：用户按下登录按钮

  ¥Initiation: the user presses a sign in button

• 打开网络浏览器：该应用会打开一个 Web 浏览器，访问身份验证提供商登录页面。为登录页面打开的 URL 通常包含用于标识应用的信息以及成功时重定向到的 URL。注意：Web 浏览器应与你的系统 Web 浏览器共享 Cookie，以便用户在已在系统浏览器上进行身份验证的情况下无需再次登录 - Expo 的 WebBrowser API 负责处理此问题。

  ¥Open web browser: the app opens up a web browser to the authentication provider sign in page. The url that is opened for the sign in page usually includes information to identify the app, and a URL to redirect to on success. Note: the web browser should share cookies with your system web browser so that users do not need to sign in again if they are already authenticated on the system browser -- Expo's WebBrowser API takes care of this.

• 身份验证提供商重定向：身份验证成功后，身份验证提供程序应通过重定向到应用在登录页面 (详细了解链接在移动应用中的工作原理) 上的查询参数中提供的 URL 来重定向回应用，前提是该 URL 位于允许的重定向 URL 的白名单中。将重定向 URL 列入白名单对于防止恶意行为者冒充你的应用非常重要。重定向包括 URL 中的数据（例如用户 ID 和令牌）、位置哈希、查询参数或两者。

  ¥Authentication provider redirects: upon successful authentication, the authentication provider should redirect back to the application by redirecting to URL provided by the app in the query parameters on the sign in page (read more about how linking works in mobile apps), provided that the URL is in the allowlist of allowed redirect URLs. Allowlisting redirect URLs is important to prevent malicious actors from pretending to be your application. The redirect includes data in the URL (such as user id and token), either in the location hash, query parameters, or both.

• 应用处理重定向：重定向由应用处理，并从重定向 URL 解析数据。

  ¥App handles redirect: the redirect is handled by the app and data is parsed from the redirect URL.

安全考虑

¥Security considerations

• 切勿将任何密钥放入应用代码中，这样做没有安全的方法！相反，你应该将密钥存储在服务器上，并公开一个端点，该端点为你的客户端进行 API 调用并将数据传回。

  ¥Never put any secret keys inside your application code, there is no secure way to do this! Instead, you should store your secret key(s) on a server and expose an endpoint that makes API calls for your client and passes the data back.

API

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

Hooks

const [request, response, promptAsync] = useAuthRequest({ ... }, { ... });

const discovery = useAutoDiscovery('https://example.com/auth');

Classes

// Create a request.
const request = new AuthRequest({ ... });

// Prompt for an auth code
const result = await request.promptAsync(discovery);

// Get the URL to invoke
const url = await request.makeAuthUrlAsync(discovery);

// Get the URL to invoke
const parsed = await request.parseReturnUrlAsync("<URL From Server>");

Methods

const url = AuthSession.getRedirectUrl('redirect');

// Managed: https://auth.expo.io/@your-username/your-app-slug/redirect
// Web: https://localhost:19006/redirect

const redirectUri = makeRedirectUri({
  scheme: 'my-scheme',
  path: 'redirect'
});
// Development Build: my-scheme://redirect
// Expo Go: exp://127.0.0.1:8081/--/redirect
// Web dev: https://localhost:19006/redirect
// Web prod: https://yourwebsite.com/redirect

const redirectUri2 = makeRedirectUri({
  scheme: 'scheme2',
  preferLocalhost: true,
  isTripleSlashed: true,
});
// Development Build: scheme2:///
// Expo Go: exp://localhost:8081
// Web dev: https://localhost:19006
// Web prod: https://yourwebsite.com

Interfaces

Types

Enums

提供者

¥Providers

AuthSession 内置了对一些流行提供商的支持，使使用尽可能简单。这些允许你跳过重复的事情，例如定义端点和抽象常见功能（例如 language）。

¥AuthSession has built-in support for some popular providers to make usage as easy as possible. These allow you to skip repetitive things like defining endpoints and abstract common features like language.

谷歌

¥Google

已弃用：该提供程序已被弃用，并将在未来的 SDK 版本中删除。请参阅 谷歌认证。

import * as Google from 'expo-auth-session/providers/google';

• 有关使用的更多信息，请参阅指南：谷歌认证。

  ¥See the guide for more info on usage: Google Authentication.

• 提供额外的 loginHint 参数。如果提前知道用户的电子邮件地址，则可以将其提供为默认选项。

  ¥Provides an extra loginHint parameter. If the user's email address is known ahead of time, it can be supplied to be the default option.

• 对以下 API 强制执行最小范围，以实现 Firebase 和 Auth0 等服务的最佳使用。

  ¥Enforces minimum scopes to the following APIs for optimal usage with services like Firebase and Auth0.

  ['openid', 'https://www.googleapis.com/auth/userinfo.profile', 'https://www.googleapis.com/auth/userinfo.email']
  

• 默认情况下，授权 code 将自动交换为访问令牌。这可以用 shouldAutoExchangeCode 覆盖。

  ¥By default, the authorization code will be automatically exchanged for an access token. This can be overridden with shouldAutoExchangeCode.

• 默认使用打包 ID 和包名称进行原生 URI 重定向，而不是反向客户端 ID。

  ¥Defaults to using the bundle ID and package name for the native URI redirect instead of the reverse client ID.

• 对隐式和基于 id 令牌的身份验证响应禁用 PKCE。

  ¥Disables PKCE for implicit and id-token based auth responses.

• 在网络上，弹出窗口显示针对 Google 登录 UI ({ width: 515, height: 680 }) 优化的尺寸。

  ¥On web, the popup is presented with the dimensions that are optimized for the Google login UI ({ width: 515, height: 680 }).

useAuthRequest()

用于跨平台运行的有态度的 Google 身份验证的钩子。

¥A hook used for opinionated Google authentication that works across platforms.

参数

¥Arguments

• 配置（GoogleAuthRequestConfig） - 一个 GoogleAuthRequestConfig 对象，其中包含应支持的每个平台的客户端 ID。

  ¥config (GoogleAuthRequestConfig) - A GoogleAuthRequestConfig object with client IDs for each platform that should be supported.

• 重定向 Uri 选项 (AuthSessionRedirectUriOptions) - 用于构造重定向 URI（传递到 makeRedirectUri()）的可选属性。

  ¥redirectUriOptions (AuthSessionRedirectUriOptions) - Optional properties used to construct the redirect URI (passed to makeRedirectUri()).

返回

¥Returns

• 请求（GoogleAuthRequest | null） - 可用于提示用户授权的 GoogleAuthRequest 实例。这将是 null，直到身份验证请求完成加载。

  ¥request (GoogleAuthRequest | null) - An instance of GoogleAuthRequest that can be used to prompt the user for authorization. This will be null until the auth request has finished loading.

• 响应（AuthSessionResult | null） - 在调用 promptAsync 之前，这是 null。一旦完成，它将返回有关授权的信息。

  ¥response (AuthSessionResult | null) - This is null until promptAsync has been invoked. Once fulfilled it will return information about the authorization.

• 提示异步 (function) - 调用时，Web 浏览器将打开并提示用户进行身份验证。接受 AuthRequestPromptOptions 对象，其中包含有关如何执行提示的选项。

  ¥promptAsync (function) - When invoked, a web browser will open up and prompt the user for authentication. Accepts an AuthRequestPromptOptions object with options about how the prompt will execute.

discovery

包含用于 Google 身份验证的发现 URL 的 DiscoveryDocument 对象。

¥A DiscoveryDocument object containing the discovery URLs used for Google auth.

Facebook

已弃用：该提供程序已被弃用，并将在未来的 SDK 版本中删除。请参阅 脸书认证。

import * as Facebook from 'expo-auth-session/providers/facebook';

• 默认情况下使用隐式身份验证 (ResponseType.Token)。

  ¥Uses implicit auth (ResponseType.Token) by default.

• 有关使用的更多信息，请参阅指南：脸书认证。

  ¥See the guide for more info on usage: Facebook Authentication.

• 将最小范围强制为 ['public_profile', 'email']，以实现 Firebase 和 Auth0 等服务的最佳使用。

  ¥Enforces minimum scopes to ['public_profile', 'email'] for optimal usage with services like Firebase and Auth0.

• 使用 display=popup 以获得更好的 UI 结果。

  ¥Uses display=popup for better UI results.

• 禁用隐式身份验证响应的 PKCE。

  ¥Disables PKCE for implicit auth response.

• 在网络上，弹出窗口的尺寸为 { width: 700, height: 600 }

  ¥On web, the popup is presented with the dimensions { width: 700, height: 600 }

useAuthRequest()

用于跨平台工作的有态度的 Facebook 身份验证的钩子。

¥A hook used for opinionated Facebook authentication that works across platforms.

参数

¥Arguments

• 配置（FacebookAuthRequestConfig） - 一个 FacebookAuthRequestConfig 对象，其中包含应支持的每个平台的客户端 ID。

  ¥config (FacebookAuthRequestConfig) - A FacebookAuthRequestConfig object with client IDs for each platform that should be supported.

• 重定向 Uri 选项 (AuthSessionRedirectUriOptions) - 用于构造重定向 URI（传递到 makeRedirectUri()）的可选属性。

  ¥redirectUriOptions (AuthSessionRedirectUriOptions) - Optional properties used to construct the redirect URI (passed to makeRedirectUri()).

返回

¥Returns

• 请求（FacebookAuthRequest | null） - 可用于提示用户授权的 FacebookAuthRequest 实例。这将是 null，直到身份验证请求完成加载。

  ¥request (FacebookAuthRequest | null) - An instance of FacebookAuthRequest that can be used to prompt the user for authorization. This will be null until the auth request has finished loading.

• 响应（AuthSessionResult | null） - 在调用 promptAsync 之前，这是 null。一旦完成，它将返回有关授权的信息。

  ¥response (AuthSessionResult | null) - This is null until promptAsync has been invoked. Once fulfilled it will return information about the authorization.

• 提示异步 (function) - 调用时，Web 浏览器将打开并提示用户进行身份验证。接受 AuthRequestPromptOptions 对象，其中包含有关如何执行提示的选项。

  ¥promptAsync (function) - When invoked, a web browser will open up and prompt the user for authentication. Accepts an AuthRequestPromptOptions object with options about how the prompt will execute.

discovery

包含用于 Facebook 身份验证的发现 URL 的 DiscoveryDocument 对象。

¥A DiscoveryDocument object containing the discovery URLs used for Facebook auth.

高级用法

¥Advanced usage

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

¥Filtering out AuthSession events in Linking handlers

你可能想要处理应用中的入站链接的原因有很多，例如推送通知或只是常规深度链接（你可以在 链接指南 中阅读有关此内容的更多信息）；身份验证重定向只是深层链接的一种类型，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 guide); 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.