为你的 Express 应用添加认证 (Authentication)

提示

• 示例项目可以在我们的 SDK 仓库 中找到。

前提条件

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

安装

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

npm

npm i @logto/express cookie-parser express-session

pnpm

pnpm add @logto/express cookie-parser express-session

yarn

yarn add @logto/express cookie-parser express-session

集成

准备配置和所需的中间件

为 Logto 客户端准备配置：

app.ts

import { LogtoExpressConfig } from '@logto/express';

const config: LogtoExpressConfig = {
  appId: '<your-application-id>',
  appSecret: '<your-application-secret>',
  endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
  baseUrl: '<your-express-app-base-url>', // 例如 http://localhost:3000
};

SDK 需要预先配置 express-session。

app.ts

import cookieParser from 'cookie-parser';
import session from 'express-session';

app.use(cookieParser());
app.use(
  session({
    secret: 'random_session_key', // 替换为你自己的密钥
    cookie: { maxAge: 14 * 24 * 60 * 60 * 1000 }, // 毫秒
  })
);

配置重定向 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/callback。

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

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

注册路由

SDK 提供了一个辅助函数 handleAuthRoutes 来注册 3 个路由：

1. /logto/sign-in: 使用 Logto 登录。
2. /logto/sign-in-callback: 处理登录回调。
3. /logto/sign-out: 使用 Logto 登出。

将以下代码添加到你的应用中：

app.ts

import { handleAuthRoutes } from '@logto/express';

app.use(handleAuthRoutes(config));

实现登录和登出

注册路由后，现在让我们在主页中实现登录和登出按钮。我们需要在需要时将用户重定向到登录或登出路由。为此，使用 withLogto 将认证 (Authentication) 状态注入到 req.user。

app.ts

import { withLogto } from '@logto/express';

app.get('/', withLogto(config), (req, res) => {
  res.setHeader('content-type', 'text/html');

  if (req.user.isAuthenticated) {
    res.end(`<div>Hello ${req.user.claims?.sub}, <a href="/logto/sign-out">Sign Out</a></div>`);
  } else {
    res.end('<div><a href="/logto/sign-in">Sign In</a></div>');
  }
});

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

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

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

获取用户信息

显示用户信息

当用户登录时，req.user 的值将是一个包含用户信息的对象。你可以在你的应用中显示这些信息：

app.ts

import { withLogto } from '@logto/express';

app.get('/', withLogto(config), (req, res) => {
  response.json(request.user.claims);
});

请求额外的声明 (Claims)

你可能会发现从 req.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)，你可以在配置中添加权限：

app.ts

import { LogtoExpressConfig, UserScope } from '@logto/express';

const config: LogtoExpressConfig = {
  scopes: [UserScope.Email, UserScope.Phone], // 根据需要添加更多权限
  // ...other configs
};

然后你可以在 req.user 对象中访问额外的声明：

app.ts

import { withLogto } from '@logto/express';

app.get('/', withLogto(config), (req, res) => {
  response.end(`User email: ${req.user.claims.email}`);
});

需要网络请求的声明

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

app.ts

const config: LogtoExpressConfig = {
fetchUserInfo: true,
// ...other configs
};

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

权限和声明

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

声明名称	类型	描述	需要用户信息吗？
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 资源和组织 (Organizations)

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

配置 Logto 客户端

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

app.ts

import { UserScope } from '@logto/express';

const config: LogtoExpressConfig = {
  // ...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 时添加它们：

app.ts

import { UserScope } from '@logto/express';

const config: LogtoExpressConfig = {
  // ...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.ts

import { UserScope } from '@logto/express';

const config: LogtoExpressConfig = {
  // ...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 方法：

app.ts

app.get(
  '/fetch-access-token',
  withLogto({
    ...config,
    getAccessToken: true,
    resource: 'https://shopping.your-app.com/api',
  }),
  (request, response) => {
    console.log(request.user.accessToken);
    response.json(request.user);
  }
);

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

获取组织令牌

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

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

app.ts

import { UserScope } from '@logto/express';

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

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

app.ts

app.get(
  '/fetch-organization-token',
  withLogto({
    ...config,
    getOrganizationToken: true,
  }),
  (request, response) => {
    response.json(request.user.organizationTokens);
  }
);

延伸阅读

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