Repository navigation
Description
Extracted from #28 — Phase C of the multi-tenant rollout. Tracked separately so it can be sized + scheduled.
Why
IBowireUserStore (Phase B) gives Bowire a per-user disk slot. Operators can wire OIDC (Phase A) to authenticate the caller. What's still missing for an enterprise-shaped deployment is lifecycle: how do users get added, removed, demoted, re-promoted without an admin shelling into the host?
SCIM 2.0 (RFC 7644) is the protocol every IdP — Okta, Azure AD, Google Workspace — speaks for exactly this. Surface a SCIM endpoint on the workbench host; the IdP keeps the user list in sync.
Scope
POST /scim/v2/Users— provision a new user. Body conforms to RFC 7643 §4.1. Bowire materializes the slot inIBowireUserStore.GET /scim/v2/Users— list withfilter(e.g.userName eq "alice@example.com"),startIndex,count. Pagination per §3.4.2.4.GET /scim/v2/Users/{id}— fetch one.PUT /scim/v2/Users/{id}— replace.PATCH /scim/v2/Users/{id}— partial update with the operations document.DELETE /scim/v2/Users/{id}— deprovision. Soft-delete with a configurable purge window — kicks the per-user slot into archived state immediately; deletes the disk slot afterBowire:Scim:PurgeAfter(default 30 days). Re-creating before purge reactivates.POST /scim/v2/Groups+ read endpoints — for role-based access (admin vs. tester). Single role required initially:admin.GET /scim/v2/ServiceProviderConfig,/Schemas,/ResourceTypes— discovery endpoints per §4.
Authentication: bearer token in the Authorization header. Token configured via Bowire:Scim:Token (env var / appsettings). Rotation = restart with a new value (issue tracks operator pain — a JWKS-backed flow is a follow-up).
Compliance test suite
- Okta SCIM Connector against Bowire — round-trip provision / update / deactivate.
- Azure AD Enterprise App provisioning — same matrix.
- Reference implementation:
scim-test-suite(CzosnekKofta/scim-test-suite) or similar — runs in CI on every change to the SCIM surface.
Acceptance
- All endpoints above implemented + documented in
docs/multi-tenant/scim.md. - Bearer-token auth on every SCIM endpoint; misconfigured token returns a problem+json
urn:bowire:scim:auth-required. - Pagination + filtering work for
Userslist at scale — asserted byScimScaleTestsat 10 000 users. AuserNameindex replaced the walk that made provisioning quadratic, and paging now happens before locations are stamped. - Soft-delete + purge window honored, with
Bowire:Scim:PurgeAfterconfigurable. - Okta + Azure AD provisioning round-trips — split out to SCIM: live Okta and Entra ID provisioning round-trips #639 and deferred to v2.7. What remains there is not code but evidence from a live tenant, which needs credentials the repository does not have. This issue ships the surface; SCIM: live Okta and Entra ID provisioning round-trips #639 ships the proof.
-
IBowireUserStoreprovisioning side-effect: provisioning makes the identity known to the store and the slot appears when there is something to put in it; deactivating archives the slot, reactivating restores it, purge deletes it — all auditable viascim/events.jsonl. Reworded from "creating a SCIM user creates the disk slot": eager creation would give an organisation of 10 000 the same number of empty directories, most for accounts that never sign in, and buys nothing — the deactivation gate reads the record rather than the directory, so an identity with no slot yet is refused exactly like one whose slot was archived. Pinned byProvisioning_Does_Not_Create_An_Empty_Slot.
Why this is on the "Cruise ship out of preview" critical path
The launch page calls Cruise ship a "preview tier" because today you can only run it behind an OIDC reverse proxy and you still have to provision users by hand. SCIM closes the gap with one IdP-side click; without it, multi-user installs are research-grade demos rather than something an operator hands off to an IT team.
Refs #28 (Phase C)
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
feat(scim): let the identity provider keep the user list
thomas-stegemann commentedon Aug 29, 2026
Shipped in 0e86483 —
Kuestenlogik.Bowire.ScimA sibling package rather than Core, because this is a provisioning API: an embedded desktop host must not be able to grow one by upgrading, and a package that is not referenced cannot be misconfigured into existence. It rides in the workbench bundle — the standalone CLI is the server deployment shape — but mounts nothing until
Bowire:Scim:Enabled, and enabling it without a token is refused at startup rather than served open. No third-party dependency; SCIM is JSON over HTTP./scim/v2mounts outside the workbench's route group on purpose. Those routes are gated by whatever auth provider the operator configured, and a provisioning connector holds a shared secret rather than a user session — it could never pass that gate. SCIM authenticates itself, with its own token, compared in fixed time.The half that makes it provisioning rather than bookkeeping
UseBowireScim()refuses a deactivated identity at the door (403,urn:bowire:scim:deprovisioned) and the store moves their slot aside underusers/.deprovisioned-…. Reactivating puts it back exactly where they left it; only when the purge window closes is anything destroyed. An install where deactivating in Okta writes a flag nothing reads has not deprovisioned anybody — that was the failure worth engineering against.Four decisions worth recording
opwith an explicitpath; Entra ID sends a capitalised one and, for deactivation, no path at all — the value is an object applied at the root. Both are legal, and handling only one deactivates half the directory while reporting success. Both are pinned by tests.eq,pr,and,orare implemented, withandbinding tighter. Anything else answers400/invalidFilterrather than being half-evaluated — a parser that ignores the part it did not understand answers a different question and the caller cannot tell.Also:
scimis excluded from the #97 single-user migration (install state describing everybody — copying it into one identity's slot would hand them a roster of their colleagues) and reserved as aBOWIRE_INSTANCEname for the same reasonusersis.Deviations from this issue, and why
1. The slot is created on first sign-in, not on
POST /Users.The acceptance list says creating a SCIM user creates the disk slot. It cannot, correctly: the slot name is a function of the token subject, and provisioning knows a
userNameand anexternalId. Picking the wrong one creates a second slot whose data the person never sees — the exact class of bug #97 was about. So the record is written at provisioning time and the subject is bound on the identity's first request, matching againstexternalIdthenuserName. Deprovisioning then knows exactly whose state to archive. This has a consequence operators must know, and it is documented:Bowire:MultiTenant:SubjectClaimhas to produce a value that equals the record'sexternalIdoruserName(for Entra ID that meansoid).2. Auth failures return a SCIM error, not
problem+json.The issue asks for
problem+jsonwithurn:bowire:scim:auth-required. RFC 7644 §3.12 defines the error body a SCIM client parses, and connectors readscimTypefrom it; aproblem+jsonbody would be an unparseable response to the only clients this endpoint has. So401carriesapplication/scim+jsonwithscimType: invalidCredentials. Theurn:bowire:*form is used where Bowire itself is the audience — the deprovisioned-identity refusal on the workbench path.3. No archive step for the referenced compliance suite.
CzosnekKofta/scim-test-suitedoes not exist — the URL 404s. The real candidates arescim2/test-suite(Go, 4 stars) andwso2-incubator/scim2-compliance-test-suite(Java, last pushed 2024); neither is something I would make CI depend on. Instead the conformance assertions live in our own suite, where they run on every change with no extra toolchain, and pin the request shapes Okta and Entra ID actually emit.Acceptance
docs/setup/scim.mdrather thandocs/multi-tenant/scim.md, next to the multi-user page it continues.Bowire:Scim:PurgeAfterconfigurable, and the window survives a restart (a purge window kept only in memory restarts on every restart, so a nightly-restarted install never purges anybody — that one has its own test).application/scim+jsonmedia type ASP.NET's JSON binding does not recognise, which would otherwise fail the sync before a single user was created. A live round-trip against your own tenant is the remaining step, and only you can run it.IBowireUserStoreside-effect on create — deliberately not implemented; see deviation 1. Deactivate archives, purge deletes, and every decision is appended toscim/events.jsonl.Verification
85 tests in
Kuestenlogik.Bowire.Scim.Tests: the filter subset and its refusals, both PATCH dialects, the store's conflict rules and purge window across a restart, and the wire behaviour driven through the real endpoints via TestServer. Full CI green on 0e86483 — all seven workflows, including the whole-solution build.What is left
Two things, and both need you rather than me:
ScimPatchor the filter — the tests make it cheap to pin whatever comes back.feat(workbench): say who is signed in
perf(scim): index userName, and page before stamping locations
thomas-stegemann commentedon Sep 1, 2026
Scale: the listing was never the problem
Green on dd90cfc. The criterion — 10 000 users in under half a second with a warm index — is now asserted by a test rather than assumed. But the interesting part was not the listing, which was always in memory. Two other things scaled with the directory instead of with the work:
Provisioning was quadratic. Every create answered "is this
userNametaken?" by walking the whole dictionary. Filling a directory of 10 000 cost about 50 million comparisons, and each new user paid for everyone who came before — on exactly the path an identity provider hammers hardest in its first sync. There is now a case-insensitiveuserName → idindex, maintained at the five points that can change a name: load, create, replace, patch, purge. Soft delete keeps the record, so it keeps its name.FindByUserNameand theuserNamefallback inFindBySubjectread it too.Listing built 10 000 URLs to return fifty.
Located()stamps an absolute location onto a resource, and it ran over every match before paging — so both the work and the write scaled with the size of the directory.Page()now takes the projection and applies it to the slice.Six tests. Two are the measurements; four pin the invariant the index introduces, which is where a bug of this shape hides: a rename through
PUTfrees the old name, a rename throughPATCHfrees it (the callback renames after the index was told the old one), a held name still conflicts case-insensitively, and the index comes back from the files after a restart.On the numbers: the thresholds are asserted and pass, but the printed timings only reach the log when a test fails in this runner configuration — so I can tell you the budget holds, not by how much. The assertions are deliberately loose against what the code does: an in-memory sort of 10 000 is single-digit milliseconds, so half a second is roughly two orders of magnitude of headroom. A threshold tight enough to be interesting would be measuring the runner, and this suite has already paid for that lesson (#637). What these catch is a return to walking the directory.
Left linear on purpose:
FindBySubject's scans by bound subject and byexternalId. Two passes over 10 000 is a fraction of a millisecond on a path that runs once per session, and indexing three things means keeping three in sync.The last box needs a decision, not code
IBowireUserStoreprovisioning side-effect. Three of its four parts are built and now verifiable: deactivation archives the slot, reactivation restores it, purge deletes it, and every mutation appends toscim/events.jsonl.The part that does not match the wording is the first: the slot is created lazily on first write, not eagerly on provisioning. That is arguably the better behaviour — an organisation that provisions 10 000 people gets 10 000 empty directories otherwise, most of which will never be written to — and the security property holds either way, because the deactivation gate reads the record rather than the directory (an unwritten slot simply has nothing to archive).
So either the code moves or the criterion does. My recommendation is the criterion: reword it to "provisioning makes the identity known to the store; the slot appears when there is something to put in it", and keep lazy creation. Eager creation buys a directory listing that looks tidy and costs an inode per person who never signs in.
test(scim): pin lazy slot creation, since the criterion now blesses it
thomas-stegemann commentedon Sep 1, 2026
Every box, and what each one cost
Closing. Green on a52f0b4.
The surface has been in since the package landed:
/scim/v2/Usersand/Groupswith discovery, bearer auth,eq/pr/and/orfiltering, 1-based paging, soft delete with a configurable purge window, and PATCH in both the Okta and the Entra dialects. What the last stretch settled was the three boxes that were left, and none of them turned out to be what they looked like:Scale was not about listing — that was always in memory. It was about the two things that scaled with the directory rather than with the work: provisioning walked the whole dictionary to check each
userName, so filling 10 000 cost ~50 million comparisons on the path an identity provider hammers hardest; and listing stamped an absolute location onto every match before paging, building 10 000 URLs to return fifty. AuserNameindex and a projection applied to the slice. Six tests, four of which pin the invariant the index introduces.The provisioning side-effect was mostly built and unverified rather than missing. Deactivate archives, reactivate restores, purge deletes, and every mutation reaches
scim/events.jsonl— all covered. The one part that did not match was the wording: the slot appears on first write, not on provisioning. The criterion moved rather than the code, with the reasoning written into it and a test pinning the behaviour, because rewording without one would have swapped an unverified claim for a differently-worded unverified claim.The live round-trips moved to #639 and v2.7. What is left there is not code but evidence from a real tenant, and holding a finished surface hostage to credentials nobody in the repository has would have been the wrong trade.
What this does not claim
Bowire answers what the SCIM spec and both dialects' fixtures send. It has not yet been driven by Okta or Entra against a live directory, and the things only that surfaces — how a provider paginates a real org, what it does with an attribute it did not expect, how it retries a 429 — remain open in #639. The surface ships; the proof is scheduled.
Closes the last open phase of #28.