If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.

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

ddev add-on get Pronovix/ddev-oidc-provider-mock
ddev restart && ddev start --profiles=oidc-provider-mock

Updating

When updating this add-on, a standard ddev restart or ddev restart --no-cache will not rebuild or pull the service container if changes are made to profile-gated services (tracked in ddev/ddev#8817).

To update the add-on and properly restart the OIDC Provider Mock service:

ddev add-on get Pronovix/ddev-oidc-provider-mock
ddev debug rebuild -s oidc-provider-mock
ddev restart && ddev start --profiles=oidc-provider-mock

Note: ddev debug rebuild -s <service> (or its alias ddev utility rebuild -s <service>) for profile-gated services requires DDEV >= v1.25.3 (ddev/ddev#8463). Following up with ddev restart && ddev start --profiles=oidc-provider-mock ensures all project containers and profile services restart cleanly together (see ddev/ddev#7904).

Usage

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 && ddev start --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

Note

<site> corresponds to your DDEV project name and <tld> corresponds to your configured project_tld (default: ddev.site). The hostname dynamically adapts to custom primary domains or TLDs configured in DDEV.

Endpoint	URL	Description
Issuer URL	`https://oidc.<site>.<tld>`	Base OpenID Provider URL
Discovery	`https://oidc.<site>.<tld>/.well-known/openid-configuration`	OpenID Connect discovery metadata
Authorization	`https://oidc.<site>.<tld>/oauth2/authorize`	HTML authorization form / redirect
Token	`https://oidc.<site>.<tld>/oauth2/token`	Exchange code for tokens
Userinfo	`https://oidc.<site>.<tld>/userinfo`	Fetch authenticated user claims
Client Registration	`POST https://oidc.<site>.<tld>/oauth2/clients`	Dynamic client registration (optional)
Dynamic Claims API	`PUT https://oidc.<site>.<tld>/users/{sub}`	Inject/update user claims during test runs

Tip

For any additional endpoints, or to view all available paths discovered dynamically, inspect your project’s discovery metadata at https://oidc.<site>.<tld>/.well-known/openid-configuration, or consult the official OIDC Provider Mock Documentation.

Usage & Commands

Command	Description
`ddev describe`	View service status and exposed endpoints
`ddev logs -s oidc-provider-mock`	Check OIDC Provider Mock logs

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:

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

Credits

Contributed and maintained by @Pronovix