The OIDC redirect default: retiring default('') in the Keycloak socket
Status: built; this note is still its only description. The Keycloak
oidcsocket no longer defaults a redirect URI to*. Written 2026-08-07 as a design. Verified against ce main9ed947aand shc main09812f03b. No production estate was contacted; every estate-facing claim below is marked as owed measurement, not as a finding.
This document covers the ce half of the wildcard-redirect defect. The shc
half already landed: 9f16daee4 corrected the three offending plugs and added
tests/unit/catalog/oidc_redirect_uris_test.go, which fails any in-repo
oidc/sso plug that omits redirectUris; 46b2c7446 narrowed the client
mailcow mints. What survives is ce’s own default('*'), which is what protects
(or fails to protect) third-party and hand-written plugs that the shc
catalogue guard cannot see.
Recommendation in one line: take Option 2, refusing to mint on an empty allowlist and deriving nothing, that is, Option 1’s refusal, applied to the rendered value rather than the authored one, with the consumer-host derivation of Option 2 explicitly rejected in §3.2 because the socket cannot see the consumer’s host and the value it could guess is wrong more often than it is right. §6 states this precisely; §1.2 and §1.3 are the two corrections that make it affordable.
1. The defect, and two corrections to how it has been recorded
Section titled “1. The defect, and two corrections to how it has been recorded”1.1 The template
Section titled “1.1 The template”builtin/keycloak/oidc.socket.yaml:132 renders
REDIRECT_URIS: "{{ integration.plug.data.redirectUris | default('*') }}"and the create branch (:240) posts it as
{"clientId":"…","publicClient":false,"redirectUris":["$${REDIRECT_URIS}"],…}A plug that never mentions redirectUris therefore does not get an unset
allowlist. It gets *, on a confidential client, silently, at install
time. Keycloak will hand an authorization code to any redirect_uri a caller
names, an open redirect and an authorization-code exfiltration path against a
client that also holds a secret.
The failure mode is omission, not misconfiguration, which is why three plugs survived review: the file looks complete, and there is nothing wrong on the page to notice.
Two things recorded elsewhere about this defect are wrong, and both change the economics of the fix. They are the reason this proposal recommends what it does.
1.2 Correction A: the mint is NOT create-only
Section titled “1.2 Correction A: the mint is NOT create-only”The prevailing account of this defect holds that the mint is create-only, so an already-minted wildcard client is never revisited and any ce-side fix would be inert on live estates until each client is destroyed and re-minted by hand.
That is not true of ce main, and has not been true since the socket rename.
oidc.socket.yaml:263-304 is an else branch that runs whenever the client
already exists, and its PUT body (:296) carries redirectUris:
BODY="{\"publicClient\":$${PUBLIC_CLIENT},$${SECRET_FRAG}\"redirectUris\":[\"$${REDIRECT_URIS}\"],…}"The template says so in its own words at :264-275: the job “re-runs on every
consumer install/update (runSocketIntegrationJobs sits on the shared deploy
path), so this is the natural repair point when a consumer’s callback moves”,
and at :281 names the reconcile ”★ THE LOAD-BEARING HALF” for the
publicClient knob, precisely because every already-minted client on a live
estate is reconciled there and never re-created.
Dated by git log -S on the interpolation: the reconcile has set redirectUris
since 1c8aba6 (2026-08-04) (the feat(app)!: the identity socket is oidc“ rename itself) and is contained in tags v0.0.21 through v0.0.25.
ded968f (2026-08-06) only added the publicClient and webOrigins fragments
to the same body.
Three consequences, and they point in opposite directions:
- Any ce-side change to the default is self-applying. A narrowed or refused default reaches already-minted clients at each consumer’s next install or update, with no destroy-and-re-mint step and no bespoke migration tool. This is the single largest cost the prevailing account attributed to Options 1 and 2, and it does not exist.
- The blast radius of a refusal is correspondingly wider. The same property means a refusal does not merely stop new wildcard clients; it fires on every existing consumer’s next deploy, turning a routine update of an unrelated app into a failed integration. §4 is about exactly this.
- A hand-repair in the Keycloak admin console is reverted. An operator who narrows a wildcard client by hand loses that edit at the consumer’s next deploy, because the reconcile SETS the plug’s declared value. This is the same mechanism recorded as G4 in the 2026-08-05 gap inventory, where the reconcile was found to overwrite a working hand-configured redirect URI. Hand-repair is therefore not an available mitigation, which removes the obvious workaround under Option 3.
1.3 Correction B: default fires on falsy, not merely on absent
Section titled “1.3 Correction B: default fires on falsy, not merely on absent”ce’s Jinja layer deliberately diverges from Jinja2 here. core/jinja/jinja.go:8
lists “default firing on falsy” among the semantics the catalogue was authored
against, and core/jinja/gonja_parity_test.go:40
(TestGonjaDefaultFiresOnFalsy) pins it:
{`{{ vars.empty | default('fallback') }}`, "fallback"},{`{{ vars.zero | default('fallback') }}`, "fallback"},{`{{ vars.absent | default('fallback') }}`, "fallback"},So the wildcard is reachable three ways, not one: the field is absent, the field is declared empty, or the field is declared as a template that renders empty at deploy time.
The third is the one that matters, because it is a runtime condition and the shc catalogue guard is static. That guard reads the authored YAML and proves a non-empty literal key exists; it cannot know what the value renders to on a given deployment. A plug can pass the guard on every run and still mint a wildcard client on an estate.
Currently latent, not live. All 33 oidc.plug.yaml files on shc main
declare the field, and every declaration carries a literal path or suffix after
its template expression ({{ url('gitea') }}/user/oauth2/keycloak/callback,
{{ vars.siteUrl }}/auth/v1/callback) so none can render to the empty string
even when the interpolated part does. url() cannot return empty either: it
falls back to localhost:<port> and then to the internal alias
<environment>.<service>.<stack> (modules/app/install_runner.go:4587-4617).
That is an accident of authorship, and nothing enforces it. A future plug
written as a bare {{ vars.callbackUrl }} against an unset var mints a
wildcard client, passes the shc guard, and reports clean.
This is the argument that decides between the options. Any fix keyed on the authored value (the current shc guard, and Option 1 as usually stated) leaves this path open. Only a check on the rendered value closes it, and the only place the rendered value exists is ce.
2. What the socket job can see: Option 2’s feasibility, settled
Section titled “2. What the socket job can see: Option 2’s feasibility, settled”Option 2 as posed asks the socket to default to something derived from the
consuming app’s own host, e.g. https://<app-host>/*. Whether the socket can
do that is a question of fact about the render context, and the answer is no.
modules/app/socket_jobs.go:189-199 builds the per-job context:
| key | what it holds |
|---|---|
integration.plug.data | the consumer’s rendered plug data |
integration.socket.data | the provider’s socket data |
vars | the provider’s vars.yaml |
stack, stack_name | ic.ProviderStackName, the provider’s stack |
environment, tenant | the deployment’s tenant and environment |
connections | the provider’s own bound connections |
The comment at :160-163 is explicit that vars is the provider’s “so
templates like image: "{{ vars.images.postgres }}" resolve against the
provider’s image map, not the consumer’s”. stack is likewise the provider’s.
IntegrationContext itself (modules/app/integration_render.go:204-278)
carries ProviderStackName, ProviderTenant, ProviderApp, ProviderNetwork,
SocketData, PlugData and ConsumerServices, and no consumer stack name
and no consumer host. The only channel from the consumer into the socket job
is integration.plug.data, which is exactly the field the plug omitted.
The daemon does know the consumer’s hosts: HostRenderCtx
(modules/app/install_runner.go:4712-4717) maps service → public hostname and
is already threaded through integration resolution. But it is consumer-side
and service-keyed, and it is not projected into the socket job’s context.
So Option 2 is not a template edit. It requires ce plumbing (widening
IntegrationContext and the socket render context with a new
integration.consumer.* namespace) and then it still has to answer a question
the data cannot answer, which §3.2 takes up.
3. The options
Section titled “3. The options”3.1 Option 1: refuse to mint on an absent allowlist
Section titled “3.1 Option 1: refuse to mint on an absent allowlist”Replace | default('*') with a hard failure. Mechanically: render the field
strictly and have the job exit non-zero with a coded error naming the plug, the
socket and the consumer, so the integration (and with it the install) fails
loudly.
| Closes | absent-field wildcards, for every plug including third-party and hand-written ones |
| Leaves open | the empty-render path of §1.3, if the refusal is keyed on absence rather than on the rendered value |
| Breaks | every consumer whose plug omits the field, at its next deploy, not at mint time |
The honest cost. Per §1.2 the reconcile branch is on the shared deploy path, so
a refusal does not sit quietly waiting for new installs. It fires on the next
shc update of any already-integrated consumer whose plug omits the field,
including updates that have nothing to do with SSO. The operator experience is
that an unrelated routine update starts failing, and the remedy lives in a
package the operator may not be able to move (§4).
It is also the option most exposed to the two-clocks problem, because refusal is delivered on the fast clock and the correction that satisfies it is delivered on the slow one.
3.2 Option 2: derive the default from the consuming app’s host
Section titled “3.2 Option 2: derive the default from the consuming app’s host”Two variants, and they are not equally sound.
2a: the socket derives it. Not implementable. §2 settles it: the consumer’s host is not in the socket job’s render context.
2b: ce plumbs the consumer’s host into the socket context, then defaults
to https://<consumer-host>/*.
This is buildable (HostRenderCtx already holds the data) and it is
non-breaking for the common case, which is its whole appeal. But it has a
defect that is not fixable by more plumbing, and it is the same defect the
port-selector proposal named for url(): the ambiguity is not in the key, it
is in the question.
HostRenderCtx.PublicHosts is map[service]hostname. An app has many
services, and the catalogue shows the callback origin is routinely not the
app’s obvious one: defectdojo-nginx, dtrack-frontend, penpot-frontend,
wazuh-dashboard, windmill-server, glitchtip-web, mas. A default that
picks one service picks wrong for a large fraction of the catalogue, and it
picks wrong silently, minting a plausible-looking allowlist for the wrong
origin. That is worse than the status quo in one specific way: * is at least
recognisable as a defect on sight, and a wrong-origin URI is not.
Three further problems:
- It is still a wildcard, just a smaller one.
https://<host>/*allows every path on that origin. For an app with any open redirect or any user-controlled path under the same origin, that is still an authorization-code interception path. It reduces the blast radius; it does not close the class. - It fails closed when the deployment has no
--host, which is the one genuinely good property here.url()falls back to the internal alias<environment>.<service>.<stack>, so a hostless deployment would mint an unreachable URI and the login would break loudly rather than work insecurely. That is the correct direction for a security default, and it is a property Option 1 gets too, more simply. - It entrenches a guess in the socket. Once a derived default exists, a plug author who omits the field gets a plausible client and no signal, so the omission stays invisible, the exact property that let this defect survive review in the first place.
The variant worth keeping from Option 2 is not the derivation. It is the insight that the check belongs on the rendered value, in ce, at mint time, which is §1.3’s conclusion and is folded into the recommendation.
3.3 Option 3: status quo in ce, shc guard only
Section titled “3.3 Option 3: status quo in ce, shc guard only”Keep default('*'). Rely on tests/unit/catalog/oidc_redirect_uris_test.go.
| Closes | in-repo catalogue regressions: a new shc app that forgets the field fails CI |
| Leaves open | third-party plugs, hand-written plugs, and the §1.3 empty-render path on every plug |
| Breaks | nothing |
The guard is real and worth keeping under every option: it holds today (all 33
oidc.plug.yaml files declare the field) and it carries a corpus floor of 25
so it cannot pass by scanning nothing.
But it is a guard on this repository’s catalogue, and the thing being
protected is a product surface. An operator writing their own plug against
the published oidc socket contract gets no guard, no warning, and a
confidential client with *. Per §1.2 consequence 3, they cannot even repair
it by hand durably, because the reconcile reverts the edit at the next deploy.
Option 3 is the honest floor, not a fix. Choosing it is choosing to ship a socket whose documented contract has an insecure default.
3.4 Side by side
Section titled “3.4 Side by side”| closes absent | closes empty-render | protects third-party plugs | breaks existing deploys | ce code change | |
|---|---|---|---|---|---|
| 1: refuse on absent | yes | no | yes | yes | template only |
| 2b: derive from host | yes | yes | partly (wrong origin) | no | plumbing + template |
| 3: shc guard only | in-repo only | no | no | no | none |
| recommended (§6) | yes | yes | yes | yes | template only |
4. The two clocks: why sequencing dominates the choice
Section titled “4. The two clocks: why sequencing dominates the choice”This is the constraint that decides how, not whether.
The socket rides the deb. The plugs ride the registry index.
/usr/lib/shc/apps on a live estate holds only keycloak, openobserve,
postgres and traefik. builtin/keycloak/oidc.socket.yaml is therefore
delivered with the daemon package, and the builtin repo re-syncs within seconds
of each daemon restart. Every other app (every oidc.plug.yaml) is served
from the apps index and resolved per deployment by its own version+revision
pin.
So the two halves of this fix move on different clocks, in the wrong order:
- The ce default change arrives everywhere, at once, on daemon roll.
- The plug correction that satisfies it arrives per deployment, only when that deployment’s pin moves and it is re-rendered, and a re-render of a stack holding production data is a consented decision, not a follow-up.
The cautionary tale: the sso → oidc rename
Section titled “The cautionary tale: the sso → oidc rename”This exact shape has already broken production SSO on three stacks, and it is
recorded as G1 in docs/handoff/2026-08-05-sso-certs-and-the-gap-inventory.md.
The socket was renamed sso → oidc in ce (1c8aba6). The daemon half
shipped with the deb, so every estate immediately served oidc.socket.yaml.
The app half (renaming each sso.plug.yaml) shipped through the apps index
on its own clock, and the deployed stacks were still pinned to packages
shipping sso.plug.yaml. The result was an integration unreachable from
both spellings: -i oidc=keycloak found no plug, -i sso=keycloak found no
socket, and nothing diagnosed it.
Then the second jaw closed. Registry retention had deleted the pinned app
packages (G19, X404012APPDIR), so re-rendering at the pinned revision
refused outright. The fix could not be applied in either direction. Three
Keycloak clients were minted by hand with kcadm, and integration still
carries 0 rows on both estates; no integration has ever been attached in
production.
The transferable lesson, stated as a rule: never ship a daemon-side change that requires an app-side change to already-deployed stacks, unless the app-side change is already delivered everywhere it is needed or the daemon-side change degrades safely when it is not. A refusal does not degrade safely. That is the whole risk in Option 1, and §5 exists to answer it.
5. Sequencing plan, for Option 1 or the recommended variant
Section titled “5. Sequencing plan, for Option 1 or the recommended variant”Four steps, in order. Step 4 is the only one that changes ce.
5.1 Measure: an estate-wide audit of minted clients
Section titled “5.1 Measure: an estate-wide audit of minted clients”Owed before anything lands. The audit is read-only and answers one question per
estate: which existing Keycloak clients carry * in redirectUris?
Per realm, via the same admin REST API the socket job already uses
(GET /admin/realms/<realm>/clients), record for each client: realm, clientId,
publicClient, the redirectUris array, and whether an integration row
exists for it. The last field is the one that matters, because a client with no
integration row is a hand-minted client (per G1, that is how the live ones came
to exist) and no ce change will ever reconcile it; the socket job only
runs for edges the daemon knows about.
The audit must also be run against the plug side: for each deployed
consumer, the package revision it is pinned to and whether that revision’s
oidc.plug.yaml declares redirectUris. That is what converts “how many
wildcard clients” into “how many are fixable by moving a pin”, which is the
number the sequencing decision actually needs.
Expected output: a table of (estate, tenant, realm, clientId, wildcard?, integration row?, pinned revision declares the field?). Until it exists, the blast radius of Option 1 is unknown, and this proposal does not guess at it.
5.2 The re-mint mechanism: mostly already there
Section titled “5.2 The re-mint mechanism: mostly already there”Per §1.2 this is far cheaper than the create-only account implies.
- Edges the daemon knows about need no new mechanism. The reconcile branch
rewrites
redirectUrisfrom the plug’s declared value on the consumer’s next install or update. Correcting the plug and moving the pin is the whole migration. - Hand-minted clients with no integration row are not reachable by any re-render, and per G1 that is the live population on both estates. These need either a one-off admin-API pass or adoption into a real integration edge. Whichever is chosen, it is operator work, not a code path, and it should be scheduled explicitly rather than assumed away.
- A
doctorcheck is the durable form. A check that walks every deployment’s minted client and reports a*allowlist (and a plug/client disagreement) turns this from a one-time sweep into a standing gate. It is also the piece that would have caught the original defect, and it is worth landing independently of which option wins, because it is non-breaking under all of them.
5.3 Ordering, and the gate between steps
Section titled “5.3 Ordering, and the gate between steps”- Land the doctor check and run the §5.1 audit. Non-breaking. Produces the number.
- Correct any remaining plugs and publish the packages, so a corrected revision exists in the index before the daemon change ships. The shc guard already keeps in-repo plugs correct; this step is about publication, not authorship.
- Move the affected deployments’ pins and re-render, consented per stack. This is where the wildcard clients actually get narrowed, by the reconcile branch, at deploy time.
- Only then change the ce default, and roll it. By this point the refusal has nothing left to refuse on the estates, and it is protecting future and third-party plugs rather than breaking present ones.
Step 4 last is the entire lesson of §4. Doing it first is the sso → oidc
rename again, with the same two jaws: a fast-clock change that demands a
slow-clock remedy, on stacks whose pinned packages may no longer exist.
The gate between 3 and 4 is the audit re-run showing zero wildcard clients that a re-render can reach. Not zero wildcard clients; hand-minted ones may legitimately remain, and they are unaffected by the ce change either way.
6. Recommendation and consequences
Section titled “6. Recommendation and consequences”Take Option 1’s refusal, applied to the rendered value, and reject Option 2’s derivation.
Concretely, in builtin/keycloak/oidc.socket.yaml:
- Drop
| default('*')at:132. The plug field is either declared or it is not. - Refuse in the job body, on the rendered value, before any admin call:
an empty
REDIRECT_URISexits non-zero with a coded error naming the consumer, the plug and the socket, and saying what to declare. This is the §1.3 requirement: it catches absence, an authored empty string, and a template that rendered empty, which no static guard can. - Keep an explicit
*working.apps/frappe/oidc.plug.yaml:20declares*deliberately and documents why: one Frappe deployment serves N sites, each with its own hostname and callback, while the socket writes"redirectUris":["<value>"](exactly one element, no comma splitting) so naming one site’s callback would reject every other site’s login. The meaningful distinction is declared wildcard (audited, justified, on the page) versus inherited wildcard (silent). Refusing the second while permitting the first is the whole design. - Keep the shc guard (§3.3) as the in-repo floor, and add the doctor check from §5.2 as the estate-side one.
Why not Option 2b. It cannot see the consumer’s host without new plumbing (§2); the value it would guess is the wrong service’s origin for a large part of the catalogue and wrong silently; it is still an origin-wide wildcard; and it re-creates the property that made this defect survive review: an omission that produces a plausible result and no signal. Its one good property, failing closed on a hostless deployment, is inherited by the recommendation for free.
Why not Option 3. The guard protects this repository’s catalogue. The socket is a published contract, and per §1.2 an operator cannot durably hand-repair a client the reconcile will overwrite. Shipping a documented socket whose default is insecure is a product decision, and it should be made deliberately if it is made at all.
What this costs, honestly:
- It is a breaking change on the fast clock, and §5 exists solely to make that
affordable. Landing it without steps 1-3 repeats the
sso→oidcfailure. - Hand-minted clients (per G1, the live population on both estates) are untouched by it. It prevents the next one; it does not clean up the last one. That is what §5.2’s admin-API pass is for.
- A third-party plug that omits the field now fails the install rather than
installing insecurely. That is the intended trade and it should be stated in
the socket’s schema comment, which today describes
redirectUrisonly as “Comma-separated redirect URIs” (:19), itself inaccurate, see §7.
7. Open questions for the owner
Section titled “7. Open questions for the owner”- Sequencing consent. §5 requires per-stack re-renders of stacks holding production data. That is a consented decision per the migration doctrine, and this proposal does not assume it.
- The hand-minted population. Adopt them into real integration edges, or
sweep them once with the admin API and accept they drift again? This is a
product-posture question about whether
integrationrows are meant to be the source of truth for every client. The comma-splitting contract.ANSWERED IN CODE, 2026-08-07. ceb433f42(“the socket promised comma-separated redirect uris, and wrote exactly one”) splits on comma, trims whitespace, skips empties and emits a real JSON array; a single value still renders["<value>"]byte for byte. It is contained in the shc pin (v0.0.26-0.20260807091440-c50f7e8fceb8). The remaining half of that question (what an EMPTY rendered value should do) is still open and is deliberately not pre-empted: today it falls back to emitting the raw value rather than[], because[]on the reconcile PUT would wipe a working allowlist.- Whether the doctor check lands independently. It is non-breaking under all three options and would have caught the original defect. It does not need to wait for a ruling on the default.
- ★ The write precedes the refusal, and the refusal is non-fatal. See §7.1, this is new since the body above was written and it changes what Option 3 (“status quo in ce, shc guard only”) is worth.
7.1 ★ G4’s ordering half: measured, and worse than recorded
Section titled “7.1 ★ G4’s ordering half: measured, and worse than recorded”§1.2 records G4 as “a hand-repair in the Keycloak admin console is reverted”. That understates it. The reconcile does not merely revert a hand-repair: on the one estate shape the catalogue explicitly anticipates, it destroys a working login before the guard that exists to prevent exactly that can run, and then reports the deploy a success.
The ordering is structural, not incidental. On the install/update path:
| step | code | what it does |
|---|---|---|
| 1 | ce/modules/app/install_runner.go:1561, RunSocketIntegrationJobs | runs the keycloak socket’s create-oidc-client, whose reconcile branch PUTs redirectUris from the plug’s render-time value (ce/builtin/keycloak/oidc.socket.yaml:355-356) |
| 2 | compose up + post_install hooks | the consumer’s containers come up |
| 3 | ce/modules/app/install_runner.go:1849, runConsumerPlugPostDeploymentJobs | runs apps/nextcloud/oidc.plug.yaml’s configure-oidc, whose SSO-surface survey refuses when a foreign login app is enabled |
Step 1 is before step 2 on purpose (the socket must create DB users before
a consumer’s initializer dials them). Step 3 is after step 2 on purpose
(the survey execs php occ and needs a running container). Both reasons are
sound in isolation, and together they make it impossible for the consumer’s
posture gate to run before the socket’s write. There is no pre_integration
plug phase to move it to.
What that costs on the nc shape. apps/nextcloud/oidc.plug.yaml:38
renders redirectUris from ssoSurface, which defaults to refuse. At
refuse it renders …/apps/user_oidc/code, a callback the plug’s own survey
has not yet earned the right to assert, since refuse means “I do not know
which app owns this login”. So on a live sociallogin estate:
- the reconcile PUT replaces the working
…/apps/sociallogin/custom_oidc/keycloakwith…/apps/user_oidc/code. The existing login is now broken; keycloak answers “Invalid parameter: redirect_uri”; - the survey then finds
socialloginenabled and refuses, correctly, having already lost the thing it was refusing to protect; - the refusal is NON-FATAL by contract (
install_runner.go:1837-1843: the app is already up, so a failed reconcile must not roll the deployment back), so the deploy’s overall verdict is success with a loud message.
Net: a correct guard, a broken login, and a green deploy.
Why this is not fixed here. Every available fix touches the same PUT this proposal is deciding, and each one pre-empts a different option:
- make the plug declare both callbacks: widens an authz allowlist to a path the deployment may not even serve, blind, on every green-field install;
- give ce a “preserve” sentinel so a plug can decline to assert: new authz
surface, and the socket already carries an in-code note (
:232-241) deliberately declining to pre-empt the empty-value decision, which is the same seam; - stamp SHC-minted clients and refuse to replace an unstamped client’s allowlist: correct in principle, but on live estates no client carries the stamp, so the first reconcile after the upgrade would decline to repair every one of them, including the matrix callback-ULID case this branch was built for.
It is one ruling, not three fixes. A shc-side plug change is blocked
regardless: at the current pin, a plug that declared any sentinel would write
the sentinel string itself into redirectUris.
The live probe that settles it, against a stack with a foreign login app
enabled (do NOT run this on nc without consent; step 3 is destructive):
# 0. one-time: authenticate kcadm inside the keycloak containersudo -n shc exec -s <keycloak-stack> -t <tenant> -e <env> --service keycloak -- \ sh -c '/opt/keycloak/bin/kcadm.sh config credentials \ --server "$KC_HOSTNAME" --realm master \ --user "$KEYCLOAK_ADMIN" --password "$KEYCLOAK_ADMIN_PASSWORD"'
# 1. BEFORE: what the client actually allows todaysudo -n shc exec -s <keycloak-stack> -t <tenant> -e <env> --service keycloak -- \ /opt/keycloak/bin/kcadm.sh get clients -r <realm> \ -q clientId=nextcloud --fields redirectUris
# 2. confirm the foreign surface is present AND owns the pagesudo -n shc exec -s nextcloud -t <tenant> -e <env> --service nextcloud -- \ php occ app:listsudo -n shc exec -s nextcloud -t <tenant> -e <env> --service nextcloud -- \ php occ config:system:get hide_default_login
# 3. ⛔ DESTRUCTIVE: attach with ssoSurface left at its `refuse` defaultsudo -n shc update nextcloud -t <tenant> -e <env> -i oidc=<keycloak-stack>
# 4. AFTER: both halves of the defect, in two commandssudo -n shc exec -s <keycloak-stack> -t <tenant> -e <env> --service keycloak -- \ /opt/keycloak/bin/kcadm.sh get clients -r <realm> \ -q clientId=nextcloud --fields redirectUris# expect: the sociallogin callback is GONE, replaced by /apps/user_oidc/codesudo -n shc job ls -t <tenant> -e <env> -s nextcloudsudo -n shc ls -t <tenant># expect: configure-oidc REFUSED, and nextcloud's own status is unaffectedStep 4 is the whole finding: the first command shows the write landed, the next two show that the refusal which existed to prevent it ran afterwards and did not fail the deploy. Step 1’s output is the thing to capture first; it is the only record of the working allowlist once step 3 has run.
Appendix: verification ledger
Section titled “Appendix: verification ledger”Verified against ce main 9ed947a:
builtin/keycloak/oidc.socket.yaml: the default('*') render (:132), the
create body (:240), the reconcile else branch and its redirectUris PUT
(:263-304, body at :296), the schema’s comma-separated claim (:19);
modules/app/socket_jobs.go:189-199: the socket-job render context;
modules/app/integration_render.go:204-278: IntegrationContext fields, no
consumer host; modules/app/install_runner.go:4712-4717: HostRenderCtx;
:4587-4617 and :4630-4646: BuildHostFunc / BuildURLFunc fallback
chain; core/jinja/jinja.go:8 and core/jinja/gonja_parity_test.go:40:
default fires on falsy.
Verified by git log / git tag --contains on ce: the reconcile has set
redirectUris since 1c8aba6 (2026-08-04), contained in v0.0.21-v0.0.25;
ded968f (2026-08-06) added only the publicClient and webOrigins
fragments; 65e94fc added webOrigins for the SPA CORS case.
Verified against shc main 09812f03b: all 33 apps/*/oidc.plug.yaml files
declare a non-comment redirectUris (0 sso.plug.yaml remain);
apps/frappe/oidc.plug.yaml:20 is the deliberate * and carries its
rationale; no declaration can render empty; each carries a literal suffix; no
declaration uses a comma; tests/unit/catalog/oidc_redirect_uris_test.go
carries a corpus floor of 25.
Taken from the handoff corpus, not re-measured here:
docs/handoff/2026-08-07-agents-catalog-and-oidc.md §2 (the three offenders:
mailcow, matomo, supabase, and the 34/31/3 split measured 2026-08-07);
docs/handoff/2026-08-05-sso-certs-and-the-gap-inventory.md §4.1 G1 (the
sso/oidc spelling deadlock, three hand-minted clients, integration at 0
rows on both estates), G4 (the reconcile overwriting a hand-set redirect URI),
§4.3 G19 (registry retention invalidating live pins, X404012APPDIR).
Assumed, not proven here: the current wildcard-client population on any estate. §5.1 is the measurement that would establish it, and no production estate was contacted for this document.