機能
@nocobase/app-plugin-authentication は、Better Auth をアプリに組み込みます。身元、セッション、ブラウザーのクライアント、サーバーのミドルウェアです。だれが呼び出しているかを確定し、その呼び出し元が何をできるかは 権限管理 が決めます。
認証は身元とセッションを提供します。サインインの画面はアプリが所有し、業務上のアクセスは Authorization が決めます。
シナリオと例
例：招待制のメンバーシップ
- 必要なサインインの方法は残したまま、セルフ登録を無効にします。
- アプリの登録の画面を、その設定とそろえます。
- ユーザー管理 でメンバーを招待します。
- ゲスト、メンバー、無効なユーザーとして、ページと API を検証します。
組み込みの再設定メールを使うには、auth.passwordReset.enabled を有効にし、アプリの公開アドレスと利用可能なシステムのメールチャネルを設定して、その入口に usePasswordResetCapability() を使います。メールとパスワードによるサインインだけでは、再設定は有効になりません。代わりに、アプリが sendResetPassword を提供することもできます。オリジンをまたぐデプロイでは、オリジンのチェックを回避するのではなく、信頼できるオリジンを設定してください。
開発用のプロンプト（アプリのディレクトリで作業するコーディングエージェント向け）：
Authentication を使って、このアプリを招待制にしてください。既存のサインイン、セッション、
拡張の設定は保ってください。サーバーでセルフ登録を無効にし、画面もそろえてください。
再設定を有効にする場合は、公開する前に公開 URL とメールチャネルを確認してください。
ゲスト、招待されたユーザー、無効なユーザー、サインアウトした状態のアクセスを検証してください。完了の条件直接のセルフ登録のリクエストが拒否され、招待されたユーザーは引き続き意図したアクセスでサインインできること。
主な仕組みと実装
以下は、この例での組み込みの領域と、想定される画面の変化です。開発作業を記述したもので、実際のファイル構成はアプリに合わせてください。
| 組み込みの領域 | コードまたは設定の変更 | 画面と動作の変化 |
|---|---|---|
| client/config/auth.ts と server/config/auth.ts | 対応する拡張を保ち、登録と再設定を設定する | 有効な方法と表示される入口が一致する |
| アプリの認証のページ | テンプレートのページと、機能に応じた操作を再利用する | 使えない登録や再設定の操作は表示されない |
| 保護されたルートと API | 認証してから、業務操作を認可する | 直接の API の呼び出しを含め、ゲストが正しく扱われる |
組み込みと設定
既定のテンプレートは両方のランタイムを登録し、client/config/auth.ts と server/config/auth.ts で認証を組み立てています。設定を編集するときは、plugins の配列全体を例で置き換えるのではなく、既存の拡張を保ってください。
| 設定またはファイル | 役割 |
|---|---|
server/config/auth.ts | defineAuthConfig でサインインの方法と拡張を組み立てる |
client/config/auth.ts | 対応するクライアントの拡張を登録する |
auth.emailAndPassword.enabled | メールとパスワードによるサインインを有効にする |
auth.emailAndPassword.disableSignUp | セルフ登録を無効にする |
secrets.keys / SECRETS_KEYS | 認証のキーを導く元になる、永続的なキー |
auth.passwordReset | パスワードの再設定と、そのメールチャネルを設定する |
プラグインのマイグレーションが認証のテーブルを管理します。サインイン、サインアップ、再設定のページはアプリに属します。別のページを追加する前に、そのルートと有効な方法を確認してください。
認証を使う
/client の useAuthentication() はセッションと読み込みの状態を、useAuthenticationClient() は認証のクライアントを提供します。保護されたルートは auth: 'required' を宣言します。
サーバーでは、/server から authenticationToken を解決し、そのサービスの required() ミドルウェアで API を保護します。業務上の権限はそのあとで確認します。ナビゲーションを隠しても API は保護されません。
AI 開発の制約と検証
プラグイン固有の開発の制約
- クライアントとサーバーの拡張は一緒に変更し、永続的なキーと信頼できるオリジンを保ってください。
- サインアップを無効にするときは直接の登録のリクエストを、再設定では実際のメールとリンクの動作をテストしてください。
- セッションの復元、サインアウト、無効な身元を確認し、認証のあとの認可を残してください。
よくある問題
- サインインページがない： アプリのルートとテンプレートのページを確認します。
- 再起動後にセッションが失敗する： インスタンス間の永続的なキーと、セッションの保存先を確認します。
- サインインできるがアクセスが拒否される： 業務上の権限を確認します。
- スクリプトから API にアクセスしたい： API キー を使います。
インストールとマイグレーションについては プラグインを管理する を参照してください。
これらはあなたの組み込みの検収の要件であり、実機での検証が完了したことを示すものではありません。実際の変更、実行したチェック、未検証の項目をエージェントに報告させてください。プロジェクトのガイダンス、スキル、共通のチェックについては アプリの開発を続ける と テスト を参照してください。
出典：公開のプラグインの入口と実装。