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

提示:

示例项目可以在我们的 SDK 仓库中找到。
该示例基于 Next.js App Router。
教程视频可以在我们的 YouTube 频道上观看。

前置条件

一个 Logto Cloud 账号或一个自托管 Logto。
已创建的 Logto 传统应用。

安装

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

npm
pnpm
yarn

npm i @logto/next

pnpm add @logto/next

yarn add @logto/next

集成

准备配置

为 Logto 客户端准备配置：

app/logto.ts
import { LogtoNextConfig } from '@logto/next';

export const logtoConfig: LogtoNextConfig = {
  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',
};

注意：
如果你为 cookieSecret 使用了环境变量（例如 process.env.LOGTO_COOKIE_SECRET），请确保该值至少为 32 个字符。如果不满足此要求，Logto 会在构建或运行时抛出如下错误：

TypeError: Either sessionWrapper or encryptionKey must be provided for CookieStorage

为避免此错误，请确保环境变量已正确设置，或提供一个长度不少于 32 个字符的备用值。

配置重定向 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 部分。

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

处理回调

用户登录后，Logto 会将用户重定向回上面配置的重定向 URI。但要让你的应用正常工作，还需要做一些处理。

我们提供了辅助函数 handleSignIn 用于处理登录回调：

app/callback/route.ts
import { handleSignIn } from '@logto/next/server-actions';
import { redirect } from 'next/navigation';
import { NextRequest } from 'next/server';
import { logtoConfig } from '../logto';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  await handleSignIn(logtoConfig, searchParams);

  redirect('/');
}

在 Next.js App Router 中，事件在客户端组件中处理，因此我们需要先创建两个组件：SignIn 和 SignOut。

app/sign-in.tsx
'use client';

type Props = {
  onSignIn: () => Promise<void>;
};

const SignIn = ({ onSignIn }: Props) => {
  return (
    <button
      onClick={() => {
        onSignIn();
      }}
    >
      登录
    </button>
  );
};

export default SignIn;

app/sign-out.tsx
'use client';

type Props = {
  onSignOut: () => Promise<void>;
};

const SignOut = ({ onSignOut }: Props) => {
  return (
    <button
      onClick={() => {
        onSignOut();
      }}
    >
      登出
    </button>
  );
};

export default SignOut;

记得在文件顶部添加 'use client'，以表明这些组件是客户端组件。

将按钮添加到首页

备注:

不允许在客户端组件中定义内联的 "use server" 注释的服务器操作。我们必须通过服务器组件通过 props 传递它。

现在让我们在首页添加登录和登出按钮。需要在需要时调用 SDK 中的服务端操作。为此，可以使用 getLogtoContext 获取认证 (Authentication) 状态。

app/page.tsx
import { getLogtoContext, signIn, signOut } from '@logto/next/server-actions';
import SignIn from './sign-in';
import SignOut from './sign-out';
import { logtoConfig } from './logto';

export default async function Home() {
  const { isAuthenticated, claims } = await getLogtoContext(logtoConfig);

  return (
    <nav>
      {isAuthenticated ? (
        <p>
          你好, {claims?.sub},
          <SignOut
            onSignOut={async () => {
              'use server';

              await signOut(logtoConfig);
            }}
          />
        </p>
      ) : (
        <p>
          <SignIn
            onSignIn={async () => {
              'use server';

              await signIn(logtoConfig);
            }}
          />
        </p>
      )}
    </nav>
  );
}

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

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

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

获取用户信息

显示用户信息

当用户登录时，getLogtoContext() 的返回值将是一个包含用户信息的对象。你可以在应用中显示这些信息：

app/page.tsx
import { getLogtoContext } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
  const { claims } = await getLogtoContext(logtoConfig);

  return (
    <main>
      {claims && (
        <div>
          <h2>声明：</h2>
          <table>
            <thead>
              <tr>
                <th>名称</th>
                <th>值</th>
              </tr>
            </thead>
            <tbody>
              {Object.entries(claims).map(([key, value]) => (
                <tr key={key}>
                  <td>{key}</td>
                  <td>{String(value)}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}
    </main>
  );
}

在 API 路由处理器中获取用户信息

你也可以在 API 路由处理器中获取用户信息：

app/api/profile/route.ts
import { getLogtoContext } from '@logto/next/server-actions';
import { logtoConfig } from '../../logto';

export const dynamic = 'force-dynamic';

export async function GET() {
  const { claims } = await getLogtoContext(logtoConfig);

  return Response.json({ claims });
}

请求额外的声明

你可能会发现从 getLogtoContext 返回的对象中缺少一些用户信息。这是因为 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。

要请求额外的权限，你可以在初始化 Logto 客户端时配置参数：

app/logto.ts
import { UserScope, LogtoNextConfig } from '@logto/next';

export const logtoConfig: LogtoNextConfig = {
  scopes: [UserScope.Email, UserScope.Phone], // 根据需要添加更多权限
  // ...其他配置
});

然后你可以在上下文响应中访问额外的声明：

app/page.tsx
export default async function Home() {
  const { claims: { email } = {}, } = await getLogtoContext(logtoConfig);

  return (
    <div>
      {email && <p>电子邮件：{email}</p>}
    </div>
  );
};

export default Home;

需要网络请求的声明

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

app/page.tsx
export default async function Home() {
const { userInfo } = await getLogtoContext(logtoConfig, { fetchUserInfo: true });
return (
  <div>
    {userInfo && <p>电子邮件：{userInfo.email}</p>}
  </div>
);
};

export default Home;

通过配置 fetchUserInfo，SDK 将在用户登录后通过请求 userinfo 端点来获取用户信息，并且一旦请求完成，userInfo 将可用。

权限和声明

Logto 使用 OIDC 权限 (Scopes) 和声明 (Claims) 约定来定义用于从 ID 令牌 (ID token) 和 OIDC userinfo 端点获取用户信息的权限 (Scopes) 和声明 (Claims)。"scope" 和 "claim" 都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。

对于标准 OIDC 声明 (Claims)，其在 ID 令牌 (ID token) 中的包含严格由所请求的权限 (Scopes) 决定。扩展声明 (Claims)（如 custom_data 和 organizations）可以通过自定义 ID 令牌 (Custom ID token) 设置额外配置到 ID 令牌 (ID token) 中。

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

标准 OIDC 权限 (Scopes)

openid（默认）

Claim name	Type	Description
sub	`string`	用户的唯一标识符

profile（默认）

Claim name	Type	Description
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）以来的毫秒数表示。

其他标准声明 (Claims) 包括 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 和 locale 也会包含在 profile 权限 (Scope) 中，无需请求 userinfo 端点。与上表声明 (Claims) 不同的是，这些声明 (Claims) 仅在其值不为空时返回，而上表声明 (Claims) 的值为空时会返回 null。

备注:

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

email

Claim name	Type	Description
email	`string`	用户的电子邮件地址
email_verified	`boolean`	电子邮件地址是否已被验证

phone

Claim name	Type	Description
phone_number	`string`	用户的电话号码
phone_number_verified	`boolean`	电话号码是否已被验证

address

关于 address 声明 (Claim) 的详细信息，请参阅 OpenID Connect Core 1.0。

信息:

带有 （默认） 标记的权限 (Scopes) 总是由 Logto SDK 请求。当请求相应权限 (Scope) 时，标准 OIDC 权限 (Scopes) 下的声明 (Claims) 总是包含在 ID 令牌 (ID token) 中——无法关闭。

扩展权限 (Scopes)

以下权限 (Scopes) 由 Logto 扩展，并将通过 userinfo 端点返回声明 (Claims)。这些声明 (Claims) 也可以通过控制台 > 自定义 JWT 配置为直接包含在 ID 令牌 (ID token) 中。详见自定义 ID 令牌 (ID token)。

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	`object`	用户的自定义数据

identities

Claim name	Type	Description	Included in ID token by default
identities	`object`	用户关联的身份
sso_identities	`array`	用户关联的 SSO 身份

roles

Claim name	Type	Description	Included in ID token by default
roles	`string[]`	用户的角色 (Roles)	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	`string[]`	用户所属的组织 (Organizations) ID	✅
organization_data	`object[]`	用户所属的组织 (Organizations) 数据

备注:

这些组织 (Organizations) 声明 (Claims) 也可以在使用不透明令牌 (Opaque token) 时通过 userinfo 端点获取。但不透明令牌 (Opaque tokens) 不能作为组织令牌 (Organization tokens) 用于访问组织专属资源。详见不透明令牌 (Opaque token) 与组织 (Organizations)。

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	`string[]`	用户所属组织 (Organizations) 的角色 (Roles)，格式为 `<organization_id>:<role_name>`	✅

API 资源

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

配置 Logto 客户端

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

app/logto.ts
export const 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 时添加它们：

app/logto.ts
export const 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 配置中：

app/logto.ts
export const 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)，你可以使用 获取访问令牌 (getAccessToken) 方法：

备注:

不允许在客户端组件中定义内联的 "use server" 注释的服务器操作。我们必须通过服务器组件通过 props 传递它。

app/page.ts
import { getAccessToken } from '@logto/next/server-actions';
import { logtoConfig } from './logto';
import GetAccessToken from './get-access-token';

export default async function Home() {
  return (
    <main>
      <GetAccessToken
        onGetAccessToken={async () => {
          'use server';

          return getAccessToken(logtoConfig, 'https://shopping.your-app.com/api');
        }}
      />
    </main>
  );
}

app/get-access-token.ts
'use client';

type Props = {
  onGetAccessToken: () => Promise<string>;
};

const GetAccessToken = ({ onGetAccessToken }: Props) => {
  return (
    <button
      onClick={async () => {
        const token = await onGetAccessToken();
        console.log(token);
      }}
    >
      获取访问令牌 (访问控制台日志)
    </button>
  );
};

export default GetAccessToken;

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

如果你需要在服务端组件中获取访问令牌 (Access token)，可以使用 getAccessTokenRSC 函数：

app/page.tsx
// 引入 getAccessTokenRSC
import { getAccessTokenRSC } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
  const accessToken = await getAccessTokenRSC(logtoConfig, 'https://shopping.your-app.com/api');

  return (
    <main>
      <p>访问令牌 (Access token): {accessToken}</p>
    </main>
  );
}

RSC 令牌缓存限制:

React Server Components 无法写入 Cookie（Next.js 限制）。虽然 getAccessTokenRSC 仍会使用刷新令牌 (Refresh token) 刷新过期的访问令牌 (Access token)，但新的访问令牌 (Access token) 不会持久化到会话 Cookie。这意味着如果缓存的令牌已过期，每个 RSC 请求都可能触发令牌刷新。

解决方案：

结合 Server Actions 使用客户端组件 —— 通过 Server Actions 从客户端组件调用 getAccessToken，这样可以更新 Cookie。
使用外部会话存储 —— 配置带有 Redis/KV 存储的 sessionWrapper。Cookie 只存储固定的会话 ID，而令牌数据存储在外部存储中，使 RSC 能够持久化刷新后的令牌。详见下方使用外部会话存储。

获取组织令牌 (Organization tokens)

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

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

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

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

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

备注:

不允许在客户端组件中定义内联的 "use server" 注释的服务器操作。我们必须通过服务器组件通过 props 传递它。

app/page.ts
import { getOrganizationToken } from '@logto/next/server-actions';
import { logtoConfig } from './logto';
import GetOrganizationToken from './get-organization-token';

export default async function Home() {
  return (
    <main>
      <GetOrganizationToken
        onGetOrganizationToken={async () => {
          'use server';

          return getOrganizationToken(logtoConfig, 'organization-id');
        }}
      />
    </main>
  );
}

app/get-organization-token.ts
'use client';

type Props = {
  onGetOrganizationToken: () => Promise<string>;
};

const GetOrganizationToken = ({ onGetOrganizationToken }: Props) => {
  return (
    <button
      onClick={async () => {
        const token = await onGetOrganizationToken();
        console.log(token);
      }}
    >
      获取组织令牌 (Organization token) （查看控制台日志）
    </button>
  );
};

export default GetOrganizationToken;

如果你需要在服务端组件中获取组织令牌 (Organization token)，可以使用 getOrganizationTokenRSC 函数：

app/page.tsx
// 引入 getOrganizationTokenRSC
import { getOrganizationTokenRSC } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
  const token = await getOrganizationTokenRSC(logtoConfig, 'organization-id');

  return (
    <main>
      <p>组织令牌 (Organization token): {token}</p>
    </main>
  );
}

RSC 令牌缓存限制:

与 getAccessTokenRSC 一样，刷新后的组织令牌 (Organization token) 不会在 RSC 中持久化。详见上方解决方案。

使用外部会话存储

SDK 默认使用 Cookie 存储加密的会话数据。这种方式安全、无需额外基础设施，并且在像 Vercel 这样的无服务器环境中表现尤为出色。

然而，有时你可能需要将会话数据存储在外部。例如，当你的会话数据变得过大，不适合存储在 Cookie 中，尤其是在你需要同时维护多个活跃的组织 (Organization) 会话时。在这些情况下，你可以通过 sessionWrapper 选项实现外部会话存储：

import { MemorySessionWrapper } from './storage';

export const config = {
  // ...
  sessionWrapper: new MemorySessionWrapper(),
};

import { randomUUID } from 'node:crypto';

import { type SessionWrapper, type SessionData } from '@logto/next';

export class MemorySessionWrapper implements SessionWrapper {
  private readonly storage = new Map<string, unknown>();
  private currentSessionId?: string;

  async wrap(data: unknown, _key: string): Promise<string> {
    // 如果已有会话 ID，则复用；仅为首次用户生成新 ID。
    // 这对于无法更新 Cookie 的环境（如 React Server Components）非常重要，
    // 因为 Cookie 中的会话 ID 必须保持稳定，而外部存储中的数据可以更新。
    const sessionId = this.currentSessionId ?? randomUUID();
    this.currentSessionId = sessionId;
    this.storage.set(sessionId, data);
    return sessionId;
  }

  async unwrap(value: string, _key: string): Promise<SessionData> {
    if (!value) {
      return {};
    }

    // 存储会话 ID，以便在 wrap() 中复用
    this.currentSessionId = value;
    const data = this.storage.get(value);
    return data ?? {};
  }
}

上述实现使用了简单的内存存储。在生产环境中，你可能需要使用更持久的存储方案，比如 Redis 或数据库。

提示:

signIn 辅助函数会修改 Cookie 以建立登录会话，因此不能直接在 React Server Component (RSC) 中调用。要在 RSC 检测到未授权用户时自动触发登录，请在专用路由处理器中调用 signIn 并重定向到该路由。

app/sign-in/route.ts
import { signIn } from '@logto/next/server-actions';
import { logtoConfig } from '../../logto';

export async function GET() {
  await signIn(logtoConfig);
}

app/protected/page.tsx
import { getLogtoContext } from '@logto/next/server-actions';
import { redirect } from 'next/navigation';
import { logtoConfig } from '../logto';

export default async function ProtectedPage() {
  const { isAuthenticated } = await getLogtoContext(logtoConfig);

  if (!isAuthenticated) {
    redirect('/sign-in');
  }

  return <div>受保护内容</div>;
}

延伸阅读

终端用户流程：认证 (Authentication) 流程、账户流程和组织流程配置连接器 (Connectors) 授权 (Authorization)

前置条件​

安装​

集成​

准备配置​

配置重定向 URI​

关于基于重定向的登录​

配置重定向 URI​

处理回调​

实现登录与登出​

实现登录与登出按钮​

将按钮添加到首页​

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

获取用户信息​

显示用户信息​

在 API 路由处理器中获取用户信息​

请求额外的声明​

需要网络请求的声明​

权限和声明​

标准 OIDC 权限 (Scopes)​

扩展权限 (Scopes)​

API 资源​

配置 Logto 客户端​

获取 API 资源的访问令牌 (Access token)​

获取组织令牌 (Organization tokens)​

使用外部会话存储​

未授权时自动重定向到登录​

延伸阅读​

前置条件

安装

集成

准备配置

配置重定向 URI

关于基于重定向的登录

配置重定向 URI

处理回调

实现登录与登出

实现登录与登出按钮

将按钮添加到首页

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

获取用户信息

显示用户信息

在 API 路由处理器中获取用户信息

请求额外的声明

需要网络请求的声明

权限和声明

标准 OIDC 权限 (Scopes)

扩展权限 (Scopes)

API 资源

配置 Logto 客户端

获取 API 资源的访问令牌 (Access token)

获取组织令牌 (Organization tokens)

使用外部会话存储

未授权时自动重定向到登录

延伸阅读