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

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

Starter のコミット 7d452a6 と同期しています。

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

ローカルで実行する

先に通常の starter セットアップを完了し、公開アプリからユーザーを作成してから管理アプリを起動します。

pnpm dev:admin

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

pnpm build:admin
pnpm start:admin

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

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 のような専用オリジンを割り当てます。

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

顧客向けアプリと同じ DATABASE_URL と BETTER_AUTH_SECRET を使う
NEXT_PUBLIC_ADMIN_WEB_URL を管理オリジンに設定する（明示的に上書きしない限り、管理ビルドは Better Auth の URL にもこの値を使います）
管理ホスト名で有効な Turnstile の site/secret キーペアを設定する（公開サイトのキー設定がそのホスト名を許可する場合にのみ再利用します）
製品に適した ADMIN_MAX_CREDIT_GRANT の上限を選ぶ（既定値は 100000）

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

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

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

現在提供されている画面については、管理コンソールのページと運用を参照してください。