為你的 Passport.js 應用程式新增驗證 (Authentication)

本指南將向你展示如何使用 Passport.js 和 OIDC 策略將 Logto 整合到你的應用程式中。

提示:

• 在本指南中，我們假設你已在專案中設置了帶有 session 的 Express。如果還沒有，請查看 Express.js 官網 以開始使用。

先決條件

• 一個 Logto Cloud 帳戶或 自託管 Logto。
• 一個已建立的 Logto 傳統應用程式。
• 一個已配置 session 的 express 專案。請參閱 Express.js 網站。

安裝

透過你喜愛的套件管理器安裝 Logto SDK：

npm

npm i passport passport-openidconnect

pnpm

pnpm add passport passport-openidconnect

yarn

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

在進入細節之前，這裡先快速說明一下終端使用者的體驗。登入流程可簡化如下：

1. 你的應用程式呼叫登入方法。
2. 使用者被重新導向至 Logto 登入頁面。對於原生應用程式，會開啟系統瀏覽器。
3. 使用者登入後，會被重新導向回你的應用程式（設定為 redirect URI）。

關於基於重導的登入

1. 此驗證流程遵循 OpenID Connect (OIDC) 協議，Logto 強制執行嚴格的安全措施以保護使用者登入。
2. 如果你有多個應用程式，可以使用相同的身分提供者 (IdP, Identity provider)（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>`);
  }
});

檢查點：測試你的應用程式

現在，你可以測試你的應用程式：

1. 執行你的應用程式，你會看到登入按鈕。
2. 點擊登入按鈕，SDK 會初始化登入流程並將你重定向到 Logto 登入頁面。
3. 登入後，你將被重定向回應用程式並看到登出按鈕。
4. 點擊登出按鈕以清除權杖存儲並登出。

權限範圍 (Scopes) 和宣告 (Claims)

Logto 採用 OIDC 權限範圍 (Scopes) 與宣告 (Claims) 慣例 來定義從 ID 權杖 (ID token) 及 OIDC userinfo 端點 取得使用者資訊時的權限範圍與宣告。無論「權限範圍 (Scope)」還是「宣告 (Claim)」，皆為 OAuth 2.0 與 OpenID Connect (OIDC) 規範中的術語。

對於標準 OIDC 宣告 (Claims)，其是否包含於 ID 權杖 (ID token) 內，完全取決於所請求的權限範圍 (Scopes)。擴充宣告（如 custom_data 與 organizations）則可透過 自訂 ID 權杖 (Custom ID token) 設定，額外配置於 ID 權杖中。

簡而言之，當你請求某個權限範圍 (Scope) 時，會在使用者資訊中取得對應的宣告 (Claims)。例如，若請求 `email` 權限範圍，則會取得使用者的 `email` 與 `email_verified` 資料。

預設情況下，Logto SDK 會始終請求三個權限範圍 (Scopes)：`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) 清單：

標準 OIDC 權限範圍 (Scopes)

openid（預設）

Claim name	Type	Description
sub	string	使用者的唯一識別符 (The unique identifier of the user)

profile（預設）

Claim name	Type	Description
name	string	使用者全名 (The full name of the user)
username	string	使用者名稱 (The username of the user)
picture	string	終端使用者大頭貼的 URL。此 URL 必須指向圖片檔案（如 PNG、JPEG 或 GIF），而非包含圖片的網頁。請注意，此 URL 應明確指向適合描述終端使用者的個人照片，而非任意由終端使用者拍攝的照片。(URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.)
created_at	number	終端使用者建立時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)
updated_at	number	終端使用者資訊最後更新時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)

其他 標準宣告 (Standard claims) 包含 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 及 locale 也會包含在 profile 權限範圍內，無需額外請求 userinfo endpoint。與上表宣告不同的是，這些宣告僅在其值不為空時才會回傳，而上表宣告若值為空則會回傳 null。

備註:

與標準宣告不同，created_at 與 updated_at 宣告使用毫秒而非秒為單位。

email

Claim name	Type	Description
email	string	使用者的電子郵件地址 (The email address of the user)
email_verified	boolean	電子郵件地址是否已驗證 (Whether the email address has been verified)

phone

Claim name	Type	Description
phone_number	string	使用者的電話號碼 (The phone number of the user)
phone_number_verified	boolean	電話號碼是否已驗證 (Whether the phone number has been verified)

address

請參閱 OpenID Connect Core 1.0 以瞭解 address 宣告的詳細資訊。

資訊:

標註為 （預設） 的權限範圍 (Scopes) 會由 Logto SDK 自動請求。當請求對應權限範圍時，標準 OIDC 權限範圍下的宣告 (Claims) 會始終包含於 ID 權杖 (ID token) 中，且無法關閉。

擴充權限範圍 (Extended scopes)

以下權限範圍由 Logto 擴充，會透過 userinfo endpoint 回傳宣告 (Claims)。這些宣告也可透過 Console > Custom JWT 設定直接包含於 ID 權杖 (ID token) 中。詳情請參閱 自訂 ID 權杖 (Custom ID token)。

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	object	使用者的自訂資料 (The custom data of the user)

identities

Claim name	Type	Description	Included in ID token by default
identities	object	使用者的連結身分 (The linked identities of the user)
sso_identities	array	使用者的連結 SSO 身分 (The linked SSO identities of the user)

roles

Claim name	Type	Description	Included in ID token by default
roles	string[]	使用者的角色 (The roles of the user)	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	string[]	使用者所屬的組織 ID (The organization IDs the user belongs to)	✅
organization_data	object[]	使用者所屬的組織資料 (The organization data the user belongs to)

備註:

這些組織宣告 (Organization claims) 也可在使用 不透明權杖 (Opaque token) 時，透過 userinfo endpoint 取得。然而，不透明權杖無法作為組織權杖 (Organization tokens) 來存取組織專屬資源。詳見 不透明權杖與組織 (Opaque token and organizations)。

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	string[]	使用者所屬組織角色，格式為 <organization_id>:<role_name> (The organization roles the user belongs to with the format of <organization_id>:<role_name>)	✅

延伸閱讀

終端使用者流程：驗證流程、帳號流程與組織流程 (End-user flows: authentication flows, account flows, and organization flows) 設定連接器 (Configure connectors) 授權 (Authorization)