diff --git a/README.md b/README.md index 58037d21..c9940683 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,12 @@ A comprehensive index of Neon Serverless Postgres documentation and best practic Choose and create the right Neon branch type for migration testing and isolated development workflows, including schema-only branches for sensitive data and reset-from-parent workflows to quickly realign child branches. +### Neon Auth + +[skills/neon-auth](skills/neon-auth/SKILL.md) + +Provision and configure Neon Auth for an app so users can sign in with email/password or OAuth without standing up a separate auth service. Covers trusted origins, OAuth providers, the email provider, and wiring the Neon JS SDK into a Next.js or React project. + ### Claimable Postgres [skills/claimable-postgres](skills/claimable-postgres/SKILL.md) diff --git a/skills/neon-auth/SKILL.md b/skills/neon-auth/SKILL.md new file mode 100644 index 00000000..5af8296c --- /dev/null +++ b/skills/neon-auth/SKILL.md @@ -0,0 +1,106 @@ +--- +name: neon-auth +description: >- + Provision and configure Neon Auth for an app so users can sign in with + email/password or OAuth without standing up a separate auth service. Use + when users ask to add authentication to a Next.js, React, or Node project + backed by Neon, configure trusted origins or OAuth providers, manage the + email provider, or wire Neon Auth into the Neon JS SDK. Triggers include + "Neon Auth", "add authentication", "sign in with Neon", "OAuth provider", + "trusted origins", "JWKS URL", "@neondatabase/neon-js auth", "neon auth + email provider", and "set up Neon Auth for my Next.js app". +--- + +# Neon Auth + +The outcome of this skill should be a Neon project branch with Neon Auth provisioned and the application wired up to authenticate users against it. + +Neon Auth provides managed user authentication infrastructure for Neon projects — email/password, OAuth providers, JWT-based sessions, and an email provider — without operating a separate auth service. + +Official docs: https://neon.com/docs/auth/overview + +## When To Use + +Pick Neon Auth when the user wants any of: + +- Email/password sign-in. +- OAuth sign-in (for example Google, GitHub). +- A JWKS endpoint they can verify in their backend. +- A managed email provider for transactional auth mail. + +If the user has an existing auth provider (Clerk, Auth0, custom JWT) and is not asking to replace it, do not provision Neon Auth — recommend their existing provider keep emitting JWTs and point them at Neon's external JWKS configuration on the Data API instead. + +## Tool Selection: MCP or Console + +Prefer the tool the user already has installed and authenticated. + +1. **Neon MCP server** (preferred when available): `provision_neon_auth`, `get_neon_auth_config`, and `configure_neon_auth` cover the full lifecycle. +2. **Neon Console**: https://console.neon.tech — visual configuration when MCP is not available. +3. **Neon REST API**: fall back to the API when neither MCP nor Console is appropriate (for example, scripting bulk provisioning). + +MCP overview: https://neon.com/docs/ai/neon-mcp-server + +## Provision + +Provision Neon Auth on the branch the application will authenticate against — typically the default branch for a project. + +### MCP path + +1. Confirm the target project and branch: + - `list_projects` to find the project. + - `describe_project` to confirm branches. +2. Call `provision_neon_auth` for the chosen branch. If Neon Auth is already provisioned, the tool returns the existing configuration instead of erroring — surface that to the user rather than re-running. +3. Read back the resulting `base_url`, `jwks_url`, and default sign-in methods with `get_neon_auth_config`. The user will need `jwks_url` for backend JWT verification. + +### What you get + +- `base_url`: hosted Neon Auth endpoint for this branch. +- `jwks_url`: public JWKS endpoint for verifying issued JWTs. +- Default trusted origins (typically `http://localhost:3000` for development). +- A default allowed auth method (email + password). + +Secrets such as OAuth client secrets and SMTP passwords are redacted in `get_neon_auth_config` responses; configure them with `configure_neon_auth`. + +## Configure + +Use `configure_neon_auth` to: + +- Add or remove trusted origins (production domains, preview deployment hosts). +- Toggle localhost as a trusted origin during development. +- Enable, disable, or tune email-and-password sign-in (for example, require email verification). +- Add, update, or remove OAuth providers (client ID and secret per provider). +- Configure the email provider (SMTP host, port, credentials, from address). +- Send a test email after configuring the provider, before relying on it for production sign-in flows. + +When updating production configuration, ask the user to confirm trusted origins and OAuth redirect URIs are correct before applying — a wrong trusted origin will break sign-in for real users. + +## Wire Up the App + +For Next.js or React, integrate via the Neon JS SDK (`@neondatabase/neon-js`), which has Neon Auth helpers built in. The SDK reads the Neon Auth `base_url` and `jwks_url` from environment variables, so emit those into the project's `.env` after provisioning (do not overwrite existing keys without confirmation). + +For backend verification in any language, validate incoming JWTs against `jwks_url`. The Neon Auth-issued JWT's `sub` claim is the user ID. + +## Agent Workflow + +1. **Confirm intent**: confirm the user wants Neon to host their auth (not just verify external JWTs). If they only need JWT verification, point them at the Neon Data API external-JWKS path instead. +2. **Pick branch**: confirm which Neon branch should host auth — usually the default branch. +3. **Provision**: call `provision_neon_auth` via MCP; if already provisioned, surface the existing config. +4. **Read config**: call `get_neon_auth_config` and share `base_url` and `jwks_url` with the user. +5. **Add trusted origins**: ask the user for their production and preview domains, then call `configure_neon_auth` to add them. +6. **OAuth providers (optional)**: if requested, gather client IDs and secrets and add them via `configure_neon_auth`. Remind the user that secrets are redacted on read and cannot be recovered through the API. +7. **Email provider (optional)**: if email/password sign-in is enabled, configure the email provider and send a test email before considering setup complete. +8. **Write env**: emit `NEON_AUTH_BASE_URL` and `NEON_AUTH_JWKS_URL` to the project's `.env`. Do not overwrite existing keys without confirmation. +9. **Report**: tell the user which branch was provisioned, where credentials were written, and what trusted origins are now active. + +## Safety and UX Notes + +- Never write Neon Auth secrets (OAuth client secrets, SMTP passwords) into committed files. They belong in environment variables or a secret manager. +- After writing to a `.env` file, check that it is covered by `.gitignore`. If not, warn the user. Do not modify `.gitignore` without confirmation. +- Do not enable email/password sign-in in production without first configuring the email provider — users will not be able to verify their addresses. +- When removing a trusted origin, confirm with the user — removing the live production origin will lock real users out. + +## Further reading + +- https://neon.com/docs/auth/overview +- https://neon.com/docs/ai/neon-mcp-server +- https://neon.com/docs/connect/choose-connection