docs: document loopback redirect_uri port-matching behavior for IDP clients (#12479)
- Dominant language
- Go
- Stars
- 2.1k
- Forks
- 274
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 106
Description
Automated documentation follow-up for a merged, user-visible behavior change.
### Source
PR #12479 — *fix: more permissive redirect check* (merged to `master` 2026-07-07), changelog fragment `changelog/unreleased/bugfix-ensure-valid-redirect-uri.md`.
### What changed (behavior)
`services/idp/pkg/middleware/checkredirect.go`'s `CheckRedirect` validation of the OIDC `redirect_uri` query parameter changed from exact string match against a client's configured `RedirectURIs` to URL-parsed comparison, with one relaxation: when both the incoming `redirect_uri` and a registered `RedirectURIs` entry resolve to a loopback host (`localhost`, `127.0.0.1`, `::1`), the port is now ignored when matching. This aligns with RFC 8252 §7.3 (native/desktop apps binding an ephemeral loopback port) and was needed to fix desktop client login, which was failing because it uses a random local port.
Non-loopback hosts still require an exact URL match (scheme, host, path) — this is not a general redirect-validation loosening, only a loopback-port carve-out. New unit tests (`checkredirect_test.go`) cover userinfo-spoofing (`http://localhost:8080@evil.com/`) and scheme-mismatch attempts, both correctly rejected.
### Documentation to update
- [ ] IDP / proxy OIDC client configuration docs — note that a client's registered loopback `RedirectURIs` (`http://localhost/...`, `http://127.0.0.1/...`, `http://[::1]/...`) now match an incoming `redirect_uri` on that same host+path regardless of port, so native/desktop OIDC clients (or third-party integrations) can rely on binding an ephemeral local port instead of a fixed one.
- [ ] Confirm no admin-facing config flag doc changes are needed (none in this PR — the client `RedirectURIs` config schema itself is unchanged, only the internal matching logic).
### Notes
- The changelog fragment covers the "why" for release notes; this issue tracks the more detailed admin/integrator-facing documentation, which isn't covered by the changelog fragment alone.
- No new config options, CLI flags, or API endpoints were introduced.
_Opened automatically by the oCIS triage routine (PR-merged trigger). Documentation PRs are not auto-merged._
🤖 Generated by Claude Code
Contributor guide
Assessment
This issue has not been assessed yet.