为你的 Passport.js 应用添加认证 (Authentication)

本指南将向你展示如何将 Logto 集成到你的应用中，使用 Passport.js 和 OIDC 策略。

提示

在本指南中，我们假设你已经在项目中设置了带有会话的 Express。如果没有，请访问 Express.js 网站开始使用。

先决条件

一个 Logto Cloud 账户或一个自托管 Logto。
一个 Logto 传统应用已创建。
一个配置了会话的 express 项目。查看 Express.js 网站。

安装

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

npm
pnpm
yarn

npm i passport passport-openidconnect

pnpm add passport passport-openidconnect

yarn add passport passport-openidconnect

集成

使用 OIDC 策略初始化 Passport.js

passport.ts
import passport from 'passport';
import OpenIDConnectStrategy, { type Profile, type VerifyCallback } from 'passport-openidconnect';

const endpoint = '<your-logto-endpoint>';
const appId = '<your-application-id>';
const appSecret = '<your-application-secret>';

export default function initPassport() {
  passport.use(
    new OpenIDConnectStrategy(
      {
        issuer: `${endpoint}/oidc`,
        authorizationURL: `${endpoint}/oidc/auth`,
        tokenURL: `${endpoint}/oidc/token`,
        userInfoURL: `${endpoint}/oidc/me`,
        clientID: appId,
        clientSecret: appSecret,
        callbackURL: '/callback',
        scope: ['profile', 'offline_access'],
      },
      (issuer: string, profile: Profile, callback: VerifyCallback) => {
        callback(null, profile);
      }
    )
  );

  passport.serializeUser((user, callback) => {
    callback(null, user);
  });

  passport.deserializeUser(function (user, callback) {
    callback(null, user as Express.User);
  });
}

此代码使用 OpenIDConnectStrategy 初始化 Passport。序列化和反序列化方法是为了演示目的而设置的。

确保在你的应用中初始化并附加 Passport 中间件：

your-app-entry.ts
import initPassport from './passport';

// ... other code
initPassport();
// ... other code
app.use(passport.authenticate('session'));
// ... other code

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

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

实现登录和登出

我们现在将为认证过程创建特定的路由：

your-app-entry.ts
app.get('/sign-in', passport.authenticate('openidconnect'));
app.get(
  '/callback',
  passport.authenticate('openidconnect', {
    successReturnToOrRedirect: '/',
  })
);
app.get('/sign-out', (request, response, next) => {
  request.logout((error) => {
    if (error) {
      next(error);
      return;
    }
    response.redirect(`${endpoint}/oidc/session/end?client_id=${appId}`);
  });
});

然后添加到主页

your-app-entry.ts
app.get('/', (request: Request, response) => {
  const { user } = request;
  response.setHeader('content-type', 'text/html');

  if (user) {
    response.end(
      `<h1>Hello Logto</h1><p>Signed in as ${JSON.stringify(
        user
      )}, <a href="/sign-out">Sign Out</a></p>`
    );
  } else {
    response.end(`<h1>Hello Logto</h1><p><a href="/sign-in">Sign In</a></p>`);
  }
});

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

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

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

权限和声明

Logto 使用 OIDC 权限和声明约定来定义从 ID 令牌和 OIDC 用户信息端点检索用户信息的权限和声明。“权限”和“声明”都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。

简而言之，当你请求一个权限时，你将获得用户信息中的相应声明。例如，如果你请求 `email` 权限，你将获得用户的 `email` 和 `email_verified` 数据。

默认情况下，Logto SDK 总是会请求三个权限：`openid`、`profile` 和 `offline_access`，并且无法移除这些默认权限。但你可以在配置 Logto 时添加更多权限：

export default function initPassport() {
  passport.use(
    new OpenIDConnectStrategy(
      {
        // ... other options
        clientID: appId,
        clientSecret: appSecret,
        callbackURL: '/callback',
        scope: ['openid', 'offline_access', 'profile', 'email'],
      }
      // ... other options
    )
  );
  // ... other options
}

以下是支持的权限（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

先决条件​

安装​

集成​

使用 OIDC 策略初始化 Passport.js​

配置重定向 URI​

配置重定向 URI​

实现登录和登出​

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

权限和声明​

延伸阅读​

先决条件

安装

集成

使用 OIDC 策略初始化 Passport.js

配置重定向 URI

配置重定向 URI

实现登录和登出

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

权限和声明

延伸阅读