iammind/dummy-oidc-provider repository overview

A dummy OIDC Provider which simply logs in the user and provides the configured claims on the resulting token for development / test purposes.

⁠Features

• Zero-UI Flow: Automatically authenticates users without any login interface
• Static JWKS: Uses a static JSON Web Key Set to prevent signature errors on restart
• Configurable Test User: Update user claims via REST API for automated testing
• Docker Ready: Multi-stage Dockerfile with health checks
• TypeScript & ESM: Modern TypeScript with ES Modules
• Environment-based Configuration: All settings via environment variables

⁠Run the container:

docker run -p 3000:3000 \
  -e CLIENT_ID=your-client-id \
  -e CLIENT_SECRET=your-client-secret \
  -e REDIRECT_URIS=http://localhost:8080/callback \
  iammind/dummy-oidc-provider

⁠Configuration

All configuration is done via environment variables. See .env.example for all available options.

⁠Required Environment Variables

⁠Optional Environment Variables

⁠API Endpoints

⁠Health Check

GET /health

Returns the health status of the service.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "service": "dummy-oidc-provider"
}

⁠Update Test User

POST /_setup/user
Content-Type: application/json

{
  "sub": "test-user-456",
  "email": "[email protected]",
  "email_verified": true,
  "name": "New Test User",
  "custom_claim": "custom_value"
}

Updates the test user claims that will be returned in ID tokens. The sub claim is required.

Response:

{
  "success": true,
  "user": {
    "sub": "test-user-456",
    "email": "[email protected]",
    "email_verified": true,
    "name": "New Test User",
    "custom_claim": "custom_value"
  }
}

⁠OIDC Endpoints

Standard OIDC endpoints are available:

• GET /.well-known/openid-configuration - Discovery document
• GET /jwks - JSON Web Key Set
• GET /auth - Authorization endpoint
• POST /token - Token endpoint
• POST /introspection - Token introspection
• POST /revocation - Token revocation

⁠Usage Example

⁠1. Configure Client

Set up your OIDC client with:

• Issuer: http://localhost:3000
• Client ID: From CLIENT_ID env var
• Client Secret: From CLIENT_SECRET env var
• Redirect URI: One of the URIs from REDIRECT_URIS env var

⁠2. Update Test User (Optional)

Before testing, you can update the test user claims:

curl -X POST http://localhost:3000/_setup/user \
  -H "Content-Type: application/json" \
  -d '{
    "sub": "user-123",
    "email": "[email protected]",
    "name": "Test User",
    "roles": ["admin", "user"]
  }'

⁠3. Initiate Authentication

Redirect users to the authorization endpoint. The provider will automatically authenticate them with the configured test user.