あなたの Passport.js アプリケーションに認証 (Authentication) を追加する

このガイドでは、Passport.js と OIDC ストラテジーを使用して、Logto をあなたのアプリケーションに統合する方法を紹介します。

ヒント:

• このガイドでは、プロジェクトに Express をセッションと共に設定していることを前提としています。まだ設定していない場合は、Express.js のウェブサイト を参照して始めてください。

前提条件

• Logto Cloud アカウントまたは セルフホスト Logto。
• 作成された Logto の従来のアプリケーション。
• セッションが設定された express プロジェクト。 Express.js のウェブサイト を確認してください。

インストール

お好みのパッケージマネージャーを使用して Logto SDK をインストールします：

npm

npm i passport passport-openidconnect

pnpm

pnpm add passport passport-openidconnect

yarn

yarn add passport passport-openidconnect

統合

Passport.js を OIDC ストラテジーで初期化する

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 を初期化します。serialize と deserialize メソッドはデモンストレーションの目的で設定されています。

アプリケーションで Passport ミドルウェアを初期化してアタッチすることを確認してください：

your-app-entry.ts

import initPassport from './passport';

// ... 他のコード
initPassport();
// ... 他のコード
app.use(passport.authenticate('session'));
// ... 他のコード

リダイレクト URI を設定する

詳細に入る前に、エンドユーザーの体験について簡単に説明します。サインインプロセスは次のように簡略化できます：

1. あなたのアプリがサインインメソッドを呼び出します。
2. ユーザーは Logto のサインインページにリダイレクトされます。ネイティブアプリの場合、システムブラウザが開かれます。
3. ユーザーがサインインし、あなたのアプリにリダイレクトされます（リダイレクト URI として設定されています）。

リダイレクトベースのサインインについて

1. この認証 (Authentication) プロセスは OpenID Connect (OIDC) プロトコルに従い、Logto はユーザーのサインインを保護するために厳格なセキュリティ対策を講じています。
2. 複数のアプリがある場合、同じアイデンティティプロバイダー (Logto) を使用できます。ユーザーがあるアプリにサインインすると、Logto は別のアプリにアクセスした際に自動的にサインインプロセスを完了します。

リダイレクトベースのサインインの理論と利点について詳しく知るには、Logto サインイン体験の説明を参照してください。

---

注記:

以下のコードスニペットでは、あなたのアプリが http://localhost:3000/ で実行されていると仮定しています。

リダイレクト URI を設定する

Logto Console のアプリケーション詳細ページに移動します。リダイレクト URI http://localhost:3000/callback を追加します。

サインインと同様に、ユーザーは共有セッションからサインアウトするために Logto にリダイレクトされるべきです。完了したら、ユーザーをあなたのウェブサイトに戻すと良いでしょう。例えば、http://localhost:3000/ をサインアウト後のリダイレクト URI セクションとして追加します。

その後、「保存」をクリックして変更を保存します。

サインインとサインアウトを実装する

次に、認証 (Authentication) プロセスのための特定のルートを作成します：

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. サインアウトボタンをクリックしてローカルストレージをクリアし、サインアウトします。

スコープとクレーム

Logto は OIDC の スコープとクレームの規約 を使用して、ID トークンおよび OIDC userinfo エンドポイント からユーザー情報を取得するためのスコープとクレームを定義します。「スコープ」と「クレーム」は、OAuth 2.0 および OpenID Connect (OIDC) 仕様からの用語です。

要するに、スコープをリクエストすると、ユーザー情報の対応するクレームを取得できます。例えば、`email` スコープをリクエストすると、ユーザーの `email` と `email_verified` データを取得できます。

デフォルトでは、Logto SDK は常に 3 つのスコープをリクエストします：`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
}

サポートされているスコープと対応するクレーム (Claims) のリストはこちらです：

openid

クレーム名	タイプ	説明	ユーザー情報が必要か？
sub	string	ユーザーの一意の識別子	いいえ

profile

クレーム名	タイプ	説明	ユーザー情報が必要か？
name	string	ユーザーのフルネーム	いいえ
username	string	ユーザーのユーザー名	いいえ
picture	string	エンドユーザーのプロフィール写真の URL。この URL は、画像を含む Web ページではなく、画像ファイル（例えば 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 トークンに表示されず、ユーザー情報エンドポイント のレスポンスで返されます。

さらなる読み物

エンドユーザーフロー：認証 (Authentication) フロー、アカウントフロー、組織フロー コネクターを設定する あなたの API を保護する