blog: Keycloak "Invalid parameter: redirect_uri" — every cause and fix

[xgp]

Keycloak "Invalid parameter: redirect_uri" — Every Cause and Fix

Queue item A1, first of the error-message troubleshooting cluster. The pattern: someone pastes a literal error string into a search engine at 2am, in a moment of acute pain. These posts are short, hard to get wrong, and convert unusually well because the reader is actively broken.

Everything here was tested, not read off a spec

Written against a live Keycloak 26.7.3. Every row of every table was produced by probing the authorization endpoint against clients registered with different patterns. Findings that are genuinely non-obvious:

1. * is a substring wildcard, not a path wildcard.
/cb* matches /cbXYZ and /cb/deep — it crosses the / boundary. And /a/* matches bare /a.

2. Trailing slashes are significant in both directions.
http://host:3000 and http://host:3000/ are different registrations, and neither matches the other. If you don't know which form your library sends, register both.

3. Keycloak rejects any redirect_uri containing a ? — regardless of what you registered.

Registered	Sent	Result
http://localhost:3000/*	.../cb?tenant=acme	rejected
http://localhost:3000/cb*	.../cb?tenant=acme	rejected
http://localhost:3000/cb?*	.../cb?tenant=acme	rejected

We tried to register our way around it and could not. Apps that put their own parameters on the callback URL — a tenant hint, a "return to this page" pointer — have to move that data into state. The post shows how, and explains that state is the correct mechanism anyway since it also carries CSRF protection.

4. The server log names the rejected URI; the error page deliberately doesn't.

WARN [org.keycloak.events] type="LOGIN_ERROR", clientId="c-multi",
  error="invalid_redirect_uri", redirect_uri="http://localhost:3000/cb?tenant=acme"

The browser can't be shown this without turning the login endpoint into an open redirector. Grepping for invalid_redirect_uri resolves most cases in seconds, and almost nobody knows the line exists. This is the single most useful thing in the post.

Also included

• A curl one-liner that tests a redirect URI without a browser — exactly how the tables were generated. Turns a click-and-reload loop into a one-second check.
• kcadm.sh / Terraform snippets so URIs stop drifting between environments.
• An honest section on wildcard security: why redirect URI validation exists, why broad wildcards are dangerous, and why an upgrade may have broken a redirect that used to work.

Verification

• pnpm build passes
• 1,332 words
• Named author byline, keyword in title / description / first 150 words
• Direct-answer block in the opening for snippet and AI extraction

Note

The closing CTA originally linked to /tutorials/, which ships in #355. Removed here so the link checker passes on this branch — worth adding once #355 merges.

[cloudflare-workers-and-pages]

Deploying phasetwo-docs with    Cloudflare Pages

Latest commit:	6338a24
Status:	✅  Deploy successful!
Preview URL:	https://3e671114.phasetwo-docs.pages.dev
Branch Preview URL:	https://content-2026-w1-redirect-uri.phasetwo-docs.pages.dev

View logs