跳到主要内容

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

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

前提条件

安装

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

npm i @logto/rn
npm i 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>
);

实现登录和登出

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

  1. 你的应用调用登录方法。
  2. 用户被重定向到 Logto 登录页面。对于原生应用,将打开系统浏览器。
  3. 用户登录并被重定向回你的应用(配置为重定向 URI)。
关于基于重定向的登录
  1. 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议,Logto 强制执行严格的安全措施以保护用户登录。
  2. 如果你有多个应用程序,可以使用相同的身份提供商 (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>
);
};

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

现在,你可以测试你的应用程序:

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

获取用户信息

显示用户信息

要显示用户的信息,你可以使用 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):openidprofileoffline_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

声明名称类型描述需要用户信息吗?
substring用户的唯一标识符

profile

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

其他 标准声明 包括 family_namegiven_namemiddle_namenicknamepreferred_usernameprofilewebsitegenderbirthdatezoneinfolocale 也将包含在 profile 权限中,而无需请求用户信息端点。与上述声明的区别在于,这些声明只有在其值不为空时才会返回,而上述声明在值为空时将返回 null

备注:

与标准声明不同,created_atupdated_at 声明使用毫秒而不是秒。

email

声明名称类型描述需要用户信息吗?
emailstring用户的电子邮件地址
email_verifiedboolean电子邮件地址是否已验证

phone

声明名称类型描述需要用户信息吗?
phone_numberstring用户的电话号码
phone_number_verifiedboolean电话号码是否已验证

address

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

custom_data

声明名称类型描述需要用户信息吗?
custom_dataobject用户的自定义数据

identities

声明名称类型描述需要用户信息吗?
identitiesobject用户的关联身份
sso_identitiesarray用户的关联 SSO 身份

urn:logto:scope:organizations

声明名称类型描述需要用户信息吗?
organizationsstring[]用户所属的组织 ID
organization_dataobject[]用户所属的组织数据

urn:logto:scope:organization_roles

声明名称类型描述需要用户信息吗?
organization_rolesstring[]用户所属的组织角色,格式为 <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:readshopping:write 权限,而 https://store.your-app.com/api 资源具有 store:readstore: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 资源,它将请求 readwrite 权限。

备注:

请求 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