[pimlock]

Summary

Fixes the E2E jobs that load the Keycloak fixture realm, which have failed since #5065 merged. That PR added http://[::1]:* to the openshell-cli client in scripts/keycloak-realm.json. Keycloak 24 refuses to import it, so Keycloak exits at startup with Invalid client openshell-cli: A redirect URI is not a valid URI and never becomes healthy.

Example failures:

• Release Dev on main (50a3237): docker-e2e / E2E (oidc-pkce-docker), docker-e2e / E2E (oidc-python), feature-specific-integration (fedora-podman-rootful, provider-refresh)
• Branch E2E on fix(server): consistent sandbox access after the main process exits #4950: e2e-suites / E2E suites (features/keycloak-provider-refresh)

Related Issue

No issue required: localized fix for a test fixture that broke E2E on main.

Changes

• Remove the http://[::1]:* redirect URI and web origin from the openshell-cli client in the Keycloak fixture realm.
• Correct docs/how-it-works/gateways/authentication.mdx: the bundled realm allows only the IPv4 loopback and localhost forms, so an IPv6 callback bind against it needs an exact http://[::1]:<port>/callback redirect URI.

The CLI's IPv6 callback support from #5065 is unchanged.

Keycloak 24 can't allowlist an IPv6 loopback address with an arbitrary port. Tested against quay.io/keycloak/keycloak:24.0:

• http://[::1]:*, http://[::1]*, http://[0:0:0:0:0:0:0:1]:* and http://[::1]:1* all fail realm import.
• http://[::1]/* imports but rejects http://[::1]:<port>/callback, and Keycloak doesn't relax the port for IPv6 loopback.

Testing

• mise run pre-commit passes (ran as the commit hook)
• Started Keycloak 24 with the fixed realm. The openshell realm imports, the discovery endpoint returns 200, and an auth request with redirect_uri=http://127.0.0.1:41234/callback is accepted.
• E2E: test:e2e applied so the OIDC Docker, provider-refresh and features/keycloak lanes run on this PR

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5089.docs.buildwithfern.com/openshell

[pimlock]

Why Keycloak 24 rejects http://[::1]:*

Keycloak has no explicit rule against IPv6 wildcards. The rejection is a side effect of how it validates redirect URIs.

Validation: DefaultClientValidationProvider.checkUri passes each redirect URI, * included, to new java.net.URI(url). A URISyntaxException becomes "A redirect URI is not a valid URI". The same call is still on Keycloak main.

java.net.URI first tries to parse the authority as host and port, which fails because * isn't a port. It then falls back to a registry-based authority, which allows * and : but not the [] an IPv6 host needs. So the existing IPv4 wildcard entries only pass through that fallback (host=null), and the IPv6 ones have no fallback. Output from the JVM in quay.io/keycloak/keycloak:24.0:

OK   http://127.0.0.1:*            host=null authority=127.0.0.1:*
OK   http://localhost:*            host=null authority=localhost:*
FAIL http://[::1]:*                Illegal character in port number at index 13
FAIL http://[::1]*                 Expected port number at index 12
FAIL http://[::1]:1*               Illegal character in port number at index 14
OK   http://[::1]/*                host=[::1] authority=[::1]
OK   http://[::1]:5555/callback    host=[::1] authority=[::1]:5555

Matching: http://[::1]/* imports but doesn't help. In 24.0.5, RedirectUtils.verifyRedirectUri ignores the port only for redirects that start with http://localhost or http://127.0.0.1, so http://[::1]:<port>/callback is rejected.

Newer Keycloak: keycloak/keycloak@af5eef57bf ("Improve handling for loopback redirect-uri validation", part of the CVE-2024-8883 fix) adds [::1] to the loopback hosts and matches any port against the registered URI. It shipped in 26.0.0; 24.0.5 and 25.0.6 don't have it. On 26.0.0 or later, an exact http://[::1]/callback (no wildcard, no port) accepts any callback port. http://[::1]:* still fails import there because the java.net.URI check is unchanged.

Docs: the admin guide only says wildcards go at the end of the pattern; IPv6 isn't mentioned. The 26.6.3 upgrade notes recommend not using wildcard redirect URIs at all.

Follow-up option: to support IPv6 callbacks in the dev realm, move the fixture to Keycloak 26.0.0 or later and register exact loopback URIs (http://127.0.0.1/callback, http://[::1]/callback) instead of wildcards. That's a separate change; this PR only restores the realm to what worked before #5065.