Implemented flow
The mock implements the OAuth 2.0 authorization code flow with OpenID Connect: authorization and consent, code exchange, signed ID tokens, discovery, JWKS and userinfo. It supports PKCE, offline access and token refresh.
Google APIs such as Calendar and Drive are not served. Accepting their scopes lets you test sign-in configuration; it does not make those APIs available or validate your Google Cloud project's consent and verification settings.
Sources: web server flow, OIDC.
OpenID Connect (OIDC)
This provider supports OpenID Connect (OIDC), which adds signed ID tokens to OAuth 2.0 so your app can verify the signed-in user's identity. Mockatoo publishes OIDC discovery and signing keys for this provider. See the Hono + oauth4webapi example for a minimal authorization code flow with discovery and ID-token validation, including this provider's differences, without an auth abstraction.
Using the connector
// Better Auth: pass the same options you give socialProviders.googleimport { mockGoogle } from "@mockatoo/connect-better-auth";const google = { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, accessType: "offline" as const };export const auth = betterAuth({ socialProviders: process.env.NODE_ENV === "production" ? { google } : {}, plugins: process.env.NODE_ENV === "production" ? [] : [mockGoogle(google)],});// Auth.jsimport Google from "next-auth/providers/google";import { MockGoogle } from "@mockatoo/connect-authjs";providers: [process.env.NODE_ENV === "production" ? Google() : MockGoogle()],- Request
access_type=offlinefor a refresh token. Each normal mock sign-in represents first consent;+returningrepresents a later sign-in with no refresh token unless you requestprompt=consent. - Published Google scopes are accepted, including API scopes. With
include_granted_scopes=true, granted scopes accumulate for the user. prompt=nonereturnsinteraction_requiredbecause there is no remembered login session. Bad clients and invalid scopes stop at an error page; denial returnsaccess_deniedto your callback.- Email verification, missing names and Workspace membership can be exercised with the special addresses below.
Special test addresses
Log in as you+<tag>@example.com with your own account's password to get a distinct, stable test user. Tags combine with dots, such as you+hd.unverified@example.com. Any other tag, such as you+1@example.com, is just another user; see Email tags.
| Tag | Behavior | |
|---|---|---|
hd | Workspace user: ID token includes hd with the email's domain | Example |
unverified | email_verified: false (GitHub: primary email verified: false; Discord: verified: false; LinkedIn: "false" in the ID token) | Example |
renamed | Same user ID (sub, Microsoft oid, GitHub, Discord, X and Facebook id) as the address without +renamed, different email | Example |
noname | No name (Google: also no given_name/family_name; GitHub: name: null; Discord: global_name: null) | Example |
firstname | Only name/given_name, no family_name | Example |
returning | Same user and email as without the tag, signing in again. Google: no refresh token unless prompt=consent. Apple: no user field, so no name | Example |
revoked | Sign-in works; every refresh returns invalid_grant (GitHub: bad_refresh_token, and only with offline_access; X: invalid_request) | Example |
badcode | The code exchange fails (invalid_grant; GitHub: bad_verification_code; LinkedIn and X: invalid_request; Facebook: Invalid verification code format.) | Example |
down | The token endpoint returns 503 | Example |
flaky | The first exchange of each code returns 503; a retry succeeds | Example |
slow | Token responses are delayed (10 seconds) | Example |
blocked | After login, Google's "Access blocked" or Microsoft's "Need admin approval" page | Example |
Known differences
Shared mock limits
| Difference | Effect |
|---|---|
| ID tokens are issued to the shared mock client. Native bundle IDs and native client registrations are not modeled. | Hides a native audience setting that does not match your production registration. |
Refresh tokens do not expire from age or inactivity, even when a response advertises refresh_token_expires_in. Rotation and revocation still apply where supported; +revoked forces refresh failure. | Hides failures after long periods without sign-in. Use +revoked to exercise expired or revoked grant handling. |
Any http/https callback URL is accepted, including localhost. Apple refuses http and localhost, and Microsoft refuses http except for localhost, whatever the app registered. | Hides a callback URL the real provider refuses outright. |
Everyone uses one shared client (mockatoo / mockatoo-secret). The connectors replace your production client ID and secret, Apple's signed client secret, and Microsoft's client assertion. | Hides wrong production credentials or a broken client-secret setup. |
The login form and the consent screen appear on every sign-in; there is no remembered session. prompt=none fails for Google (interaction_required) and Microsoft (login_required), and Discord and LinkedIn, which skip consent for a returning user (LinkedIn even with prompt=consent), always ask again. | Breaks silent sign-in that works with a real signed-in user. |
Issuers and signing keys are the mock's (for example https://app.mockatoo.globalunderdog.com/google, not https://accounts.google.com). Discord's authorization responses carry iss=https://app.mockatoo.globalunderdog.com/discord, not https://discord.com. | Breaks code that hardcodes a real issuer or key URL. |
Tokens are only valid at the mock. Real provider APIs (Google APIs, Microsoft Graph, GitHub's api.github.com, Discord's discord.com/api, LinkedIn's api.linkedin.com, X's api.x.com, Facebook's graph.facebook.com) reject them, and the mock doesn't serve those APIs beyond what sign-in needs. | Breaks app features that call the provider's API after sign-in. |
A special address (you+tag@…) is a different test user with the same password. Apps that strip +tags from emails will merge them into one user. | Breaks special addresses in such apps. |