为你的 Expo (React Native) 应用程序添加认证 (Authentication)

提示

以下演示基于 Expo ~50.0.6。
示例项目可在我们的 SDK 仓库中找到。

前提条件

一个 Logto Cloud 账户或一个自托管 Logto。
一个已创建的 Logto 原生应用程序。

安装

安装 Logto SDK 和对等依赖项，可以通过你喜欢的包管理器：

npm
Yarn
pnpm

npm i @logto/rn
npm i expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage

yarn add @logto/rn
yarn add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage

pnpm add @logto/rn
pnpm add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage

@logto/rn 包是 Logto 的 SDK。其余的包是它的对等依赖项。它们不能被列为直接依赖项，因为 Expo CLI 要求所有本机模块的依赖项必须直接安装在根项目的 package.json 中。

备注

如果你在 bare React Native app 中安装此软件包，还应遵循这些额外的安装说明。

集成

初始化 Logto 提供者

导入并使用 LogtoProvider 来提供 Logto 上下文：

App.tsx
import { LogtoProvider, LogtoConfig } from '@logto/rn';

const config: LogtoConfig = {
  endpoint: '<your-logto-endpoint>',
  appId: '<your-application-id>',
};

const App = () => (
  <LogtoProvider config={config}>
    <YourAppContent />
  </LogtoProvider>
);

实现登录和登出

在我们深入细节之前，这里是终端用户体验的快速概述。登录过程可以简化如下：

你的应用调用登录方法。
用户被重定向到 Logto 登录页面。对于原生应用，将打开系统浏览器。
用户登录并被重定向回你的应用（配置为重定向 URI）。

关于基于重定向的登录

此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议，Logto 强制执行严格的安全措施以保护用户登录。
如果你有多个应用程序，可以使用相同的身份提供商 (IdP)（日志 (Logto)）。一旦用户登录到一个应用程序，当用户访问另一个应用程序时，Logto 将自动完成登录过程。

要了解有关基于重定向的登录的原理和好处的更多信息，请参阅 Logto 登录体验解释。

切换到 Logto Console 的应用详情页面。添加一个原生重定向 URI（例如，io.logto://callback），然后点击“保存”。

对于 iOS，重定向 URI 方案并不重要，因为 ASWebAuthenticationSession 类会监听重定向 URI，无论它是否已注册。
对于 Android，重定向 URI 方案必须填写在 Expo 的 app.json 文件中，例如：
app.json
```
{
  "expo": {
    "scheme": "io.logto"
  }
}
```

现在回到你的应用，你可以使用 useLogto 钩子来登录和登出：

App.tsx
import { useLogto } from '@logto/rn';
import { Button } from 'react-native';

const Content = () => {
  const { signIn, signOut, isAuthenticated } = useLogto();

  return (
    <div>
      {isAuthenticated ? (
        <Button title="Sign out" onPress={async () => signOut()} />
      ) : (
        // 将重定向 URI 替换为你自己的
        <Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
      )}
    </div>
  );
};

检查点：测试你的应用程序

现在，你可以测试你的应用程序：

运行你的应用程序，你将看到登录按钮。
点击登录按钮，SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
登录后，你将被重定向回你的应用程序，并看到登出按钮。
点击登出按钮以清除本地存储并登出。

获取用户信息

显示用户信息

要显示用户的信息，你可以使用 getIdTokenClaims() 方法：

App.tsx
import { useLogto } from '@logto/rn';
import { Button, Text } from 'react-native';

const Content = () => {
  const { getIdTokenClaims, isAuthenticated } = useLogto();
  const [user, setUser] = useState(null);

  useEffect(() => {
    if (isAuthenticated) {
      getIdTokenClaims().then((claims) => {
        setUser(claims);
      });
    }
  }, [isAuthenticated]);

  return (
    <div>
      {isAuthenticated ? (
        <>
          <Text>{user?.name}</Text>
          <Text>{user?.email}</Text>
          <Button title="Sign out" onPress={async () => signOut()} />
        </>
      ) : (
        <Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
      )}
    </div>
  );
};

请求额外的声明

你可能会发现从 getIdTokenClaims() 返回的对象中缺少一些用户信息。这是因为 OAuth 2.0 和 OpenID Connect (OIDC) 的设计遵循最小权限原则 (PoLP)，而 Logto 是基于这些标准构建的。

默认情况下，返回的声明（Claim）是有限的。如果你需要更多信息，可以请求额外的权限（Scope）以访问更多的声明（Claim）。

信息

“声明（Claim）”是关于主体的断言；“权限（Scope）”是一组声明。在当前情况下，声明是关于用户的一条信息。

以下是权限（Scope）与声明（Claim）关系的非规范性示例：

提示

“sub” 声明（Claim）表示“主体（Subject）”，即用户的唯一标识符（例如用户 ID）。

Logto SDK 将始终请求三个权限（Scope）：openid、profile 和 offline_access。

要请求额外的权限，你可以将权限传递给 LogtoConfig 对象：

App.tsx
import { LogtoProvider, LogtoConfig, UserScope } from '@logto/rn';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations,
  ],
};

const App = () => <LogtoProvider config={config}>{/* Your app content */}</LogtoProvider>;

需要网络请求的声明

为了防止 ID 令牌 (ID token) 过大，一些声明需要通过网络请求来获取。例如，即使在权限中请求了 custom_data 声明，它也不会包含在用户对象中。要访问这些声明，你可以使用 fetchUserInfo() 方法：

App.tsx
import { useLogto } from '@logto/rn';
import { Button, Text } from 'react-native';

const Content = () => {
  const { fetchUserInfo, isAuthenticated } = useLogto();
  const [user, setUser] = useState(null);

  useEffect(() => {
    if (isAuthenticated) {
      fetchUserInfo().then((userInfo) => {
        setUser(userInfo);
      });
    }
  }, [isAuthenticated]);

  return (
    <div>
      {isAuthenticated ? (
        <>
          <Text>{user?.name}</Text>
          <Text>{user?.email}</Text>
          <Button title="退出" onPress={async () => signOut()} />
        </>
      ) : (
        <Button title="登录" onPress={async () => signIn('io.logto://callback')} />
      )}
    </div>
  );
};

该方法将通过请求 userinfo 端点来获取用户信息。要了解更多可用的权限和声明，请参阅权限和声明部分。

权限和声明

Logto 使用 OIDC 权限和声明约定来定义从 ID 令牌和 OIDC 用户信息端点检索用户信息的权限和声明。“权限”和“声明”都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。

以下是支持的权限（Scopes）及其对应的声明（Claims）列表：

openid

声明名称	类型	描述	需要用户信息吗？
sub	`string`	用户的唯一标识符	否

profile

声明名称	类型	描述	需要用户信息吗？
name	`string`	用户的全名	否
username	`string`	用户名	否
picture	`string`	终端用户的个人资料图片的 URL。此 URL 必须指向一个图像文件（例如，PNG、JPEG 或 GIF 图像文件），而不是包含图像的网页。请注意，此 URL 应特别引用适合在描述终端用户时显示的终端用户的个人资料照片，而不是终端用户拍摄的任意照片。	否
created_at	`number`	终端用户创建的时间。时间表示为自 Unix 纪元（1970-01-01T00:00:00Z）以来的毫秒数。	否
updated_at	`number`	终端用户信息最后更新的时间。时间表示为自 Unix 纪元（1970-01-01T00:00:00Z）以来的毫秒数。	否

其他标准声明包括 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 和 locale 也将包含在 profile 权限中，而无需请求用户信息端点。与上述声明的区别在于，这些声明只有在其值不为空时才会返回，而上述声明在值为空时将返回 null。

备注

与标准声明不同，created_at 和 updated_at 声明使用毫秒而不是秒。

email

声明名称	类型	描述	需要用户信息吗？
email	`string`	用户的电子邮件地址	否
email_verified	`boolean`	电子邮件地址是否已验证	否

phone

声明名称	类型	描述	需要用户信息吗？
phone_number	`string`	用户的电话号码	否
phone_number_verified	`boolean`	电话号码是否已验证	否

address

请参阅 OpenID Connect Core 1.0 以获取地址声明的详细信息。

custom_data

声明名称	类型	描述	需要用户信息吗？
custom_data	`object`	用户的自定义数据	是

identities

声明名称	类型	描述	需要用户信息吗？
identities	`object`	用户的关联身份	是
sso_identities	`array`	用户的关联 SSO 身份	是

urn:logto:scope:organizations

声明名称	类型	描述	需要用户信息吗？
organizations	`string[]`	用户所属的组织 ID	否
organization_data	`object[]`	用户所属的组织数据	是

urn:logto:scope:organization_roles

声明名称	类型	描述	需要用户信息吗？
organization_roles	`string[]`	用户所属的组织角色，格式为 `<organization_id>:<role_name>`	否

考虑到性能和数据大小，如果“需要用户信息吗？”为“是”，则表示声明不会显示在 ID 令牌中，而会在用户信息端点响应中返回。

API 资源和组织

我们建议首先阅读 🔐 基于角色的访问控制 (RBAC)，以了解 Logto RBAC 的基本概念以及如何正确设置 API 资源。

配置 Logto 客户端

一旦你设置了 API 资源，就可以在应用中配置 Logto 时添加它们：

App.tsx
import { LogtoConfig } from '@logto/rn';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  // 添加 API 资源
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

每个 API 资源都有其自己的权限（权限）。

例如，https://shopping.your-app.com/api 资源具有 shopping:read 和 shopping:write 权限，而 https://store.your-app.com/api 资源具有 store:read 和 store:write 权限。

要请求这些权限，你可以在应用中配置 Logto 时添加它们：

App.tsx
import { LogtoConfig } from '@logto/rn';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

你可能会注意到权限是与 API 资源分开定义的。这是因为 OAuth 2.0 的资源指示器指定请求的最终权限将是所有目标服务中所有权限的笛卡尔积。

因此，在上述情况下，权限可以从 Logto 中的定义简化，两个 API 资源都可以拥有 read 和 write 权限，而无需前缀。然后，在 Logto 配置中：

App.tsx
import { LogtoConfig } from '@logto/rn';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

对于每个 API 资源，它将请求 read 和 write 权限。

备注

请求 API 资源中未定义的权限是可以的。例如，即使 API 资源没有可用的 email 权限，你也可以请求 email 权限。不可用的权限将被安全地忽略。

成功登录后，Logto 将根据用户的角色向 API 资源发布适当的权限。

获取 API 资源的访问令牌

要获取特定 API 资源的访问令牌 (access token)，你可以使用 getAccessToken 方法：

AccessToken.tsx
import { useLogto } from '@logto/rn';

const AccessToken = () => {
  const { isAuthenticated, getAccessToken } = useLogto();
  const [accessToken, setAccessToken] = useState('');

  useEffect(() => {
    (async () => {
      if (isAuthenticated) {
        const token = await getAccessToken('https://shopping.your-app.com/api');
        setAccessToken(token);
      }
    })();
  }, [isAuthenticated, getAccessToken]);

  return <p>{{ accessToken }}</p>;
};

此方法将返回一个 JWT 访问令牌 (access token)，当用户具有相关权限时，可以用来访问 API 资源。如果当前缓存的访问令牌 (access token) 已过期，此方法将自动尝试使用刷新令牌 (refresh token) 获取新的访问令牌 (access token)。

为用户获取组织令牌

如果你对组织不熟悉，请阅读 🏢 组织（多租户）以开始了解。

在配置 Logto 客户端时，你需要添加 用户权限.组织 (UserScope.Organizations) 权限：

App.tsx
import { LogtoConfig, UserScope } from '@logto/rn';

const config: LogtoConfig = {
  // ...other configs
  scopes: [UserScope.Organizations],
};

用户登录后，你可以获取用户的组织令牌：

Organizations.tsx
import { useLogto } from '@logto/rn';
import { useEffect, useState } from 'react';

const Organizations = () => {
  const { isAuthenticated, getOrganizationToken, getIdTokenClaims } = useLogto();
  const [organizationIds, setOrganizationIds] = useState<string[]>();

  useEffect(() => {
    (async () => {
      if (!isAuthenticated) {
        return;
      }
      const claims = await getIdTokenClaims();

      console.log('ID 令牌声明', claims);
      setOrganizationIds(claims?.organizations);
    })();
  }, [isAuthenticated, getIdTokenClaims]);

  return (
    <section>
      <ul>
        {organizationIds?.map((organizationId) => {
          return (
            <li key={organizationId}>
              <span>{organizationId}</span>
              <button
                type="button"
                onClick={async () => {
                  console.log('原始令牌', await getOrganizationToken(organizationId));
                }}
              >
                获取令牌（查看控制台）
              </button>
            </li>
          );
        })}
      </ul>
    </section>
  );
};

export default Organizations;

疑难解答

无法解析 `@logto/client/shim`

对于 Expo 项目，如果你遇到错误 Unable to resolve "@logto/client/shim" from "node_modules/@logto/rn/lib/index.js"，可以通过在 metro.config.js 文件中添加以下内容来解决：

metro.config.js
const config = {
  // ...
  resolver: {
    unstable_enablePackageExports: true,
  },
};

module.exports = config;

此错误表明 @logto/rn 包无法解析 @logto/client/shim 模块。

由于在 @logto/client 包中使用了节点导出，而 Metro bundler 默认未启用包导出，因此需要手动启用它们。

有关更多详细信息，请参阅 React Native 包导出支持。

延伸阅读

终端用户流程：认证流程、账户流程和组织流程配置连接器保护你的 API

前提条件​

安装​

集成​

初始化 Logto 提供者​

实现登录和登出​

检查点：测试你的应用程序​

获取用户信息​

显示用户信息​

请求额外的声明​

需要网络请求的声明​

权限和声明​

API 资源和组织​

配置 Logto 客户端​

获取 API 资源的访问令牌​

为用户获取组织令牌​

疑难解答​

无法解析 @logto/client/shim​

延伸阅读​