管理コンソールのセットアップとアクセス

独立した管理アプリの実行とデプロイ、運用担当者の昇格、MFA の必須化、専用オリジンの設定を説明します。

スターターのコミット e632762 と同期しています。

顧客向けアプリの外から、顧客、請求、運用障害を調べる担当者が必要な場合に使います。管理コンソール自体は含まれていますが、デプロイするか、誰にアクセス権を与えるか、専用オリジンをどう保護するかは自分で決めます。

推奨の出発点： 専用のホスト名へデプロイし、日常調査には admin_ro を使います。意図した変更を行う少人数のグループだけに admin_rw を与え、全員に MFA を必須とします。小規模チームは、運用上の制御が整うまで管理コンソールをデプロイしない選択もできます。顧客向けアプリは管理コンソールに依存しません。

完了後は、認可された運用担当者が別アプリへログインでき、一般ユーザーと読み取り専用の運用担当者は書き込めない状態になります。

スターターには、apps/admin に運用用の管理コンソールが含まれています。これは顧客向けアプリ内の /admin ルートではなく、二つ目の Next.js アプリです。この境界により、認証、データベーススキーマ、モデル、サービスを共有しながら、コンソールを保護された専用オリジンに配置し、独立してリリースできます。

ローカルで実行する

先に通常のスターターのセットアップを完了し、顧客向けアプリからユーザーを作成してから管理アプリを起動します。

pnpm dev:admin

http://localhost:3001 で待ち受けます。関連コマンドは次のとおりです。

pnpm build:admin
pnpm start:admin

.env.development.local にローカル管理オリジンを設定します。

NEXT_PUBLIC_ADMIN_WEB_URL=http://localhost:3001

この値がある場合、シェルまたはデプロイ環境が BETTER_AUTH_URL や NEXT_PUBLIC_AUTH_BASE_URL を明示的に指定しない限り、管理ビルドはこの値を Better Auth のオリジンとして使います。NEXT_PUBLIC_ADMIN_WEB_URL はビルド時に埋め込まれるため、本番環境で変更した後は再デプロイが必要です。

運用担当者を昇格する

プラットフォーム管理権限は users.role に保存され、組織の owner、admin、member ロールとは別です。

admin_ro はコンソールを開き、運用データを閲覧できます。
admin_rw はさらにコンソールの書き込み操作を実行できます。

リポジトリのルートから既存アカウントを昇格します。

pnpm admin:promote operator@example.com admin_rw

このコマンドは既定で admin_rw を使い、--dry-run に対応します。同じメールアドレスが複数の認証事業者のアカウントに属する場合、コマンドは推測せず停止します。その場合は、たとえば次のように --provider で正確なアカウントを選びます。

pnpm admin:promote operator@example.com --role admin_ro --provider google

認可処理がメールアドレスからロールを解決することはありません。サーバーはセッション固有の ID または UUID に一致するデータベースユーザーを読み込み、保護されたすべてのページと API ルートで保存済みロールを検査します。

MFA は必須

管理ロールだけではアクセスできません。すべての運用担当者は公開側のアカウント UI で Better Auth の二要素認証を有効にする必要があります。管理ロールがあっても MFA が未設定なら /mfa-required に移動し、有効化後に管理アプリ固有の /two-factor チャレンジを完了します。

Google のみでログインするアカウントは、Better Auth で二要素認証を有効にする前にパスワードが必要です。この場合、公開側のアカウント UI に パスワードを設定 が表示されます。設定後も Google ログインは引き続き利用できます。

管理コンソールへのログインは、顧客向けアプリと同じ、確認処理付きのメールログインエンドポイントを使います。そのため CAPTCHA 保護を有効にしている場合は、管理アプリのデプロイにも NEXT_PUBLIC_TURNSTILE_SITE_KEY と TURNSTILE_SECRET_KEY が必要です。

別アプリとしてデプロイする

同じリポジトリから 2 つ目のホスティングプロジェクトを作成し、pnpm build:admin を実行します。https://admin.example.com のような専用オリジンを割り当てます。

管理アプリはスターター共通の本番環境検証を読み込むため、管理画面が各外部サービスを直接使わない場合でも、現時点では本番で必須の環境変数一式が必要です。まず顧客向けアプリの本番環境変数を複製し、.env.example とデプロイとセキュリティを確認してください。そのうえで管理アプリ固有の値を調整します。

顧客向けアプリと同じ DATABASE_URL と BETTER_AUTH_SECRET を使う
NEXT_PUBLIC_ADMIN_WEB_URL、BETTER_AUTH_URL、NEXT_PUBLIC_AUTH_BASE_URL を Admin のオリジンに設定します。NEXT_PUBLIC_WEB_URL は顧客アプリを指します。明示したデプロイ変数が自動で推定する認証 URL より優先されます。
管理ホスト名で有効な Turnstile のサイトキーとシークレットキーの組を設定する（顧客向けアプリのキー設定がそのホスト名を許可する場合に限り再利用する）
製品に適した ADMIN_MAX_CREDIT_GRANT の上限を選ぶ（既定値は 100000）

現在の認証アダプターをデプロイする前に、SaaS 移行 0037_neat_excalibur.sql を適用し、確認済みの MFA 登録と Admin ログインを検証してください。Web の変数をコピーした場合は、Admin の二つの認証 URL が Web を指したままにならないよう変更します。環境設定ガイドに詳細があります。

Web と管理のオリジンは分離してください。管理アプリは noindex、nofollow、noarchive、no-store のレスポンスヘッダーに加えて、厳格なフレーム、リファラー、コンテンツセキュリティポリシーを適用します。ただし、これらは露出を抑えるためのもので認可の代わりではありません。サーバーレイアウトと各管理 API がロールと MFA を検査します。

リリース前チェックリスト

pnpm build:admin でコンソールをビルドします。
管理オリジンと認証ベース URL が同じデプロイ先を指すことを確認します。
admin_ro でログインし、データは見える一方で書き込み操作が使えないことを確認します。
admin_rw でログインして MFA を完了し、元に戻せる書き込みを 1 つ試します。
その操作が /audit に表示されることを確認します。
一般ユーザーが管理ページを開けず、管理 API も呼べないことを確認します。

現在提供されている画面と各操作の使い分けは、管理コンソールのページと運用を参照してください。公開前のネットワーク、シークレット、ヘルスチェックはデプロイとセキュリティで最終確認します。

/[locale]/account/profile で名前、パスワード、MFA、最近のセッションを管理します。管理 API はトークンや内部 ID を返さず、失効には作成後15分以内のセッションが必要です。SDK の公開セッション一覧・失効 API は閉じています。管理者には現在のセッションでの MFA 検証が必要です。web/admin より先に 0038_young_rafael_vega.sql を適用してください。既存や OAuth のセッションは /two-factor を完了します。不正なコードは権限を付与せず、MFA 変更で以前の検証状態を消去します。