Skip to content

Multi-tenant Phase C — SCIM 2.0 provisioning endpoints #96

Closed

Description

@thomas-stegemann

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 in IBowireUserStore.
  • GET /scim/v2/Users — list with filter (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 after Bowire: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 Users list at scale — asserted by ScimScaleTests at 10 000 users. A userName index replaced the walk that made provisioning quadratic, and paging now happens before locations are stamped.
  • Soft-delete + purge window honored, with Bowire:Scim:PurgeAfter configurable.
  • 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.
  • IBowireUserStore provisioning 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 via scim/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 by Provisioning_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)

Activity

  1. moved this to Backlog in Bowireon Jun 15, 2026
  2. thomas-stegemann commented on Aug 29, 2026

    @thomas-stegemann
    MemberAuthor

    Shipped in 0e86483 — Kuestenlogik.Bowire.Scim

    A 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/v2 mounts 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 under users/.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

    • PATCH speaks both dialects. Okta sends a lower-case op with an explicit path; 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.
    • An unmodelled attribute is kept, not dropped. A connector that reads back a resource missing what it just wrote concludes the write failed and retries forever, so anything outside the modelled set round-trips through the extension bag.
    • A filter outside the subset is refused. eq, pr, and, or are implemented, with and binding tighter. Anything else answers 400 / invalidFilter rather than being half-evaluated — a parser that ignores the part it did not understand answers a different question and the caller cannot tell.
    • Provisioning does not create the slot. See the deviation below; this one changes the shape of the feature.

    Also: scim is 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 a BOWIRE_INSTANCE name for the same reason users is.

    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 userName and an externalId. 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 against externalId then userName. Deprovisioning then knows exactly whose state to archive. This has a consequence operators must know, and it is documented: Bowire:MultiTenant:SubjectClaim has to produce a value that equals the record's externalId or userName (for Entra ID that means oid).

    2. Auth failures return a SCIM error, not problem+json.
    The issue asks for problem+json with urn:bowire:scim:auth-required. RFC 7644 §3.12 defines the error body a SCIM client parses, and connectors read scimType from it; a problem+json body would be an unparseable response to the only clients this endpoint has. So 401 carries application/scim+json with scimType: invalidCredentials. The urn: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-suite does not exist — the URL 404s. The real candidates are scim2/test-suite (Go, 4 stars) and wso2-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

    • All endpoints implemented + documented — the doc landed at docs/setup/scim.md rather than docs/multi-tenant/scim.md, next to the multi-user page it continues.
    • Bearer-token auth on every SCIM endpoint, including the discovery documents — see deviation 2 for the body shape.
    • Pagination + filtering at scale. Both work and are tested; the "10k users in ≤ 500 ms with a warm index" figure is not measured. The store holds its lookups in memory and writes one file per record, which is the shape that makes it achievable, but I am not ticking a number I have not put a stopwatch on.
    • Soft-delete + purge window honoured, Bowire:Scim:PurgeAfter configurable, 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).
    • Okta + Entra round-trips green in a test suite. Not achievable from CI: it needs real tenants and their secrets. What is green is the request shapes both connectors send, replayed against the real endpoints — including the application/scim+json media 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.
    • IBowireUserStore side-effect on create — deliberately not implemented; see deviation 1. Deactivate archives, purge deletes, and every decision is appended to scim/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:

    1. A live provisioning round-trip against an Okta or Entra tenant. If it surfaces a shape mismatch, that is a small fix in ScimPatch or the filter — the tests make it cheap to pin whatever comes back.
    2. A decision on the throughput criterion — whether to measure it, or drop the specific number.
  3. moved this from Backlog to In review in Bowireon Aug 29, 2026
  4. thomas-stegemann commented on Sep 1, 2026

    @thomas-stegemann
    MemberAuthor

    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 userName taken?" 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-insensitive userName → id index, 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. FindByUserName and the userName fallback in FindBySubject read 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 PUT frees the old name, a rename through PATCH frees 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 by externalId. 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

    IBowireUserStore provisioning 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 to scim/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.

  5. thomas-stegemann commented on Sep 1, 2026

    @thomas-stegemann
    MemberAuthor

    Every box, and what each one cost

    Closing. Green on a52f0b4.

    The surface has been in since the package landed: /scim/v2/Users and /Groups with discovery, bearer auth, eq/pr/and/or filtering, 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. A userName index 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.

  6. moved this from In review to Done in Bowireon Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    • Status
      Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions