neon-auth

最初に：Neon の概要、Neon の始め方、Neon 開発のベストプラクティスなどについては、親の neon スキルを使用してください。

neon スキルがインストールされていない場合は、https://neon.com/docs/ai/skills/neon/SKILL.md から取得するか、次のコマンドでインストールしてください：

neon skills -s neon -y

Neon Auth

Neon Auth は Managed Better Auth です。ユーザー、セッション、認証設定はブランチの Lakebase Postgres 上の neon_auth スキーマに保存され、認証状態はデータベースとともにブランチ化されます。クライアント API は @neondatabase/auth を介した Better Auth のメソッドセット（signIn.email、signIn.social、getSession）です。このラッパーは、素の better-auth/client とそのまま置き換えられるものではありません。プラグインリストを固定し、Neon 固有の OAuth 検証機能、iframe ポップアップ、JWT 処理を追加しています。Auth がマネージドである間は、このラッパーを使用してください。

このスキルでは、ID の方式を選択してから Managed Better Auth を実装します。Postgres、Functions、Object Storage、AI Gateway を使うために、動作中の認証サーバーを置き換えることはありません。

使用するタイミング

プロビジョニングの前に、既存の ID 方式と必要なログイン機能を確認してください。DATABASE_URL が指定されていても、ID 方式を変更する理由にはなりません。Neon Function を追加することも、ID 方式を変更する理由にはなりません。

状況	対応
既存の認証がない	Managed Better Auth をデフォルトとして使用します。Managed のセットアップの後、references/managed-auth.mdを参照してください。
Managed では提供されていない機能が必要	既存のアプリホスト（Vercel など）または Neon Function で、セルフマネージドの Better Auth を使用します。Lakebase Postgres はそのまま使用します。移行を勧める前に、インストール済みの Better Auth バージョンのドキュメントで、その具体的なフローが説明されていることを確認してください。サポート状況が不明なままなら、現在の ID 方式を維持してください。references/self-managed.md。
すでに Better Auth を使用している	そのまま使用してください。他の Neon プリミティブと連携します。ユーザーから依頼があった場合に限り、Managed に移行します。
Supabase Auth からの移行を依頼された	Managed Better Auth を使用します。Supabase Auth。Postgres のみを移行する場合や Function を追加する場合は、Supabase Auth をそのまま使用します。
Clerk、Auth.js、Supabase Auth、またはその他の動作中の IdP を使用している	ユーザーから移行を依頼されない限り、そのまま使用してください。

Managed Auth では、Google、GitHub、Vercel のソーシャル OAuth を利用できます。これらは Managed Auth を離れる理由にはなりません。その他の OAuth プロバイダー、汎用 OAuth、MFA、パスキー、API キー、MCP OAuth、SSO、カスタムプラグイン、フック、カスタム JWT クレームについては、プラグイン対応状況を確認してください。

Managed Auth を有効にする前に、プロジェクトが AWS 上にあり、IP Allow または Private Networking を使用していないことを確認してください。これらの保護機能は有効なままにしてください。

対応している Managed プラグインは、@neondatabase/auth に plugins を渡すのではなく、Neon（Console、API、または neon neon-auth）で設定してください。auth: true を有効にするだけでは、ログインの実装にはなりません。

機能

• Postgres 内のマネージド ID — ユーザーとセッションは neon_auth に保存され、SQL で照会でき、RLS と互換性があります。
• アプリのメール送信機能なしで認証メールを送信 — メールアドレスの確認、メール OTP、マジックリンク、パスワードリセットに対応します。スタートガイドでは共有 SMTP（[email protected]）を使用します。ログインを実装するために Resend や SendGrid を追加する必要はありません。本番環境ではカスタム SMTP が必要です：https://neon.com/docs/auth/production-checklist.md
• データベースとともにブランチ化 — 各ブランチに専用の Auth URL と分離された認証状態があります。
• Neon SDK 経由の Better Auth クライアントメソッド — @neondatabase/auth（認証のみ）または @neondatabase/neon-js/auth（統合 SDK）を使用します。UI は任意で @neondatabase/auth-ui を利用できます。
• 固定されたプラグインセット — Managed クライアントは plugins オプションを受け付けません。プラグイン対応状況を参照してください。

利用条件

Managed Better Auth は一般提供されています。AWS リージョンのみで利用できます。IP Allow または Private Networking が設定されたプロジェクトでは有効にできません。

Organization は別途、Partial / Beta です。Neon Function でセルフマネージドの Better Auth をホストする場合は、Functions の提供状況とクレームのルールに従います。そのホストについては neon-functions スキルを使用してください。Auth を有効にできる未クレームのプロジェクトでも、クレームするまでは Functions を使用できません。

マネージドセットアップ

Auth を既存の neon.ts にマージします。他のフィールドは置き換えないでください。

import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true,
});

neon deploy
neon neon-auth status

その設定の Function が process.env を読み取る場合は、親スキルの説明に従って neon deploy --env <file> を使用します。手動でサービスを有効にするコマンドは neon neon-auth enable です。neon.ts で auth: true がすでに宣言されている場合、冗長な必須手順として enable と deploy の両方を実行しないでください。

次に、ログインを実装します：references/managed-auth.md。

Claimable プロジェクトの場合は、親の Claimable の手順に従い、ログインが必要で既存のプロバイダーを維持する必要がない場合は auth: true と neon deploy を実行します。

Supabase Auth

ユーザーが Supabase Auth からのログイン移行を依頼した場合は、Managed Better Auth を推奨し、https://neon.com/docs/auth/migrate/from-supabase.md に従います。Postgres のみを移行したり Function を追加したりするのは、その依頼に該当しません。Supabase Auth を維持してください。

SupabaseAuthAdapter() では、signInWithPassword や signInWithOAuth などのメソッドの形式が維持されます。これらの呼び出しは、デフォルトの Better Auth の例（signIn.email）と互換性がありません。既存のアダプター呼び出し元は、その API を引き続き使用してください。

実際に使用されている認証メソッドとデータベース呼び出しを確認します。

• パスワードハッシュは移行できません。ユーザーは新しいアカウントを作成するか、OAuth でサインインします。
• ユーザー ID、セッション、アカウント連携が変更されないとは約束しないでください。アプリケーションの外部キーについて、オーナーと計画してください。
• Managed Auth では、updateUser() でメールアドレスやパスワードを変更できません。メールアドレスの確認にはアプリケーションの UI が必要です（共有 SMTP ではコードが使えます。リンクにはカスタム SMTP が必要です）。
• 移行ガイドでは、Supabase の電話／SMS／WhatsApp、SAML、Web3 は Managed Auth でサポートされていないと記載されています。それでもユーザーがその特定のフローを必要とする場合は、インストール済みの Better Auth のバージョンを確認してください。サポートが未解決のままなら、Supabase Auth を維持し、認証の切り替えを中止します。このページの「電話認証なし」という記載は、Supabase の電話番号サインインを指しており、制約付きの Managed Phone Number プラグイン（既存ユーザーが電話番号を連携するもの）を指すものではありません。
• @supabase/supabase-js を Auth にのみ使用している場合、Data API を有効にする理由にはなりません。既存の PostgREST／Supabase データベースクライアントのクエリで使用されている場合に限り、Data API を維持してください。

検証

マネージドの経路では、サインアップ、サインイン、サインアウト、再読み込み後のセッション復元、保護されたリソースへのアクセスを、エラー状態と読み込み状態も含めて確認します。有効になっている場合は、メールアドレスの確認（共有 SMTP でのコード）もテストしてください。未検証のまま残っているフローがあれば報告します。

セルフマネージドの経路で必須のプラグインは、そのアプリの Better Auth 設定で検証します。Managed のフローとして検証するものではありません。

プラグインのサポート

2026-09-17 に、https://neon.com/docs/auth/guides/plugins.md、https://neon.com/docs/auth/roadmap.md、および @neondatabase/auth クライアントのプラグイン一覧を照合して確認しました。このスキルが古くなっている可能性がある場合は、これらのページを再取得してください。上流のプラグインが一覧にない場合は、最新情報を確認する必要があります。この表にないことを、日付の付いたロードマップ項目として扱わないでください。

「公開されていません」とは、Managed SDK/UI の契約において公開されていないことを意味します。すべての生のサーバーリクエストをテストしたという意味ではありません。

機能	Managed Auth	境界
メールアドレス／パスワード	サポート対象	signUp.email、signIn.email
ソーシャル OAuth（Google、GitHub、Vercel）	サポート対象	signIn.social。共有の Google 認証情報は開発用です。本番環境および GitHub／Vercel では、独自の OAuth アプリが必要です。https://neon.com/docs/auth/guides/setup-oauth.md
管理者	サポート対象	管理者セッションが必要です。プラグインのカスタマイズはロードマップに含まれています。
メール OTP	サポート対象	配信は Managed が行います。emailOtp.sendVerificationOtp、signIn.emailOtp。
マジックリンク	サポート対象	ブランチで有効にしてください（デフォルトでは無効です）。signIn.magicLink。
組織	一部サポート、ベータ版	メンバー、招待、オーナー／管理者／メンバーに対応します。チーム、サーバーフック、カスタムロール／権限、動的アクセス制御には対応していません。メールによる招待については、managed-auth.md を参照してください。
JWT	サポート対象	EdDSA（Ed25519）、有効期限は15分、カスタムクレームには非対応です。デフォルトクライアントでは .token() の後に data.token を使用します。SupabaseAuthAdapter() では getSession() の後に data.session.access_token を使用します（.token() はありません）。
Open API	サポート対象	サーバールート /reference および /open-api/generate-schema。
電話番号	制約付きでサポート	ブラウザクライアントでは、既存ユーザーは電話番号を紐付けてからサインインします。電話番号を先に使ったサインアップには対応していません。独自の SMS ウェブフックとカスタム UI が必要です。Next.js の auth.handler() は、電話 OTP を含むキャッチオールパスを転送します。サーバーメソッド auth.phoneNumber がないのは、型付きヘルパーがないためであり、プロキシによる拒否ではありません。https://neon.com/docs/auth/guides/plugins/phone-number.md
MFA／二要素認証	ロードマップ	Managed Auth では利用できません。必要な場合は、インストール済みの Better Auth のバージョンを確認したうえで、self-managed.md を参照してください。
パスキー、API キー、Generic OAuth、ワンタップ、複数セッション	Managed SDK/UI では公開されていません	必要な場合は、self-managed.md を参照してください。Generic OAuth は Google／GitHub／Vercel のソーシャルサインインとは異なります。
MCP／OAuth プロバイダー	Managed Auth ではありません	サードパーティの MCP クライアントが、サーバーに対して独自に認証します。既存のログインを維持してください。neon-functions の references/mcp.md を参照してください。
SSO／SAML	一覧に記載されておらず、公開もされていません	必要な場合は、インストール済みの Better Auth のバージョンを確認したうえで、self-managed.md を参照してください。

デフォルトの Managed クライアントメソッドは getAnonymousToken() です。この JWT は Neon の匿名 Data API トークンです。Better Auth の Anonymous アカウントプラグイン（signIn.anonymous）ではありません。anonymousTokenClient() は SDK プラグインのファクトリーであり、公開クライアントのメソッドではありません。これを呼び出さないでください。また、SupabaseAuthAdapter() で getAnonymousToken() を呼び出さないでください。

信頼済みドメインとウェブフックは Neon の設定であり、インストール可能な Better Auth プラグインではありません。

信頼済みドメイン

Auth は、許可リストに登録されたオリジンにのみリダイレクトします。invalid domain は、アプリのオリジンが登録されていないことを意味します。スキームを含め、末尾のスラッシュは省略してください。ユーザーを誘導する前に本番環境とプレビュー環境のオリジンを登録し、正しいブランチを指定してください。

neon neon-auth domain add https://app.example.com
neon neon-auth domain list
neon neon-auth domain delete https://old.example.com

デフォルトでは、localhost のポートは事前に承認されています。既存のプロジェクトでは、この設定がオフになっている場合があります：neon neon-auth domain allow-localhost get|enable|disable。ドキュメント：https://neon.com/docs/auth/guides/configure-domains.md

OAuth プロバイダーのリダイレクト先は {NEON_AUTH_BASE_URL}/callback/{provider} です（Auth URL にはパスが含まれます）。signIn.social の callbackURL は、その後にアプリが遷移するランディング先のオリジンであり、信頼済みとして登録する必要があります。

Managed SDK は、iframe を使った OAuth ポップアップと neon_auth_session_verifier を処理します。ラッパー、コールバックルート、ミドルウェアをそのまま使用してください。このフローを独自に再実装したり、すべてのブラウザーでサードパーティ Cookie が使えると約束したりしないでください。

Functions と Data API

Function は、すでにユーザーのサインインに使用されている認証情報を使って認証します。Function を呼び出すために ID を切り替えないでください。トークンの検証については、neon-functions スキルと https://neon.com/docs/compute/functions/authentication.md を参照してください。

Managed Auth：NEON_AUTH_JWKS_URL が注入され、issuer は NEON_AUTH_BASE_URL から取得します。トークン：デフォルトクライアントでは .token() を呼び出し、その後 data.token を取得します。SupabaseAuthAdapter() では getSession() を呼び出し、その後 data.session.access_token を取得します。有効なトークンがあっても、他のユーザーの行を読み取る権限があるとは限りません。サインアウトするとブラウザーのセッションは終了しますが、すでに発行された JWT がただちに失効すると説明しないでください。

Data API の ID については、references/managed-auth.md を参照してください。新規アプリでは、Data API ではなく Functions または既存のハンドラーから Postgres にクエリを実行してください。