auth0-mock

module
v0.234.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT

README ΒΆ

auth0-mock

A drop-in mock of Auth0's HTTP API (Authentication + Management) that you can point any Auth0-using service at, with no code changes.

Real RS256 JWTs. 400+ Management API endpoints. Runtime claim and permission injection. MFA, PKCE, OIDC discovery. HTTP and HTTPS.

Quick start Β· What's mocked Β· Recipes Β· Architecture Β· Contributing

CI CodeQL Go Report Card codecov Go Reference OpenSSF Scorecard OpenSSF Best Practices Signed releases govulncheck Release Go version GHCR Go module Conventional Commits PRs welcome

πŸ“– Docs: https://sergiu.dev/auth0-mock/

✨ What is this?

A self-contained Go service that looks and behaves like Auth0 to a calling client:

  • 🎫 Mints real RS256 JWTs signed with an in-process key, and publishes the matching JWKS at /.well-known/jwks.json. Consumer SDKs validate signatures normally β€” no InsecureSkipVerify, no fake-token kludges.
  • πŸ“¦ Covers the whole Management API by embedding a stripped skeleton of Auth0's OpenAPI 3.1 document (~480 operations: paths, methods, and schemas; Auth0's prose removed) and routing every endpoint through one generic handler. You stub responses by POSTing {method, path, response} to /admin0/expectations, and the OpenAPI schema validates the stubbed body at registration time. Set "template": true to fill in {{uuid}}, {{now}}, {{path.NAME}} and {{body.PATH}} per request. An optional request matcher lets you register multiple responses per operation; resolution is 4-tier (exact-path beats template-path; within a path, a request-matched expectation beats a catch-all; newest wins within a tier).
  • πŸ›  Shapes runtime state over HTTP: custom JWT claims, per-audience permissions, and the MFA-required flag are mutable mid-test through /admin0/* endpoints. No restart, no config-file juggling.
  • 🐳 Ships as a single static binary (~13 MB) or a small Docker image. Sub-second boot, both HTTP (:8080) and HTTPS (:8443) by default.

🎯 Who is this for?

Anyone whose service talks to Auth0 in tests or local dev:

  • CI pipelines that need deterministic Auth0 responses without burning rate limit on a real tenant.
  • Local dev loops where you don't want to share an Auth0 tenant or wait on its latency.
  • Integration test suites for Auth0 SPA / native / API SDKs (auth0-react, auth0-js, auth0-spa-js, auth0-android, auth0-swift, auth0-react-native, etc.).
  • Resilience tests for code paths that hit /api/v2/users, /api/v2/clients, /api/v2/roles, etc.
  • Service-to-service flows using client_credentials, with realistic scopes and permissions claim shapes.

It is not for: production traffic, replacing your IdP, or anything that needs a real RBAC engine.

πŸš€ Quick start

docker run --rm -p 127.0.0.1:8080:8080 -e ADMIN_ALLOW_REMOTE=true ghcr.io/sergiught/auth0-mock:latest

Then, in another terminal:

# 1. Mint a real signed access token
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)

# 2. Stub a Management API response
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"}}}'

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

Your code calls auth0-mock the same way it calls Auth0. No SDK shims, no monkey-patching.

πŸ“– Documentation

Full docs live at https://sergiu.dev/auth0-mock/.

Page What it covers
Installation Install and run auth0-mock from a release, from source, with go install, in a live-reload loop or in Docker.
First request Mint a token, stub a Management API response and call it, using only curl.
curl quickstart Call the mock with plain curl, from starting it to calling a stubbed endpoint.
Node.js quickstart Test a Node API and a Management API client against the mock with express-oauth2-jwt-bearer and the auth0 SDK.
Python quickstart Test a Python API and a Management API client against the mock with PyJWT and the auth0-python SDK.
Go quickstart Test a Go API and a Management API client against the mock with go-jwt-middleware and the go-auth0 SDK.
Stubbing the Management API Stub Management API responses, errors and retries, and reset or inspect what is registered.
Tokens and claims Test code that reads permissions or custom claims, and test token expiry without sleeping.
Login flows Test PKCE, login errors, silent login, MFA challenges and the password-realm grant.
Event streams Drive an event-stream consumer from a test.
HTTPS / TLS Run auth0-mock over HTTPS and make clients trust its self-signed certificate.
Calling the API from Postman or Insomnia Import the merged OpenAPI document into Postman or Insomnia, and regenerate it after spec changes.
Browser apps Call the mock from a browser app.
Go SDK Use the typed Go client and test helpers to drive auth0-mock from Go tests.
Common recipes Short curl recipes for claims, permissions, MFA and the clock.
What's mocked What the mock implements: the Authentication API, supported OAuth grants, the Management API, event streams, the admin surface and operations endpoints.
Configuration Every environment variable and flag that configures auth0-mock.
Verifying releases Verify the Cosign signature on Docker images and find the SBOM for each release.
Architecture A walkthrough of how auth0-mock is put together, for contributors and curious users.

🀝 Contributing

PRs welcome. See CONTRIBUTING.md for local setup, code style, testing requirements, and how to add a new endpoint. Also see SECURITY.md, CODE_OF_CONDUCT.md and CHANGELOG.md.

βš–οΈ License

MIT.

⚠️ 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.

To route and validate every Management API endpoint, this repo embeds a stripped skeleton of Auth0's published Management API OpenAPI specification (sourced from https://auth0.com/docs/api/management/openapi.json): paths, methods, parameters, and JSON-schema shapes only. Every Auth0-authored description, externalDocs link, and x-* extension is removed before commit by stripUpstreamProse; see the refresh procedure. The raw download is gitignored and never committed; only the skeleton is.

Auth0 does not attach an explicit redistribution license to the published spec. The deliberate stripping above is what lets us redistribute the structural shape for interoperability without redistributing Auth0's prose. If the distinction matters for your compliance review, confirm the terms with Auth0/Okta directly.

Directories ΒΆ

Path Synopsis
Package api embeds the OpenAPI assets the auth0-mock binary needs: the Auth0 Management API skeleton (input to the bundler) and the merged OpenAPI document served at /openapi.json.
Package api embeds the OpenAPI assets the auth0-mock binary needs: the Auth0 Management API skeleton (input to the bundler) and the merged OpenAPI document served at /openapi.json.
cmd
api command
Command auth0-mock is the entry point for the auth0-mock service.
Command auth0-mock is the entry point for the auth0-mock service.
genopenapi command
Command genopenapi bundles the embedded Auth0 Management API skeleton, the per-package OpenAPI fragments shipped by each surface (authapi, admin0, router service endpoints) into a single OpenAPI 3.1 document.
Command genopenapi bundles the embedded Auth0 Management API skeleton, the per-package OpenAPI fragments shipped by each surface (authapi, admin0, router service endpoints) into a single OpenAPI 3.1 document.
features
scenario
Package scenario holds the godog test harness: a per-scenario context that boots the auth0-mock service in-process on a random port and provides HTTP helpers for the .feature step files.
Package scenario holds the godog test harness: a per-scenario context that boots the auth0-mock service in-process on a random port and provides HTTP helpers for the .feature step files.
internal
admin0
Package admin0 exposes the mock's control-plane endpoints under /admin0/*.
Package admin0 exposes the mock's control-plane endpoints under /admin0/*.
authapi
Package authapi mounts hand-coded Auth0 Authentication API endpoints onto chi.
Package authapi mounts hand-coded Auth0 Authentication API endpoints onto chi.
authorizeerr
Package authorizeerr keeps the in-memory rules that make /authorize fail on purpose: a rule with an optional match on the /authorize query returns an OAuth error to the redirect_uri instead of logging the user in.
Package authorizeerr keeps the in-memory rules that make /authorize fail on purpose: a rule with an optional match on the /authorize query returns an OAuth error to the redirect_uri instead of logging the user in.
bearer
Package bearer provides middleware that validates an Authorization: Bearer JWT against a jwks.KeySet and attaches the claims to the request context.
Package bearer provides middleware that validates an Authorization: Bearer JWT against a jwks.KeySet and attaches the claims to the request context.
claims
Package claims owns a per-process map of custom JWT claims that get merged into every access token minted by the authapi package.
Package claims owns a per-process map of custom JWT claims that get merged into every access token minted by the authapi package.
clock
Package clock provides a pluggable Now() time source so the mock's protocol-time outputs (JWT iat/exp, code/OTP TTLs, bearer validation) can be frozen or skewed at runtime via /admin0/clock for deterministic tests.
Package clock provides a pluggable Now() time source so the mock's protocol-time outputs (JWT iat/exp, code/OTP TTLs, bearer validation) can be frozen or skewed at runtime via /admin0/clock for deterministic tests.
config
Package config loads runtime settings from environment variables.
Package config loads runtime settings from environment variables.
events
Package events owns the in-process Server-Sent Events hub for the mock's GET /events endpoint.
Package events owns the in-process Server-Sent Events hub for the mock's GET /events endpoint.
httperr
Package httperr writes JSON error responses in either Auth0 Management API shape or Auth0 Authentication API shape.
Package httperr writes JSON error responses in either Auth0 Management API shape or Auth0 Authentication API shape.
journal
Package journal records Management API calls in a bounded in-memory ring so tests can assert on what the application under test actually sent.
Package journal records Management API calls in a bounded in-memory ring so tests can assert on what the application under test actually sent.
jwks
Package jwks owns the in-process RS256 signing key, JWT minting, JWT verification, and JWKS publication.
Package jwks owns the in-process RS256 signing key, JWT minting, JWT verification, and JWKS publication.
logger
Package logger constructs the project's zerolog.Logger.
Package logger constructs the project's zerolog.Logger.
matches
Package matches owns the in-memory store of registered mock expectations.
Package matches owns the in-memory store of registered mock expectations.
mfa
Package mfa implements the in-memory state for Auth0's MFA challenge dance.
Package mfa implements the in-memory state for Auth0's MFA challenge dance.
mgmtapi
Package mgmtapi mounts the spec-driven Management API surface onto chi: one generic, bearer-protected handler per Auth0 Management API operation.
Package mgmtapi mounts the spec-driven Management API surface onto chi: one generic, bearer-protected handler per Auth0 Management API operation.
middleware
Package middleware contains shared net/http middleware.
Package middleware contains shared net/http middleware.
permissions
Package permissions owns a per-audience map of permission strings.
Package permissions owns a per-audience map of permission strings.
pkce
Package pkce implements the in-memory store of per-code authorization state that links a /authorize redirect to its later /oauth/token exchange.
Package pkce implements the in-memory store of per-code authorization state that links a /authorize redirect to its later /oauth/token exchange.
router
Package router builds the http.Handler that fronts the mock service.
Package router builds the http.Handler that fronts the mock service.
seed
Package seed loads a YAML or JSON seed file into the mock's in-memory stores: expectations, claims, claim mappings, permissions and the MFA flag.
Package seed loads a YAML or JSON seed file into the mock's in-memory stores: expectations, claims, claim mappings, permissions and the MFA flag.
server
Package server hosts the HTTP and (later) HTTPS listeners.
Package server hosts the HTTP and (later) HTTPS listeners.
session
Package session keeps the in-memory state that ties a logged-in user to the tokens the mock has issued, so later requests (/userinfo) can see the same user the id_token described.
Package session keeps the in-memory state that ties a logged-in user to the tokens the mock has issued, so later requests (/userinfo) can see the same user the id_token described.
spec
Package spec wraps the embedded Auth0 Management API skeleton.
Package spec wraps the embedded Auth0 Management API skeleton.
tlscert
Package tlscert produces a *tls.Config from either user-supplied cert/key files or an auto-generated self-signed cert covering configured hostnames.
Package tlscert produces a *tls.Config from either user-supplied cert/key files or an auto-generated self-signed cert covering configured hostnames.
tmpl
Package tmpl parses and renders response templates: JSON bodies and header values that hold {{uuid}}, {{now}}, {{path.NAME}} and {{body.PATH}} placeholders.
Package tmpl parses and renders response templates: JSON bodies and header values that hold {{uuid}}, {{now}}, {{path.NAME}} and {{body.PATH}} placeholders.
version
Package version exposes build-time metadata baked into the binary at link time via `-ldflags="-X ..."`.
Package version exposes build-time metadata baked into the binary at link time via `-ldflags="-X ..."`.
pkg
auth0mock
Package auth0mock is the Go SDK for the auth0-mock control plane.
Package auth0mock is the Go SDK for the auth0-mock control plane.
auth0mock/auth0mocktest
Package auth0mocktest provides testing.TB-aware helpers for the pkg/auth0mock SDK.
Package auth0mocktest provides testing.TB-aware helpers for the pkg/auth0mock SDK.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL