convex-auth

OIDC プロバイダー（Clerk、Auth0、WorkOS）または組み込みの Convex Auth ライブラリを使用して、Convex の認証および認可パターンを実装します。 - **認証の概要**: https://docs.convex.dev/auth - **Convex Auth（ベータ版）**: https://docs.convex.dev/auth/convex-auth - **認証方法**: https://labs.convex.dev/auth - **Clerk との統合**: https://docs.convex.dev/auth/clerk - **WorkOS との統合**: https://docs.convex.dev/auth/authkit/ - Convex は OpenID Connect JWT を使用します。 - 統合先：Clerk、WorkOS AuthKit、Auth0。カスタム OIDC にも対応しています。 - Convex Auth（ベータ版）：外部サービスなしで、マジックリンク、OTP、OAuth、パスワードに対応する組み込みライブラリです（labs.convex.dev）。 - ID：サーバー関数で `ctx.auth.getUserIdentity()` を使用して取得します。 - 認可：各パブリック関数で適用します。機密性の高いロジックには、必ず内部関数を使用してください。

認証操作

• 関数内で ctx.auth.getUserIdentity() を呼び出すと、tokenIdentifier、subject、issuer とプロバイダーのクレームが返されます。
• カスタム JWT 認証では、identity["properties.email"] のようなパスでクレームが公開される場合があります。
• ユーザーの保存パターン：
  • クライアントのミューテーションで JWT からユーザーを保存するか、プロバイダーからの Webhook でユーザーを upsert します。
  • インデックス検索には by_token / byExternalId を使用することが推奨されます。
• Webhook：HTTP アクションを使用して実装し、プロバイダーの SDK で署名を検証する必要があります。署名シークレットは環境変数に保存する必要があります。

Convex Auth（ベータ版）の詳細

• 対応方式：
  1. マジックリンクと OTP：メールでリンクまたはコードを送信します。
  2. OAuth：GitHub、Google、Apple などに対応します。
  3. パスワード：リセットフローと、オプションのメール認証に対応します。
• コンポーネント：UI コンポーネントは提供されません。ライブラリのフックを使って React で構築する必要があります。
• Next.js：SSR／ミドルウェアのサポートは実験的なベータ版です。

サーバー関数のパターン

• ctx.auth.getUserIdentity() を使用して ID を取得する必要があります。
• すべてのパブリック関数で、行レベルの認可を適用する必要があります。
• 機密性の高いロジックをパブリック関数経由で公開しないでください。内部関数を使用することが推奨されます。

サービス間アクセス

• ユーザー JWT を利用できない場合は、共有シークレットのパターンを使用することが推奨されます。
• シークレットはデプロイ環境の環境変数に保存する必要があります。ハードコードしてはいけません。

クライアント向けガイダンス

• プロバイダーのクイックスタートに従い、独自のフローを作らないでください。
• サーバーで検証せずに、クライアントのみのコードで認証データに依存しないでください。