189 lines
8.2 KiB
Markdown
189 lines
8.2 KiB
Markdown
# Convex Auth
|
|
|
|
Official docs: https://docs.convex.dev/auth/convex-auth Setup guide:
|
|
https://labs.convex.dev/auth/setup
|
|
|
|
Use this when the user wants auth handled directly in Convex rather than through
|
|
a third-party provider.
|
|
|
|
## Workflow
|
|
|
|
1. Confirm the user wants Convex Auth specifically
|
|
2. Determine which sign-in methods the app needs:
|
|
- magic links or OTPs
|
|
- OAuth providers
|
|
- passwords and password reset
|
|
3. Ask whether the user wants local-only setup or production-ready setup now
|
|
4. Read the Convex Auth setup guide before writing code
|
|
5. Make sure the project has a configured Convex deployment:
|
|
- run `npx convex dev` first if `CONVEX_DEPLOYMENT` is not set
|
|
- if CLI configuration requires interactive human input, stop and ask the
|
|
user to complete that step before continuing
|
|
6. Install the auth packages:
|
|
- `npm install @convex-dev/auth @auth/core@0.37.0`
|
|
7. Run the initialization command:
|
|
- `npx @convex-dev/auth`
|
|
8. Confirm the initializer created:
|
|
- `convex/auth.config.ts`
|
|
- `convex/auth.ts`
|
|
- `convex/http.ts`
|
|
9. Add the required `authTables` to `convex/schema.ts`
|
|
10. Replace plain `ConvexProvider` wiring with `ConvexAuthProvider`
|
|
11. Configure at least one auth method in `convex/auth.ts`
|
|
12. Run `npx convex dev --once` or the normal dev flow to push the updated
|
|
schema and generated code
|
|
13. Verify the client can sign in successfully
|
|
14. Verify Convex receives authenticated identity in backend functions
|
|
15. If the user wants production-ready setup, make sure the same auth setup is
|
|
configured for the production deployment as well
|
|
16. Only add a `users` table and `storeUser` flow if the app needs app-level
|
|
user records inside Convex
|
|
|
|
## What This Reference Is For
|
|
|
|
- choosing Convex Auth as the default provider for a new Convex app
|
|
- understanding whether the app wants magic links, OTPs, OAuth, or passwords
|
|
- keeping the setup provider-specific while using the official Convex Auth docs
|
|
for identity and authorization behavior
|
|
|
|
## What To Do
|
|
|
|
- Read the Convex Auth setup guide before writing setup code
|
|
- Follow the setup flow from the docs rather than recreating it from memory
|
|
- If the app is new, consider starting from the official starter flow instead of
|
|
hand-wiring everything
|
|
- Treat `npx @convex-dev/auth` as a required initialization step for existing
|
|
apps, not an optional extra
|
|
|
|
## Concrete Steps
|
|
|
|
1. Install `@convex-dev/auth` and `@auth/core@0.37.0`
|
|
2. Run `npx convex dev` if the project does not already have a configured
|
|
deployment
|
|
3. If `npx convex dev` blocks on interactive setup, ask the user explicitly to
|
|
finish configuring the Convex deployment
|
|
4. Run `npx @convex-dev/auth`
|
|
5. Confirm the generated auth setup is present before continuing:
|
|
- `convex/auth.config.ts`
|
|
- `convex/auth.ts`
|
|
- `convex/http.ts`
|
|
6. Add `authTables` to `convex/schema.ts`
|
|
7. Replace `ConvexProvider` with `ConvexAuthProvider` in the app entry
|
|
8. Configure the selected auth methods in `convex/auth.ts`
|
|
9. Run `npx convex dev --once` or the normal dev flow so the updated schema and
|
|
auth files are pushed
|
|
10. Verify login locally
|
|
11. If the user wants production-ready setup, repeat the required auth
|
|
configuration against the production deployment
|
|
|
|
## Expected Files and Decisions
|
|
|
|
- `convex/schema.ts`
|
|
- frontend app entry such as `src/main.tsx` or the framework-equivalent provider
|
|
file
|
|
- generated Convex Auth setup produced by `npx @convex-dev/auth`
|
|
- an existing configured Convex deployment, or the ability to create one with
|
|
`npx convex dev`
|
|
- `convex/auth.ts` starts with `providers: []` until the app configures actual
|
|
sign-in methods
|
|
|
|
- Decide whether the user is creating a new app or adding auth to an existing
|
|
app
|
|
- For a new app, prefer the official starter flow instead of rebuilding setup by
|
|
hand
|
|
- Decide which auth methods the app needs:
|
|
- magic links or OTPs
|
|
- OAuth providers
|
|
- passwords
|
|
- Decide whether the user wants local-only setup or production-ready setup now
|
|
- Decide whether the app actually needs a `users` table inside Convex, or
|
|
whether provider identity alone is enough
|
|
|
|
## Gotchas
|
|
|
|
- Do not assume a specific sign-in method. Ask which methods the app needs
|
|
before wiring UI and backend behavior.
|
|
- `npx @convex-dev/auth` is important because it initializes the auth setup,
|
|
including the key material. Do not skip it when adding Convex Auth to an
|
|
existing project.
|
|
- `npx @convex-dev/auth` will fail if the project does not already have a
|
|
configured `CONVEX_DEPLOYMENT`.
|
|
- `npx convex dev` may require interactive setup for deployment creation or
|
|
project selection. If that happens, ask the user explicitly for that human
|
|
step instead of guessing.
|
|
- `npx @convex-dev/auth` does not finish the whole integration by itself. You
|
|
still need to add `authTables`, swap in `ConvexAuthProvider`, and configure at
|
|
least one auth method.
|
|
- A project can still build even if `convex/auth.ts` still has `providers: []`,
|
|
so do not treat a successful build as proof that sign-in is fully configured.
|
|
- Convex Auth does not mean every app needs a `users` table. If the app only
|
|
needs authentication gates, `ctx.auth.getUserIdentity()` may be enough.
|
|
- If the app is greenfield, starting from the official starter flow is usually
|
|
better than partially recreating it by hand.
|
|
- Do not stop at local dev setup if the user expects production-ready auth. The
|
|
production deployment needs the auth setup too.
|
|
- Keep provider-specific setup and Convex Auth authorization behavior in the
|
|
official docs instead of inventing shared patterns from memory.
|
|
|
|
## Production
|
|
|
|
- Ask whether the user wants dev-only setup or production-ready setup
|
|
- If the answer is production-ready, make sure the auth configuration is applied
|
|
to the production deployment, not just the dev deployment
|
|
- Verify production-specific redirect URLs, auth method configuration, and
|
|
deployment settings before calling the task complete
|
|
- Do not silently write a notes file into the repo by default. If the user wants
|
|
rollout or handoff docs, create one explicitly.
|
|
|
|
## Human Handoff
|
|
|
|
If `npx convex dev` or deployment setup requires human input:
|
|
|
|
- stop and explain exactly what the user needs to do
|
|
- say why that step is required
|
|
- resume the auth setup immediately after the user confirms it is done
|
|
|
|
## Validation
|
|
|
|
- Verify the user can complete a sign-in flow
|
|
- Offer to validate sign up, sign out, and sign back in with the configured auth
|
|
method
|
|
- If browser automation is available in the environment, you can do this
|
|
directly
|
|
- If browser automation is not available, give the user a short manual
|
|
validation checklist instead
|
|
- Verify `ctx.auth.getUserIdentity()` returns an identity in protected backend
|
|
functions
|
|
- Verify protected UI only renders after Convex-authenticated state is ready
|
|
- Verify environment variables and redirect settings match the current app
|
|
environment
|
|
- Verify `convex/auth.ts` no longer has an empty `providers: []` configuration
|
|
once the app is meant to support real sign-in
|
|
- Run `npx convex dev --once` or the normal dev flow after setup changes and
|
|
confirm Convex codegen and push succeed
|
|
- If production-ready setup was requested, verify the production deployment is
|
|
also configured correctly
|
|
|
|
## Checklist
|
|
|
|
- [ ] Confirm the user wants Convex Auth specifically
|
|
- [ ] Ask whether the user wants local-only setup or production-ready setup
|
|
- [ ] Ensure a Convex deployment is configured before running auth
|
|
initialization
|
|
- [ ] Install `@convex-dev/auth` and `@auth/core@0.37.0`
|
|
- [ ] Run `npx convex dev` first if needed
|
|
- [ ] Run `npx @convex-dev/auth`
|
|
- [ ] Confirm `convex/auth.config.ts`, `convex/auth.ts`, and `convex/http.ts`
|
|
were created
|
|
- [ ] Follow the setup guide for package install and wiring
|
|
- [ ] Add `authTables` to `convex/schema.ts`
|
|
- [ ] Replace `ConvexProvider` with `ConvexAuthProvider`
|
|
- [ ] Configure at least one auth method in `convex/auth.ts`
|
|
- [ ] Run `npx convex dev --once` or the normal dev flow after setup changes
|
|
- [ ] Confirm which sign-in methods the app needs
|
|
- [ ] Verify the client can sign in and the backend receives authenticated
|
|
identity
|
|
- [ ] Offer end-to-end validation of sign up, sign out, and sign back in
|
|
- [ ] If requested, configure the production deployment too
|
|
- [ ] Only add extra `users` table sync if the app needs app-level user records
|