ZTXBAS チャレンジのライフサイクル
認証処理は短い状態遷移に従います。予期しない応答を調査する際に、この仕組みを理解しておくと役立ちます。
状態
approved（承認）、denied（拒否）、expired（期限切れ）は最終状態です。いずれかに移行すると、スイーパーがデータを削除するまでポーリング結果は変わりません。
時間に関する設定
| パラメーター | 値 | 備考 |
|---|---|---|
| チャレンジ有効期限 | 5 分 | 作成から expired まで |
| JWT の有効期間 | 5 分 | 発行から exp まで |
| SDK の JWKS キャッシュ | 5 分 | 鍵情報の再取得間隔 |
| 時刻ずれ許容 | HMAC ±5 分 / JWT ±30 秒 | RP 側の検証 |
チャレンジの有効期限が 5 分であるため、poll_challenge の既定タイムアウトは 4 分 30 秒です。サーバーが expired を返す前に ChallengeTimeoutError として処理できます。
シークレットのローテーションの影響
アプリの HMAC シークレットをローテーションしても、すでに進行中のチャレンジは無効になりません。チャレンジは ID、オリジン、ユーザーに結び付いています。新しいシークレットの展開中は一時的に INVALID_SIGNATURE が発生することがありますが、既存チャレンジの状態は維持されます。
冪等性と安全性
- チャレンジ作成は冪等ではありません。 連続実行すると端末へ 2 回通知されます。ログインボタンの多重クリックは RP 側で抑止してください。
- 状態ポーリングは冪等で、メモリ上のストアに対するインデックス検索です。
- 承認は 1 回限り。 最初の承認で
approvedに移行し、以後のタップは無視されます。
よくある失敗と原因
| 症状 | 可能性の高い原因 |
|---|---|
create_challenge が 404 | このアプリのテナントにユーザーが未登録 |
create_challenge が 403 UNREGISTERED_ORIGIN | /v1/origins に対象オリジンが未登録 |
pending が続き、その後 expired | プッシュが端末に到達していない（ネット接続、通知設定等） |
INVALID_SIGNATURE がチャレンジ作成でのみ発生 | RP と ZTXBAS のシークレット不一致 |
全呼び出しで TIMESTAMP_EXPIRED | RP ホストの時刻ずれ。NTP を確認 |