Step-up Authentication で破壊的な操作を防ぐ
Preventing Destructive Actions with Step-up Authentication の翻訳です。
Jessica Temporal — Sr. Developer Advocate
2026年9月17日・読了時間 16分
Cursor は、たった 1 つのプロンプトから「すべてのスコアをリセットする」機能を構築しました。そして、その実行には直前の MFA による Step-up Authentication が必要になるようにしました。
私は Agentic Arcade の管理画面にある Danger Zone セクションを作っていて、Cursor に 1 つだけプロンプトを渡して、この機能全体を追加させることにしました。
Agentic Arcade に、管理者専用の「すべてのスコアをリセット」機能を追加してください。管理画面にボタンを配置し、すべてのプレイヤーのスコアを永久に削除します。ただし、実行前に直前の Multi-factor authentication(MFA) による Step-up Authentication を必須にしてください。
Cursor は、これをすべてゼロから構築しました。
この記事では、Cursor が生成したものを順番に見ていきながら、それぞれの要素がなぜ重要なのかを説明します。
このようなセキュリティ機能は、マージ前にざっと見て「よさそう」と判断するだけでは不十分です。特に、アプリを vibe coding しているならなおさらです。
Tip: Cursor を使っている場合は、開始前に Auth0 Cursor plugin をインストールしてください。Auth0 のドキュメントや SDK の知識が組み込まれているため、プロンプトにドキュメントを貼り付けなくても、モデルが Auth0 SDK や Step-up Authentication のパターンを理解できます。
実際の利用フローは次のようになります。
/admin パネルを開き、Danger Zone までスクロールして「Reset all scores…」をクリックします。
確認画面が表示されます。そこで続行すると、リセットリクエストが送信される前にポップアップが開きます。
MFA challenge を完了するとポップアップが閉じ、その後でリセット処理が実行されます。
この順序は偶然ではありません。
古いセッションからデータ全削除を実行できないように、どのように配線されているのかを詳しく見ていきましょう。
前提条件
Agentic Arcade は Next.js アプリケーションで、私は Auth0 for AI Agents のさまざまな機能をデモするためによく使っています。
README には、テナントのセットアップ全体が説明されています。
今回の機能で特に必要なのは以下です。
- Steps 1–2
- Application
- Scores API
- 基本的なユーザー認証が動作しており、アプリケーションがローカルで実行できること。
- Step 3
step-up-mfaActionacr_valuesで MFA が要求された場合に Guardian challenge を発行する Post-Login Action です。- Google / Token Vault のセットアップ全体は不要です。Action 自体をデプロイし、Post-Login Flow に追加してあれば十分です。
- Step 6
arcade-adminrole/adminにアクセスするために、このロールをユーザーへ付与する必要があります。
リポジトリを clone し、Cursor に Auth0 plugin をインストール して、Cursor にアプリケーションをセットアップさせることもできます。
すでに Arcade が動作していて、上記の手順を完了しているなら準備完了です。
ゼロから始める場合は、先に README.md を進めてから、この記事に戻ってきてください。
影響の大きい操作では、Role だけでは不十分な理由
ユーザーにスコアリセットを実行させるうえで、最も分かりやすい実装は Role のチェックです。
/admin エンドポイントがユーザーの Auth0 Role を読み取り、arcade-admin が含まれていることを確認し、リセットを実行する。
これで終わりです。
多くのエンドポイントなら、それで問題ありません。
しかし、すべてのプレイヤーの履歴を 1 回のリクエストで消去できるほど強力なボタンでは、それだけでは不十分です。
Role のチェックが答えられるのは、1 つの質問だけです。
この人物は管理者なのか?
次の質問には答えられません。
この人物はいま実際にキーボードの前にいて、この特定の操作を意図的に実行しようとしているのか?
長時間働いた後も有効な管理者セッションを考えてみてください。
午前9時に MFA を使ってログインしました。
8時間後になってもセッションは有効です。arcade-admin Role も残っています。
サーバーから見れば、セッションが期限切れになっていないかぎり、ブラウザから送信されるリクエストが午前9時1分に送信されたものなのか、午後5時に送信されたものなのか区別できません。
Role も通常、それほど頻繁には変化しません。
盗まれたセッショントークン、ロックされずに放置された共有 PC、あるいは危険なボタンを反射的にクリックしてしまった場合も、サーバーからはすべて同じに見えます。
ログイン時の MFA と、操作実行時の MFA は同じではありません。
例えば銀行を考えてみてください。
銀行は送金を行う際に、「口座を持っているか」だけを確認するわけではありません。
高額な送金を行うその瞬間に、本人確認を再度要求します。
同じ考え方は、影響範囲が 1 ユーザーではなく、すべてのユーザーに及ぶ操作にも当てはまります。
パターン:Role Check + Step-Up Authentication
ここでは 3 段階の保護を考えます。それぞれが異なる弱点を防ぎます。
- Role Check のみ
- 管理者以外は排除できます。
- しかし、盗まれた管理者セッションや、ロックされていない PC からでもリセットを実行できます。
- サーバーには違いが分かりません。
- Role Check + セッションに MFA が存在することを確認
- こちらのほうが改善されています。
- ただし、管理者が以前どこかの時点で MFA を実行したことが分かるだけで、
auth_timeは数時間前かもしれません。 - 今朝 MFA で認証したセッションと、たった今 MFA を実行したセッションを区別できません。
- Role Check + Step-up Authentication
amrにmfaが含まれているauth_timeが 5 分以内- ポップアップでは
max_age=0 - 操作を行うその瞬間に MFA を使った再認証を強制します。
- 直前の MFA を持たないセッションではポップアップが表示され、チャレンジを完了するまでリセットは実行されません。
経験則として、「MFA を利用したセッション」と「Step-up Authentication Flow」は同じではありません。
Enrollment は、その認証方式が登録済みであることを示します。
amr は、そのセッションで実際に MFA が実行されたかどうかを示します。
auth_time は、それがいつ行われたかを示します。
なお、amr と auth_time の両方の Claim は、認証後にそのユーザーへ発行される ID Token に含まれます。
アプリケーションに Step-Up Authentication を追加する
game-library-demo では、既存の /admin パネルがアクセスリクエストと All-Access Pass を処理しています。
Cursor にプロンプトを渡したところ、新たに次の 3 ファイルが生成されました。
src/lib/mfa-step-up.ts- Step-up URL の生成と、サーバー側で Freshness を確認するための共有 Helper
src/components/AdminResetScores.tsx- 管理画面の Danger Zone に表示される Client Component
src/app/api/admin/reset-scores/route.ts- Client Component から呼び出される Endpoint
Step 1: Step-Up Helper
Endpoint や Button を見る前に、まず両方から import される共有 Module を見てみましょう。
export const MFA_ACR =
"http://schemas.openid.net/pape/policies/2007/06/multi-factor";
/** Custom claim the tenant Action sets after a completed step-up authentication. */
export const MFA_STEPUP_CLAIM = "https://agentic-arcade/mfa_stepup";
export const MFA_FRESH_WINDOW_SECONDS = 5 * 60;
export function buildMfaStepUpUrl(
returnTo: string,
options?: { forceReauth?: boolean },
) {
const params = new URLSearchParams({
acr_values: MFA_ACR,
returnTo,
});
if (options?.forceReauth) {
params.set("max_age", "0");
}
return `/auth/login?${params}`;
}
function hasStepUpSignal(user: Record<string, unknown>): boolean {
if (asStringArray(user.amr).includes("mfa")) return true;
if (user.acr === MFA_ACR || asStringArray(user.acr).includes(MFA_ACR)) {
return true;
}
return user[MFA_STEPUP_CLAIM] === true;
}
export function hasFreshMfaStepUp(user: unknown): boolean {
if (!user || typeof user !== "object") return false;
const claims = user as Record<string, unknown>;
if (!hasStepUpSignal(claims)) return false;
const now = Math.floor(Date.now() / 1000);
for (const ts of [claims.auth_time, claims.iat]) {
const age = ageSeconds(ts, now);
if (age !== null && age <= MFA_FRESH_WINDOW_SECONDS) return true;
}
return false;
}
hasStepUpSignal は、Step-up Challenge が完了したことを示す 3 つの独立した Signal を確認します。
amrに"mfa"が含まれているacrが PAPE URI と一致する- テナントの Action が設定したカスタム Claim
MFA_STEPUP_CLAIMがtrue
このうち 1 つでも満たせば十分です。
Auth0 テナントの構成によって Step-up の情報がどの形で現れるかが異なるため、この実装では 3 種類すべてを確認しています。
hasFreshMfaStepUp は、この Signal の確認と Freshness の確認を組み合わせます。
まず auth_time を確認し、その後 iat を fallback として使います。
max_age を使わない MFA のみの Step-up では、返された Token に auth_time が含まれない場合があります。しかし、新しい Token の iat は発行されたばかりであるため、Challenge が直前に行われた証拠として利用できます。
指定された時間枠内なら、どちらでも十分です。
buildMfaStepUpUrl には、オプションの forceReauth フラグが追加されています。
管理者のセッションがすでに新しい場合は、acr_values だけで完全な再ログインを要求せずに MFA Challenge を発生させることができます。
セッションが古い場合には forceReauth: true によって max_age=0 が追加されます。
これにより Auth0 は再認証を強制し、返されるセッションに新しい auth_time を発行します。
どちらを使うかは、Component が recentLogin prop をもとに判断します。これについては Step 4 で説明します。
Step 2: Step-Up の Claim を保持する
問題は、hasFreshMfaStepUp が Session User Object から次の値を読み取る点です。
amrauth_timeiatacr- Custom Claim
しかし、Auth0 Next.js SDK のデフォルトの Claim Filter は、これらをすべて削除してしまいます。
この処理を行わなければ、すべての Signal が undefined になり、hasFreshMfaStepUp は常に false を返します。
修正方法は、Auth0Client に beforeSessionSaved Hook を追加することです。
export const auth0 = new Auth0Client({
// ...existing config...
async beforeSessionSaved(session) {
return {
...session,
user: {
...filterDefaultIdTokenClaims(session.user),
...(session.user.amr !== undefined ? { amr: session.user.amr } : {}),
...(typeof session.user.auth_time === "number"
? { auth_time: session.user.auth_time }
: {}),
...(typeof session.user.iat === "number"
? { iat: session.user.iat }
: {}),
...(typeof session.user.acr === "string"
? { acr: session.user.acr }
: {}),
...(session.user[MFA_STEPUP_CLAIM] !== undefined
? { [MFA_STEPUP_CLAIM]: session.user[MFA_STEPUP_CLAIM] }
: {}),
},
};
},
});
filterDefaultIdTokenClaims で通常の Filter を適用したあと、Token に存在する場合に限り、Step-up に関連する 5 つの Signal を手動で追加し直しています。
ここでは iat の fallback が重要です。
max_age を使わない MFA のみの Step-up Popup では、auth_time が必ず更新されるわけではありません。しかし、新しい ID Token は発行されるため、新しい iat が設定されます。
この行がなければ、この Code Path では hasFreshMfaStepUp がひそかに失敗します。
Type Guard によって、undefined や誤った型の値が入り込まないようにもしています。
Note: ほかのものをテストする前に、必ずこの Hook を追加してください。これがなければ、Endpoint 側の Step-up Logic がどれだけ正しくても機能しません。
Step 3: Endpoint
Helper Module と Session Claim が揃ったところで、それらを結び付ける Endpoint を見てみましょう。
POST /api/admin/reset-scores は、データに触れる前に次の 3 つを確認します。
- Session
- Role
- Freshness
それぞれの段階で Fail Closed します。
export async function POST() {
// Gate 1: active admin session
const session = await auth0.getSession();
if (!session) {
return NextResponse.json({ error: "unauthorized" }, { status: 401 });
}
// Gate 2: arcade-admin role (server-side check, never trust the client)
const roles = await getUserRoles(session.user.sub as string);
if (!roles.includes("arcade-admin")) {
return NextResponse.json(
{ error: "You need the arcade-admin role to do this." },
{ status: 403 },
);
}
if (!hasFreshMfaStepUp(session.user)) {
return NextResponse.json(
{
error: "mfa_required",
error_description:
"Resetting every player's scores needs a fresh MFA step-up. Complete the challenge and try again.",
},
{ status: 403 },
);
}
const { players, scores } = await resetAllScores();
return NextResponse.json({ reset: true, deletedPlayers: players, deletedScores: scores });
}
Gate 1 と Gate 2 は、このアプリケーションですでに使われている標準的な Role Check Pattern です。
この記事で追加したのが Gate 3 です。
hasFreshMfaStepUp を 1 回呼び出すことで、Step 1 で説明した複数 Signal による Step-up の検出と Freshness の確認を行います。
src/lib/scores.ts にある実際の resetAllScores() は次のようになっています。
export async function resetAllScores(): Promise<{ players: number; scores: number }> {
const store = await load();
const players = Object.keys(store).length;
const scores = Object.values(store).reduce((n, p) => n + p.scores.length, 0);
await saveJson(FILE, {});
return { players, scores };
}
1 回の書き込みで Store 全体を空にし、削除した Player 数と Score 数を返します。
これにより、成功メッセージに具体的な件数を表示できます。
Step 4: Admin Button
Component は Server Page から 2 つの Props を受け取り、次の 5 つの Phase のいずれかを管理します。
idle → confirm → step up → wiping → done
「まずリクエストを送り、MFA が必要だというレスポンスを受けてから対応する」パターンとの重要な違いは、Popup が mfa_required Response への反応として開くのではなく、Confirm の段階から能動的に開かれることです。
SDK の Popup が正常に完了したあとで初めて Reset Request が送信されます。
async function wipe() {
setError(null);
setPhase("wiping");
try {
const res = await fetch("/api/admin/reset-scores", { method: "POST" });
const body = await res.json().catch(() => ({}));
if (!res.ok) {
throw new Error(
body.error_description ?? body.error ?? `Failed (${res.status})`,
);
}
setResult({
deletedPlayers: body.deletedPlayers ?? 0,
deletedScores: body.deletedScores ?? 0,
});
setPhase("done");
} catch (e) {
setError(e instanceof Error ? e.message : "Something went wrong.");
setPhase("confirm");
}
}
async function startStepUp() {
setError(null);
setPhase("stepup");
try {
await mfa.challengeWithPopup({
audience,
acr_values: MFA_ACR,
...(recentLogin ? {} : { prompt: "login" }),
popupWidth: 500,
popupHeight: 700,
timeout: 180_000,
});
await wipe();
} catch (e) {
if (e instanceof PopupCancelledError) {
setError("MFA was cancelled before it finished.");
} else if (e instanceof PopupBlockedError) {
setError("Popup blocked — allow popups for this site and try again.");
} else if (e instanceof PopupTimeoutError) {
setError("MFA timed out. Approve the Guardian push, then try again.");
} else {
setError(e instanceof Error ? e.message : "Something went wrong.");
}
setPhase("confirm");
}
}
「Continue — verify with MFA」をクリックすると、startStepUp が Auth0 SDK の mfa.challengeWithPopup() を呼び出します。
SDK は Popup を開き、単純に window.closed を待つのではなく、/auth/callback の Response によって Session Cookie が書き込まれるまで待機します。
その処理が終わって初めて Promise が resolve します。
そして、それから wipe() が実行されます。
管理者が Challenge をキャンセルした場合、ブラウザが Popup をブロックした場合、あるいは Guardian Push が Timeout した場合には、SDK が型付きの Error を throw します。
PopupCancelledErrorPopupBlockedErrorPopupTimeoutError
この場合、wipe() は一切呼び出されません。
recentLogin Prop は、完全な再ログインが必要かどうかを制御します。
管理者の Session が Freshness Window 内に開始されている場合、acr_values だけで MFA Challenge を開始し、Password での再ログインまでは要求しません。
Session が古い場合には prompt: "login" を追加します。
これによって Auth0 は、Step-up Token を発行する前にユーザーを完全に再認証します。
Server Page は Component を Render する前に isRecentLogin(session) を使ってこの Flag を計算します。これについては Step 6 で説明します。
Step 5: すでに存在している Action
Gate 3 は次の 3 種類の Signal を確認します。
amracr- Custom
MFA_STEPUP_CLAIM
最初の 2 つは、MFA 実行時に Auth0 がネイティブで発行する標準的な OIDC Claim です。
Custom Claim は、Step-up Challenge が正常に完了したあと、テナントの Post-Login Action によって設定されます。
Demo ですでに必要とされているもの以外に、新しい Action を追加する必要はありません。
MFA の Enforcement は、Demo ですでに利用している step-up-mfa Post-Login Action によって実現されています。
これは README の Step 3 にあるもので、Token Vault の Consent Flow でも使われている同じ Action です。
Popup から acr_values を含む Request が届くと、この Action が Guardian Challenge を発行します。
Challenge が完了すると、ID Token に Custom MFA_STEPUP_CLAIM を設定します。
異なるテナント構成でも動作するように、Server は 3 つすべての Signal を確認します。
そのうち 1 つでも見つかれば、「たった今 Challenge を通過した」という十分な証拠になります。
なお、すでに README の Step 3 まで完了している場合、この機能を動かすために追加の Action や Tenant Policy の変更は必要ありません。
上の画像では、すでにこの Account に Auth0 Guardian が MFA として登録されているため、MFA の方法として Auth0 Guardian App への Push Notification を受け取る選択肢が表示されています。
Mobile 端末で Notification を承認すると、Popup は自動的に閉じます。
Step 6: Admin Page に Button を組み込む
src/app/admin/page.tsx は Component を import し、2 つの Props を渡します。
import AdminResetScores from "@/components/AdminResetScores";
import { isRecentLogin } from "@/lib/mfa-step-up";
// ...
<h2 className="mb-3 mt-8 text-lg font-semibold">Reset all scores</h2>
<AdminResetScores
recentLogin={isRecentLogin(session!)}
audience={process.env.AUTH0_AUDIENCE ?? "https://arcade-scores-api"}
/>
Admin Page は Server Component です。
AdminResetScores は Client Component("use client")です。
Page は isRecentLogin を使い、Server Side で recentLogin を計算します。
isRecentLogin は、Session の auth_time、または fallback として iat が、5 分間の Freshness Window 内にあるかを確認します。
audience Prop は Scores API の Audience String です。
mfa.challengeWithPopup() が Step-up Token の Scope を正しく設定するために必要です。
Page が Button を Render し、Button 側が次のものを管理します。
- Fetch
- Phase State
- Popup Lifecycle
フロー全体を最初から最後まで見る
arcade-admin Role を持つユーザーが、Database 内のすべての Score を削除しようとする場合の流れをまとめてみましょう。
/adminへ移動する- 下までスクロールし、「Reset all scores」をクリックする
- Confirm Prompt を読み、「Continue — verify with MFA」をクリックする
mfa.challengeWithPopup()が開くacr_valuesによって MFA Challenge が開始される- Session が古い場合には
prompt: "login"も送信され、先に完全な再ログインが必要になる
- Session が古い場合には
- Guardian Push を完了する
- SDK Popup が resolve する
- Session Cookie が更新される
wipe()が実行されるPOST /api/admin/reset-scores- Gate 1: Session が存在する ✓
- Gate 2:
arcade-adminRole がある ✓ - Gate 3:
hasFreshMfaStepUpが成功する- Step-up Signal が存在する ✓
auth_timeまたはiatが 5 分以内 ✓
resetAllScores()が実行される- Score Store 全体が削除される
- Danger Zone に次のようなメッセージが表示される
✓ Wiped 10 scores across 2 players
Happy Path であれば、Confirm をクリックしてから成功するまでおよそ 10 秒です。
知っておくべき注意点
beforeSessionSaved は任意ではありません。
SDK はデフォルトで次の値を削除します。
amrauth_timeiatacr- Custom Claim
Hook を追加しなければ、hasFreshMfaStepUp が確認する Signal はすべて undefined となり、Button は永遠に mfa_required の状態から抜け出せません。
ほかのものをテストする前に Hook を追加してください。
iat も忘れないでください。
これがないと、max_age を使用しない MFA のみの Step-up がひそかに失敗します。この Flow では auth_time が存在しないことがよくあるからです。
Step-up Signal と Freshness Timestamp の両方が必要です。
Timestamp だけを確認すると抜け道ができます。
例えば、Freshness Window 内で Password だけを使ってログインした場合、MFA が実行されていなくてもチェックを通過してしまいます。
Signal だけを確認するのも不十分です。
Challenge がいつ実行されたのか分からないからです。
両方を組み合わせることで、
「MFA が実行された。そして、それは最近実行された」
ことを確認できます。
arcade-admin Role があっても MFA Gate は bypass できません。
Role は Gate 2 です。
Freshness は Gate 3 です。
有効な Role を持つ Admin でも、最近 MFA を行っていなければ mfa_required になります。
Role Holder 向けの Shortcut はありません。
Policy は Code の中にあります。
auth_time の Freshness が Policy です。
5 分間という Window は、mfa-step-up.ts の MFA_FRESH_WINDOW_SECONDS に定義されています。
Threat Model に合わせて調整してください。
短すぎれば、一連の作業中に Admin が何度も Challenge を要求されます。
長すぎれば、古い Step-up が有効なまま残ります。
元に戻せない操作に対しては、5 分は妥当な Default です。
Popup がブロックされる場合。
Browser が Popup をブロックすると、mfa.challengeWithPopup() は PopupBlockedError を throw し、AdminResetScores は次の Message を表示します。
Popup blocked — allow popups for this site and try again.
Step-up Flow の Callback URL は、Auth0 Application の Allowed Callback URLs に登録されている必要があります。
不足していると、Popup 自体は開きますが Redirect のところで止まります。
キャンセルされた Step-up は Endpoint に到達しません。
Admin が MFA Challenge をキャンセルすると、SDK が PopupCancelledError を throw し、wipe() は呼び出されません。
何らかの理由で Fresh Step-up がない Request が Endpoint に到達したとしても、Gate 3 が最終的な防波堤になります。
しかし通常の Flow では、その前に SDK が防いでくれます。
PopupCancelledError を Auth0 Log Streams に記録することも検討してください。
破壊的な Admin Action に対して Step-up がキャンセルされたという Event は、確認する価値があります。
まとめ
1 つの Prompt から 3 つの File が生成され、古い Session から全 Score 削除を実行できない仕組みが作られました。
Cursor の出力で私が興味深いと感じたのは、Security Model が正しく構築されていたことです。
3 つの Gate があり、複数 Signal による Step-up 検出と Freshness Timestamp が組み合わされ、SDK Popup は事前に開かれます。
さらに beforeSessionSaved も正しく実装されていました。
iat の fallback まで含まれています。
これは Auth0 SDK 固有の挙動であり、Auth0 Cursor Plugin がうまく役割を果たした部分です。
この Hook がなければ、全体が気づかないうちに壊れてしまいます。
この Pattern は、影響範囲が 1 人より大きいあらゆる Button に適用できます。
Step-up Signal、
amracr- Custom Claim
のいずれかと、直近の
auth_timeiat
を組み合わせることで、次の質問に答えられます。
この人物は、たった今 MFA で認証したのか?
そして、それは十分最近のことなのか?
この Check に次のものを組み合わせます。
mfa.challengeWithPopup()- Claim を Session に保持する
beforeSessionSavedHook - 既存の
step-up-mfaAction
これによって、
「この人物は MFA を登録している」
という状態と、
「この人物は、いまたった今 MFA で本人確認をやり直した」
という状態の間にある Gap を埋める Identity Gate を作ることができます。
自分でも試してみてください。
- 完全な Diff は PR #1 で確認できます。
acr_valuesPattern と Post-Login Action の詳細については、Auth0 Step-up Authentication Docs を参照してください。- Auth0 が
auth_timeClaim をどのように発行・更新するかについては、Auth0auth_timeClaim Docs を参照してください。
著者について
Jessica Temporal
Sr. Developer Advocate
Jessica Temporal は Auth0 の Senior Developer Advocate であり、ブラジル初の Data Science Podcast Pizza de Dados の共同創設者です。
The Big Git Microbook の著者であり、GitFichas.com の Creator でもあります。また、LinkedIn Learning の Instructor Team の一員でもあります。
Jessica は、ブラジルの政治家による違法である可能性のある支出を特定する AI の開発にも携わりました。
また、Technology 分野における Diversity と Inclusion の向上を目指す PyLadies Initiative に参加しています。
余暇には編み物をしたり、Video Game をプレイしたり、3D Printer を使ったりしており、現在は 3D Model の作成も学んでいます。