pomerium / pomerium / 24161261011

52%

Build Type

push

github

Committed by web-flow

Commit Message

fix: allow loopback redirect URIs with any port per OAuth 2.1 (#6251)

## Summary

MCP OAuth authorization rejects clients that use loopback redirect URIs
with dynamic ephemeral ports (e.g. Claude Code), returning
`invalid_grant` because redirect URI validation requires an exact string
match including the port.

[OAuth 2.1
§2.3.1](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-2.3.1)
requires an exception for loopback redirects:

> Authorization servers MUST require clients to register their complete
redirect URI (including the path component). Authorization servers MUST
reject authorization requests that specify a redirect URI that doesn't
exactly match one that was registered, **with an exception for loopback
redirects, where an exact match is required except for the port URI
component.**

[OAuth 2.1 §8.4.2 "Loopback Interface
Redirection"](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-8.4.2)
further specifies that native apps use loopback redirects with ephemeral
ports, and the authorization server must not require clients to
pre-register a specific port.

The [MCP Authorization spec
(2025-11-25)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
defers to OAuth 2.1 for redirect URI validation rules and explicitly
permits `localhost` redirect URIs.

## Related issues

- [ENG-3857](https://linear.app/pomerium/issue/ENG-3857)

## User Explanation

MCP clients using loopback redirect URIs (e.g.
`http://localhost:<port>/callback`) can now authenticate successfully
regardless of which ephemeral port they bind to.

## Checklist

- [x] reference any related issues
- [x] updated unit tests
- [x] add appropriate label (`enhancement`, `bug`, `breaking`,
`dependencies`, `ci`)
- [ ] ready for review

Coverage Stats

23 of 26 new or added lines in 1 file covered. (88.46%)

6 existing lines in 3 files now uncovered.

35090 of 77209 relevant lines covered (45.45%)

114.19 hits per line