为你的 React 应用添加认证 (Authentication)
本指南将向你展示如何将 Logto 集成到你的 React 应用中。
- 示例项目可在我们的 SDK 仓库 中找到。
- 教程视频可在我们的 YouTube 频道 上观看。
前提条件
- 一个 Logto Cloud 账户或一个 自托管 Logto。
- 在 Logto Console 中创建的单页应用 (SPA)。
- 一个 React 项目。
安装
通过你喜欢的包管理器安装 Logto SDK：
- npm
- pnpm
- yarn
npm i @logto/reactpnpm add @logto/reactyarn add @logto/react集成
初始化 Logto 提供程序
将 LogtoProvider 导入并用于为你的应用提供一个 Logto 上下文：
import { LogtoProvider, LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
appId: '<your-application-id>',
};
const App = () => (
<LogtoProvider config={config}>
<YourAppContent />
</LogtoProvider>
);
配置重定向 URI
在我们深入细节之前，这里是终端用户体验的快速概述。登录过程可以简化如下：
- 你的应用调用登录方法。
- 用户被重定向到 Logto 登录页面。对于原生应用，将打开系统浏览器。
- 用户登录并被重定向回你的应用（配置为重定向 URI）。
关于基于重定向的登录
- 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议，Logto 强制执行严格的安全措施以保护用户登录。
- 如果你有多个应用程序，可以使用相同的身份提供商 (IdP)（日志 (Logto)）。一旦用户登录到一个应用程序，当用户访问另一个应用程序时，Logto 将自动完成登录过程。
要了解有关基于重定向的登录的原理和好处的更多信息，请参阅 Logto 登录体验解释。
在以下代码片段中，我们假设你的应用程序运行在 http://localhost:3000/。
配置重定向 URI
切换到 Logto Console 的应用详情页面。添加一个重定向 URI http://localhost:3000/callback。
就像登录一样，用户应该被重定向到 Logto 以注销共享会话。完成后，最好将用户重定向回你的网站。例如，添加 http://localhost:3000/ 作为注销后重定向 URI 部分。
然后点击“保存”以保存更改。
处理重定向
由于我们使用 http://localhost:3000/callback 作为重定向 URI，现在我们需要正确处理它。
首先，让我们创建一个回调页面：
import { useHandleSignInCallback } from '@logto/react';
const Callback = () => {
const { isLoading } = useHandleSignInCallback(() => {
// 完成后执行某些操作，例如重定向到主页
});
// 当它正在处理中
if (isLoading) {
return <div>正在重定向...</div>;
}
return null;
};
最后插入下面的代码来创建一个不需要认证 (Authentication) 的 /callback 路由：
// 假设使用 react-router
<Route path="/callback" element={<Callback />} />
实现登录和登出
我们提供了两个钩子 useHandleSignInCallback() 和 useLogto()，可以帮助你轻松管理认证 (Authentication) 流程。
在调用 .signIn() 之前，请确保你已在管理控制台中正确配置了重定向 URI。
import { useLogto } from '@logto/react';
const Home = () => {
const { signIn, signOut, isAuthenticated } = useLogto();
return isAuthenticated ? (
<button onClick={signOut}>Sign Out</button>
) : (
<button onClick={() => signIn('http://localhost:3000/callback')}>Sign In</button>
);
};
调用 .signOut() 将清除内存和 localStorage 中所有的 Logto 数据（如果存在）。
检查点：测试你的应用程序
现在，你可以测试你的应用程序：
- 运行你的应用程序，你将看到登录按钮。
- 点击登录按钮，SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
- 登录后，你将被重定向回你的应用程序，并看到登出按钮。
- 点击登出按钮以清除本地存储并登出。
获取用户信息
显示用户信息
要显示用户的信息，你可以使用 getIdTokenClaims() 方法。例如，在你的 Home 页面中：
import { useLogto, type IdTokenClaims } from '@logto/react';
import { useEffect, useState } from 'react';
const Home = () => {
const { isAuthenticated, getIdTokenClaims } = useLogto();
const [user, setUser] = useState<IdTokenClaims>();
useEffect(() => {
(async () => {
if (isAuthenticated) {
const claims = await getIdTokenClaims();
setUser(claims);
}
})();
}, [getIdTokenClaims, isAuthenticated]);
return (
// ...
{isAuthenticated && user && (
<table>
<thead>
<tr>
<th>名称</th>
<th>值</th>
</tr>
</thead>
<tbody>
{Object.entries(user).map(([key, value]) => (
<tr key={key}>
<td>{key}</td>
<td>{typeof value === 'string' ? value : JSON.stringify(value)}</td>
</tr>
))}
</tbody>
</table>
)}
);
}
请求额外的声明 (Claims)
你可能会发现从 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。
要请求额外的权限 (Scopes)，你可以配置 Logto provider 配置：
import { LogtoConfig, UserScope } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
scopes: [
UserScope.Email,
UserScope.Phone,
UserScope.CustomData,
UserScope.Identities,
UserScope.Organizations,
],
};
然后你可以在 getIdTokenClaims() 的返回值中访问额外的声明 (Claims)：
const claims = await getIdTokenClaims();
// 现在你可以访问额外的声明 (Claims) `claims.email`, `claims.phone`, 等。
需要网络请求的声明
为了防止 ID 令牌 (ID token) 过大，一些声明需要通过网络请求来获取。例如，即使在权限中请求了 custom_data 声明，它也不会包含在用户对象中。要访问这些声明，你可以使用 fetchUserInfo() 方法：
const { fetchUserInfo } = useLogto();
const userInfo = await fetchUserInfo();
// 现在你可以访问声明 (Claim) `userInfo.custom_data`
权限 (Scopes) 和声明 (Claims)
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
| 声明名称 | 类型 | 描述 | 需要用户信息吗？ |
|---|---|---|---|
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 时添加它们：
import { LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // 添加 API 资源 (API resources)
};
每个 API 资源都有其自己的权限（权限）。
例如，https://shopping.your-app.com/api 资源具有 shopping:read 和 shopping:write 权限，而 https://store.your-app.com/api 资源具有 store:read 和 store:write 权限。
要请求这些权限，你可以在应用中配置 Logto 时添加它们：
import { LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
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 配置中：
import { LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
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 资源的访问令牌 (Access token)
要获取特定 API 资源的访问令牌 (access token)，你可以使用 获取访问令牌 (Access token) 方法：
import { useLogto } from '@logto/react';
const Home = () => {
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)。
获取组织令牌 (Organization tokens)
如果你对组织不熟悉，请阅读 🏢 组织（多租户） 以开始了解。
在配置 Logto 客户端时，你需要添加 UserScope.Organizations 权限：
import { LogtoConfig, UserScope } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
scopes: [UserScope.Organizations],
};
用户登录后，你可以获取用户的组织令牌：
import { useLogto } from '@logto/react';
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 令牌 (ID token) 声明 (claims)', 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('原始令牌 (token)', await getOrganizationToken(organizationId));
}}
>
获取令牌 (token) （查看控制台）
</button>
</li>
);
})}
</ul>
</section>
);
};
export default Organizations;
将访问令牌 (Access token) 附加到请求头
将令牌放在 HTTP 头的 Authorization 字段中，使用 Bearer 格式（Bearer YOUR_TOKEN），然后你就可以开始了。
Bearer Token 的集成流程可能会根据你使用的框架或请求者而有所不同。选择你自己的方式来应用请求 Authorization 头。