docs: developing against a mock identity provider

[turegjorup]

Documentation only. Shows how a consuming application can run the whole authorization code flow locally against a mock identity provider, and says why that beats switching the firewall off in dev.

Changes

• New README section, Local development against a mock identity provider: a compose service, the matching development-only provider configuration, and the two things that bite.
• Changelog entry.

Why

Pointing a development environment at the real provider is usually impractical — it will not have your local hostname among its registered redirect URIs. The tempting shortcut is when@dev: security: false, and the cost only shows up later: no OIDC path is exercised until the code reaches a server, so a broken callback path, a renamed claim or a login loop all stay invisible locally. It is also easy to forget, and then someone loses an afternoon debugging authentication against a firewall that was never running.

Written to be useful to anyone: it links only to public repositories — oidc-provider-mock and the worked two-provider example in deltag.aarhus.dk — and points ITK Dev developers at the internal documentation for the fuller setup without linking to it.

The two things that bite

• allow_http: true is mandatory, because container-to-container traffic is http. Worth flagging now: since itk-dev/openid-connect 5.1 the scheme check covers every endpoint the discovery document announces, not just metadata_url, so a mock setup that worked on 5.0 fails on 5.1 without it. The section says to keep it in development-only configuration rather than drive it from an environment variable that could be set wrong elsewhere.
• PKCE, which is on by default as of this release.

PKCE against this mock — verified

Not asserted from documentation; I ran the flow. Against ghcr.io/geigerzaehler/oidc-provider-mock:

Step	Result
authorize with code_challenge + code_challenge_method=S256	200, login form, no error
authorize without them	200, identical
Login, then token exchange with code_verifier	access_token, id_token, refresh_token, no error

So a login completes with the bundle's default and no pkce: false is needed.

The README also records what this does not prove: the mock omits code_challenge_methods_supported from its discovery document, so it is not verifying the challenge. The round trip is exercised; the protection is not. Worth knowing before anyone treats a green local login as evidence that PKCE works against the real provider.

Note

An earlier draft of this used Soluto/oidc-server-mock, which our internal documentation still describes. That image is amd64-only and aborts under emulation on arm64, and the current tool is the one used here.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.52%. Comparing base (e7506e9) to head (3eb11ff).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff             @@
##             develop      #81   +/-   ##
==========================================
  Coverage      99.52%   99.52%           
  Complexity       205      205           
==========================================
  Files             15       15           
  Lines            834      834           
==========================================
  Hits             830      830           
  Misses             4        4           

Flag	Coverage Δ
unittests	99.52% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.