Skip to content
SHC Docs

Portal accounts and cluster identity: RULED 2026-08-16

Status: RULED (three rulings), with one open edge marked as such. This records owner decisions from the 2026-08-16 conversation that until now lived only in a chat transcript. It is a design record, not a description of running code: none of the federation described here is implemented (§1.4). Corrected 2026-11-01: the portal-to-master edge and the rung are built; §8 records what shipped.

Companions · 2026-08-16-marketplace-identity-and-install.md: the adjacent subject (who buys, who installs, how a console click becomes an install). This document is the other half: who administers a registered cluster, and how portal accounts relate to that cluster’s Keycloak. Ruling 1 below closes that document’s open question Q1. · ../proposals/2026-08-14-portal-architecture.md · ../proposals/2026-08-14-marketplace-architecture.md · 2026-08-16-marketplace-entitlement-and-licensing.md extends Ruling 1 below with the spending-limit mechanics (recurring vs transaction spend, atomicity, request expiry) and records the licensing substrate a paid install actually reuses.

A cluster’s master realm may federate the portal as an OIDC identity provider; authorized portal users sign in and Keycloak JIT-creates a linked shadow account. The portal never creates users in a customer’s Keycloak. That choice is what makes the compliance seal real: because we hold no admin credential on the customer’s Keycloak, sealing is one IdP entry the customer deletes on their own server, and we structurally cannot put it back. A compliance control the restricted party can flip is theatre; this one is not. App installs and purchase approval survive the seal, because neither ever ran on a portal human identity.


1. Ground truth: verified by content, 2026-08-16

Section titled “1. Ground truth: verified by content, 2026-08-16”

Everything below was read, not remembered. Four corrections are marked ★.

1.1 master is SHC’s own realm and its own tenant: confirmed

Section titled “1.1 master is SHC’s own realm and its own tenant: confirmed”

ce/modules/tenant/master_reserved.go: platform stacks (postgres, keycloak, traefik, openobserve) deploy at tenant=master, SHC’s own operators authenticate against the master Keycloak realm, and the name is unconditionally reserved from tenant create, checked before the edition gate, before the tombstone gate, and out of reach of the Internal option that used to bypass every name rule (ReservedSystemTenant, SystemTenantName = "master"). Scope is honest in the file: it stops a tenant row named master through every create surface, not a root operator writing the row by hand.

1.2 One system Keycloak, one realm per tenant: confirmed

Section titled “1.2 One system Keycloak, one realm per tenant: confirmed”

docs/architecture/access-control.md: a single Keycloak for the estate; one realm per tenant, named after the tenant; no default main realm; a bearer-only shc-access client provisioned in every realm carrying the tenant:* / stack:* role grammar; decisions enforced at the edge by Traefik forward-auth against /api/auth/forward-auth. Users belong to exactly one realm.

★ Correction (path). The file cited in the brief (website/src/content/docs/architecture/access-control.md) is a generated mirror. website/.gitignore reads “generated by scripts/sync-docs.mjs from ../docs (do not commit)” and src/content/docs/ is ignored. The tracked source is docs/architecture/access-control.md; an edit to the website copy is discarded on the next sync.

★ Correction (terminology). That page’s table says the Keycloak lives “in the system tenant”, while the code names it master (modules/tenant/master_reserved.go:47, modules/health/reconcile/types.go:47, modules/capabilities/service.go:11). The page’s own cross-tenant section writes “the master (system) tenant”, so they are the same thing, but system is separately a reserved tenant name in the same list, so the short spelling is drift worth fixing in that page rather than propagating.

1.3 Inbound realm sync: add-only, fail-closed, master excluded: confirmed

Section titled “1.3 Inbound realm sync: add-only, fail-closed, master excluded: confirmed”

ce/modules/health/reconcile/ (actions.go:syncInboundRealms, types.go): a realm an operator made by hand becomes an SHC tenant. It is ADD ONLY, and the file states why as a hard rule, not a scope cut: “shc tenant rm issues an unconditional realm DELETE, so any ‘realm vanished → remove the tenant’ direction would let a single flaky list destroy an operator’s stacks. A realm’s ABSENCE is never a signal here.” It excludes master deliberately (keycloakTenantEligible(name, masterRealm)), skips Keycloak-disabled realms, and skips names tenant validation would reject.

VdeploymentRealmLister exists purely to keep adoption off realms SHC created as keycloak/realm vdeployments, realms whose entire purpose is to exist without being a tenant. Adopting one provisions it as a tenant realm and injects a wildcard-redirect public OIDC client: “That is destruction of intent, and it is unrecoverable by re-running anything.” A nil lister, or a lister that errors, disables inbound adoption entirely rather than adopting without the exclusion set; “a delayed adoption is invisible and self-healing on the next pass, a wrong adoption is not.”

1.4 Portal → cluster IdP federation is not implemented

Section titled “1.4 Portal → cluster IdP federation is not implemented”

shc/modules/portal is the ruled skeleton, feature-flagged off (portal.enabled): the shc portal register / deregister verbs refuse X503145PTLNYI past the flag, Agent.Run refuses rather than pretending to connect, and doc.go lists “the master-realm federation edge lifecycle” under deliberately not here. The Frappe side (frappe/apps/portal) has Cluster / Registration Code / Support Grant DocTypes and a phase-1 bench API, but nothing that touches a customer realm.

★ Correction (the grep). The brief reports ~24 identity-provider / identityProvider hits across ce+shc, all incidental. Measured today, excluding .git: 15 in ce (genuinely incidental: test helper names, NodeIDProvider-style words, comments) and 89 in shc, which are not all incidental. Three real clusters:

  • keycloak/spi/.../events/FederationGuard.java: a shipped Keycloak SPI that watches admin events and acts on IDENTITY_PROVIDER CREATE, disabling (or removing) external IdPs when the sso entitlement is refused. Post-hoc by necessity (Keycloak has no supported pre-commit admin-API interceptor), fail-open, and OFF by default by owner ruling.
  • keycloak/themes/shc/admin/: an admin-console theme that hides the Identity Providers and User Federation panels. Explicitly “COSMETIC ONLY … NOT a security boundary”; opt-in via SHC_KC_ADMIN_THEME, empty by default.
  • apps/flagship/mailcow/oidc.plug.yaml (+ the mailbox reconciler): a real, large IdP integration, but the opposite direction: it configures mailcow to use SHC’s Keycloak, not a realm to trust an external issuer.

The brief’s conclusion stands: nothing anywhere provisions an IdP entry into a realm; no identity-provider/instances create exists outside a CSS comment. But the estate is not a blank slate, and two of those three pieces constrain the design (§3, §4).

1.5 The install channel carries no human: confirmed, and load-bearing

Section titled “1.5 The install channel carries no human: confirmed, and load-bearing”

modules/portal/wire/wire.go: the down direction is exactly two directive kinds (install_dispatch, catalog_query); InstallDispatch is {app, version}; Directive.ID correlates a directive with its answer. There is no portal-user field, no requester, and no correlation to a cluster-minted pending request; the sibling document’s §6 “the daemon is the final authority” is ruled and owed, not built. What is already true is the part §4 leans on: the machine channel never carried a portal human identity, so there is none to lose when human access is sealed.


2. RULING 1: purchasing authority is request-and-approve (ruled)

Section titled “2. RULING 1: purchasing authority is request-and-approve (ruled)”

“if you try to purchase an app that costs money, it creates a request. It has to be approved. That’s probably my preferred one, but the other option is the admin has to preapprove things.”

RULED: request-and-approve is the default. This closes Q1 of 2026-08-16-marketplace-identity-and-install.md §10, candidate (2) in that list.

BUILT 2026-08-16: 2026-08-16-install-request-state-machine.md. The state machine, its four policies and its expiry are in frappe/apps/portal/portal/install_request.py; the §2.1 routing below is implemented as an opaque requester handle plus a daemon-delivered outcome queue. §1.5’s missing correlation now exists on the wire (InstallDispatch.RequestID) but is carried, not honoured; the daemon consumes nothing yet, so the belt-and-braces property stays owed.

The reasoning, recorded so it is not re-derived. Default-deny with an escape hatch beats default-allow with a fence. And the request is not merely a gate: it carries the context (who asked, which app, which cluster) that turns approval into a real decision instead of a rubber stamp. An allowlist approved months ago in the abstract cannot do that.

Pre-approval is NOT the competing option. Stated explicitly so a reviewer does not re-litigate this as either/or: pre-approval is an optimization layered on top of the request path: a spending limit, or an allowlist of pre-approved apps, below which requests auto-approve. Both mechanisms exist; the request is the substrate, and the auto-approval is a policy that short-circuits it. Removing the request path to “just do pre-approval” removes the audit record and the escape hatch at once.

2.1 Routing: it crosses two populations (ruled, and the reason it needs stating)

Section titled “2.1 Routing: it crosses two populations (ruled, and the reason it needs stating)”

Per the sibling doc §1, purchases are owned by central accounts and installs are performed by cluster tenant users. A purchase request is the one flow that touches both:

requesterapprover
whoa tenant realm usera portal account, the registrant / billing contact
account with usnonethe one registration bound (Cluster.account_owner)
notified bythe daemon (the tenant realm holds their email)the portal (it holds theirs)

So the request travels up from the daemon to the portal, and the two notifications go over different channels. Neither side has to enumerate the other’s users: the portal never learns the customer’s employee roster, and the cluster never learns our account list. That is the same boundary §3 defends, arriving from the other direction.


3. RULING 2: multiple portal users per cluster, via federation, never push provisioning (ruled)

Section titled “3. RULING 2: multiple portal users per cluster, via federation, never push provisioning (ruled)”

“can you have multiple portal users that have access to a cluster? Do they just get a master identity per user? How does the portal manage all of the accounts in the master realms of clusters registered with it? It should have the ability to create users in the master realm. Right?”

RULED: yes to multiple portal users; NO to the portal creating users.

The cluster’s master realm configures the portal as an OIDC identity provider. An authorized portal user signs in, and Keycloak JIT-creates a linked shadow account on first broker login. Authorization (which portal accounts may reach which cluster, in which role) lives in the portal, rides in the token as a claim, and is mapped onto master-realm roles by an IdP mapper. The cluster stores no portal roster; it trusts an issuer and reads a claim.

This extends the portal proposal’s ruled federation carve-out (§2: “you can login to your cluster to your master keycloak realm using your portal username. but all users on your system would be in your keycloak”) from one user to many, without changing its shape.

Four reasons. The fourth is the one that matters most.

(a) Credentials we would otherwise have to hold forever. Push provisioning requires the portal to hold admin credentials on every customer Keycloak, permanently, for every registered cluster. Federation needs only a public key and a discovery document. One design makes our portal database a master key to the fleet; the other makes it a directory.

(b) Revocation. Federated: one change in the portal, and the next token fails. Pushed: reach into N clusters and delete N accounts, and every unreachable cluster keeps a live account for as long as it stays unreachable. Revocation that depends on reachability is not revocation.

(c) Reachability. Clusters go behind NAT, go offline, go dark; the portal channel is agent-initiated outbound precisely because of this (portal proposal §4). Push breaks at grant time, when nobody is watching. Federation resolves at login time, when the user is right there and a failure is legible.

(d) It matches this repo’s existing instinct about writing into an operator’s auth domain. The inbound realm sync goes to real lengths to avoid reshaping a realm an operator made: a whole exclusion lister, fail-closed on a nil or erroring registry, because adopting one realm injects an OIDC client and “that is destruction of intent, and it is unrecoverable by re-running anything” (§1.3). The portal minting users into a customer’s master realm is that same act at a larger scale: writing our shape into an auth domain somebody else owns, across every cluster at once. We already decided we do not do this when the blast radius is one realm on one estate.

3.1 What this costs the seat gate: nothing (verified)

Section titled “3.1 What this costs the seat gate: nothing (verified)”

Shadow accounts land in master, and keycloak/spi/.../seats/SeatGate.java compiles master into EXEMPT_REALMS: “Capping it would turn a seat limit into an estate-wide admin lockout.” Separately, ShcDatastoreProviderFactory.java records that IdP first-broker-login user creation is uncapped (IdpCreateUserIfUniqueAuthenticator, no user profile built), and deliberately so: “refusing it turns a seat cap into a LOGIN failure for a user whose IdP already authenticated them.” So JIT shadow accounts neither consume seats nor get refused at login. The flip side is that nothing counts them either, which is exactly the open edge in §5.

3.2 A local break-glass admin stays necessary, and it is the customer’s

Section titled “3.2 A local break-glass admin stays necessary, and it is the customer’s”

Federation down must not mean nobody can log in. The master realm keeps at least one local administrator, and it is the customer’s, not ours. The machinery already exists: ce/modules/auth/keycloak_permanent_admin.go converts Keycloak’s temporary bootstrap admin into a permanent account under the canonical vault-managed username, resumable from a crash at any point. Ownership of that credential is the customer’s escrow problem, and under §4 L2 it is the only way in.


4. RULING 3: the compliance seal, and the property that makes it real

Section titled “4. RULING 3: the compliance seal, and the property that makes it real”

“for compliance, you can disable the ability for portal to be able to manage users on the master realm, in which case when you register, it’s just the user that registers the cluster that is linked… when that’s disabled it actually disables sign in to the cluster from the portal. Portal access to the cluster is completely blocked in that case. Except for, of course, installing apps. They can still install an app.”

4.1 Lead with this: the seal is enforced at the cluster

Section titled “4.1 Lead with this: the seal is enforced at the cluster”

A compliance control the restricted party can flip is theatre. If sealing were a portal-side policy flag, the customer’s assurance would be our promise not to un-flip it, and their auditor would be reading our documentation instead of their configuration.

It is not a flag. Because we chose federation over push provisioning (§3), the portal structurally cannot re-establish access. Provisioning an IdP entry into a realm requires admin credentials on that Keycloak, which under this design we never hold. Sealing is the customer deleting one IdP entry on their own Keycloak, and they can do it without asking us, without a release, and without our cooperation.

Note plainly what this means about the alternative: under a push-provisioning design this mode could only ever have been a promise. A portal holding admin credentials can always re-create the account it deleted. Ruling 2 is not merely tidier; it is the precondition for Ruling 3 being a control at all.

The owner described two distinct states. They are recorded here as a ladder of three, and naming them separately is the point: an on/off switch would conflate a support-scope choice with a hard boundary, and a customer who wanted the first would be sold the second.

rungportal IdP on masterwho is linkedportal sign-in to the cluster
L0 FEDERATED (default)presentany authorized portal account; shadow accounts JIT-createdyes
L1 REGISTRANT ONLYpresentexactly one, the account that registered the clusteryes, for that one account
L2 SEALEDabsentnoneno; master-realm admins are local accounts the customer manages

L1 is a scope decision: no portal-driven user management, one link, and the link that survives is the one registration already binds (Cluster.account_owner). L2 is a boundary decision: no portal identity is accepted at the cluster at all.

4.3 What survives L2, and why each is evidence the boundary is in the right place

Section titled “4.3 What survives L2, and why each is evidence the boundary is in the right place”

App installs survive. They never used a portal human identity. Authority is the cluster registration credential (issued at registration, signed over the cluster id (sibling doc §5)), and the daemon is the final authority: it honours a dispatch only if it matches a pending request it minted (sibling §6; ruled, not yet built; §1.5). The v1 wire carries {app, version} and no principal at all. Sealing human access does not touch the machine channel, because the machine channel was never wearing a human’s face.

Purchase approval survives. Ruling 1’s approver acts in the portal, on a billing relationship, and the resulting entitlement flows to the cluster as a Keygen tier binding on the cluster’s domain. Purchasing authority was never cluster access. So Rulings 1 and 3 compose with no special-casing; a sealed cluster can still have apps bought for it. That is not obvious, and it is a genuine confirmation that the trust boundary was drawn in the right place: the things that survive are exactly the things that never crossed it.

4.4 What L2 costs, stated plainly, because it is the trade

Section titled “4.4 What L2 costs, stated plainly, because it is the trade”
  • We cannot get in to help. Support access is gone. Break-glass is the customer’s own escrowed local admin (§3.2), and if they lose it, the answer is a database-level recovery on their side, not a call to us. Support bundles are a separate, customer-granted channel (portal proposal §5) and are not a way back in to identity.
  • The install audit trail thins. The sibling doc’s Q4 recommendation is to execute a portal-dispatched install as the registration principal while recording “installed via portal by <portal account>”. Under L2 the portal-human half of that record has no meaning, leaving the registration principal plus whatever tenant-user claim the daemon itself recorded. Note that today neither exists: sibling §9 verified that ce’s deployment rows carry no installed_by-shaped column at all, so L2 thins a record that still has to be built. Corrected 2026-08-18: the tenant-user claim now EXISTS; ce!114 landed deployment.installed_by, and a realm user’s install records user:<sub>@<realm>. L2 therefore thins a record that is really there, which is a sharper cost than the one this paragraph originally described. The portal-human half still does not exist, for a reason unrelated to L2: the dispatch wire carries no account (sibling §9.2).

The customer’s seal action is “delete the IdP entry in your own Keycloak”, and keycloak/themes/shc/admin/ hides the Identity Providers panel from the admin console. It is cosmetic (kcadm and the admin REST API reach the same endpoint), it is opt-in (SHC_KC_ADMIN_THEME, empty by default), and its own header says it “must never be described as” a boundary. But if that theme is ever switched on by default, we would be hiding the one control this ruling asks the customer to operate. Either the theme keeps the panel visible on master, or L2’s documented procedure is a kcadm command.


5. ONE OPEN EDGE: orphaned shadow accounts (recommendation, NOT a ruling)

Section titled “5. ONE OPEN EDGE: orphaned shadow accounts (recommendation, NOT a ruling)”

Sealing a cluster that was previously L0 leaves orphaned shadow accounts in the master realm: JIT-created by first-broker-login, now credential-less (their only credential was the federated issuer, which is gone), still present and still holding whatever master-realm roles the IdP mapper granted them. Leaving them is a stale-access hazard; deleting them is destructive; they may have been granted local roles, they appear in audit history, and a delete is unrecoverable by re-running anything.

RECOMMENDATION: disable-and-report, never delete. Two precedents in this repo, both chosen for exactly this asymmetry:

  1. The inbound realm sync is add-only because “a shc tenant rm issues an unconditional realm DELETE, so a realm-vanished-drop-the-tenant direction would let one failed list destroy operator data” (§1.3). Same shape (an absence used as a signal to destroy), same answer.
  2. FederationGuard disables by default and removes only on an explicit opt-in (federationGuardRemoves(); SHC_KC_FEDERATION_GUARD_ACTION defaults to disable), on the same class of object, in the same realm.

Also unresolved, and flagged rather than answered:

  • Is L2 reversible by the customer alone? Mechanically yes; re-adding the IdP entry is theirs to do, on their Keycloak, and we cannot stop it any more than we can perform it. Whether it should be reversible without a compliance-visible event (a re-registration, a countersignature, an audit record on both sides) is a policy question nobody has ruled on.
  • Should the portal SHOW a cluster as sealed rather than as unreachable? From the portal side the two look identical: no sign-in, no identity, and possibly a live heartbeat. Conflating them will generate support tickets; we will chase an outage that is a deliberate configuration. A sealed cluster can still heartbeat (the machine channel survives, §4.3), so the daemon can report the state; nothing says it should be believed as a compliance attestation, only used as a display hint.

  1. Amend the sibling doc’s Q1 to point here once 2026-08-16-marketplace-identity-and-install.md lands on main. ✅ DONE 2026-08-16; that document’s §10 Q1 is now marked CLOSED and points at Ruling 1 here, including the pre-approval is a layer, not an alternative framing. Its Q2 and Q3 were closed in the same pass by a later owner ruling (free installs do require a portal account, so there is no per-cluster storefront); only its Q4 remains open.
  2. Master-realm federation edge lifecycle in shc/modules/portal, established at registration, removed at deregistration (portal proposal §2), plus the L0/L1/L2 rung as a cluster-side setting. BUILT 2026-11-01 (FZ-8761), §8.
  3. The FederationGuard master-realm exemption named in portal proposal §2, still design; the guard has no exemption of any kind today (§1.4). BUILT: FederationGuard.inspect consults isVendorPortalIdPInMaster before acting, pinned by FederationCarveOutTest, and the IdP is created by SHC’s admin service client, which the guard’s second exemption also covers.
  4. Request-and-approve: the purchase request object, the two notification paths (§2.1), and the pre-approval optimization (limit + allowlist) on top.
  5. The installed_by-shaped audit column the sibling doc §9 records as owed; §4.4 is its consumer. ✅ DONE 2026-08-18; landed as ce!114: deployment.installed_by and vdeployment.installed_by, carrying a closed <kind>:<id> actor grammar (user:<sub>@<realm>, local:, portal:[<account>]), nullable, with NULL meaning “the row predates the column” and never “unknown actor”. The sibling doc’s §9.1 records the whole shape. One half remains and it is named there, not here: the dispatch wire carries no portal account, so a portal-dispatched install records the bare portal: (sibling §9.2).
  6. Fix the system/master spelling in docs/architecture/access-control.md (§1.2).

7. First user into the first app (ruled 2026-10-31): seeded, not brokered

Section titled “7. First user into the first app (ruled 2026-10-31): seeded, not brokered”

Status: RULED. Clay picked seeding on the compare card (rv_f8c134b16c42fc8d, FZ-8732) after three independent refuters rejected every brokering shape. Built in 0.1.48 (ce and shc lanes lane/FZ-8732-seed-first-user).

Ruling 2 gets the registrant into the console: the portal account is JIT-shadowed into master. It does not get them into Nextcloud. Apps sign in through their own tenant’s realm (the trusted-realms ruling, FZ-8104, and 2026-08-06-rbac-role-matrix.md §2 R-3 as amended 2026-10-29), so the first app on a portal-born cluster lives in the default tenant’s realm, and that realm held no user for the person. The scenario ended at a login page with nobody who could log in.

The cluster seeds the registrant into the default tenant realm at registration, from the facts the enrolment answer carried. The portal’s enroll reply names the account that minted the code (email, names, the portal’s OIDC subject); the daemon stores them on the registration row and creates that person in the default realm with a verified email, tenant:manage, no password and UPDATE_PASSWORD required. The same rule runs for shc tenant add: the realm’s first user is the person asking (the signed-in account when there is one, else the registrant on a registered estate); --admin-user or --admin-password keep the generated admin whose password the vault holds. A cluster nobody is signed in to and nobody registered still gets the generic admin.

The person then sets one password: the console’s People screen offers the signed-in registrant “Set your app password” (the existing reset-password path, not temporary), and shc user reset-password is the CLI way. A mailed execute-actions link waits on outgoing mail (FZ-8491).

Two defaults ride along. portal.store_grants left empty on a registered cluster means default/<the estate's default environment>, so the storefront’s Install button has a target without an operator typing one; an explicit row replaces it. The portal’s terraform runner sets bootstrap.accept_ee_trial = true on every cluster it provisions, so the first dispatch finds the Hobby trial already accepted. A dispatched install records installed_by = portal:<actor>@<org>, which closes §6 item 5’s open half.

  • Broker master into the tenant realm as an identity provider. Every master identity is platform root (gatedecide/privilege.go), and master is reserved from app installs (modules/tenant/master_reserved.go). FZ-8104 removed exactly this edge; putting it back makes the registrant platform root inside every app and reopens the sso gate, the FederationGuard carve-out and the L2 seal that §4 made real.
  • Broker the portal into the tenant realm. The same objection with a longer reach: it puts a vendor IdP entry in a customer realm, which §3(d) refused for one realm on one estate, and it turns L2 sealing into two deletions the customer has to know about.
  • Have the portal create the user. Ruling 2 stands: the portal never creates users in a customer’s Keycloak. The cluster creates them, from facts the registration edge carried, and the portal holds no credential for it.
  • Seed per install dispatch. A dispatch that names tenant admins lets a compromised portal pick admins on every cluster it reaches, and installs survive the L2 seal precisely because the machine channel never wore a human’s face. Seeding happens at registration or tenant create only.

A roletest portal account registers a test cluster, dispatches nextcloud from the storefront, sets one password in the console and signs into Nextcloud; frames on FZ-8732. Doctor and a realm read-back show no identity provider in the tenant realm. This runs after 0.1.48 rolls.

8. The edge as built (FZ-8761, 2026-11-01)

Section titled “8. The edge as built (FZ-8761, 2026-11-01)”

The vendor IdP is the portal’s own Keycloak realm (keycloak.realm on the marketplace deploy: cloud, cloud-dev on dev). The bench declares it in site config as portal_idp_issuer (keycloak.baseUrl + /realms/ + the realm) and portal_idp_client_id (keycloak.clusterClientId, default shc-cluster).

One public client per cluster, minted by the portal in its own realm. At enrolment the daemon sends its broker endpoint (<system keycloak>/realms/master/broker/shc-portal/endpoint) as idp_redirect_uri. The portal accepts it only on the estate’s domain, mints shc-cluster-<cluster uid>: public, PKCE S256 required, that one exact redirect, consent required, an audience mapper naming itself. It answers idp_issuer, idp_client_id and idp_userinfo_url. Deregistration deletes the client. The cluster holds no secret, only a discovery document, which is §3’s property (a). A shared client was refused: it needs either a wildcard redirect, which hands any website a signed-in portal user’s identity, or a place in frappe_keycloak’s trusted clients, which would make every token a customer’s Keycloak receives a key to the whole portal API.

Authorization rides as a claim, read at login. The master IdP points its userinfo at the bench (portal.federation.userinfo). The bench takes the bearer before frappe_keycloak sees it, checks it at the issuer, and requires its azp and aud to be that cluster’s client, so a token minted for one cluster never reads another’s grants. It answers shc_grants, the caller’s grants on that cluster: registrant (the account that registered it) and the caller’s role in the cluster’s org (owner, admin, member, viewer). No registrant, owner or admin grant is a 403, so no shadow account is created for someone the portal does not authorize.

The mappers, on master’s shc-portal IdP (sync FORCE, so every login re-reads the claim and revocation is the next login):

shc_grants valuemaster role (shc-access)
registrant, owner, adminplatform:manage
membernothing
viewernothing

The shadow account is named shc-portal.<preferred_username> so it can never collide with a local master account. The master realm’s own administrator stays the customer’s break-glass (§3.2): no shc_grants value maps to Keycloak’s admin realm role or to that account, so federation never reaches it, and L2 leaves it the only way in.

The rung is portal.federation, a cluster config key: federated (L0, the default), registrant (L1: registrant maps to platform:manage, the member and viewer mappers match nothing so a role L0 granted is revoked at the next login, and the userinfo URL asks the portal to refuse everyone else) or sealed (L2: the IdP is deleted from master; registration, the channel and store installs are untouched). A change converges master on the leader at once. Under sealed the daemon also asks the portal for no client at registration.

Open console in the portal links to https://console.<domain>/?realm=master&idp=shc-portal. The console starts the master sign-in with kc_idp_hint=shc-portal once per tab, and Keycloak’s existing session in the portal realm completes it with no second login. The first visit to each cluster shows Keycloak’s consent screen once.

Measured on Keycloak 26.7.0 (the shipped base image, 2026-11-01): the IdP takes pkceEnabled, pkceMethod: S256, clientAuthMethod: client_secret_post with no secret against the public client, and a custom userInfoUrl; the advanced claim-to-role mappers read shc_grants from that userinfo; the access token carries azp and aud naming the cluster’s client; a 403 from userinfo ends the login with no shadow account; a grant change moves the master role at the next login; L1 refuses a non-registrant and revokes what L0 granted; L2 leaves master’s own login page.

Owed live proof. On dev: a roletest portal account registers a test cluster, presses Open console, lands signed in as shc-portal.<name> with platform:manage; a member or viewer is refused; an outsider is refused; portal.federation=sealed removes the IdP and a store install still lands. Frames on FZ-8761.

The federation carve-out (portal §2), extended from one user to many, unchanged in direction. One-way federation (sibling §3), untouched; nothing here points an arrow from a customer realm into our store. master reserved and never a customer tenant (master_reserved.go); the shadow accounts live in it, no tenant row is ever created for it. Add-only inbound sync, cited as precedent, not modified. Placement: everything cluster-side here is shc-proprietary; ce carries none of it (portal §2, Placement).