curroya/oauth2-mock repository overview

⁠oauth2-mock

A tiny OpenID Connect provider for local development and end-to-end tests: the authorization-code flow with PKCE, signed RS256 ID tokens, and a one-click sign-in page.

Do not use in production. Anyone who can reach oauth2-mock can sign in as any user without a password, and with the default KEY_SEED anyone can forge its ID tokens. It is for testing and development only. The examples publish it on 127.0.0.1 so only your machine can reach it.

• Site: https://oss.curroya.es/oauth2-mock/⁠
• Source: https://github.com/curro-ya/oauth2-mock⁠

With love from the curroya.es⁠ team: a simple way to find temporary jobs near you.

⁠Quick start

docker run --rm -p 127.0.0.1:5556:5556 -e [email protected],[email protected] curroya/oauth2-mock

Point your OIDC client at the issuer http://localhost:5556, with client id local-client and secret local-secret.

⁠Tags

Every tag is a multi-platform image for linux/amd64 and linux/arm64.

⁠Docker Compose

OIDC clients compare iss byte for byte. When your backend reaches the mock as http://oidc:5556 inside Docker and the browser as http://localhost:5556, keep one issuer and move only the browser-facing endpoint:

services:
  oidc:
    image: curroya/oauth2-mock
    ports: ["127.0.0.1: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

⁠Environment variables

The container exits at startup, naming the variable, when a value is invalid or USERS_FILE cannot be read.

⁠Users file

Mount a JSON list and point USERS_FILE at it. name and id are optional:

[
  {
    "name": "Candidate",
    "email": "[email protected]",
    "id": "6f8d3c1e-0b2a-4f5c-9d7e-1a2b3c4d5e6a"
  },
  { "email": "[email protected]" }
]

• USERS and USERS_FILE combine; the file wins when an email is in both.
• The fallback sub is the same on every restart and every machine, so an email always maps to the same account.

⁠Signing in

• Any email signs in, listed or not.
• Codes are single-use and live in memory.
• PKCE with S256 is mandatory; a request without it gets 400.
• A wrong code_verifier, a reused code, or a different redirect_uri gets invalid_grant.

⁠Endpoints

• The token response carries access_token (random, opaque), token_type: Bearer, expires_in and id_token.
• The ID token carries iss, sub, aud, iat, exp, nonce when one was sent, email, email_verified and name.

⁠End-to-end tests

Click a configured user on the sign-in page:

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

Or type any email, which needs no configuration:

await page.getByLabel('Email').fill('[email protected]')
await page.getByRole('button', { name: 'Sign in' }).click()

• Each email is a stable identity, so give every parallel worker its own address.
• Backends that forward login_hint to the provider skip the page entirely.

⁠Not supported

• Refresh tokens, client_credentials, userinfo and logout.
• More than one client.
• plain PKCE or flows without PKCE.