Repository navigation
[#1230] Allow any port for loopback redirect URIs (RFC 8252 7.3) - #1231
Conversation
|
If the behavior change is considered breaking, allow for new forward boolean setting which can control this behavior. |
… NumberFormatException
maximthomas
left a comment
There was a problem hiding this comment.
Hi @nicholascowan,
Thank you for the contribution!
There is a feedback below:
praise: The new matching code only adds an extra path for loopback redirect URIs. It does not loosen exact matching for any other URI.
RedirectUriValidator.validatestill triesuri.equals(request)first.isLoopbackMatchchecks the request side (http, no user info, loopback host) before it looks at the registration, so single-port and non-loopback URIs still need an exact match. The 16rejectedRedirectsrows cover this, including127.0.0.2,user@,localhost.example.comandlocalhost:80*.LOOPBACK_PORT_PATTERNhas to match the whole raw authority. A registereduser@localhost:*orapp.example.com:*therefore never takes the pattern branch.
issue (blocking): A redirect URI registered with a port pattern has no host, so the pairwise sub is computed from the string "null".
openam-oauth2/src/main/java/org/forgerock/openam/oauth2/OpenAMClientRegistration.java:930, :952-960
java.net.URI reads http://localhost:*/callback and http://127.0.0.1:8000-9000/callback as registry-based authorities, so getHost() returns null (checked on JDK 26). Without a sector_identifier_uri, getSubValue computes the hash of host + id + salt. Because of the Objects.equals change at L956, these clients now reach that hash instead of failing with an NPE, and the sector is "null". Three things follow:
- Moving a pairwise client from
http://localhost:8080/callback(sectorlocalhost) to the newly documentedhttp://localhost:*/callbackchanges every user'ssub. localhost:*and127.0.0.1:*clients end up in the same sector.- The port-less form, which the guide lists next to the pattern forms as equivalent, keeps the sector
localhost.
Relying parties store these sub values, so fixing the sector after a release would change them again. The fix below reuses the validator's own regex. A host such as app_1.example.com also has a null host today, and the fix keeps that behaviour unchanged.
// RedirectUriValidator
/**
* Returns the host of a loopback redirect uri registered with a port pattern, e.g. {@code localhost} for
* {@code http://localhost:*}{@code /callback}, for which {@link URI#getHost()} is {@code null}.
*
* @param registered A redirect uri registered for the client.
* @return The host, or {@code null} if the uri is not a loopback port pattern.
*/
public static String loopbackPatternHost(URI registered) {
final Matcher pattern = LOOPBACK_PORT_PATTERN.matcher(String.valueOf(registered.getRawAuthority()));
return pattern.matches() ? pattern.group(1) : null;
}
// OpenAMClientRegistration (import org.forgerock.oauth2.core.RedirectUriValidator;)
private static String redirectUriHost(URI uri) {
return uri.getHost() != null ? uri.getHost() : RedirectUriValidator.loopbackPatternHost(uri);
}
// getSubValue, L930
host = redirectUriHost(getRedirectUris().iterator().next());
// containsMultipleRedirectUriHosts, L953 and L956
String host = redirectUriHost(redirectUris.iterator().next());
...
if (!Objects.equals(redirectUriHost(uri), host)) {The fix covers L930, L953 and L956, the only places in the repo that call getHost() on a redirect URI. L925 is out of scope, because a sector_identifier_uri is an https URL. Also out of scope: containsMultipleRedirectUriHosts returns true when all hosts are equal, which gives a null sub. That inversion predates this PR, and two port-less URIs on the same host already hit it.
Pin, in RedirectUriValidatorTest (import static org.testng.Assert.assertEquals;):
@DataProvider
public Object[][] loopbackPatternHosts() {
return new Object[][] {
{"http://localhost:*/callback", "localhost"},
{"http://127.0.0.1:8000-9000/cb", "127.0.0.1"},
{"http://app_1.example.com/callback", null},
{"http://user@localhost:*/callback", null},
};
}
@Test(dataProvider = "loopbackPatternHosts")
public void shouldResolveLoopbackPatternHost(String registered, String host) {
assertEquals(RedirectUriValidator.loopbackPatternHost(URI.create(registered)), host);
}question (non-blocking): Should the request query be compared? The Javadoc, the admin guide and the PR body say the query must match exactly, but the code never compares the request's query.
openam-oauth2/src/main/java/org/forgerock/oauth2/core/RedirectUriValidator.java:90-91, :111; openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-agents.adoc:1669; openam-oauth2/src/test/java/org/forgerock/oauth2/core/RedirectUriValidatorTest.java:53
validate clears the request query at L62-63, before the loop. In isLoopbackMatch, request.getRawQuery() is therefore always null, and L111 only checks that the registered URI has no query. A probe confirms both effects: a registered http://localhost:*/cb?app=x fails on every request, and a request carrying ?evil=1 passes. The allowed row at L53 (?state=abc) agrees with the code. Exact matching has always ignored the request query, so the PR opens no new hole; the text claims more than the code does.
If ignoring the query is intended (Minor), only the text changes (L111 can stay):
* response on an ephemeral port of the loopback interface. Scheme, host and path must match the
* registered uri; only the port is flexible. As for every redirect uri, the query of the request is not
* compared. A registered {@code http} redirect uri on {@code localhost},In chap-agents.adoc:1669, "The scheme, host, path and query must still match exactly:" becomes "The scheme, host and path must still match exactly:". The PR body needs the same change. If the query was meant to be compared, the code and the L53 row are wrong, and this becomes a Major.
issue (non-blocking): The * list item in the admin guide renders without its asterisks.
openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-agents.adoc:1673
Asciidoctor applies bold (strong) formatting before monospace. The * in `*` and the * in localhost:*/callback therefore open and close one bold span. Asciidoctor 2.0.20 renders the line as <code><strong></code> as the port, for example <code>http://localhost:</strong>/callback</code>, so the only example of the * form reads http://localhost:/callback. The doc build (doc-maven-plugin, asciidoctorj 2.5.3) also runs Asciidoctor 2.0.x. The literal-monospace form below renders correctly in 2.0.20. Drop the \, because +…+ already prevents the autolink. L1672 and L1674 render correctly as they are.
* With `+*+` as the port, for example `+http://localhost:*/callback+`, any port is accepted.suggestion (non-blocking): Three conditions in isLoopbackMatch can be deleted without any test failing: the registered scheme (L109), the registered user info (L116) and the default port 80 (L114).
openam-oauth2/src/test/java/org/forgerock/oauth2/core/RedirectUriValidatorTest.java:69-99; openam-oauth2/src/main/java/org/forgerock/oauth2/core/RedirectUriValidator.java:109, :114, :116
The request-scheme check at L107 rejects both https rows before L109 runs. No row registers a URI with user info, and every range row sends an explicit port. A probe harness ran all 29 rows against two mutants, and no row failed for either:
- Without L109, a registered
https://127.0.0.1/cbacceptshttp://127.0.0.1:5000/cb, an http downgrade on any port. - Without the user-info check,
http://user@localhost/cbacceptshttp://localhost:5000/cb.
The port-80 mutant was not run; that gap comes from reading L114 and the range rows.
// rejectedRedirects
{"https://127.0.0.1/callback", "http://127.0.0.1:5000/callback"}, // fails if L109 is deleted
{"http://user@localhost/callback", "http://localhost:5000/callback"}, // fails if getRawUserInfo() == null is deleted
// allowedLoopbackRedirects
{"http://localhost:1-100/callback", "http://localhost/callback"}, // fails if the default 80 at L114 changesquestion (non-blocking): Is it intended that a loopback IP redirect URI registered with an explicit port, such as http://127.0.0.1:8080/callback, still matches only that port?
openam-oauth2/src/main/java/org/forgerock/oauth2/core/RedirectUriValidator.java:116; openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-agents.adoc:1677
RFC 8252 section 7.3 says: "The authorization server MUST allow any port to be specified at the time of the request for loopback IP redirect URIs". For a registered URI that has a host, L116 returns true only when registered.getPort() == -1. So http://127.0.0.1:8080/callback and http://[::1]:8080/callback still require the same port.
The PR body and chap-agents.adoc:1677 state the rule, but not its consequence. A native client registered with one of these URIs gets redirect_uri_mismatch as soon as the OS assigns it a different port. This affects, for example, clients registered through dynamic client registration, which accepts neither * nor ranges. The test rows that pin exact matching (RedirectUriValidatorTest.java:59, :73) use localhost, which 7.3's MUST does not cover (section 8.3 marks localhost NOT RECOMMENDED).
If full 7.3 compliance is the goal, L116 should ignore the registered port for 127.0.0.1 and [::1]. That is another behaviour change for stored registrations, so it also needs a line in the upgrade note below. If the stricter reading is deliberate, chap-agents.adoc:1677 should say so and give the reason.
suggestion (non-blocking): No test exercises the containsMultipleRedirectUriHosts change. The suite stays green if L956 is reverted to uri.getHost().equals(host).
openam-oauth2/src/main/java/org/forgerock/openam/oauth2/OpenAMClientRegistration.java:956
The only test the PR changes is RedirectUriValidatorTest, which mocks ClientRegistration. No file outside src/main mentions getSubValue or pairwise subjects. With the blocking fix, host resolution moves to the static loopbackPatternHost, and the rows above test it without an AMIdentity. The call sites still need a test of their own.
Pin: getSubValue(id, settings) on a pairwise OpenAMClientRegistration (with a mocked AMIdentity) whose redirect URIs are http://localhost:*/a and http://127.0.0.1/b returns a non-null sub. With L956 reverted, the same call throws NullPointerException.
suggestion (non-blocking): The behaviour change for existing port-less loopback redirect URIs is described only in the PR body. Add it to the upgrade guide.
openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc; openam-oauth2/src/main/java/org/forgerock/oauth2/core/RedirectUriValidator.java:115-117
A stored http://localhost/callback used to match only the same URI without a port. At the PR head, L116 accepts it on any port, as the PR body states. Release notes are generated lists of PR titles, so operators who upgrade never see the body. An existing confidential web client registered this way now receives authorization codes on any loopback port; PKCE, which is enabled by default, limits code interception. chap-upgrade-servers.adoc already records non-GHSA behaviour changes as [IMPORTANT] blocks (L105-107, L124-126):
[IMPORTANT]
====
Starting with this release an `http` redirection URI on `localhost`, `127.0.0.1` or `[::1]` that is registered without a port accepts the redirect URI on any port, as described in RFC 8252 section 7.3. Previously it matched only the same URI without a port, that is the default port 80. A loopback redirection URI registered with an explicit port still matches that port only.
====…ack port patterns, docs, tests - Resolve the host of a loopback port pattern (getHost() is null) through RedirectUriValidator.loopbackPatternHost, so the pairwise sub of a http://localhost:*/callback client uses the sector "localhost", as http://localhost:8080/callback does, instead of "null". - Javadoc and admin guide: the query of the request is not compared. - Admin guide: render the * form correctly and explain why an explicit loopback port still matches only that port. - Upgrade guide: note the behaviour change for port-less loopback URIs. - Tests: registered https and user info, default port 80 in a range, loopbackPatternHost, and the pairwise sub of loopback port patterns.
|
Thanks for the thorough review, @maximthomas. All points are addressed in a509336. Blocking, pairwise sector: applied as suggested. Query: ignoring the request query is intended, matching exact matching. I updated the Javadoc, the admin guide and the PR body, and kept L111. Admin guide Mutants: added your three rows (registered Explicit loopback IP port: the stricter reading is deliberate. Changing it would alter how every stored Upgrade guide: added your
|
|
To add, I think it is better to lean toward full RFC compliance but if you suspect any regression risk possibility for other users I am happy to gate this behind property flags; advise how you would prefer to proceed on any change, I will be happy to modify the PR. |
maximthomas
left a comment
There was a problem hiding this comment.
Hi @nicholascowan,
Thank you for the quick fix!
praise: The round-1 points landed as asked, each with a test or text that holds them.
RedirectUriValidator.loopbackPatternHostreusesLOOPBACK_PORT_PATTERN, sohttp://localhost:*/callbacknow has the pairwise sectorlocalhost, andpairwiseSubForLoopbackPortPatternUsesTheLoopbackHostAsSectorturns red ifOpenAMClientRegistration.java:931goes back togetHost().- The three mutant-killing rows are in, verbatim (
RedirectUriValidatorTest.java:59,:87,:88), and the[IMPORTANT]upgrade note is inchap-upgrade-servers.adoc:176-179.
suggestion (non-blocking): No test pins the redirectUriHost() call inside containsMultipleRedirectUriHosts, and pairwiseSubForLoopbackPortPatternsIsNotNull asserts the pre-existing inverted outcome.
openam-oauth2/src/test/java/org/forgerock/openam/oauth2/OpenAMClientRegistrationTest.java:341-347, openam-oauth2/src/main/java/org/forgerock/openam/oauth2/OpenAMClientRegistration.java:954, :956
Only the two new tests reach getSubValue. The sector test registers one URI per call, so size() != 1 (:927) skips the helper. The :341 test registers localhost:*/a + 127.0.0.1/b, whose hosts differ under both getHost() and redirectUriHost(), so it passes either way. Reverting :954 and/or :956 to uri.getHost() therefore stays green, although it changes the outcome for localhost:*/a + localhost:8080/b. So the sentence "Both fail if the host lookup is reverted to getHost()" in the PR body holds only for the sector test. Also, isNotNull() at :346 on a two-host client without sector_identifier_uri pins the inverted helper, which OIDC Core 8.1 says should require a sector identifier. A later fix of that helper would break a test that reads as a spec. The test really guards against the old NullPointerException. The pin below compares a pattern pair with an explicit same-host pair instead of asserting a value, so it holds before and after any fix of the inversion. In a replica of the head logic (not run under Maven), the two rows together kill the :954, :956 and both-sites reverts.
@Test
public void pairwiseSubForLoopbackPortPatternsDoesNotThrow() throws Exception {
setUpAgentWithAttribute(SUBJECT_TYPE, "pairwise");
setUpAgentWithAttribute(OAuth2Constants.OAuth2Client.REDIRECT_URI,
"[0]=http://localhost:*/a", "[1]=http://127.0.0.1/b");
// Threw a NullPointerException before; the sub of a multi-host client is not asserted here.
clientRegistration.getSubValue("user", providerSettings);
}
@Test
public void pairwiseSubTreatsALoopbackPortPatternAsItsHost() throws Exception {
setUpAgentWithAttribute(SUBJECT_TYPE, "pairwise");
setUpAgentWithAttribute(OAuth2Constants.OAuth2Client.REDIRECT_URI,
"[0]=http://localhost:8080/a", "[1]=http://localhost:9090/b");
final String explicitPortsSub = clientRegistration.getSubValue("user", providerSettings);
setUpAgentWithAttribute(OAuth2Constants.OAuth2Client.REDIRECT_URI,
"[0]=http://localhost:*/a", "[1]=http://localhost:8080/b");
final String wildcardAndPortSub = clientRegistration.getSubValue("user", providerSettings);
setUpAgentWithAttribute(OAuth2Constants.OAuth2Client.REDIRECT_URI,
"[0]=http://localhost:*/a", "[1]=http://localhost:3000-4000/b");
final String wildcardAndRangeSub = clientRegistration.getSubValue("user", providerSettings);
assertThat(wildcardAndPortSub).isEqualTo(explicitPortsSub);
assertThat(wildcardAndRangeSub).isEqualTo(explicitPortsSub);
}Pin: the first test replaces pairwiseSubForLoopbackPortPatternsIsNotNull; the second is new.
suggestion (non-blocking): No row exercises the case-insensitive host match of the port-pattern branch.
openam-oauth2/src/main/java/org/forgerock/oauth2/core/RedirectUriValidator.java:121, :157; openam-oauth2/src/test/java/org/forgerock/oauth2/core/RedirectUriValidatorTest.java:52-59
Every pattern row registers lowercase localhost:* / 127.0.0.1:… and sends a lowercase host. The only uppercase row (:49, http://LOCALHOST/callback) has a host, so it returns in the port-less branch before the pattern branch. Dropping (?i) from LOOPBACK_PORT_PATTERN, or turning equalsIgnoreCase at :121 into equals, keeps all rows green. Either change would make a stored http://LOCALHOST:*/callback reject http://localhost:5000/callback. These mutants were measured in a replica of validate(), not under Maven.
// allowedLoopbackRedirects
{"http://LOCALHOST:*/callback", "http://localhost:5000/callback"}, // kills both mutants
{"http://localhost:*/callback", "http://LocalHost:5000/callback"}, // kills the equals one
Thanks - no property flag needed in this PR, in my view. The port-less change is what RFC 8252 7.3 requires for loopback redirects, it is documented in the [IMPORTANT] upgrade note, and PKCE limits the interception risk. A global flag would add a setting, an upgrade step and tests for both states to switch off behaviour the RFC requires. Admins can already opt a single client out: registering http://localhost:80-80/callback (or 127.0.0.1) restores the old match - the port-less request and :80 are accepted, other ports are not. Note that http://localhost:80/callback does not do this: an explicit port keeps exact matching, so it would reject the port-less http://localhost/callback. If you like, add that one sentence to the upgrade note. On full 7.3 compliance for loopback IPs registered with an explicit port: please keep the current strict reading here. It is the only way to tie a client to one port, and widening it would change every stored 127.0.0.1: / [::1]: registration at once. If someone needs it, let's track it as a separate issue - that change, unlike this one, is where a flag might be justified. From my side the PR is good to merge; the two remaining test suggestions are in the review and are optional. |
…directUriHosts and case-insensitive port patterns
… loopback match with the 80-80 range
vharseko
left a comment
There was a problem hiding this comment.
Thanks for the contribution. I found two problems with the upgrade guidance:
-
[P2] The suggested
80-80migration breaks requests that omitredirect_uri—openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc:178An existing client with the single registered URI
http://localhost/callbackcan omitredirect_urifrom an authorization request:RedirectUriValidator.validateaccepts it andRedirectUriResolver.resolveuses that registered URI as the destination. After following the suggested migration tohttp://localhost:80-80/callback, the same request is still accepted, but the resolver returns the pattern itself as the destination.80-80is not a valid URL port, so the browser cannot follow that redirect. The same issue applies to a sole*or range registration more generally. Please handle omitted redirect URIs for pattern registrations explicitly and add a test covering the resolver/authorization path; for the80-80migration, preserving the former default destination would avoid breaking existing clients. -
[P2] The suggested migration does not preserve matching for all port-less loopback URIs —
openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc:178The note presents
80-80as a way to keep the previous behavior, but it also accepts an explicit:80request that the previousURI.equalscheck rejected. More significantly, the note covers[::1]as well:http://[::1]:80-80/callbackcannot be parsed as ajava.net.URI, and the new matcher supports patterns only forlocalhostand127.0.0.1. Registeringhttp://[::1]:80/callbackinstead rejects the port-less request that previously worked. Please make the migration guidance explicit about these limits and provide an actual opt-out for existing IPv6 registrations if preserving their prior behavior is required.
…ration is a loopback port pattern - RedirectUriValidator rejects an omitted redirect_uri, and RedirectUriResolver does not fall back to the registered uri, when the client's only redirect uri is a port pattern such as http://localhost:*/callback or http://localhost:80-80/callback, as a pattern is not a usable destination. - Upgrade guide: drop the 80-80 migration, which did not preserve the previous behaviour, and state that there is no opt-out.
vharseko
left a comment
There was a problem hiding this comment.
Thanks for addressing the review.
The omitted redirect_uri case is now handled explicitly in both the validator and the resolver, with tests for wildcard, range, and port-less registrations. The upgrade guide also removes the misleading 80-80 migration and states that there is no setting to restore the previous port-less matching behavior.
One small documentation follow-up: the PR description still says the multi-host pairwise-sub test asserts a non-null value, but the current test only checks that the call does not throw.
The CI checks for the latest commit are still pending.
Summary
httpredirect URI onlocalhost,127.0.0.1or[::1]. Scheme, host and path must still match exactly; as for every redirect URI, the query of the request is not compared. A request on another host, overhttps, with user info, or on a different path is rejected.http://127.0.0.1/callback: any port;*as the port, e.g.http://localhost:*/callback: any port;http://localhost:49152-65535/callback: any port in the range, inclusive.*or a range. Malformed patterns such aslocalhost:80*never match.chap-upgrade-servers.adoc) records this in an[IMPORTANT]note.*and range ports are supported onlocalhostand127.0.0.1only, becausejava.net.URIcan't parse them on an IPv6 literal. A port-lesshttp://[::1]/callbackcovers that case.RedirectUriValidatoralready validates both the authorization and token requests, so it's the only matching change.URI.getHost()isnullfor a port pattern, soOpenAMClientRegistrationreads the host of a redirect URI throughRedirectUriValidator.loopbackPatternHost. A pairwise-subject client onhttp://localhost:*/callbacktherefore uses the sectorlocalhost, the same ashttp://localhost:8080/callback, instead of throwing aNullPointerExceptionor hashing"null".chap-agents.adoc).Test plan
RedirectUriValidatorTest/shouldAllowLoopbackRedirectOnAnyMatchingPort: 14 cases (default port 80 in a range, port-less,*and range onlocalhost,127.0.0.1and[::1]; range bounds; an exact explicit port)RedirectUriValidatorTest/shouldRejectNonMatchingRedirect: 18 cases (registeredhttpsor user info, other explicit port, out of range, path/host/scheme mismatch,127.0.0.2, user info, non-loopback host with or without*,httpsloopback,localhost.example.com, malformed patterns)RedirectUriValidatorTest/teststill passesRedirectUriValidatorTest/shouldResolveLoopbackPatternHost: 4 cases (localhost:*,127.0.0.1range,app_1.example.com,user@localhost:*)OpenAMClientRegistrationTest: the pairwise sub ofhttp://localhost:*/a+http://127.0.0.1/bis not null, andhttp://localhost:*/callbackhas the same sub ashttp://localhost:8080/callbackand a different one fromhttp://127.0.0.1:*/callback. Both fail if the host lookup is reverted togetHost()mvn -pl openam-oauth2 test: 989 tests, 0 failuresmaster) withhttp://localhost:*/callback,http://127.0.0.1:49152-65535/callbackandhttp://[::1]/callbackregistered:/authorizeaccepted random ports on all three and still rejected out-of-range ports, other paths,https,127.0.0.2, user info and non-loopback hosts. An MCP client then signed in end to end (authorization code + PKCE) on an unregistered port, 54321