A mock OpenID Connect server for developers.

Stop waiting for identity providers. Start building.

Building apps with OAuth 2.0 / OpenID Connect authentication can be a frustrating process. stubIdP is a lightweight, fully-compliant OpenID Connect provider that runs locally or in your CI pipeline so you can stay focused on building your application.

Single client (local dev):

npx @cerberauth/stubidp --redirect-uri http://localhost:8080/callback

--client-id and --client-secret are optional — a human-readable ID (e.g. brave-falcon-3a9f12) and a secure secret are generated and printed in the startup table when omitted.

Central test IdP with dynamic client registration (RFC 7591/7592):

npx @cerberauth/stubidp --enable-registration

Any service can register its own client via POST /register without restarting the server.

Your OIDC provider is now live at http://localhost:8484

npx @cerberauth/stubidp --preset better-auth

import { betterAuth } from 'better-auth'

export const auth = betterAuth({
  socialProviders: {
    genericOAuth: {
      clientId: '<printed client ID>',
      clientSecret: '<printed client secret>',
      discoveryUrl: 'http://localhost:8484/.well-known/openid-configuration',
    },
  },
})

npx @cerberauth/stubidp --preset next-auth

Auth.js v5:

import NextAuth from 'next-auth'

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      type: 'oidc',
      issuer: 'http://localhost:8484',
      clientId: '<printed client ID>',
      clientSecret: '<printed client secret>',
    },
  ],
})

All CLI flags can be set via environment variables instead:

stubIdP supports RFC 7591 (Dynamic Client Registration) and RFC 7592 (Client Registration Management), making it suitable as a shared OIDC server for teams or multi-service test environments.

# Open registration — any caller can register a client
npx @cerberauth/stubidp --enable-registration

# Protected registration — callers must supply a bearer token
npx @cerberauth/stubidp --enable-registration --registration-initial-access-token mysecret

curl -X POST http://localhost:8484/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "my-service",
    "redirect_uris": ["http://localhost:3000/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"]
  }'

The response includes client_id, client_secret, and a registration_access_token used for subsequent management calls.

# Read
curl http://localhost:8484/register/<client_id> \
  -H 'Authorization: Bearer <registration_access_token>'

# Update
curl -X PUT http://localhost:8484/register/<client_id> \
  -H 'Authorization: Bearer <registration_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{ "redirect_uris": ["http://localhost:3001/callback"], ... }'

# Delete
curl -X DELETE http://localhost:8484/register/<client_id> \
  -H 'Authorization: Bearer <registration_access_token>'

stubIdP supports fully headless authentication for use in E2E test suites, CI pipelines, and other automation scenarios.

Pass --skip-prompt (or set STUBIDP_SKIP_PROMPT=true) to make stubIdP auto-approve every login and consent interaction. The OIDC redirect chain completes transparently — your test runner receives the authorization code at the redirect URI without any browser interaction.

STUBIDP_SKIP_PROMPT=true stubidp --redirect-uri http://localhost:3000/callback

Use --default-user (or STUBIDP_DEFAULT_USER) to specify the OIDC claims returned in every ID token and UserInfo response. The sub field also sets the subject identifier used during auto-login.

STUBIDP_DEFAULT_USER='{"sub":"alice","name":"Alice Example","email":"alice@example.com","email_verified":true}' \
STUBIDP_SKIP_PROMPT=true \
stubidp --redirect-uri http://localhost:3000/callback

If you need UI available by default but headless completion in specific tests, navigate to GET /interaction/:uid/auto instead of /interaction/:uid to auto-complete the current step without any flags.

TODO

• For development and testing only - stubIdP is not hardened for production identity management
• No user management - stubIdP handles OAuth/OIDC flows; your app handles user authentication

Deploy stubIdP as a globally distributed OIDC server on Cloudflare Workers with D1 persistent storage.

• STUBIDP_ISSUER is derived automatically from the incoming request URL — no placeholder to update.
• D1 database is created and migrated automatically when you use the Deploy button or the GitHub Actions workflow.

Click the button above. Cloudflare will:

1. Fork / clone the repository to your account.
2. Prompt you to create a new D1 database.
3. Deploy the Worker — the issuer URL is detected at runtime.

After deployment you can override the default client credentials (STUBIDP_CLIENT_ID, STUBIDP_CLIENT_SECRET, STUBIDP_REDIRECT_URI) in the Cloudflare dashboard under Workers & Pages → stubidp → Settings → Variables.

Add the following secrets to your forked repository (Settings → Secrets and variables → Actions):

Every push to main (or a manual trigger) will:

1. Create the stubidp-db D1 database if it does not exist yet.
2. Apply any pending migrations.
3. Deploy the Worker.

# 1. Create the D1 database and note the returned database_id
npx wrangler d1 create stubidp-db

# 2. Patch wrangler.json with the real database_id, then apply migrations
npx wrangler d1 migrations apply stubidp-db --remote

# 3. Deploy (issuer is detected from the worker URL automatically)
npm run worker:deploy

cp .dev.vars .dev.vars.local  # optional: override vars locally
npm run worker:migrate:local
npm run worker:dev             # runs at http://localhost:8787

Note: The Workers deployment mounts OIDC at the root (/). OIDC discovery: https://<worker>.workers.dev/.well-known/openid-configuration

Contributions welcome! Please feel free to submit a Pull Request.

This repository is licensed under the MIT License @ CerberAuth.