クレームのリクエストガイドで示したようにDID Connectセッションのクレームを定義した後、次の重要なステップは、ユーザーのDIDウォレットからの応答を処理することです。@arcblock/did-connect-jsライブラリは、ユーザーが承認、拒否、またはセッションがタイムアウトした場合など、セッションのあらゆる結果を管理するための包括的なライフサイクルコールバックを提供します。
これらのコールバックは関数として handlers.attach() メソッドに渡され、認証プロセスに特定のフックを提供して、ビジネスロジックを実行できるようにします。
DID Connectのライフサイクル
一般的なDID Connectセッションは、明確な一連のイベントに従います。下の図は、このフローと、各主要なライフサイクルコールバックがいつトリガーされるかを示しています。

ライフサイクルコールバック
以下に、DID Connectセッションのライフサイクル全体を処理するために使用できる、利用可能なコールバックの詳細を示します。
| コールバック | トリガーされるタイミング... | 一般的なユースケース |
|---|---|---|
onStart | 新しいセッションが開始され、QRコードの準備ができたとき。 | セッション開始のロギング、セッション固有のリソースの準備。 |
onConnect | ユーザーのウォレットがQRコードをスキャンして接続を確立したが、クレームが承認される前。 | userDidに基づく権限チェック、動的なクレームの生成。 |
onDecline | ユーザーがウォレットでリクエストを明示的に拒否したとき。 | キャンセルメッセージの表示、拒否のロギング。 |
onAuth | (必須) ユーザーがリクエストを承認し、要求されたクレームを送信したとき。 | **コアビジネスロジック:**クレームの検証、ユーザーセッションの作成、データベースの更新。 |
onComplete | 成功か失敗かにかかわらず、DID Connectセッション全体が終了したとき。 | 最終的なクリーンアップタスク、一時的なセッションデータの削除。 |
onExpire | ユーザーがアクションを完了する前にセッションがタイムアウトしたとき。 | QRコードの有効期限が切れたことをユーザーに通知し、古いセッションをクリーンアップする。 |
onError | セッション中に予期しないエラーが発生したとき。 | エラーのロギングと報告。 |
onConnect:承認前のロジックと動的クレーム
onConnectコールバックは、ユーザーのDIDを把握した後、ユーザーがクレームの全リストを見る前にロジックを実行できるため、特に強力です。これは、ユーザーのIDに基づいて権限チェックを行ったり、動的にクレームを生成したりするのに最適な場所です。
パラメータ:{ req, challenge, userDid, userPk, extraParams, updateSession }
例:onConnectで動的クレームを生成
handlers.attach({
action: 'dynamic-claims',
// この関数は非同期にできます
onConnect: ({ userDid }) => {
// ユーザーのDIDを許可リストと照合して確認できます
if (!isUserAllowed(userDid)) {
throw new Error('このサービスにアクセスする権限がありません。');
}
// または、ユーザーのプロパティに基づいて動的なクレームのセットを返します
return {
profile: () => ({
fields: ['fullName', 'email'],
description: '続行するには、氏名とメールアドレスを入力してください',
}),
};
},
onAuth: async ({ claims, userDid }) => {
// `claims` には、動的に生成されたプロファイルクレームの結果が含まれています
console.log('動的クレーム承認者:', userDid, claims);
},
});onAuth:認証成功の処理
onAuthコールバックは、DID Connect統合の核心部分です。これは唯一の必須コールバックであり、ユーザーがウォレットでリクエストを正常に承認したときに実行されます。ユーザーが送信したクレームデータを受け取り、それを使用して、ユーザーのログインや資産の所有権の検証など、アプリケーションのロジックを完了できます。
パラメータ:{ req, challenge, claims, userDid, userPk, extraParams, updateSession }
例:onAuthで送信されたクレームを処理する
handlers.attach({
action: 'profile-login',
claims: {
profile: () => ({
fields: ['fullName', 'email'],
description: 'ログインするには、氏名とメールアドレスを入力してください。',
}),
},
onAuth: async ({ userDid, claims }) => {
try {
const profileClaim = claims.find((c) => c.type === 'profile');
if (profileClaim) {
console.log(`ログイン成功:${userDid}`);
console.log('ユーザープロファイル:', profileClaim.value);
// ここでは通常、ユーザーセッションを作成したり、データベースに保存したりします。
const user = await findOrCreateUser(userDid, profileClaim.value);
}
} catch (err) {
console.error('ログイン処理中のエラー:', err);
}
},
});onDecline:ユーザーによるキャンセルの処理
ユーザーがウォレットでリクエストをキャンセルした場合、onDeclineコールバックがトリガーされます。これにより、例えばフロントエンドでユーザーにログイン試行がキャンセルされたことを通知するなど、キャンセルを適切に処理できます。
パラメータ:{ req, challenge, userDid, userPk, extraParams, updateSession }
例:拒否されたリクエストの処理
handlers.attach({
action: 'profile-login',
claims: { /* ... */ },
onAuth: async ({ userDid, claims }) => { /* ... */ },
onDecline: ({ userDid }) => {
console.log(`ユーザー ${userDid} が接続リクエストを拒否しました。`);
// セッションを更新してフロントエンドに通知することができます
},
});updateSessionによるデータの永続化
onAuth、onConnect、onStartを含むいくつかのコールバックは、パラメータとしてupdateSession関数を受け取ります。このユーティリティは、バックエンドのロジックからセッション状態に情報を渡し、それをフロントエンドアプリケーションがポーリングして取得できるようにするために不可欠です。
例えば、onAuthでのログインが成功した後、アプリケーション固有のJWTを生成してセッションに保存できます。フロントエンドはその後このトークンを取得して、後続のAPIリクエストを認証できます。
- プレーンで機密性の低い情報を永続化するには:
await updateSession({ key: 'value' }); - 機密情報(暗号化されます)を永続化するには:
await updateSession({ key: 'sensitive-value' }, true);
例:updateSessionを使用してフロントエンドにトークンを渡す
handlers.attach({
action: 'profile-login',
claims: { /* ... */ },
onAuth: async ({ userDid, claims, updateSession }) => {
const user = await findOrCreateUser(userDid, claims);
const appToken = generateAppToken(user);
// 機密性の低いセッションIDを永続化する
await updateSession({ sessionId: 'some-session-id' });
// 機密性の高いJWTを永続化する。これはセッションストアで暗号化される
await updateSession({ token: appToken }, true);
console.log(`ユーザー ${userDid} のセッションが更新されました`);
},
});これらのライフサイクルコールバックを効果的に使用することで、堅牢でユーザーフレンドリーな認証フローを構築できます。単一セッションの応答処理を理解した今、より複雑なユーザージャーニーを探求する準備が整いました。
次に、ワークフローの連鎖ガイドで、複数のDID Connectセッションをリンクさせて複数ステップのインタラクションを作成する方法を学びましょう。