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 是托管式 Better Auth：用户、会话和身份验证配置位于分支的 Lakebase Postgres 中的 neon_auth 架构内，身份验证状态会随数据库一起分支。客户端 API 通过 @neondatabase/auth 提供 Better Auth 方法集（signIn.email、signIn.social、getSession）。该封装并非裸 better-auth/client 的即插即用替代品：它固定了插件列表，并添加了 Neon 专用的 OAuth 验证器、iframe 弹出窗口和 JWT 处理逻辑。使用托管式 Auth 期间，请继续使用该封装。

此技能会选择身份验证方案，然后实现托管式 Better Auth。它不会为了使用 Postgres、Functions、Object Storage 或 AI Gateway 而替换现有的可用身份验证服务器。

适用场景

在配置资源之前，先检查现有身份验证方案和所需的登录功能。提供了 DATABASE_URL 并不代表需要更改身份验证方案。添加 Neon Function 也不代表需要更改身份验证方案。

情况	操作
没有现有身份验证方案	默认使用托管式 Better Auth。请参阅托管式设置，然后参阅 references/managed-auth.md。
需要托管式方案不提供的功能	在现有应用托管平台（Vercel 或类似平台）或 Neon Function 上自行托管 Better Auth。继续使用 Lakebase Postgres。推荐迁移前，请确认已安装的 Better Auth 版本文档明确说明了该确切流程。如果支持情况仍未明确，请保留当前身份验证方案。参阅 references/self-managed.md。
已经使用 Better Auth	保持不变。它可与其他 Neon 基础组件配合使用。仅在用户提出要求时迁移到托管式方案。
用户要求从 Supabase Auth 迁移	使用托管式 Better Auth。请参阅 Supabase Auth。仅迁移 Postgres 或添加 Function 时，继续使用 Supabase Auth。
正在使用 Clerk、Auth.js、Supabase Auth 或其他可用的 IdP	除非用户要求迁移，否则保持不变。

托管式 Auth 提供 Google、GitHub 和 Vercel 社交 OAuth。它们并非离开托管式 Auth 的理由。其他 OAuth 提供商、通用 OAuth、MFA、通行密钥、API 密钥、MCP OAuth、SSO、自定义插件、钩子和自定义 JWT 声明，请参阅插件支持矩阵。

启用托管式 Auth 前，请确认项目位于 AWS 上，且未使用 IP Allow 或 Private Networking。请保留这些保护措施。

请通过 Neon（Console、API 或 neon neon-auth）配置受支持的托管式插件，不要将 plugins 传入 @neondatabase/auth。启用 auth: true 并不等于实现了登录功能。

功能

• Postgres 中的托管式身份 — 用户和会话存储在 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。
• 固定的插件集 — 托管式客户端不接受 plugins 选项。请参阅插件支持。

可用性

托管式 Better Auth 已正式发布。仅支持 AWS 区域。启用了 IP Allow 或 Private Networking 的项目无法启用此功能。

组织功能仍处于 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。

可认领项目：遵循父级的可认领项目路径；当用户要求登录且不应保留现有提供方时，再设置 auth: true 并运行 neon deploy。

Supabase Auth

当用户要求从 Supabase Auth 迁移登录时，建议使用托管式 Better Auth，并遵循 https://neon.com/docs/auth/migrate/from-supabase.md。仅迁移 Postgres 或添加 Function 并不属于此需求：保留 Supabase Auth。

SupabaseAuthAdapter() 保留了 signInWithPassword 和 signInWithOAuth 等方法的形式。这些调用不能与默认 Better Auth 示例（signIn.email）互换。现有适配器调用方应继续使用该 API。

盘点实际使用的 Auth 方法和数据库调用：

• 密码哈希无法迁移。用户需要创建新账号或使用 OAuth 登录。
• 不要承诺用户 ID、会话或账号关联保持不变。与所有者一起规划应用外键。
• Managed Auth 上的 updateUser() 无法更改电子邮件地址或密码。电子邮件验证需要应用界面（共享 SMTP 可使用验证码；链接则需要自定义 SMTP）。
• 迁移指南列出的 Supabase 电话/SMS/WhatsApp、SAML 和 Web3 在 Managed Auth 上不受支持。如果用户仍需要该特定流程，请确认已安装的 Better Auth 版本；如果支持情况仍未确认，请保留 Supabase Auth 并停止 Auth 切换。该页面所说的“无电话 Auth”指的是 Supabase 电话登录，并非受限的 Managed Phone Number 插件（现有用户可关联电话号码）。
• 仅将 @supabase/supabase-js 用于 Auth，并不构成启用 Data API 的理由。只有现有的 PostgREST / Supabase 数据库客户端查询才需要保留 Data API。

验证

托管路径：验证注册、登录、登出、重新加载后的会话恢复，以及受保护资源的访问，包括错误和加载状态。如果启用了电子邮件验证（共享 SMTP 上的验证码），也要进行测试。报告任何尚未验证的流程。

自托管路径上必需的插件，应在该应用的 Better Auth 配置中验证，而不是作为托管流程验证。

插件支持

截至 2026-09-17，已对照 https://neon.com/docs/auth/guides/plugins.md、https://neon.com/docs/auth/roadmap.md 和 @neondatabase/auth 客户端插件列表进行核查。如果此技能可能已过时，请重新获取这些页面。上游未列出的插件需要实时核查；不要将其缺席视为表中注明日期的路线图事项。

“未公开”指托管式 SDK/UI 合约，并不表示已测试每个原始服务器请求。

功能	托管式身份验证	边界
邮箱/密码	支持	signUp.email、signIn.email
社交 OAuth（Google、GitHub、Vercel）	支持	signIn.social。共享的 Google 凭据仅用于开发；生产环境以及 GitHub/Vercel 需要使用你自己的 OAuth 应用。https://neon.com/docs/auth/guides/setup-oauth.md
管理员	支持	需要管理员会话。插件自定义功能已列入路线图。
邮箱 OTP	支持	托管式投递。emailOtp.sendVerificationOtp、signIn.emailOtp。
Magic Link	支持	在分支上启用（默认关闭）。signIn.magicLink。
组织	部分支持，Beta	成员、邀请、所有者/管理员/成员。没有团队、服务器钩子、自定义角色/权限或动态访问控制。通过邮件发送的邀请：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 Webhook；需自定义 UI。Next.js auth.handler() 会转发包括电话 OTP 在内的 catch-all 路径。缺少 auth.phoneNumber 服务器方法表示缺少类型化辅助方法，并非代理拒绝请求。https://neon.com/docs/auth/guides/plugins/phone-number.md
MFA / 双因素	路线图	托管式身份验证不支持。如有需要：self-managed.md，并先确认已安装的 Better Auth 版本。
Passkey、API Key、Generic OAuth、One Tap、Multi Session	托管式 SDK/UI 未公开	如有需要：self-managed.md。Generic OAuth 不等同于使用 Google/GitHub/Vercel 进行社交登录。
MCP / OAuth 提供方	不属于托管式身份验证	第三方 MCP 客户端直接向你的服务器进行授权。保留现有登录方式。参见 neon-functions references/mcp.md。
SSO / SAML	未列出或公开	如有需要：self-managed.md，并先确认已安装的 Better Auth 版本。

默认托管式客户端方法是 getAnonymousToken()。该 JWT 是 Neon 匿名 Data API 令牌，不是 Better Auth 的 Anonymous-account 插件（signIn.anonymous）。anonymousTokenClient() 是 SDK 插件工厂，并非公开客户端的方法。不要调用它，也不要在 SupabaseAuthAdapter() 上调用 getAnonymousToken()。

受信任域名和 Webhook 是 Neon 设置，并非可安装的 Better Auth 插件。

受信任的域名

Auth 只会重定向到允许列表中的源。invalid domain 表示应用源缺失。请包含 scheme，不要在末尾加斜杠；在将生产和预览源用于面向用户的服务之前，先注册它们，并指定正确的分支：

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 时不要切换身份。请参阅 neon-functions 技能和 https://neon.com/docs/compute/functions/authentication.md，验证令牌。

Managed Auth：注入的 NEON_AUTH_JWKS_URL，以及来自 NEON_AUTH_BASE_URL 的 issuer。令牌：默认客户端调用 .token()，然后读取 data.token；SupabaseAuthAdapter() 调用 getSession()，然后读取 data.session.access_token。有效令牌并不意味着有权读取其他用户的行。退出登录会结束浏览器会话；不要声称它会立即撤销已签发的 JWT。

Data API 身份信息：references/managed-auth.md。新应用应从 Functions 或现有处理程序查询 Postgres，而不是使用 Data API。