A real OpenID Connect provider, small enough to forget about.

Authorization code with PKCE, signed RS256 ID tokens and a one-click sign-in page. Built for local development and end-to-end tests, where Google has no sandbox and Dex wants a password.

docker run --rm -p 5556:5556 curroya/oauth2-mock

Then point your client at http://localhost:5556 with local-client / local-secret. More setups

localhost:5556/auth?response_type=code&code_challenge_method=S256&…

Pick a user or type any email to see the redirect.

Your client runs for real. Only the person signing in is fake.

Discovery, PKCE, code exchange and ID-token verification all happen against a working provider. What you skip is a Google account and a password field.

Any email signs in
No user list to keep in sync with your tests. List users only when you want buttons, fixed ids or names.
login_hint=worker-7@example.test
Same email, same id
An email without an id gets a SHA-256-derived UUID, identical on every restart and every machine.
sub = uuid(sha256(email))
A key that survives restarts
The RSA key comes from a seed, so restarting the mock never invalidates the keys your backend cached.
KEY_SEED=oauth2-mock
One issuer, two hosts
Keep iss as your backend sees it and serve the browser from another host. No /etc/hosts edits.
http://oidc:5556 ↔ http://localhost:5556
Strict where it matters
PKCE S256 is mandatory and codes are single-use. A wrong verifier or redirect fails the way production would.
400 invalid_grant
Tested with a real client
The test suite drives the full flow with the Rust openidconnect crate, not hand-written requests.
tests/flow.rs

How it compares

Against Dex and mock-oauth2-server, measured idle with no requests in flight.

	oauth2-mock	Dex	mock-oauth2-server
Image	~52 MB	~100 MB	~350 MB
Idle memory	~3 MiB	~25 MB	~150–300 MB (JVM)
Sign in	Click, type any email, or `login_hint`	Email and password	Form or `login_hint`
Users	Optional; any email works	Static list with bcrypt hashes	Any username
Signing key across restarts	Stable	Rotates	Rotates
Issuer	Configured	Configured	From the request's host

Quick start

Images for amd64 and arm64 are on Docker Hub. latest follows main; a vX.Y.Z tag pins a release.

shell

docker run --rm -p 5556:5556 -e USERS=alice@example.test,bob@example.test curroya/oauth2-mock

docker-compose.yml

services:
  oidc:
    image: curroya/oauth2-mock
    ports: ["5556:5556"]
    environment:
      ISSUER: http://oidc:5556
      BROWSER_BASE_URL: http://localhost:5556
      CLIENT_ID: my-app
      CLIENT_SECRET: my-app-secret
      USERS_FILE: /users.json
    volumes:
      - ./users.json:/users.json:ro

users.json

[
  {
    "name": "Candidate",
    "email": "candidate@example.test",
    "id": "6f8d3c1e-0b2a-4f5c-9d7e-1a2b3c4d5e6a"
  },
  { "email": "empty@example.test" }
]

What happens on a sign-in

Standard authorization code with PKCE. Nothing your client does is skipped.

Your backend
Discovers the provider
GET /.well-known/openid-configuration · GET /keys
Endpoints and the public key, cached like any production provider.
Browser
Opens the authorization page
GET /auth?code_challenge=…&nonce=…&state=…
A request without an S256 challenge gets 400.
Person
Picks a user
POST /auth login_hint=… → 303 /callback?code=…
A click, a typed email, or a login_hint on the first request, which skips the page.
Your backend
Exchanges the code
POST /token → id_token (RS256)
Client, redirect and verifier are checked before a signed ID token comes back.

Configuration

Environment variables only. An invalid value stops the server at startup and names the variable.

Variable	Default	Purpose
`ISSUER`	`http://localhost:5556`	Exact `iss` and base of the server-to-server endpoints; its path is the mount point
`BROWSER_BASE_URL`	`ISSUER`	Base of the authorization endpoint the browser opens
`CLIENT_ID`	`local-client`	The one accepted client
`CLIENT_SECRET`	`local-secret`	Its secret, basic or post
`USERS`	none	Comma-separated emails shown as buttons
`USERS_FILE`	none	JSON list of `{ email, name?, id? }`; wins over `USERS`
`KEY_SEED`	`oauth2-mock`	Seed of the deterministic RSA key
`TOKEN_LIFETIME_SECONDS`	`3600`	ID and access token lifetime
`PORT`	`5556`	Listen port

In end-to-end tests

Every email is a stable identity, so give each parallel worker its own address. No fixture list required.

sign-in.spec.ts

// click a configured user
await page.getByRole('button', { name: /candidate@example\.test/ }).click()

// or sign in as anyone
await page.getByLabel('Email').fill(`worker-${workerIndex}@example.test`)
await page.getByRole('button', { name: 'Sign in' }).click()

A real OpenID Connect provider, small enough to forget about.

Sign in

Your client runs for real. Only the person signing in is fake.

Any email signs in

Same email, same id

A key that survives restarts

One issuer, two hosts

Strict where it matters

Tested with a real client

How it compares

Quick start

What happens on a sign-in

Discovers the provider

Opens the authorization page

Picks a user

Exchanges the code

Configuration

In end-to-end tests