Nuxt
Sign in through OAuth in a Nuxt 3 app with Auth.js, locally and in CI, with any of the eight providers Mockatoo mocks.
You don't need a Nuxt auth module. One Nitro server route hands each request
to @auth/core, and @mockatoo/connect-authjs swaps each Auth.js provider
for one pointed at the mock. This guide covers Auth.js. There's no example
for nuxt-auth-utils yet.
Example on GitHub: mockatoo/examples/authjs-nuxt.
The connector setup is the same as in
authjs-next
and authjs-sveltekit.
How it works
- Your sign-in button posts to
/api/auth/signin/<provider>, and Auth.js redirects to the mock on the provider's real paths:accounts.google.com/o/oauth2/v2/authbecomesapp.mockatoo.globalunderdog.com/google/o/oauth2/v2/auth. - You (or a test) fill in the login page and click Authorize.
- The mock redirects back to
/api/auth/callback/<provider>. Auth.js exchanges the code for provider-shaped tokens, checks the ID token or reads the profile, and sets the session cookie, as it would in production.
Your scopes, callbacks and session handling don't change. Only the provider list does, and only when the mock is on.
Prerequisites
- Node.js 24, with
nuxt3,@auth/core,next-auth5 (for its provider imports) and@mockatoo/connect-authjs(package.json). - A Mockatoo test account. Sign up at app.mockatoo.globalunderdog.com, then copy the email and password from the dashboard.
Mount Auth.js in a server route
server/api/auth/[...auth].ts
converts the H3 event to a web Request, runs Auth.js, and sends its
Response back:
import { Auth } from "@auth/core";import { authConfig } from "../../../lib/auth";export default defineEventHandler(async (event) => { const config = useRuntimeConfig(event); const response = await Auth( toWebRequest(event), authConfig(config.mockatooForce || process.env.NODE_ENV !== "production"), ); return sendWebResponse(event, response);});- The catch-all route serves every Auth.js endpoint under
/api/auth: sign-in, callback, session, CSRF and sign-out. - The mock is on outside production. The example's committed
.envalso setsMOCKATOO_FORCE=true, whichnuxt.config.tsreads intoruntimeConfig.mockatooForceat build time, so its live demo runs on the mock. Delete that line in your app. Never ship it.
Point the providers at the mock
lib/auth.ts
picks the mock helpers or the real providers with one switch:
import type { AuthConfig } from "@auth/core";import { MockGitHub, MockGoogle } from "@mockatoo/connect-authjs";import GitHub from "next-auth/providers/github";import Google from "next-auth/providers/google";import { providers } from "./providers";export function authConfig(useMock: boolean): AuthConfig { const options = (index: number) => ({ authorization: { params: { scope: providers[index].scope } }, }); return { secret: process.env.AUTH_SECRET, basePath: "/api/auth", trustHost: true, pages: { signIn: "/", error: "/" }, providers: useMock ? [ MockGoogle({ ...options(1) }), MockGitHub({ ...options(2) }), // …the other providers ] : [ Google({ clientId: process.env.AUTH_GOOGLE_ID, clientSecret: process.env.AUTH_GOOGLE_SECRET, ...options(1), }), // …the other providers ], };}- Each helper wraps Auth.js's own provider and fills in the shared client,
mockatoo/mockatoo-secret. It accepts anyhttp(s)callback, so localhost and preview URLs need no provider setup. optionssets each provider's scopes fromlib/providers.ts, which also lists the buttons.basePathmust match the server route's path.trustHost: truestops Auth.js from rejecting the request's host withUntrustedHost.pagessends sign-in and errors back to/, where the page shows an error when the URL has?error=.
Already use Auth.js with real providers? Keep your list, and in development or
CI swap each provider for its Mock* helper. The example's
README
lists every real provider's credentials and callback path.
Sign in and read the session
app.vue
reads the session during server rendering, and signs in with a CSRF token and
a POST:
const { data: session } = await useFetch<Session | null>("/api/auth/session");async function submit(provider?: string) { const { csrfToken } = await $fetch<{ csrfToken: string }>("/api/auth/csrf"); const result = await $fetch<{ url: string }>( provider ? `/api/auth/signin/${provider}` : "/api/auth/signout", { method: "POST", headers: { "X-Auth-Return-Redirect": "1" }, body: new URLSearchParams({ csrfToken, callbackUrl: "/" }), }, ); window.location.assign(result.url);}useFetchforwards the request's cookies during server rendering, so the first render already knows the user.X-Auth-Return-Redirect: 1makes Auth.js return the redirect URL as JSON instead of a 302, so the page can navigate to it.- With no provider, the same call signs out.
Handle provider differences
| Provider | What Auth.js needs |
|---|---|
| Discord | issuer: "https://discord.com" on both the real and the mock provider: Discord sends iss on every sign-in, and Auth.js rejects it otherwise. MockDiscord swaps in the mock's issuer |
| Microsoft | A profile that skips the photo request: the provider fetches it from graph.microsoft.com, which the mock can't serve |
| X | The users.read tweet.read scope. X's OAuth 2.0 API has no email, so the session shows the name |
| Apple | Nothing with the mock. With the real provider, a signed client secret |
The Microsoft options, from the example:
const microsoft = { ...options(6), profile: (profile: { sub: string; name?: string; email?: string }) => ({ id: profile.sub, name: profile.name, email: profile.email, image: null, }),};See each provider's page, e.g. Discord or Microsoft, for its flow and known differences.
Run it
Create .env.local with AUTH_SECRET set to the output of
openssl rand -base64 32, then run:
pnpm installpnpm devOpen http://localhost:3000, pick a provider and sign in with your dashboard
email and password. To sign in as another user, add a tag to the email, e.g.
you+alice@example.com (see Email tags).
Test with Playwright
To cover failures after setting up sign-in, see OAuth failure testing.
playwright.config.ts
builds and starts the production server, or tests a deployed app when
PLAYWRIGHT_BASE_URL is set:
if (existsSync(".env.local")) process.loadEnvFile(".env.local");export default defineConfig({ testDir: "./tests", use: { baseURL: process.env.PLAYWRIGHT_BASE_URL || "http://localhost:3000" }, webServer: process.env.PLAYWRIGHT_BASE_URL ? undefined : { command: "pnpm build && pnpm start", url: "http://localhost:3000", reuseExistingServer: !process.env.CI, timeout: 180000, },});tests/sign-in.spec.ts
signs in and out with every provider, and declines consent with Google:
await page.goto("/");await page .getByRole("button", { name: `Sign in with ${provider}` }) .click();await page.locator("#email").fill(email as string);await page.locator("#password").fill(password as string);await page.getByRole("button", { name: "Log in with password" }).click();await page.getByRole("button", { name: decision }).click();Add MOCKATOO_TEST_EMAIL and MOCKATOO_TEST_PASSWORD to .env.local or the
environment, then run:
pnpm exec playwright install chromiumpnpm testThe Playwright guide covers fresh users per test, edge-case tags and token refresh. Those tests work the same against a Nuxt app.
Run in CI
The example's workflow type-checks, generates a secret, then runs the tests with the credentials as secrets:
- run: pnpm --dir authjs-nuxt typecheck- name: Generate runtime secret run: echo "AUTH_SECRET=$(openssl rand -base64 32)" >> "$GITHUB_ENV"- run: pnpm --dir authjs-nuxt exec playwright install --with-deps chromium- run: pnpm --dir authjs-nuxt test env: MOCKATOO_TEST_EMAIL: ${{ secrets.MOCKATOO_TEST_EMAIL }} MOCKATOO_TEST_PASSWORD: ${{ secrets.MOCKATOO_TEST_PASSWORD }}More in Run in CI.
Troubleshooting
| Symptom | Fix |
|---|---|
AUTH_SECRET is required. Set it in .env.local or your deployment environment. | Add a random secret to .env.local, or to the deployment's environment |
| The real provider's login page opens | The mock isn't on: run pnpm dev, or set MOCKATOO_FORCE=true in .env before pnpm build. Nuxt reads it at build time |
Set MOCKATOO_TEST_EMAIL and MOCKATOO_TEST_PASSWORD in .env.local or the environment. | Copy the test account's email and password from the dashboard |
| Login fails after a password change | Copy the new password from the dashboard into .env.local and your secrets |
Next steps
- All examples: Auth.js, Better Auth, SvelteKit, Nuxt, Hono, Django, Flask, Laravel and Spring Boot
- Playwright · Email tags · Account flow · Run in CI
- Use Mockatoo only outside production, and never commit its credentials.