convex-setup-auth

Convex 認証のセットアップ

Convex でユーザー管理とアクセス制御を備えた、安全な認証を実装します。

使用する場面

• 初めて認証をセットアップするとき
• ユーザー管理（ユーザーテーブル、ID マッピング）を実装するとき
• 認証ヘルパー関数を作成するとき
• 認証プロバイダー（Convex Auth、Clerk、WorkOS AuthKit、Auth0、カスタム JWT）をセットアップするとき

使用しない場面

• Convex 以外のバックエンドの認証
• Convex での実装を伴わない、OAuth/OIDC のみのドキュメント
• 認証コードの近くで発生しただけの、無関係なバグのデバッグ
• 認証プロバイダーの設定がすでに完了しており、ユーザーが必要としているのが1行の修正だけの場合

最初のステップ：認証プロバイダーを選択する

Convex は複数の認証方式に対応しています。プロバイダーを決めつけないでください。

セットアップコードを書く前に、次のことを行います。

1. リポジトリを見れば明らかな場合を除き、どの認証ソリューションを使うかユーザーに確認します
2. リポジトリですでにプロバイダーを使用している場合、ユーザーが切り替えを希望しない限り、そのプロバイダーを使います
3. ユーザーがプロバイダーを選んでおらず、リポジトリを見ても明らかでない場合は、作業を進める前に確認します

一般的な選択肢：

• Convex Auth - Convex で認証を直接処理したい場合の適切なデフォルトです
• Clerk - アプリですでに Clerk を使用している場合や、Clerk のホスト型認証機能を使いたい場合に使用します
• WorkOS AuthKit - アプリですでに WorkOS を使用している場合や、AuthKit を特に使いたい場合に使用します
• Auth0 - アプリですでに Auth0 を使用している場合に使用します
• カスタム JWT プロバイダー - 上記に含まれない既存の認証システムと連携する場合に使用します

ユーザーに尋ねる前に、リポジトリ内で次のような手がかりを探します。

• @clerk/*、@workos-inc/*、@auth0/*、または Convex Auth のパッケージなどの依存関係
• convex/auth.config.ts、認証ミドルウェア、プロバイダーラッパー、ログインコンポーネントなどの既存ファイル
• 特定のプロバイダーを明確に示す環境変数

プロバイダーの選択後

プロバイダーの公式ガイドと、対応するローカルのリファレンスファイルを確認してください。

• Convex Auth：公式ドキュメント、続いて references/convex-auth.md
• Clerk：公式ドキュメント、続いて references/clerk.md
• WorkOS AuthKit：公式ドキュメント、続いて references/workos-authkit.md
• Auth0：公式ドキュメント、続いて references/auth0.md

ローカルのリファレンスファイルには、具体的なワークフロー、必要なファイルと環境変数、注意点、検証項目が記載されています。

次の項目には、これらの情報源を使用してください。

• パッケージのインストール
• クライアントプロバイダーの接続
• 環境変数
• convex/auth.config.ts の設定
• ログインとログアウトの UI パターン
• React、Vite、Next.js 向けのフレームワーク固有の設定

共通の認証動作については、公式の Convex ドキュメントを信頼できる情報源として使用してください。

• ctx.auth.getUserIdentity() については、Functions での認証
• アプリレベルでユーザーを保存する場合は、Convex データベースへのユーザーの保存
• 認証と認可に関する一般的なガイダンスは、認証
• プロバイダーが Convex Auth の場合は、Convex Auth の認可

プロバイダーの CLI や Convex Auth の内部実装はバージョンによって変わるため、記憶に頼った手順より公式ドキュメントを優先してください。記憶を頼りに設定を作成すると、古いパターンを使ってしまうおそれがあります。サードパーティープロバイダーでは、アプリが Convex 内にユーザードキュメントを実際に必要とする場合にのみ、アプリレベルのユーザー保存を追加してください。すべてのアプリに users テーブルが必要なわけではありません。Convex Auth では、並行して users テーブルや storeUser フローを追加するのではなく、Convex Auth のドキュメントと組み込みの認証テーブルに従ってください。Convex Auth はすでにユーザーレコードを内部で管理しています。プロバイダーの初期化コマンドを実行した後は、生成されたファイルを確認し、プロバイダーのリファレンスに記載された初期化後の接続手順を完了してください。初期化コマンドだけで連携全体が完了することはほとんどありません。

基本パターン：バックエンド関数の保護

最も一般的な認証タスクは、Convex 関数で ID を確認することです。

// Bad: trusting a client-provided userId
export const getMyProfile = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

// Good: verifying identity server-side
export const getMyProfile = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    return await ctx.db
      .query("users")
      .withIndex("by_tokenIdentifier", (q) =>
        q.eq("tokenIdentifier", identity.tokenIdentifier),
      )
      .unique();
  },
});

ワークフロー

1. ユーザーに尋ねるか、リポジトリから推測してプロバイダーを特定します
2. ユーザーに、ローカル環境のみの設定を希望するか、今すぐ本番環境向けの設定を希望するか尋ねます
3. 対応するプロバイダーのリファレンスファイルを確認します
4. 最新の設定の詳細については、プロバイダーの公式ドキュメントに従います
5. 共通のバックエンド認証動作、ユーザーの保存、認可パターンについては、Convex の公式ドキュメントに従います
6. ドキュメントとアプリの要件で必要とされる場合にのみ、アプリレベルのユーザー保存を追加します
7. 所有権、ロール、チームへのアクセスに関する認可チェックは、アプリで必要な場合にのみ追加します
8. 要望があれば、ログイン状態、保護されたクエリ、環境変数、本番環境の設定を検証します

対話形式のプロバイダー設定やデプロイ設定で作業が止まる場合は、必要な人手での手順を具体的にユーザーに尋ね、その手順が完了したら続行してください。UI に関わる認証フローでは、設定完了後に実際のサインアップまたはサインインフローを検証することを提案してください。環境にブラウザー自動化ツールがあれば、それを使用できます。ない場合は、簡潔な手動検証チェックリストをユーザーに提示してください。

リファレンスファイル

プロバイダーのリファレンス

• references/convex-auth.md
• references/clerk.md
• references/workos-authkit.md
• references/auth0.md

チェックリスト

• セットアップコードを書く前に、正しい認証プロバイダーを選択しました
• 該当するプロバイダーのリファレンスファイルを読みました
• ローカルのみのセットアップと本番環境対応のセットアップのどちらを希望するか、ユーザーに確認しました
• プロバイダー固有の接続設定には、公式プロバイダードキュメントを使用しました
• 共通の認証動作と認可パターンには、公式の Convex ドキュメントを使用しました
• アプリで実際に必要な場合に限り、アプリレベルのユーザーストレージを追加しました
• Convex Auth 用に、プロバイダーをまたいで使う users テーブルや storeUser フローを独自に作成していません
• 保護されたバックエンド関数に認証チェックを追加しました
• アプリで実際に必要な箇所に認可チェックを追加しました
• 明確なエラーメッセージ（「Not authenticated」「Unauthorized」）を設定しました
• 選択したプロバイダー用にクライアントの認証プロバイダーを設定しました
• 要望があった場合、本番環境向けの認証セットアップも網羅しています