# Google

## 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](https://developers.google.com/identity/protocols/oauth2/web-server),
[OIDC](https://developers.google.com/identity/openid-connect/openid-connect).

## 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](https://github.com/mockatoo/examples/blob/main/oauth4webapi-hono/src/app.tsx)
for a minimal authorization code flow with discovery and ID-token validation,
including this provider's differences, without an auth abstraction.

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.google
import { 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.js
import Google from "next-auth/providers/google";
import { MockGoogle } from "@mockatoo/connect-authjs";
providers: [process.env.NODE_ENV === "production" ? Google() : MockGoogle()],
```

- Request `access_type=offline` for a refresh token. Each normal mock sign-in
  represents first consent; `+returning` represents a later sign-in with no
  refresh token unless you request `prompt=consent`.
- Published Google scopes are accepted, including API scopes. With
  `include_granted_scopes=true`, granted scopes accumulate for the user.
- `prompt=none` returns `interaction_required` because there is no remembered
  login session. Bad clients and invalid scopes stop at an error page; denial
  returns `access_denied` to 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](../email-tags.md).

| Tag | Behavior | |
| --- | --- | --- |
| `hd` | Workspace user: ID token includes `hd` with the email's domain | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/hd.spec.ts) |
| `unverified` | `email_verified: false` (GitHub: primary email `verified: false`; Discord: `verified: false`; LinkedIn: `"false"` in the ID token) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/unverified.spec.ts) |
| `renamed` | Same user ID (`sub`, Microsoft `oid`, GitHub, Discord, X and Facebook `id`) as the address without `+renamed`, different email | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/renamed.spec.ts) |
| `noname` | No name (Google: also no `given_name`/`family_name`; GitHub: `name: null`; Discord: `global_name: null`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noname.spec.ts) |
| `firstname` | Only `name`/`given_name`, no `family_name` | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/firstname.spec.ts) |
| `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](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/returning.spec.ts) |
| `revoked` | Sign-in works; every refresh returns `invalid_grant` (GitHub: `bad_refresh_token`, and only with `offline_access`; X: `invalid_request`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/revoked.spec.ts) |
| `badcode` | The code exchange fails (`invalid_grant`; GitHub: `bad_verification_code`; LinkedIn and X: `invalid_request`; Facebook: `Invalid verification code format.`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/badcode.spec.ts) |
| `down` | The token endpoint returns 503 | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/down.spec.ts) |
| `flaky` | The first exchange of each code returns 503; a retry succeeds | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/flaky.spec.ts) |
| `slow` | Token responses are delayed (10 seconds) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/slow.spec.ts) |
| `blocked` | After login, Google's "Access blocked" or Microsoft's "Need admin approval" page | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/blocked.spec.ts) |

## 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. |
