authentication-setup

認証のセットアップ

このスキルは、JWT のスニペットを羅列したり、認証、認可、セキュリティ強化、ドキュメント作成をすべて同じ作業として扱ったりするのではなく、実際のアプリに適したプロダクト認証を選択し、構成することが主な目的である場合に使用します。

authentication-setup は、次のセットアップ層を担当します。

• ホステッド型、フレームワークネイティブ、プラットフォームネイティブ、エンタープライズアドオン、セルフホスト型の認証から選択する
• セッション／Cookie とトークンの境界を決める
• ログイン方法を選ぶ：メールアドレス／パスワード、マジックリンク、ソーシャル OAuth、パスキー
• ユーザー／プロフィール／組織／メンバーシップのどのデータをアプリ側で管理するかを定義する
• SSO／SCIM、ドメインマッピング、移行／切り替えの境界を計画する
• コールバック URL、Cookie ドメイン、プレビュー／ステージング環境の差異、ロールアウトに関するメモを記録する

採用する方針や引き継ぎ先を決める前に、次のサポートドキュメントを確認してください。

• references/auth-decision-matrix.md
• references/boundary-checklist.md
• references/session-and-deployment-notes.md
• references/enterprise-and-migration-notes.md

このスキルを使用する場合

• 新しい Web アプリ、SaaS プロダクト、管理アプリ、または API を利用するプロダクトの認証をセットアップする
• Clerk、Auth.js、Better Auth、Supabase Auth、Firebase Auth、Cognito、Keycloak、または類似の選択肢から選ぶ
• セッション、Cookie、リフレッシュトークンの方針、OAuth プロバイダー、またはパスキーを追加またはリファクタリングする
• 認証プロバイダーとの境界で、アプリ側が管理するユーザー、プロフィール、組織、メンバーシップ、ロールを定義する
• 次のマイルストーンとして、組織、招待、エンタープライズ SSO、SCIM、またはドメイン検証を追加する
• フロントエンドのルート、ミドルウェア、バックエンド API、データベースのポリシー層にまたがる認証の境界を整理する
• 現在の認証スタックが特定ベンダーに依存しすぎている、自前実装が多すぎる、または安全に拡張するには曖昧すぎるかを検討する

このスキルを使用しない場合

• 主な作業が認可ポリシー、権限の継承、または ABAC／ReBAC のモデリングである場合 → 専用の認可設計の問題として扱い、API 契約のセマンティクスは api-design に引き継ぎます
• 主な作業が Cookie フラグ、CSRF、レート制限、シークレットの管理、不正利用の防止、または一般的な脆弱性対策である場合 → security-best-practices を使用します
• 主な作業が、API に認証を適切に組み込む前の API 契約／インターフェースの設計である場合 → api-design を使用します
• 主な作業が、開発者向けのリファレンスドキュメント、クイックスタート、または利用者向けの API 認証ドキュメントである場合 → api-documentation を使用します
• 主な作業が、バックエンドの回帰テスト、ログイン／コールバックのテスト、またはロールマトリックスのテスト計画である場合 → backend-testing を使用します
• 主な作業が、認証が所有するテーブルや ID の境界ではなく、より深いスキーマの正規化／インデックス設計である場合 → database-schema-design を使用します

手順

ステップ 1：ベンダーを挙げる前に認証の作業を分類する

まず、依頼内容を整理します。

auth_setup_profile:
  app_type: saas | internal-tool | marketplace | consumer-app | api-only | mixed | unknown
  auth_lane: hosted | framework-native | platform-native | enterprise-add-on | self-hosted | unknown
  runtimes: browser | server | edge | mobile | api | mixed
  login_methods: password | magic-link | social-oauth | passkeys | sso | mixed | unknown
  identity_scope: single-user | teams-orgs | b2b-enterprise | mixed | unknown
  session_model: server-session | stateless-jwt | hybrid | unknown
  data_ownership: vendor-owned | app-owned | hybrid | unknown
  rollout_stage: greenfield | mvp | scale-up | migration | enterprise-expansion

次の点を質問するか、推測してください。

1. すでに導入されているフレームワーク、ランタイム、デプロイ環境は何ですか？
2. チームが優先するのは、安全かつ最速でのリリース、より高度な制御、エンタープライズサポート、セルフホストのどれですか？
3. アプリに必要なのはサインインだけですか。それとも組織、招待、ロール、管理者アクセス、顧客向け SSO も必要ですか？
4. 現在のスタックによって、すでに固定されている認証／データ関連の要素は何ですか？

Step 2: 信頼できる最小構成の認証方式を選ぶ

記憶を頼りに選択肢を再構築するのではなく、auth-decision-matrix.md を使用します。

デフォルトの方式選択ガイド：

• ホスト型認証：スピード、事前構築済みの UX、プロバイダー、MFA／パスキー、洗練されたオンボーディングを最優先する場合
• フレームワーク標準の認証：アプリのコードやアプリ所有のデータに認証を密接に結び付けたい場合
• プラットフォーム標準の認証：Supabase／Firebase／Appwrite などのプラットフォームをすでに選定済みの場合
• エンタープライズ向けアドオン：SAML／OIDC SSO、SCIM、ディレクトリ同期、ドメイン検証が要件に含まれる場合
• セルフホスト：主権性、エアギャップ、OSS のみ、オンプレミスの要件が最優先の場合

ルール：

1. 第一候補を1つ、代替案は最大1つ推奨します。
2. バックエンドプラットフォームがすでに決まっている場合は、まずプラットフォーム標準の方式を評価します。
3. エンタープライズ ID が挙げられている場合は、コンシューマー向けログインにまとめず、明確に分岐させます。
4. 移行や切り替えのリスクが重要な場合は、enterprise-and-migration-notes.md を参照します。

Step 3: プロバイダーとアプリの責任範囲を明確にする

実装の前に、各要素の所有者を明示します。

責任範囲として最低限定める項目：

• 通常、プロバイダーが担当するもの： サインイン方法、パスワードリセット／メール認証、MFA／パスキーの認証フロー、トークン／セッションの発行、エンタープライズフェデレーションの接続点
• 通常、アプリが担当するもの： ローカルのユーザー／プロフィールレコード、組織／ワークスペースのメンバーシップ、ロール／権利、請求に連動したアクセス権、管理者／サポート向けの例外、ドメイン固有の認可
• 共有する領域： トークンやセッションにコピーされるクレーム、Webhook／ユーザー同期、コールバック URL、ミドルウェア、Cookie の設定、監査／イベントの可視性

boundary-checklist.md を使い、スキルが隣接する領域へ逸脱しないようにします。

Step 4: セッションとログインのモデルを慎重に選ぶ

詳しいヒューリスティクスについては、session-and-deployment-notes.md を使用します。

簡単なデフォルト設定：

• ブラウザー中心のアプリ、SSR、ミドルウェアと相性のよい認証状態には、サーバーセッション／署名付き Cookie
• トークン検証が主要な要件となる、API 中心および複数サービス間の通信には、ステートレス JWT
• ブラウザーセッションと API／マシントークンの両方が重要な場合は、ハイブリッド

必ず記録する項目：

• 選択したログイン方法と、それが現時点で必要な理由
• トークン／セッションの有効期間と更新戦略
• ログアウト／失効に関する要件
• ローカル、プレビュー、ステージング、本番環境それぞれでのコールバック URL と Cookie／ドメインの動作
• ヘルパーの利用可否に影響する可能性があるエッジ／ランタイムの制約

Step 5: アプリ所有の認証データをモデル化する

ホスト型認証を使っても、ローカルテーブルが不要になるとは限りません。

通常、少なくとも次を定義します：

• users または profiles
• マルチテナントの場合は organizations ／ workspaces
• memberships ／ roles
• チームが招待制／管理者管理の場合は、招待、プロビジョニング、またはシートの状態

次の項目を記録します：

• プロバイダーとアプリの DB 間で共通する安定したユーザー識別子
• ベンダーが所有するフィールドと、ローカルに複製するフィールド
• 権限をクレーム、ローカルテーブル、またはその両方のどこに保持するか
• Webhook または同期の失敗をどのように検知し、修復するか

依頼内容がより広範なスキーマ設計に及ぶ場合は、詳細なモデリングを database-schema-design に引き継ぎます。

Step 6: エンタープライズまたは移行に関する作業を明確に分岐させる

SSO、SCIM、ドメイン検証、既存ユーザーの紐付け、プロバイダーの移行、セルフホストへの切り替えリスクが依頼に含まれる場合は、enterprise-and-migration-notes.md を使用します。

次の項目を明示します：

• アドオンなのか、置き換えなのか
• アカウント紐付けと組織／ドメインのマッピングルール
• プロビジョニング／プロビジョニング解除の動作
• 顧客のオンボーディング／サポートに関する要件
• ロールアウトまたは移行が失敗した場合のロールバック範囲

ステップ 7：認証セットアップの引き継ぎ資料を作成する

次の実装ステップを成功させるための情報をまとめます。

推奨する引き継ぎ資料：

1. 選択した認証方式とその理由
2. 主要なスタックの推奨案と代替案
3. プロバイダーとアプリの所有範囲
4. セッションとログインのモデル
5. アプリ側で管理するデータモデルの概要
6. 環境チェックリスト
7. 関連する作業の振り分け先
8. 未解決のリスクや移行に関する注意点

出力形式

ユーザーが別の形式を求めない限り、次の構成を使用してください。

# Authentication Setup Plan

## Auth lane
- chosen lane
- why it fits

## Recommended stack
- primary option
- fallback option
- tradeoffs

## Ownership boundary
- provider owns
- app owns
- shared edge / sync points

## Session + login model
- sessions vs JWT vs hybrid
- chosen login methods
- callback/cookie/runtime notes

## App-owned data model
- users/profiles
- orgs/memberships/roles
- sync strategy

## Environment + rollout checklist
- local
- preview/staging
- production
- migration notes

## Route-outs
- adjacent skills and why

例

例 1：プロダクト認証を備えた Next.js SaaS

入力：

メールログイン、Google OAuth、組織のロール、管理パネルを備えた Next.js SaaS アプリの認証を設定してください。

期待される対応：

• ブラウザーとサーバーを併用する、チームや組織を持つ SaaS として分類する
• JWT のコード例にすぐ飛びつかず、ホスト型とフレームワーク標準の方式を比較する
• アプリ側で管理する組織／メンバーシップのテーブルを定義する
• SSR／ミドルウェア／Cookie の境界に触れる
• セキュリティ強化と認証フローのテストを関連スキルに振り分ける

例 2：Supabase を中心にしたアプリ

入力：

すでに Supabase を使用しています。認証を Supabase とアプリの DB のどちらに持たせるべきか、またロールをどう扱うべきか判断してください。

期待される対応：

• まずプラットフォーム標準の方式を選ぶ
• プロバイダーの ID と、アプリ側で管理する権限を分ける
• RLS／認可について、関連する設計・テスト上の検討事項として明示する

例 3：エンタープライズ向けの拡張または移行

入力：

すでにログイン機能があります。認証スタック全体を書き換えずに、B2B 顧客向けのエンタープライズ SSO と SCIM を追加してください。

期待される対応：

• 基本的なコンシューマー向けログイン設定ではなく、エンタープライズ向けの追加機能または移行に伴う作業として分類する
• アカウントのリンク、組織／ドメインのマッピング、プロビジョニングの境界を扱う
• SSO／SCIM がソーシャルログインやパスワード認証と同じ作業であるかのように扱わない

ベストプラクティス

1. コード例ではなく、認証方式と所有範囲の境界から始めます。
2. 認証のセットアップと、より詳細な認可ポリシーや一般的なセキュリティ強化を分けます。
3. ホスト型認証を使用していても、ほとんどのプロダクトでアプリ側にユーザー／組織／メンバーシップのテーブルが必要だと想定します。
4. B2B や切り替えの必要性が生じたら、エンタープライズ SSO／SCIM と移行を別の分岐として扱います。
5. 環境ごとのコールバック、Cookie、プレビュー環境の挙動を早い段階で記録します。
6. ベンダーの候補を大量に並べるのではなく、明確な第一推奨案を一つと代替案を提示します。
7. authentication-setup が別のバックエンド全般の受け皿にならず、再利用できるように、関連作業の振り分け先を明示します。

参考資料

• Next.js 認証
• Auth.js
• Clerk ドキュメント
• Supabase Auth ドキュメント
• Keycloak ドキュメント
• WorkOS ドキュメント