Hono
Sign in through OAuth and OpenID Connect in a Hono app with oauth4webapi, locally and in CI, with Google, Apple, Microsoft, Discord or LinkedIn.
There is no connector package for oauth4webapi. You don't need one: the app reads each provider's endpoints from its discovery document, so changing the issuer URL to the mock's is the whole switch. The authorize, token, user info and JWKS URLs all follow from it.
Example on GitHub: mockatoo/examples/oauth4webapi-hono.
How it works
- Your sign-in form posts to
/sign-in, which fetches the provider's discovery document from the mock and redirects to its authorization endpoint 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
/callback/<provider>. oauth4webapi checks the state, exchanges the code with PKCE, and validates the ID token's signature, issuer, audience, expiry and nonce, as it would in production.
Your routes, scopes and checks don't change. Only the issuer URLs and the client credentials do, and only when the mock is on.
Prerequisites
- Node.js 24, with
hono,@hono/node-serverandoauth4webapi3 (package.json). - A Mockatoo test account. Sign up at app.mockatoo.globalunderdog.com, then copy the email and password from the dashboard.
Point the issuers at the mock
src/app.tsx
lists each provider with its real issuer and its path at the mock. A single
switch picks one, with the shared client or the real credentials:
const useMock = process.env.NODE_ENV !== "production" || process.env.MOCKATOO_FORCE === "true";const origin = process.env.MOCKATOO_URL || "https://app.mockatoo.globalunderdog.com";const providers = [ { id: "google", name: "Google", path: "/google", issuer: "https://accounts.google.com", scope: "openid profile email", pkce: true, }, // …Apple, Microsoft, Discord and LinkedIn] .map((provider) => { const prefix = provider.id.toUpperCase(); const issuer = useMock ? new URL(provider.path, origin).href : process.env[`${prefix}_ISSUER`] || provider.issuer; const client: oauth.Client = { client_id: useMock ? "mockatoo" : process.env[`${prefix}_CLIENT_ID`] || "", }; const clientSecret = useMock ? "mockatoo-secret" : process.env[`${prefix}_CLIENT_SECRET`] || ""; return { ...provider, issuer, client, clientSecret }; }) .filter( (provider) => provider.issuer && provider.client.client_id && provider.clientSecret, );mockatoo/mockatoo-secretis the shared client. It accepts anyhttp(s)callback, so localhost and preview URLs need no provider setup.- The mock's issuer for Google is
https://app.mockatoo.globalunderdog.com/google, and its discovery document lives under it, like Google's. - The filter drops any real provider without credentials, so you can ship with only the providers you've registered.
- The example's committed
.envsetsMOCKATOO_FORCE=trueso its live demo runs on the mock. Delete that line in your app. Never ship it.
Each request reads the endpoints from discovery:
const metadata = async (issuer: string) => { const url = new URL(issuer); return oauth.processDiscoveryResponse( url, await oauth.discoveryRequest(url, options), );};options is empty against the hosted mock. It only allows plain HTTP for a
mock running on localhost.
Sign in and read the user
The /sign-in route keeps the state, nonce and PKCE verifier in a signed
cookie, then redirects to the authorization endpoint from discovery:
const verifier = oauth.generateRandomCodeVerifier();const state = oauth.generateRandomState();const nonce = oauth.generateRandomNonce();// …setSignedCookie(c, "transaction", …) with these and the provider IDconst url = new URL(server.authorization_endpoint);url.search = new URLSearchParams({ client_id: client.client_id, redirect_uri: new URL(`/callback/${provider.id}`, c.req.url).href, response_type: "code", scope: provider.scope, state, ...(provider.id === "linkedin" ? {} : { nonce }), ...(provider.pkce ? { code_challenge: await oauth.calculatePKCECodeChallenge(verifier), code_challenge_method: "S256", } : {}), ...(provider.id === "apple" ? { response_mode: "form_post" } : {}),}).toString();return c.redirect(url.href);The /callback/:provider route checks the response against that cookie,
exchanges the code, and validates the ID token:
const parameters = oauth.validateAuthResponse( server, client, callback, transaction.state,);const response = await oauth.authorizationCodeGrantRequest( server, client, clientAuth(provider), parameters, new URL(`/callback/${provider.id}`, c.req.url).href, provider.pkce ? transaction.verifier : oauth.nopkce, options,);const tokens = await oauth.processAuthorizationCodeResponse( server, client, response, { expectedNonce: provider.id === "linkedin" ? undefined : transaction.nonce, requireIdToken: true, },);await oauth.validateApplicationLevelSignature(server, response, options);const claims = oauth.getValidatedIdTokenClaims(tokens);- For every provider but Apple, the route then calls
userInfoRequestandprocessUserInfoResponsewithclaims.sub, so user info must belong to the same subject as the ID token. - The email goes into a one-hour session cookie encrypted with AES-GCM
(
src/session.ts). No database is needed. - Any failure redirects to
/?error=callback, which the page shows as an alert.
Handle provider differences
| Provider | What oauth4webapi needs |
|---|---|
| Apple | No PKCE, response_mode=form_post, and the client secret in the form body. The callback is a cross-site POST, so the transaction cookie is SameSite=None; Secure. There's no user info endpoint: the email comes from the validated ID token |
| No PKCE and no nonce, and the client secret in the form body | |
| Discord | openid identify email. The ID token has no email, so it comes from user info |
| Microsoft | A fixed tenant in the issuer path, so discovery and the token's issuer match exactly |
Apple and LinkedIn send the secret with ClientSecretPost, the others with
HTTP Basic:
const clientAuth = (provider: (typeof providers)[number]) => provider.id === "apple" || provider.id === "linkedin" ? oauth.ClientSecretPost(provider.clientSecret) : oauth.ClientSecretBasic(provider.clientSecret);The callback route accepts GET and POST (app.on(["GET", "POST"], …)), and
rejects a POST from any provider but Apple, or a GET from Apple.
See each provider's page, e.g. Apple or Microsoft, for its flow and known differences.
Revoke the token on sign-out
Google's and Apple's discovery documents advertise a revocation_endpoint.
For those, the session keeps the access token, and /sign-out revokes it at
the provider:
const server = await metadata(provider.issuer);await oauth.processRevocationResponse( await oauth.revocationRequest( server, provider.client, clientAuth(provider), current.accessToken, options, ),);return c.redirect(`/?revoked=${provider.id}`);The mock serves the same endpoint, so the test can check that revocation succeeded: the page shows "Signed out. Your Google access token was revoked."
Run it
Create .env.local with SESSION_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
compiles the app and starts it:
export default defineConfig({ testDir: "./tests", use: { baseURL: "http://localhost:3000" }, webServer: { command: "pnpm build && pnpm start", url: "http://localhost:3000", timeout: 120000, reuseExistingServer: false, },});tests/sign-in.spec.ts
authorizes and denies with all five providers. After a sign-in it reloads,
signs out, and checks the revocation message for Google and Apple:
await page.goto("/");await page .getByRole("button", { name: `Sign in with ${provider}`, exact: true }) .click();await page.getByLabel("Email", { exact: true }).fill(email as string);await page .getByLabel("Password", { exact: true }) .fill(password as string);await page.getByRole("button", { name: "Log in with password" }).click();await page.getByRole("button", { name: decision, exact: true }).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 Hono app.
Run in CI
The example's workflow type-checks, generates a session secret, then runs the tests with the credentials as secrets:
- run: pnpm --dir oauth4webapi-hono typecheck- name: Generate runtime secret run: echo "SESSION_SECRET=$(openssl rand -base64 32)" >> "$GITHUB_ENV"- run: pnpm --dir oauth4webapi-hono exec playwright install --with-deps chromium- run: pnpm --dir oauth4webapi-hono test env: MOCKATOO_TEST_EMAIL: ${{ secrets.MOCKATOO_TEST_EMAIL }} MOCKATOO_TEST_PASSWORD: ${{ secrets.MOCKATOO_TEST_PASSWORD }}More in Run in CI.
Troubleshooting
| Symptom | Fix |
|---|---|
Set SESSION_SECRET to a random secret of at least 32 characters. on startup | Add SESSION_SECRET to .env.local or the deployment's environment |
Configure provider credentials or set MOCKATOO_FORCE=true. | The mock is off and no real provider has credentials. Set MOCKATOO_FORCE=true, or add a provider's <PROVIDER>_CLIENT_ID and <PROVIDER>_CLIENT_SECRET |
Invalid origin (403) from /sign-in or /sign-out | The POST's Origin header must match the app's origin. Post from the app's own page |
Apple sign-in ends on /?error=callback over plain HTTP | The transaction cookie is SameSite=None; Secure. Use HTTPS, or Chromium on localhost, which treats it as secure |
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: Hono, Auth.js, Better Auth, SvelteKit, Nuxt, Django, Flask, Laravel and Spring Boot
- Playwright · Email tags · Account flow · Run in CI
- Use Mockatoo only outside production, and never commit its credentials.