148 lines
6.2 KiB
Markdown
148 lines
6.2 KiB
Markdown
# WorkOS AuthKit
|
|
|
|
Official docs:
|
|
|
|
- https://docs.convex.dev/auth/authkit/
|
|
- https://docs.convex.dev/auth/authkit/add-to-app
|
|
- https://docs.convex.dev/auth/authkit/auto-provision
|
|
|
|
Use this when the app already uses WorkOS or the user wants AuthKit
|
|
specifically.
|
|
|
|
## Workflow
|
|
|
|
1. Confirm the user wants WorkOS AuthKit
|
|
2. Determine whether they want:
|
|
- a Convex-managed WorkOS team
|
|
- an existing WorkOS team
|
|
3. Ask whether the user wants local-only setup or production-ready setup now
|
|
4. Read the official Convex and WorkOS AuthKit guide
|
|
5. Create or update `convex.json` for the app's framework and real local port
|
|
6. Follow the correct branch of the setup flow based on that choice
|
|
7. Configure the required WorkOS environment variables
|
|
8. Configure `convex/auth.config.ts` for WorkOS-issued JWTs
|
|
9. Wire the client provider and callback flow
|
|
10. Verify authenticated requests reach Convex
|
|
11. If the user wants production-ready setup, make sure the production WorkOS
|
|
configuration is covered too
|
|
12. Only add `storeUser` or a `users` table if the app needs first-class user
|
|
rows inside Convex
|
|
|
|
## What To Do
|
|
|
|
- Read the official Convex and WorkOS AuthKit guide before writing setup code
|
|
- Determine whether the user wants a Convex-managed WorkOS team or an existing
|
|
WorkOS team
|
|
- Treat `convex.json` as a first-class part of the AuthKit setup, not an
|
|
optional extra
|
|
- Follow the current setup flow from the docs instead of relying on older
|
|
examples
|
|
|
|
## Key Setup Areas
|
|
|
|
- package installation for the app's framework
|
|
- `convex.json` with the `authKit` section for dev, and preview or prod if
|
|
needed
|
|
- environment variables such as `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, and
|
|
redirect configuration
|
|
- `convex/auth.config.ts` wiring for WorkOS-issued JWTs
|
|
- client provider setup and token flow into Convex
|
|
- login callback and redirect configuration
|
|
|
|
## Files and Env Vars To Expect
|
|
|
|
- `convex.json`
|
|
- `convex/auth.config.ts`
|
|
- frontend auth provider wiring
|
|
- callback or redirect route setup where the framework requires it
|
|
- WorkOS environment variables commonly include:
|
|
- `WORKOS_CLIENT_ID`
|
|
- `WORKOS_API_KEY`
|
|
- `WORKOS_COOKIE_PASSWORD`
|
|
- `VITE_WORKOS_CLIENT_ID`
|
|
- `VITE_WORKOS_REDIRECT_URI`
|
|
- `NEXT_PUBLIC_WORKOS_REDIRECT_URI`
|
|
|
|
For a managed WorkOS team, `convex dev` can provision the AuthKit environment
|
|
and write local env vars such as `VITE_WORKOS_CLIENT_ID` and
|
|
`VITE_WORKOS_REDIRECT_URI` into `.env.local` for Vite apps.
|
|
|
|
## Concrete Steps
|
|
|
|
1. Choose Convex-managed or existing WorkOS team
|
|
2. Create or update `convex.json` with the `authKit` section for the framework
|
|
in use
|
|
3. Make sure the dev `redirectUris`, `appHomepageUrl`, `corsOrigins`, and local
|
|
redirect env vars match the app's actual local port
|
|
4. For a managed WorkOS team, run `npx convex dev` and follow the interactive
|
|
onboarding flow
|
|
5. For an existing WorkOS team, get `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` from
|
|
the WorkOS dashboard and set them with `npx convex env set`
|
|
6. Create or update `convex/auth.config.ts` for WorkOS JWT validation
|
|
7. Run the normal Convex dev or deploy flow so backend config is synced
|
|
8. Wire the WorkOS client provider in the app
|
|
9. Configure callback and redirect handling
|
|
10. Verify the user can sign in and return to the app
|
|
11. Verify Convex sees the authenticated user after login
|
|
12. If the user wants production-ready setup, configure the production client
|
|
ID, API key, redirect URI, and deployment settings too
|
|
|
|
## Gotchas
|
|
|
|
- The docs split setup between Convex-managed and existing WorkOS teams, so ask
|
|
which path the user wants if it is not obvious
|
|
- Keep dev and prod WorkOS configuration separate where the docs call for
|
|
different client IDs or API keys
|
|
- Only add `storeUser` or a `users` table if the app needs first-class user rows
|
|
inside Convex
|
|
- Do not mix dev and prod WorkOS credentials or redirect URIs
|
|
- If the repo already contains WorkOS setup, preserve the current tenant model
|
|
unless the user wants to change it
|
|
- For managed WorkOS setup, `convex dev` is interactive the first time. In
|
|
non-interactive terminals, stop and ask the user to complete the onboarding
|
|
prompts.
|
|
- `convex.json` is not optional for the managed AuthKit flow. It drives redirect
|
|
URI, homepage URL, CORS configuration, and local env var generation.
|
|
- If the frontend starts on a different port than the one in `convex.json`, the
|
|
hosted WorkOS sign-in flow will point to the wrong callback URL. Update
|
|
`convex.json`, update the local redirect env var, and run `npx convex dev`
|
|
again.
|
|
- Vite can fall off `5173` if other apps are already running. Do not assume the
|
|
default port still matches the generated AuthKit config.
|
|
- A successful WorkOS sign-in should redirect back to the local callback route
|
|
and then reach a Convex-authenticated state. Do not stop at "the hosted WorkOS
|
|
page loaded."
|
|
|
|
## Production
|
|
|
|
- Ask whether the user wants dev-only setup or production-ready setup
|
|
- If the answer is production-ready, make sure the production WorkOS client ID,
|
|
API key, redirect URI, and Convex deployment config are all covered
|
|
- Verify the production redirect and callback 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.
|
|
|
|
## Validation
|
|
|
|
- Verify the user can complete the login flow and return to the app
|
|
- Verify the callback URL matches the real frontend port in local dev
|
|
- Verify Convex receives authenticated requests after login
|
|
- Verify `convex.json` matches the framework and chosen WorkOS setup path
|
|
- Verify `convex/auth.config.ts` matches the chosen WorkOS setup path
|
|
- Verify environment variables differ correctly between local and production
|
|
where needed
|
|
- If production-ready setup was requested, verify the production WorkOS
|
|
configuration is also covered
|
|
|
|
## Checklist
|
|
|
|
- [ ] Confirm the user wants WorkOS AuthKit
|
|
- [ ] Ask whether the user wants local-only setup or production-ready setup
|
|
- [ ] Choose Convex-managed or existing WorkOS team
|
|
- [ ] Create or update `convex.json`
|
|
- [ ] Configure WorkOS environment variables
|
|
- [ ] Configure `convex/auth.config.ts`
|
|
- [ ] Verify authenticated requests reach Convex after login
|
|
- [ ] If requested, configure the production deployment too
|