数分で Logto のための Node.js ベースのフレームワーク SDK を作成する

以前、この 記事 では、数分で Logto 用の Web SDK を作成しました。今回は、JavaScript 開発者に人気のあるもう一つのプラットフォームである Node.js に焦点を当てます。

このガイドでは、@logto/node を使用して Logto 用のシンプルな Express SDK を作成する手順をお教えします。この SDK はサインインフローを実装し、同じ手順で Koa、Next.js、NestJS などの他の Node.js ベースのプラットフォーム用の SDK を作成することができます。

サインインフロー#

始める前に、Logto のサインインフローを復習しましょう。サインインフローは次のステップで構成されます：

1. Logto へのリダイレクト: ユーザーは Logto のサインインページにリダイレクトされます。
2. 認証: ユーザーは認証情報を入力し、Logto で認証を行います。
3. アプリにリダイレクト: 認証が成功すると、ユーザーは認証コードと共にアプリにリダイレクトされます。
4. コード交換: アプリは認証コードをトークンと交換し、それを認証状態として保持します。

@logto/node の簡単な紹介#

@logto/browser と同様に、@logto/node パッケージは Logto のコア機能を提供する LogtoClient クラスを公開し、サインインフローのためのメソッドを含んでいます：

1. signIn(): OIDC 認証 URL を生成し、それにリダイレクトします。
2. handleSignInCallback(): コールバック URL を検査して解析し認証コードを抽出し、そのコードをトークンと交換するためにトークンエンドポイントを呼び出します。
3. getContext(): セッションクッキーに基づいて現在のリクエストのコンテキストを取得し、認証状態やユーザー情報を含みます。

Express SDK の作成#

この SDK では、/sign-in と /sign-in-callback の 2 つのルートハンドラーと、withLogto ミドルウェアを提供します：

1. /sign-in: OIDC の認証 URL にリダイレクトするレスポンスでサインインフローをトリガーするルートハンドラーです。
2. /sign-in-callback: コールバック URL を処理し、認証コードをトークンと交換し、それらを保存してサインインフローを完了するルートハンドラーです。
3. withLogto ミドルウェア: 現在のリクエストのコンテキスト、認証状態やユーザー情報を取得するために getContext() を呼び出すミドルウェアです。

この SDK を使用するには、Express アプリにミドルウェアを追加してルートを保護し、サインインフローをトリガーし、コールバックを処理するためにルートハンドラーを使用するだけです。

ステップ 1: パッケージをインストールする#

まず、npm や他のパッケージマネージャーを使用して @logto/node パッケージをインストールします：

ステップ 2: ストレージアダプターを準備する#

LogtoClient インスタンスを初期化するためにストレージアダプターが必要です。

SDK ユーザーがすでに Express セッションをセットアップしていると仮定して、新しいファイル storage.ts を作成して Storage クラスを単純に実装します：

ステップ 3: ルートハンドラーを実装する#

HTTP リクエストはステートレスであるため、各リクエストごとにクライアントインスタンスを初期化する必要があります。クライアントインスタンスを作成するために関数ヘルパーを準備しましょう：

この関数では、navigate アダプターと ExpressStorage アダプターを実装します。navigate アダプターは、ユーザーをサインイン URL にリダイレクトするために使用されます。

次に、handleAuthRoutes 関数に包まれたルートハンドラーを実装しましょう：

1. /auth/sign-in ルートハンドラーは signIn() を呼び出してサインインフローをトリガーし、サインイン状態がセッションに保存され、それが /auth/sign-in-callback ルートハンドラーによって利用されます。
2. /auth/sign-in-callback ルートハンドラーはコールバック URL を処理し、認証コードをトークンと交換するために handleSignInCallback() を呼び出し、トークンは ExpressStorage アダプターを経由してセッションに保存されます。交換が完了したら、ユーザーはホームページにリダイレクトされます。

ステップ 4: ミドルウェアを実装する#

withLogto ミドルウェアはルートを保護するために使用されます。getContext() を呼び出して現在のリクエストのコンテキストを取得し、認証状態やユーザー情報を含みます。

getContext 関数はストレージアダプターを使用してセッションからトークンを取得します。

チェックポイント: SDK の使用#

これで Logto 用の Express SDK を作成し、ルートを保護するためにミドルウェアを追加し、サインインフローをトリガーしてコールバックを処理するためにルートハンドラーを使用することができます。

ここでは、Express アプリで SDK を使用する方法の簡単な例を示します：

この例では、withLogto ミドルウェアを使用して認証状態を確認し、認証されていない場合はユーザーをサインインページにリダイレクトし、そうでない場合は歓迎メッセージを表示します。

公式の Express サンプルプロジェクトは こちら で確認できます。

結論#

このガイドでは、Logto 用の Express SDK を作成し、基本的な認証フローを実装する手順を案内しました。ここで提供された SDK は基本的な例です。アプリのニーズに応じて、さらにメソッドや機能を追加して拡張することができます。

同じ手順を踏むことで、Node.js で動作する他の JavaScript ベースのプラットフォーム向けの SDK を作成することもできます。

リソース：

1. Logto Node SDK
2. Logto Express SDK