sergiught/auth0-mock

auth0-mock

A drop-in mock of Auth0's Authentication and Management APIs for tests, local development, and CI. Same HTTP shapes and response formats: point your SDK at the mock instead of *.auth0.com and your code keeps running unchanged.

What's in the box

• Real RS256 JWTs. The mock generates a fresh keypair on boot and signs every token with it. Downstream services validate signatures against /.well-known/jwks.json with stock OSS libraries.
• 400+ Management API endpoints mounted from Auth0's published OpenAPI spec. Stubbed responses are registered per (method, path) and validated against the spec schema at registration time.
• OIDC discovery at /.well-known/openid-configuration for clients that bootstrap from a single base URL.
• Auth flows: client credentials, authorization code, PKCE, password realm, passwordless, and the full MFA challenge dance.
• Runtime claim & permission injection so a single mock can serve many audiences with different scopes.
• **Single static *ary (~13 MB) with both HTTP (:8080) and HTTPS (:8443) listeners. Sub-second boot.

Quick start

bash
docker run --rm -p 8080:8080 -p 8443:8443 sergiught/auth0-mock:latest

Mint a token, register a stubbed Management API response, and call it:

bash
TOKEN=$(curl -s -X POST http://localhost:8080/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=demo&client_secret=x&audience=http://localhost:8080/api/v2/' \
  | jq -r .access_token)

curl -X POST http://localhost:8080/admin0/expectations \
  -H 'Content-Type: application/json' \
  -d '{"method":"GET","path":"/api/v2/users/auth0|123","response":{"status":200,"body":{"user_id":"auth0|123","email":"alice@example.com"}}}'

curl -H "Authorization: Bearer ${TOKEN}" \
  'http://localhost:8080/api/v2/users/auth0%7C123'
# => {"user_id":"auth0|123","email":"alice@example.com"}

Tags

All tags are multi-arch manifests covering linux/amd64 and linux/arm64.

Provenance

Every ghcr.io/sergiught/auth0-mock:vX.Y.Z image is signed with https://github.com/sigstore/cosign keylessly from the GitHub Actions release workflow (no shared secret). The Docker Hub mirror (sergiught/auth0-mock:vX.Y.Z) is a publish-only convenience: pull the equivalent GHCR digest to verify provenance. Replace vX.Y.Z below with the tag you want to verify, e.g. v0.1.0:

bash
cosign verify \
  --certificate-identity-regexp 'https://github.com/sergiught/auth0-mock/\.github/workflows/release\.yml@.+' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/sergiught/auth0-mock:vX.Y.Z

SPDX-JSON SBOMs for each release archive live alongside the ***aries on the https://github.com/sergiught/auth0-mock/releases.

Configuration

The container is configured via environment variables. The most common ones:

The full list lives in the https://github.com/sergiught/auth0-mock#-configuration.

Disclaimer

auth0-mock is an independent, community-built testing tool. It is not affiliated with, endorsed by, or sponsored by Auth0 or Okta, Inc. "Auth0" and "Okta" are trademarks of Okta, Inc.; they are used here only nominatively, to describe what this project mocks.

More

• Source & issues: https://github.com/sergiught/auth0-mock
• Architecture deep-dive: https://github.com/sergiught/auth0-mock/blob/main/docs/ARCHITECTURE.md
• Recipes (claim injection, RBAC, MFA, TLS trusting, SDK integration): https://github.com/sergiught/auth0-mock/blob/main/docs/COOKBOOK.md
• Working SDK example: https://github.com/sergiught/auth0-mock/tree/main/examples/consumer
• License: MIT (see https://github.com/sergiught/auth0-mock/blob/main/LICENSE and https://github.com/sergiught/auth0-mock/blob/main/NOTICE)