Configuration

CLI flags

Flag	Required	Description
--client-id	No	OAuth 2.0 client ID your application will use. Auto-generated (e.g. brave-falcon-3a9f12) when omitted.
--client-secret	No	OAuth 2.0 client secret your application will use. Auto-generated (43-char random secret) when omitted.
--public-client	No	Configure as public client (no client_secret, token_endpoint_auth_method=none). For SPAs and native apps.
--redirect-uri	No*	Redirect URI registered for your client. Required unless STUBIDP_REDIRECT_URI is set.
--jwks-file	No	Path to a JWKS JSON file. A key pair is auto-generated when omitted.
--skip-prompt	No	Skip login and consent UI and auto-approve every interaction. Intended for E2E tests and automation.
--default-user	No	JSON object of OIDC claims returned for every authenticated user (e.g. '{"sub":"alice","email":"alice@example.com"}').
--rate-limit-window-ms	No	Rate limit time window in milliseconds. Default: 900000 (15 min).
--rate-limit-max	No	Max requests per IP per window. Default: 100.
--rate-limit-disabled	No	Disable rate limiting entirely.
--enable-registration	No	Enable dynamic client registration (RFC 7591) and management (RFC 7592) via /register.
--registration-initial-access-token	No	Bearer token required to call POST /register. Omit for open registration.
--trust-proxy	No	Trust reverse proxy headers (X-Forwarded-*). Enable when running behind a reverse proxy or load balancer.
--https-redirect	No	Redirect HTTP requests to HTTPS and enable CSP upgrade-insecure-requests. Enable in production behind TLS termination.
--security-headers	No	Enable security headers (CSP, HSTS, etc.) via helmet. Enable when deployed; omit for local development.
--scopes	No	Comma-separated list of supported OIDC scopes. Default: openid,offline_access,email,profile,phone,address.
--claims	No	JSON object mapping scope names to claim arrays. Overrides auto-derived claims (e.g. '{"openid":["sub"],"email":["email"]}').

When --client-id or --client-secret are omitted, the generated values are printed in the startup table so you can copy them into your application config.

Every CLI flag can also be set via an environment variable (see below). Environment variables take effect when the flag is not passed explicitly.

Environment variables

OIDC

Variable	Default	Description
STUBIDP_CLIENT_ID	auto-generated	OAuth 2.0 client ID (equivalent to --client-id)
STUBIDP_CLIENT_SECRET	auto-generated	OAuth 2.0 client secret (equivalent to --client-secret)
STUBIDP_PUBLIC_CLIENT	false	Configure as public client (no client_secret, token_endpoint_auth_method=none). For SPAs and native apps (equivalent to --public-client)
STUBIDP_REDIRECT_URI	—	Redirect URI (equivalent to --redirect-uri; required if flag is omitted)
STUBIDP_JWKS_FILE	—	Path to a JWKS JSON file (equivalent to --jwks-file)
STUBIDP_ISSUER	http://localhost:{STUBIDP_PORT}	Issuer URL embedded in issued tokens
STUBIDP_ENABLE_REGISTRATION	false	Enable dynamic client registration RFC 7591/7592 (POST /register, GET/PUT/DELETE /register/:id)
STUBIDP_REGISTRATION_INITIAL_ACCESS_TOKEN	—	Bearer token required to call POST /register (open registration when omitted)
STUBIDP_SCOPES	openid,offline_access,email,profile,phone,address	Comma-separated list of supported OIDC scopes (equivalent to --scopes)
STUBIDP_CLAIMS	auto-derived from scopes	JSON object mapping scope names to claim arrays. Overrides auto-derived claims (equivalent to --claims)

Server

Variable	Default	Description
STUBIDP_PORT	8484	HTTP server port
STUBIDP_LOG_LEVEL	info	Logging verbosity (fatal, error, warn, info, debug, trace)
STUBIDP_DATABASE_DIALECT	—	Database backend: postgresql or sqlite (in-memory when omitted)
STUBIDP_DATABASE_URL	—	Connection string (PostgreSQL) or file path (SQLite)
STUBIDP_SKIP_PROMPT	false	Set to true to skip login/consent UI and auto-approve every interaction (equivalent to --skip-prompt)
STUBIDP_DEFAULT_USER	—	JSON object of OIDC claims for the stub user (equivalent to --default-user)
STUBIDP_RATE_LIMIT_WINDOW_MS	900000	Rate limit time window in milliseconds (equivalent to --rate-limit-window-ms)
STUBIDP_RATE_LIMIT_MAX	100	Max requests per IP per window (equivalent to --rate-limit-max)
STUBIDP_RATE_LIMIT_DISABLED	false	Set to true to disable rate limiting (equivalent to --rate-limit-disabled)
STUBIDP_TRUST_PROXY	false	Set to true to trust reverse proxy headers (X-Forwarded-*) (equivalent to --trust-proxy)
STUBIDP_HTTPS_REDIRECT	false	Set to true to redirect HTTP to HTTPS and enable CSP upgrade-insecure-requests (equivalent to --https-redirect)
STUBIDP_SECURITY_HEADERS	false	Set to true to enable security headers (CSP, HSTS, etc.) via helmet (equivalent to --security-headers)

Database

stubIdP supports two database backends for persisting OIDC session state.

In-memory (default)

When no database is configured, an in-memory store is used. Sessions are lost on restart — suitable for most local development workflows.

SQLite

STUBIDP_DATABASE_DIALECT=sqlite STUBIDP_DATABASE_URL=./stubidp.db stubidp \
  --redirect-uri http://localhost:8080/callback

PostgreSQL

STUBIDP_DATABASE_DIALECT=postgresql \
STUBIDP_DATABASE_URL=postgresql://user:pass@localhost:5432/stubidp \
stubidp \
  --redirect-uri http://localhost:8080/callback

Tip

For ephemeral CI environments, the in-memory default (no database config) is usually the right choice.

Issuer URL

The STUBIDP_ISSUER value is embedded in issued tokens as the iss claim and must match what your application validates.

• Local dev — defaults to http://localhost:8484, no change needed.
• Cloudflare Workers — derived automatically from the incoming request URL, no override required.
• Custom domain — set STUBIDP_ISSUER=https://idp.example.com to match your deployed URL.

Automation and E2E testing

stubIdP has two mechanisms for running auth flows without any human interaction.

--skip-prompt / STUBIDP_SKIP_PROMPT

When this flag is set, every redirect to the login or consent screen is silently auto-approved. The browser (or test runner) follows the normal OIDC redirect chain and receives the authorization code at the redirect URI without any UI being rendered.

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

GET /interaction/:uid/auto

A headless endpoint that is always available regardless of --skip-prompt. Navigate the browser to this URL instead of /interaction/:uid to complete the current interaction step programmatically. Useful when you want UI available by default but need headless completion in specific test cases.

--default-user / STUBIDP_DEFAULT_USER

Provide a JSON object of standard OIDC claims that stubIdP will include in the ID token and UserInfo response for every authenticated session. The sub field controls the subject identifier used during --skip-prompt auto-login; all other fields are returned as-is.

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

Supported fields: any standard OIDC claims (name, given_name, family_name, email, email_verified, picture, locale, phone_number, etc.) plus arbitrary custom claims.

Tip

--default-user is also useful without --skip-prompt. Any user who logs in through the UI will receive these claims in their tokens, regardless of the username they enter.

login_hint as subject

When --skip-prompt is active and no --default-user is set, stubIdP requires a login_hint parameter in the authorization request. The value must be a valid email address or E.164 phone number. It is used as the subject identifier (sub) and automatically populates the email or phone_number claim to match.

# Authorization request includes: login_hint=alice@example.com
STUBIDP_SKIP_PROMPT=true stubidp --redirect-uri http://localhost:3000/callback
# Result: sub = "alice@example.com", email = "alice@example.com"

Caution

If login_hint is missing or not a valid email or E.164 phone number, the flow errors. Set --default-user if you need a fixed identity without per-request hints.