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

  1. 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/auth becomes app.mockatoo.globalunderdog.com/google/o/oauth2/v2/auth.
  2. You (or a test) fill in the login page and click Authorize.
  3. 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

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-secret is the shared client. It accepts any http(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 .env sets MOCKATOO_FORCE=true so 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 userInfoRequest and processUserInfoResponse with claims.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

ProviderWhat oauth4webapi needs
AppleNo 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
LinkedInNo PKCE and no nonce, and the client secret in the form body
Discordopenid identify email. The ID token has no email, so it comes from user info
MicrosoftA 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 dev

Open 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 test

The 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

SymptomFix
Set SESSION_SECRET to a random secret of at least 32 characters. on startupAdd 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-outThe 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 HTTPThe 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 changeCopy the new password from the dashboard into .env.local and your secrets

Next steps