メインコンテンツまでスキップ

Passport.js アプリケーションへ認証機能の追加

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

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

前提条件​

インストール​

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

npm i 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 Console のリダイレクト URI

サインインと同様に、ユーザーは共有セッションからサインアウトするために 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

Claim nameType説明Needs userinfo?
substringユーザーの一意の識別子No

profile

Claim nameType説明Needs userinfo?
namestringユーザーのフルネームNo
usernamestringユーザーのユーザー名No
picturestringエンドユーザーのプロフィール画像の URL。この URL は画像ファイル（例：PNG、JPEG、GIF 画像ファイル）を指す必要があります。画像を含む Web ページではありません。この URL は、エンドユーザーを説明する際に表示するのに適したプロフィール写真を参照するべきであり、エンドユーザーが撮影した任意の写真ではありません。No
created_atnumberエンドユーザーが作成された時刻。時刻は Unix エポック（1970-01-01T00:00:00Z）からのミリ秒数で表されます。No
updated_atnumberエンドユーザーの情報が最後に更新された時刻。時刻は Unix エポック（1970-01-01T00:00:00Z）からのミリ秒数で表されます。No

その他の 標準クレーム (Standard Claims) には、family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo、locale などがあり、これらも profile スコープに含まれ、userinfo エンドポイントをリクエストする必要はありません。上記のクレームとの違いは、これらのクレームは値が空でない場合のみ返される点です。一方、上記のクレームは値が空の場合 null が返されます。

注記:

標準クレームと異なり、created_at および updated_at クレームは秒ではなくミリ秒を使用しています。

email

Claim nameType説明Needs userinfo?
emailstringユーザーのメールアドレスNo
email_verifiedbooleanメールアドレスが認証済みかどうかNo

phone

Claim nameType説明Needs userinfo?
phone_numberstringユーザーの電話番号No
phone_number_verifiedboolean電話番号が認証済みかどうかNo

address

アドレスクレームの詳細については OpenID Connect Core 1.0 を参照してください。

custom_data

Claim nameType説明Needs userinfo?
custom_dataobjectユーザーのカスタムデータYes

identities

Claim nameType説明Needs userinfo?
identitiesobjectユーザーのリンク済みアイデンティティYes
sso_identitiesarrayユーザーのリンク済み SSO アイデンティティYes

roles

Claim nameType説明Needs userinfo?
rolesstring[]ユーザーのロール (Roles)No

urn:logto:scope:organizations

Claim nameType説明Needs userinfo?
organizationsstring[]ユーザーが所属する組織 (Organizations) の IDNo
organization_dataobject[]ユーザーが所属する組織 (Organizations) のデータYes
注記:

これらの組織 (Organizations) クレームは、不透明トークン (Opaque token) を使用する場合にも userinfo エンドポイント経由で取得できます。ただし、不透明トークン (Opaque token) は組織トークン (Organization token) として組織固有リソースへのアクセスには使用できません。詳細は 不透明トークン (Opaque token) と組織 (Organizations) を参照してください。

urn:logto:scope:organization_roles

Claim nameType説明Needs userinfo?
organization_rolesstring[]ユーザーが所属する組織 (Organizations) のロール (Roles)。形式は <organization_id>:<role_name>No

パフォーマンスとデータサイズを考慮し、「Needs userinfo?」が「Yes」の場合、そのクレーム (Claim) は ID トークン (ID token) には表示されず、userinfo エンドポイント のレスポンスで返されます。

さらなる読み物​

エンドユーザーフロー：認証 (Authentication) フロー、アカウントフロー、組織フロー コネクターの設定 認可 (Authorization)