mock-oidc-provider

Generic local OIDC provider for development and testing.

This is a proof-of-concept package. It is intended to let local applications exercise their normal OIDC authorization-code callback flow without depending on a real identity provider account.

It is not a production identity provider and must not be deployed as one.

Usage

Run the provider from npm in one terminal:

pnpm dlx mock-oidc-provider --claim preferred_username=test.user --claim name="Test User"

Or, after installing the package, run the binary directly:

mock-oidc-provider --claim preferred_username=test.user --claim name="Test User"

Run the client application in another terminal.

By default the provider uses:

host: 127.0.0.1
port: 4010
issuer: http://localhost:4010/mock/v2.0
clientId: mock-oidc-client

The provider prints copy-pasteable client application configuration on startup.

Options

--host <host>              Bind host. Default: 127.0.0.1
--port <port>              Bind port. Default: 4010
--issuer <url>             Issuer URL. Default: http://localhost:<port>/mock/v2.0
--client-id <id>           Client ID. Default: mock-oidc-client
--redirect-uri <uri>       Additional allowed localhost redirect URI.
--claim <key=value>        Add or override an ID token claim. Repeatable.
-h, --help                 Show help.

The authorization code flow also supports optional PKCE with code_challenge_method=S256. Non-PKCE local clients continue to work.

Local package testing

Prefer the tarball flow before publishing. It best matches how consumers will run the package:

pnpm build
pnpm pack
pnpm dlx "$(pwd)/mock-oidc-provider-0.1.0.tgz" --claim preferred_username=test.user

Safety defaults

• Runs in the foreground.
• Allows only localhost or 127.0.0.1 redirect URIs.
• Uses fake local issuer and client defaults.
• Does not set cookies or sessions in consuming applications.
• Does not store or dictate where client applications store tokens.