为你的 Next.js (Pages Router) 应用添加认证
- 示例项目可以在我们的 SDK 仓库 中找到。
- 该示例基于 Next.js Pages Router。
前提条件
- 一个 Logto Cloud 账户或一个 自托管 Logto。
- 一个 Logto 传统应用已创建。
安装
通过你喜欢的包管理器安装 Logto SDK:
- npm
- pnpm
- yarn
npm i @logto/next
pnpm add @logto/next
yarn add @logto/next
集成
初始化 LogtoClient
导入并初始化 LogtoClient:
import LogtoClient from '@logto/next';
export const logtoClient = new LogtoClient({
appId: '<your-application-id>',
appSecret: '<your-app-secret-copied-from-console>',
endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
baseUrl: 'http://localhost:3000',
cookieSecret: 'complex_password_at_least_32_characters_long',
cookieSecure: process.env.NODE_ENV === 'production',
});
配置重定向 URI
在我们深入细节之前,这里是终端用户体验的快速概述。登录过程可以简化如下:
- 你的应用调用登录方法。
- 用户被重定向到 Logto 登录页面。对于原生应用,将打开系统浏览器。
- 用户登录并被重定向回你的应用(配置为重定向 URI)。
关于基于重定向的登录
- 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议,Logto 强制执行严格的安全措施以保护用户登录。
- 如果你有多个应用程序,可以使用相同的身份提供商 (IdP)(日志 (Logto))。一旦用户登录到一个应用程序,当用户访问另一个应用程序时,Logto 将自动完成登录过程。
要了解有关基于重定向的登录的原理和好处的更多信息,请参阅 Logto 登录体验解释。
在以下代码片段中,我们假设你的应用程序运行在 http://localhost:3000/
。
配置重定向 URI
切换到 Logto Console 的应用详情页面。添加一个重定向 URI http://localhost:3000/api/logto/sign-in-callback
。
就像登录一样,用户应该被重定向到 Logto 以注销共享会话。完成后,最好将用户重定向回你的网站。例如,添加 http://localhost:3000/
作为注销后重定向 URI 部分。
然后点击“保存”以保存更改。
准备 API 路由
准备 API 路由 以连接 Logto。
返回到你的 IDE /编辑器,使用以下代码首先实现 API 路由:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.handleAuthRoutes();
这将自动创建 4 个路由:
/api/logto/sign-in
: 使用 Logto 登录。/api/logto/sign-in-callback
: 处理登录回调。/api/logto/sign-out
: 使用 Logto 登出。/api/logto/user
: 检查用户是否通过 Logto 认证,如果是,返回用户信息。
实现登录和登出
我们已经准备好了 API 路由,现在让我们在你的主页上实现登录和登出按钮。我们需要在需要时将用户重定向到登录或登出路由。为此,使用 useSWR
从 /api/logto/user
获取认证状态。
查看 此指南 以了解有关 useSWR
的更多信息。
import { type LogtoContext } from '@logto/next';
import useSWR from 'swr';
const Home = () => {
const { data } = useSWR<LogtoContext>('/api/logto/user');
return (
<nav>
{data?.isAuthenticated ? (
<p>
你好, {data.claims?.sub},
<button
onClick={() => {
window.location.assign('/api/logto/sign-out');
}}
>
登出
</button>
</p>
) : (
<p>
<button
onClick={() => {
window.location.assign('/api/logto/sign-in');
}}
>
登录
</button>
</p>
)}
</nav>
);
};
export default Home;
检查点:测试你的应用程序
现在,你可以测试你的应用程序:
- 运行你的应用程序,你将看到登录按钮。
- 点击登录按钮,SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
- 登录后,你将被重定向回你的应用程序,并看到登出按钮。
- 点击登出按钮以清除本地存储并登出。
获取用户信息
显示用户信息
当用户登录时,有三种方式获取用户信息。
通过前端的 API 请求
import { type LogtoContext } from '@logto/next';
import { useMemo } from 'react';
import useSWR from 'swr';
const Home = () => {
const { data } = useSWR<LogtoContext>('/api/logto/user');
const claims = useMemo(() => {
if (!data?.isAuthenticated || !data.claims) {
return null;
}
return (
<div>
<h2>声明 (Claims):</h2>
<table>
<thead>
<tr>
<th>名称</th>
<th>值</th>
</tr>
</thead>
<tbody>
{Object.entries(data.claims).map(([key, value]) => (
<tr key={key}>
<td>{key}</td>
<td>{String(value)}</td>
</tr>
))}
</tbody>
</table>
</div>
);
}, [data]);
return (
<div>
{claims}
</div>
);
};
export default Home;
通过 getServerSideProps
import { LogtoContext } from '@logto/next';
import { logtoClient } from '../../libraries/logto';
type Props = {
user: LogtoContext;
};
const Home = ({ user }: Props) => {
const claims = useMemo(() => {
if (!user.isAuthenticated || !user.claims) {
return null;
}
return (
<div>
<h2>声明 (Claims):</h2>
<table>
<thead>
<tr>
<th>名称</th>
<th>值</th>
</tr>
</thead>
<tbody>
{Object.entries(user.claims).map(([key, value]) => (
<tr key={key}>
<td>{key}</td>
<td>{String(value)}</td>
</tr>
))}
</tbody>
</table>
</div>
);
}, [user]);
return (
<div>
{claims}
</div>
);
};
export default Home;
export const getServerSideProps = logtoClient.withLogtoSsr(async function ({ request }) {
const { user } = request;
return {
props: { user },
};
});
在 API 路由中
import { logtoClient } from '../../libraries/logto';
export default logtoClient.withLogtoApiRoute((request, response) => {
if (!request.user.isAuthenticated) {
response.status(401).json({ message: 'Unauthorized' });
return;
}
response.json({
data: request.user.claims,
});
});
请求额外的声明 (Claims)
你可能会发现从 /api/logto/user
返回的对象中缺少一些用户信息。这是因为 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 客户端时配置参数:
import LogtoClient, { UserScope } from '@logto/next';
export const logtoClient = new LogtoClient({
scopes: [UserScope.Email, UserScope.Phone], // 如有需要可添加更多权限
// ...other configs
});
然后你可以在上下文响应中访问额外的声明 (Claims):
const Home = () => {
const { data } = useSWR<LogtoContext>('/api/logto/user');
const email = data?.claims?.email;
return (
<div>
{email && <p>Email: {email}</p>}
</div>
);
};
export default Home;
需要网络请求的声明
为了防止 ID 令牌 (ID token) 过大,一些声明需要通过网络请求来获取。例如,即使在权限中请求了 custom_data
声明,它也不会包含在用户对象中。要访问这些声明,你可以配置 fetchUserInfo
选项:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.handleAuthRoutes({ fetchUserInfo: true });
fetchUserInfo
,SDK 将在用户登录后通过请求 userinfo 端点 来获取用户信息,并且一旦请求完成,req.user.userInfo
将可用。
手动获取用户信息
你可以在 API 路由中手动获取用户信息:
import { logtoClient } from '../../libraries/logto';
export default logtoClient.withLogtoApiRoute(
(request, response) => {
if (!request.user.isAuthenticated) {
response.status(401).json({ message: 'Unauthorized' });
return;
}
response.json({
userInfo: request.user.userInfo,
});
},
{ fetchUserInfo: true }
);
权限 (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 时添加它们:
export const logtoClient = new LogtoClient({
// ...other configs
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // 添加 API 资源
});
每个 API 资源都有其自己 的权限(权限)。
例如,https://shopping.your-app.com/api
资源具有 shopping:read
和 shopping:write
权限,而 https://store.your-app.com/api
资源具有 store:read
和 store:write
权限。
要请求这些权限,你可以在应用中配置 Logto 时添加它们:
export const logtoClient = new LogtoClient({
// ...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 配置中:
export const logtoClient = new LogtoClient({
// ...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 资源的访问令牌
要获取特定 API 资源的访问令牌 (access token),你可以使用 getAccessToken
方法:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.withLogtoApiRoute(
(request, response) => {
if (!request.user.isAuthenticated) {
response.status(401).json({ message: 'Unauthorized' });
return;
}
// 在这里获取访问令牌
console.log(request.user.accessToken);
response.json(request.user);
},
{
getAccessToken: true,
resource: 'https://shopping.your-app.com/api',
}
);
此方法将返回一个 JWT 访问令牌 (access token),当用户具有相关权限时,可以用来访问 API 资源。如果当前缓存的访问令牌 (access token) 已过期,此方法将自动尝试使用刷新令牌 (refresh token) 获取新的访问令牌 (access token)。
获取组织令牌
如果你对组织不熟悉,请阅读 🏢 组织(多租户) 以开始了解。
在配置 Logto 客户端时,你需要添加 用户权限.组织 (UserScope.Organizations)
权限:
import { UserScope } from '@logto/next';
export const logtoClient = new LogtoClient({
// ...other configs
scopes: [UserScope.Organizations],
});
用户登录后,你可以获取用户的组织令牌:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.withLogtoApiRoute(async (request, response) => {
if (!request.user.isAuthenticated) {
response.status(401).json({ message: 'Unauthorized' });
return;
}
const client = await logtoClient.createNodeClientFromNextApi(request, response);
// 组织 ID 存储在用户的 ID 令牌声明中
const { organizations = [] } = await client.getIdTokenClaims();
const organizationTokens = await Promise.all(
organizations.map(async (organizationId) => client.getOrganizationToken(organizationId))
);
const organizationClaims = await Promise.all(
organizations.map(async (organizationId) => client.getOrganizationTokenClaims(organizationId))
);
// 使用组织令牌和 / 或声明进行操作
response.json({
organizations,
});
});
边缘运行时
在 @logto/[email protected]
中添加
如果你想使用 edge runtime API 路由,你需要使用子包 @logto/next/edge
。
import LogtoClient from '@logto/next/edge';
export const logtoClient = new LogtoClient({
appId: '<your-application-id>',
appSecret: '<your-app-secret-copied-from-console>',
endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
baseUrl: '<your-nextjs-app-base-url>', // 例如 http://localhost:3000
cookieSecret: 'complex_password_at_least_32_characters_long',
cookieSecure: process.env.NODE_ENV === 'production',
resources: ['<your-api-resource>'],
});
然后在 API 路由中将运行时设置为 experimental-edge
或 edge
。
import { logtoClient } from '../../../../libraries/logto';
export default logtoClient.handleSignIn();
export const config = {
runtime: 'experimental-edge',
};
查看 next-sample 以获取完整示例。