workos-convex-auth

# WorkOS Convex Auth Skill > **Always check official docs for the latest information:** > - Convex + WorkOS: https://docs.convex.dev/auth/authkit/ > - WorkOS AuthKit: https://workos.com/docs/authkit > - AuthKit React SDK: https://workos.com/docs/sdks/authkit-react > - Auto provisioning: https://docs.convex.dev/auth/authkit/auto-provision > - Netlify Docs: https://docs.netlify.com/ ## When to use this skill Use this skill when you need to: - Set up WorkOS AuthKit with a Convex backend - Configure dual JWT providers for SSO and User Management - Set environment variables for localhost and production - Implement sign in, sign out, and callback flows - Access user identity in Convex functions - Configure admin access checks based on email domain ## Architecture overview The authentication flow works as follows: 1. User clicks Sign In on the frontend 2. WorkOS AuthKit redirects to hosted login page 3. User authenticates (Google, GitHub, email, etc.) 4. WorkOS redirects back to `/callback` with auth code 5. AuthKit exchanges code for session tokens 6. Convex validates JWT tokens against WorkOS JWKS endpoint 7. `ctx.auth.getUserIdentity()` returns user claims from JWT ## Required packages ```bash npm install @workos-inc/authkit-react @convex-dev/workos ``` ## Configuration files ### convex/auth.config.ts WorkOS issues JWTs from two different issuers. Configure both: ```typescript const clientId = process.env.WORKOS_CLIENT_ID; export default { providers: [ { type: "customJwt", issuer: "https://api.workos.com/", algorithm: "RS256", applicationID: clientId, jwks: `https://api.workos.com/sso/jwks/${clientId}`, }, { type: "customJwt", issuer: `https://api.workos.com/user_management/${clientId}`, algorithm: "RS256", jwks: `https://api.workos.com/sso/jwks/${clientId}`, }, ], }; ``` Key points: - Both providers use the same JWKS endpoint - First provider handles SSO authentication - Second provider handles User Management (email, social login) - The `applicationID` is only needed for the SSO provider ### Frontend setup (React/Vite) ```typescript import { AuthKitProvider, useAuth } from "@workos-inc/authkit-react"; import { ConvexProviderWithAuthKit } from "@convex-dev/workos"; import { ConvexReactClient } from "convex/react"; const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL); const redirectUri = import.meta.env.VITE_WORKOS_REDIRECT_URI; createRoot(document.getElementById("root")!).render( <AuthKitProvider clientId={import.meta.env.VITE_WORKOS_CLIENT_ID} redirectUri={redirectUri} > <ConvexProviderWithAuthKit client={convex} useAuth={useAuth}> <App /> </ConvexProviderWithAuthKit> </AuthKitProvider> ); ``` ## Environment variables ### Frontend (.env.local) ```bash VITE_CONVEX_URL=https://your-deployment.convex.cloud VITE_WORKOS_CLIENT_ID=client_01XXXXXXXXXXXXXXXXXX VITE_WORKOS_REDIRECT_URI=http://localhost:5173/callback ``` ### Convex Dashboard Set in Environment Variables section: ``` WORKOS_CLIENT_ID=client_01XXXXXXXXXXXXXXXXXX ``` ### WorkOS Dashboard Configuration 1. **Redirect URIs**: Add callback URLs - `http://localhost:5173/callback` (development) - `https://yourdomain.netlify.app/components/callback` (Netlify production) - `https://yourdomain.com/callback` (custom domain production) 2. **CORS Origins**: Add allowed origins - `http://localhost:5173` (development) - `https://yourdomain.netlify.app` (Netlify production) - `https://yourdomain.com` (custom domain production) 3. **JWT Template**: Configure email claim (see JWT claims section) ### Netlify Deployment Configuration When deploying to Netlify, configure environment variables in Netlify Dashboard: 1. Go to Site Settings > Environment Variables 2. Add the following variables: - `VITE_CONVEX_URL`: Your Convex deployment URL (e.g., `https://your-deployment.convex.cloud`) - `VITE_WORKOS_CLIENT_ID`: Your WorkOS Client ID - `VITE_WORKOS_REDIRECT_URI`: `https://yourdomain.netlify.app/components/callback` Create a `netlify.toml` in your project root: ```toml [build] command = "npm run build" publish = "dist" [build.environment] NODE_VERSION = "20" [[redirects]] from = "/*" to = "/index.html" status = 200 ``` The SPA redirect rule ensures all routes serve `index.html` for client-side routing. ## Sign in implementation Use `signIn()` directly from the AuthKit hook. Do not use `getSignInUrl()` which is deprecated. ```typescript import { useAuth } from "@workos-inc/authkit-react"; function SignInButton() { const { signIn } = useAuth(); return ( <button onClick={() => { localStorage.setItem("authReturnPath", window.location.pathname); signIn(); }} > Sign In </button> ); } ``` ## Sign out implementation ```typescript import { useAuth } from "@workos-inc/authkit-react"; function SignOutButton() { const { signOut } = useAuth(); return ( <button onClick={() => signOut()}> Sign Out </button> ); } ``` ## OAuth callback handling Handle the callback with proper loading state checks: ```typescript function AuthCallback() { const { isLoading, user, signIn } = useAuth(); const [authFailed, setAuthFailed] = useState(false); const hasAuthCode = useMemo( () => new URLSearchParams(window.location.search).has("code"), [] ); const returnPath = useMemo(() => { const storedPath = localStorage.getItem("authReturnPath"); if (storedPath) { localStorage.removeItem("authReturnPath"); return storedPath; } return "/"; }, []); useEffect(() => { if (isLoading) return; if (user) { window.location.replace(returnPath); return; } if (hasAuthCode) { setAuthFailed(true); return; } window.location.replace(returnPath); }, [hasAuthCode, isLoading, returnPath, user]); return ( <div> {authFailed ? ( <button onClick={() => signIn()}>Try Again</button> ) : ( <div>Finishing sign in...</div> )} </div> ); } ``` ## Checking auth state in components Use `useConvexAuth()` for auth state (not `useAuth()`) to ensure the Convex backend has validated the token: ```typescript import { useConvexAuth, Authenticated, Unauthenticated } from "convex/react"; function MyComponent() { const { isLoading, isAuthenticated } = useConvexAuth(); if (isLoading) return <div>Loading...</div>; return ( <> <Authenticated> <AuthenticatedContent /> </Authenticated> <Unauthenticated> <SignInPrompt /> </Unauthenticated> </> ); } ``` ## Accessing user identity in Convex functions ```typescript import { query, QueryCtx } from "./_generated/server"; import { v } from "convex/values"; export const loggedInUser = query({ args: {}, returns: v.union( v.object({ email: v.optional(v.string()), name: v.optional(v.string()), pictureUrl: v.optional(v.string()), }), v.null() ), handler: async (ctx) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) { return null; } return { email: identity.email, name: identity.name, pictureUrl: identity.pictureUrl, }; }, }); ``` ## Admin access check pattern Check admin status based on email domain: ```typescript import { query, QueryCtx, MutationCtx, ActionCtx } from "./_generated/server"; import { v } from "convex/values"; type AuthContext = QueryCtx | MutationCtx | ActionCtx; export async function requireAdminIdentity(ctx: AuthContext) { const identity = await ctx.auth.getUserIdentity(); if (!identity) { throw new Error("Authentication required"); } const email = identity.email; if (!email?.endsWith("@yourdomain.com")) { throw new Error("Admin access required"); } return identity; } export async function getAdminIdentity(ctx: AuthContext) { const identity = await ctx.auth.getUserIdentity(); if (!identity) { return null; } const email = identity.email; if (!email?.endsWith("@yourdomain.com")) { return null; } return identity; } export const isAdmin = query({ args: {}, returns: v.boolean(), handler: async (ctx) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) { return false; } const email = identity.email; if (!email) { return false; } return email.endsWith("@yourdomain.com"); }, }); ``` ## JWT claims configuration WorkOS JWT templates do not include email by default. Configure in WorkOS Dashboard: 1. Go to WorkOS Dashboard > Authentication > JWT Templates 2. Edit the default template 3. Add required claims: ```json { "email": "{{user.email}}", "name": "{{user.first_name}} {{user.last_name}}", "picture": "{{user.profile_picture_url}}" } ``` After configuration, `ctx.auth.getUserIdentity()` returns: ```typescript { tokenIdentifier: "https://api.workos.com/user_management/client_xxx|user_yyy", subject: "user_yyy", issuer: "https://api.workos.com/user_management/client_xxx", email: "user@example.com", name: "User Name", pictureUrl: "https://..." } ``` ## Production vs development environments ### Different Client IDs Use environment variables to switch between environments: ```typescript // convex/auth.config.ts const clientId = process.env.WORKOS_CLIENT_ID; ``` Set different values in: - `.env.local` for local development - `.env.production` for Netlify builds (or Netlify Dashboard environment variables) - Convex Dashboard for each deployment (dev/prod) ### WorkOS API Key formats - Development: `sk_test_...` - Production: `sk_live_...` ### Client ID format Both environments use: `client_01XXXXXXXXXXXXXXXXXX` ### Netlify vs Local Development URLs | Environment | Redirect URI | CORS Origin | |-------------|--------------|-------------| | Local Dev | `http://localhost:5173/callback` | `http://localhost:5173` | | Netlify | `https://yourdomain.netlify.app/components/callback` | `https://yourdomain.netlify.app` | | Custom Domain | `https://yourdomain.com/callback` | `https://yourdomain.com` | Note: When hosting on Netlify with a `/components` base path, ensure your callback URL includes the full path. ## Checklist for new integration - [ ] Install `@workos-inc/authkit-react` and `@convex-dev/workos` - [ ] Set `WORKOS_CLIENT_ID` in Convex dashboard environment variables - [ ] Set `VITE_WORKOS_CLIENT_ID` in `.env.local` - [ ] Set `VITE_WORKOS_REDIRECT_URI` in `.env.local` - [ ] Configure JWT template in WorkOS dashboard with email claim - [ ] Add redirect URI(s) in WorkOS dashboard (localhost + production) - [ ] Add CORS origins in WorkOS dashboard - [ ] Configure both JWT providers in `convex/auth.config.ts` - [ ] Run `npx convex dev` to sync auth config - [ ] Handle OAuth callback with proper loading state checks - [ ] Use `signIn()` directly, not `getSignInUrl()` - [ ] Test admin access after user logs in with correct email domain ## Checklist for Netlify deployment