DDEV OpenID Connect (OIDC) Provider Mock Add-on (ddev-oidc-provider-mock)

This DDEV add-on integrates ghcr.io/geigerzaehler/oidc-provider-mock into your DDEV environment to provide a mock OpenID Connect (OIDC) identity provider out of the box for local development and testing.

Overview & Features

• Optional Profile: Defined via Docker Compose profiles (oidc-provider-mock), so the container runs only when you actively need it.
• Turnkey Setup: Pre-configured mock users (admin, alice, bob) with zero mandatory setup steps.
• Framework-Agnostic: Works with any OIDC client (Drupal openid_connect, oauth2_client, custom PHP/JS applications, etc.).
• Dual Routing: Routed through DDEV’s HTTPS router at https://oidc.<site>.<tld> (e.g. https://oidc.mysite.ddev.site) so both browser front-channel redirects and server-to-server back-channel API calls hit the exact same Issuer URL.
• Accepts Any Credentials: Accepts any Client ID and Client Secret by default (unless restricted via arguments).
• Persistent & Versionable User List: User definitions are stored in .ddev/oidc-provider-mock/users.yaml which can be customized and committed to your project’s version control.

Installation & Usage

1. Install the add-on:

   ddev add-on get Pronovix/ddev-oidc-provider-mock
   

2. Start the OIDC Provider Mock service:

   By default, this add-on provides an on-demand service using Docker Compose profiles (oidc-provider-mock). It only starts when explicitly requested so that local resources are not consumed during unrelated development tasks.

   • On-demand (default & recommended): Start your project with the oidc-provider-mock profile whenever you need OIDC authentication:

     ddev start --profiles=oidc-provider-mock
     

     (Or when restarting: ddev restart --profiles=oidc-provider-mock)

   • Always start automatically (optional): If you prefer the OIDC Provider Mock service to always start on every standard ddev start or ddev restart without passing the profile flag, create .ddev/docker-compose.oidc-provider-mock_enable.yaml to override and reset the profile constraint:

     services:
       oidc-provider-mock:
         profiles: !reset []
     

     Then restart your project:

     ddev restart
     

Key Endpoints

Usage & Commands

Customization Guide

Editing Mock Users

Edit .ddev/oidc-provider-mock/users.yaml in your project to modify existing users (admin, alice, bob) or add custom users and claims (such as given_name, family_name, and roles). Run ddev restart after making changes.

Example user configuration:

- sub: alice
  email: [email protected]
  name: Alice Smith
  given_name: Alice
  family_name: Smith
  preferred_username: alice
  roles:
    - editor

Additional Server Arguments

To pass extra flags to oidc-provider-mock (such as --require-registration or --require-nonce), add OIDC_PROVIDER_MOCK_EXTRA_ARGS to .ddev/.env.oidc-provider-mock:

OIDC_PROVIDER_MOCK_EXTRA_ARGS="--require-registration --require-nonce"

Then run ddev restart.

Changing Container Image

To override the Docker image used by the service, set OIDC_PROVIDER_MOCK_DOCKER_IMAGE in .ddev/.env.oidc-provider-mock:

OIDC_PROVIDER_MOCK_DOCKER_IMAGE="ghcr.io/geigerzaehler/oidc-provider-mock:latest"

Generic OIDC Client Configuration

To connect any OIDC client module or application to this mock provider:

1. Issuer / Base URL: https://oidc.<site>.<tld> (or use the environment variable $OIDC_ISSUER_URL inside the web container)
2. Client ID: Any string (e.g. my-client-id)
3. Client Secret: Any string (e.g. my-client-secret)
4. Scopes: openid email profile
5. Authorization Endpoint: https://oidc.<site>.<tld>/oauth2/authorize
6. Token Endpoint: https://oidc.<site>.<tld>/oauth2/token
7. Userinfo Endpoint: https://oidc.<site>.<tld>/oauth2/userinfo

Credits

Contributed and maintained by @Pronovix