跳到主要内容

为你的 Next.js (Pages Router) 应用添加认证

提示:

前提条件

安装

通过你喜欢的包管理器安装 Logto SDK:

npm i @logto/next

集成

初始化 LogtoClient

导入并初始化 LogtoClient:

libraries/logto.ts
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

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

  1. 你的应用调用登录方法。
  2. 用户被重定向到 Logto 登录页面。对于原生应用,将打开系统浏览器。
  3. 用户登录并被重定向回你的应用(配置为重定向 URI)。
关于基于重定向的登录
  1. 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议,Logto 强制执行严格的安全措施以保护用户登录。
  2. 如果你有多个应用程序,可以使用相同的身份提供商 (IdP)(日志 (Logto))。一旦用户登录到一个应用程序,当用户访问另一个应用程序时,Logto 将自动完成登录过程。

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


备注:

在以下代码片段中,我们假设你的应用程序运行在 http://localhost:3000/

配置重定向 URI

切换到 Logto Console 的应用详情页面。添加一个重定向 URI http://localhost:3000/api/logto/sign-in-callback

Logto Console 中的重定向 URI

就像登录一样,用户应该被重定向到 Logto 以注销共享会话。完成后,最好将用户重定向回你的网站。例如,添加 http://localhost:3000/ 作为注销后重定向 URI 部分。

然后点击“保存”以保存更改。

准备 API 路由

准备 API 路由 以连接 Logto。

返回到你的 IDE /编辑器,使用以下代码首先实现 API 路由:

pages/api/logto/[action].ts
import { logtoClient } from '../../../libraries/logto';

export default logtoClient.handleAuthRoutes();

这将自动创建 4 个路由:

  1. /api/logto/sign-in: 使用 Logto 登录。
  2. /api/logto/sign-in-callback: 处理登录回调。
  3. /api/logto/sign-out: 使用 Logto 登出。
  4. /api/logto/user: 检查用户是否通过 Logto 认证,如果是,返回用户信息。

实现登录和登出

我们已经准备好了 API 路由,现在让我们在你的主页上实现登录和登出按钮。我们需要在需要时将用户重定向到登录或登出路由。为此,使用 useSWR/api/logto/user 获取认证状态。

查看 此指南 以了解有关 useSWR 的更多信息。

/pages/index.tsx
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;

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

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

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

获取用户信息

显示用户信息

当用户登录时,有三种方式获取用户信息。

通过前端的 API 请求

pages/index.tsx
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

pages/index.tsx
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 路由中

pages/api/get-user-info.ts
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):openidprofileoffline_access

要请求额外的权限 (Scopes),你可以在初始化 Logto 客户端时配置参数:

libraries/logto.ts
import LogtoClient, { UserScope } from '@logto/next';

export const logtoClient = new LogtoClient({
scopes: [UserScope.Email, UserScope.Phone], // 如有需要可添加更多权限
// ...other configs
});

然后你可以在上下文响应中访问额外的声明 (Claims):

pages/index.tsx
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 选项

pages/index.tsx
import { logtoClient } from '../../../libraries/logto';

export default logtoClient.handleAuthRoutes({ fetchUserInfo: true });
通过配置 fetchUserInfo,SDK 将在用户登录后通过请求 userinfo 端点 来获取用户信息,并且一旦请求完成,req.user.userInfo 将可用。

手动获取用户信息

你可以在 API 路由中手动获取用户信息:

pages/api/get-user-info.ts
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

声明名称类型描述需要用户信息吗?
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 时添加它们:

libraries/logto.ts
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:readshopping:write 权限,而 https://store.your-app.com/api 资源具有 store:readstore:write 权限。

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

libraries/logto.ts
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 配置中:

libraries/logto.ts
export const logtoClient = new LogtoClient({
// ...other configs
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 方法:

pages/api/get-access-token.ts
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) 权限:

libraries/logto.ts
import { UserScope } from '@logto/next';

export const logtoClient = new LogtoClient({
// ...other configs
scopes: [UserScope.Organizations],
});

用户登录后,你可以获取用户的组织令牌:

pages/api/organizations.ts
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

libraries/logto.ts
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-edgeedge

pages/api/logto/sign-in.ts
import { logtoClient } from '../../../../libraries/logto';

export default logtoClient.handleSignIn();

export const config = {
runtime: 'experimental-edge',
};
备注:

查看 next-sample 以获取完整示例。

延伸阅读

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