Skip to content
Munim · OSS

oidcdoctor

Wire OIDC login into your app — and prove it actually works against Keycloak. oidcdoctor scaffolds your OIDC login, reconciles your app config against the real Keycloak client, then runs a real authorization-code + PKCE handshake over plain HTTP — no browser — to assert a token is issued.

Writing login code is easy. Knowing it works is the hard part. The #1 Keycloak pain — redirect_uri mismatch, PKCE required-but-missing, public-vs-confidential confusion — only fails at runtime, in a browser, with an opaque error. AI agents are great at writing login code; they can’t tell if it runs. oidcdoctor is that feedback loop.

Terminal window
  scaffold → analyze (reconcile) → verify (real handshake) → sync → verify ✓


  $ oidcdoctor verify
  ✗ login failed at step 'authorize'.


  redirect_uri_mismatch  'http://localhost:3000/api/auth/callback' differs from
    registered 'http://localhost:3000/api/auth/callback/' only by a trailing slash
    — Keycloak matches paths exactly
    app: Make the app's redirect_uri exactly '…/callback', watch trailing-slash.
    keycloak: Add '…/callback' to Valid Redirect URIs, or run oidcdoctor sync.


  $ oidcdoctor sync && oidcdoctor verify
  ✓ patched Keycloak client 'my-app'.
  ✓ login works — a token was issued (reached step 'done').

100% local, no browser

The verification handshake drives Keycloak over fetch — builds the authorize URL, scrapes the login form, POSTs credentials, catches the code off the redirect, exchanges it for tokens. No Playwright, no headless Chromium, no API key.

Agent-native

Run as an MCP server (oidcdoctor mcp) and wire it into Claude Code, Cursor, or Codex in one command. Four tools expose the full loop: analyze, verify_login, sync_client, scaffold.

8 failure classes, two-sided fixes

The reconciler models Keycloak’s exact matching rules and detects every classic mismatch — scheme, host, port, trailing slash, PKCE method, client type, web origins, openid scope, post-logout URI — with a fix for both the app and Keycloak.

Scaffold → verify → heal loop

Generate consistent login code (Next.js / FastAPI / Django), sync the Keycloak client to match, run the real handshake. The moat is the verification loop, not the codegen. How it works.

Install in one command

Section titled “Install in one command”
Terminal window
npx oidcdoctor install

This wires oidcdoctor into Claude Code and Cursor automatically. Restart your agent and it can scaffold, analyze, verify, and sync your OIDC login.

Next steps

Section titled “Next steps”
Quick start Write oidcdoctor.json, scaffold login code, and run a real handshake in five minutes.
Failure classes The 8 reconciler findings — what each means and the exact fix on both sides.
How it works The scaffold → reconcile → verify → sync → re-verify pipeline, explained.

MIT   MCP server   github.com/abdulmunimjemal/oidcdoctor