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.
The model in one paragraph
Section titled “The model in one paragraph”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 onIDENTITY_PROVIDERCREATE, disabling (or removing) external IdPs when thessoentitlement 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 viaSHC_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:
| requester | approver | |
|---|---|---|
| who | a tenant realm user | a portal account, the registrant / billing contact |
| account with us | none | the one registration bound (Cluster.account_owner) |
| notified by | the 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.
4.2 Three rungs, named separately (ruled)
Section titled “4.2 Three rungs, named separately (ruled)”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.
| rung | portal IdP on master | who is linked | portal sign-in to the cluster |
|---|---|---|---|
| L0 FEDERATED (default) | present | any authorized portal account; shadow accounts JIT-created | yes |
| L1 REGISTRANT ONLY | present | exactly one, the account that registered the cluster | yes, for that one account |
| L2 SEALED | absent | none | no; 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 thatCorrected 2026-08-18: the tenant-user claim now EXISTS; ce!114 landedce’s deployment rows carry noinstalled_by-shaped column at all, so L2 thins a record that still has to be built.deployment.installed_by, and a realm user’s install recordsuser:<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).
4.5 One friction to fix before L2 ships
Section titled “4.5 One friction to fix before L2 ships”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:
- The inbound realm sync is add-only because “a
shc tenant rmissues 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. FederationGuarddisables by default and removes only on an explicit opt-in (federationGuardRemoves();SHC_KC_FEDERATION_GUARD_ACTIONdefaults todisable), 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.
6. Owed work
Section titled “6. Owed work”Amend the sibling doc’s Q1 to point here once✅ 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.2026-08-16-marketplace-identity-and-install.mdlands onmain.Master-realm federation edge lifecycle inBUILT 2026-11-01 (FZ-8761), §8.shc/modules/portal, established at registration, removed at deregistration (portal proposal §2), plus the L0/L1/L2 rung as a cluster-side setting.TheBUILT:FederationGuardmaster-realm exemption named in portal proposal §2, still design; the guard has no exemption of any kind today (§1.4).FederationGuard.inspectconsultsisVendorPortalIdPInMasterbefore acting, pinned byFederationCarveOutTest, and the IdP is created by SHC’s admin service client, which the guard’s second exemption also covers.- Request-and-approve: the purchase request object, the two notification paths (§2.1), and the pre-approval optimization (limit + allowlist) on top.
The✅ DONE 2026-08-18; landed as ce!114:installed_by-shaped audit column the sibling doc §9 records as owed; §4.4 is its consumer.deployment.installed_byandvdeployment.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 bareportal:(sibling §9.2).- Fix the
system/masterspelling indocs/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).
7.1 The gap
Section titled “7.1 The gap”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.
7.2 The ruling
Section titled “7.2 The ruling”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.
7.3 The shapes refused, and why
Section titled “7.3 The shapes refused, and why”- Broker
masterinto 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.
7.4 Owed live proof
Section titled “7.4 Owed live proof”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 value | master role (shc-access) |
|---|---|
registrant, owner, admin | platform:manage |
member | nothing |
viewer | nothing |
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.
Bindings honoured
Section titled “Bindings honoured”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).