sessionミドルウェアは、Blocklet SDKの認証システムの中核をなすコンポーネントです。Express.jsのルートに対するゲートキーパーとして機能し、リクエスターの身元を検証し、認証が成功するとreq.userプロパティにSessionUserオブジェクトをアタッチします。これにより、後続のミドルウェアやルートハンドラは、認証されたユーザー情報に容易にアクセスできます。
このミドルウェアは非常に柔軟で、DID Connectからのログイントークン、プログラムによるアクセスキー、安全なコンポーネント間コールなど、複数の認証戦略を標準でサポートしています。
仕組み
セッションミドルウェアは、特定の優先順位で受信リクエストの資格情報を検査します。有効な資格情報が見つかると、req.userを設定し、次のハンドラに制御を渡します。有効な資格情報が見つからない場合、その動作はstrictModeが有効かどうかによって異なります。
blockletの設定でenableBlacklist機能が有効になっている場合、追加のセキュリティチェックが実行されます。ログイントークンを検証する前に、ミドルウェアはサービスAPIを呼び出し、トークンが失効またはブロックされていないことを確認します。
基本的な使い方
sessionミドルウェアは、アプリケーション全体、または認証が必要な特定のルートに適用できます。
セッションミドルウェアの適用
import express from 'express';
import session from '@blocklet/sdk/middlewares/session';
const app = express();
// すべてのルートに適用
app.use(session());
// または、保護する必要がある特定のルートに適用
app.get('/api/profile', session({ strictMode: true }), (req, res) => {
// strictモードでは、req.userが存在しない場合、ミドルウェアはすでに401レスポンスを送信しています。
if (req.user) {
res.json(req.user);
}
});
// ログインしているユーザーで挙動が異なる公開ルート
app.get('/api/info', session(), (req, res) => {
if (req.user) {
res.json({ message: `Hello, ${req.user.fullName}`});
} else {
// non-strictモードでは、未認証のユーザーに対してreq.userはundefinedです
res.json({ message: 'Hello, guest.' });
}
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});設定オプション
sessionMiddleware関数は、その動作を調整するためにオプションの設定オブジェクトを受け入れます。
- strictMode
boolean(default:false) — 「true」の場合、無効なトークンまたはトークンがない場合は「401 Unauthorized」レスポンスが返されます。「false」の場合、「user」オブジェクトなしで「next()」を呼び出し、リクエストを未認証として扱います。 - loginToken
boolean(default:true) — 通常はDID Connectから提供され、「login_token」クッキーに含まれる標準JWTログイントークンによる認証を有効にします。 - accessKey
boolean(default:false) — 長期間有効なアクセスキー（例：CI/CDやスクリプト用）による認証を有効にします。これらも「login_token」クッキーから読み取られます。 - componentCall
boolean(default:false) — 「x-component-sig」のようなヘッダーを使用して検証される、他のコンポーネントからの安全な署名付きリクエストの認証を有効にします。 - signedToken
boolean(default:false) — クエリパラメータとして渡される一時的な署名付きJWTによる認証を有効にします。 - signedTokenKey
string(default:__jwt) — 「signedToken」認証に使用されるクエリパラメータの名前。
設定例
厳格なAPIエンドポイント
保護する必要があるエンドポイントの場合、「strictMode」は未認証のリクエストが即座に拒否されることを保証します。
```javascript
app.use('/api/admin', session({ strictMode: true }));
**アクセスキーを有効にする**
```javascript
app.use('/api/data', session({ accessKey: true }));SessionUserオブジェクト
認証が成功すると、req.userオブジェクトは以下の構造で設定されます。このオブジェクトは、認証されたユーザーまたはコンポーネントに関する重要な情報を提供します。
- user
object— 認証成功時に「req.user」にアタッチされるSessionUserオブジェクト。- did
string(required) — ユーザーの分散型識別子（DID）。 - role
string(required) — ユーザーに割り当てられたロール（例：「owner」、「admin」、「guest」）。 - provider
string(required) — 使用された認証プロバイダー（例：「wallet」、「accessKey」）。 - fullName
string(required) — ユーザーのフルネーム、または資格情報に関連付けられた備考。 - method
AuthMethod(required) — このセッションで使用された特定の認証方法（例：「loginToken」、「accessKey」、「componentCall」）。 - walletOS
string(required) — 該当する場合、使用されたウォレットのオペレーティングシステム。 - emailVerified
boolean— ユーザーのメールアドレスが検証済みかどうかを示します。 - phoneVerified
boolean— ユーザーの電話番号が検証済みかどうかを示します。
- did
以下は、ログイン成功後のreq.userオブジェクトの例です。
req.userオブジェクトの例
{
"did": "z8iZgeJjzB6Q1bK2rR1BfA2J8cNEJ8cNEJ8c",
"role": "owner",
"fullName": "Alice",
"provider": "wallet",
"walletOS": "ios",
"emailVerified": true,
"phoneVerified": false,
"method": "loginToken"
}次のステップ
sessionミドルウェアでユーザーが認証されると、そのロールと権限に基づいて、よりきめ細かいアクセス制御を実行できます。次のセクションに進み、認証ミドルウェアを使用してユーザーロールに基づいてルートを保護する方法を学んでください。