Skip to content

feat(auth): add SCIM 2.0 user provisioning - #456

Merged
vishr merged 2 commits into
mainfrom
feat/scim-provisioning
Nov 8, 2026
Merged

vishr merged 2 commits into
mainfrom
feat/scim-provisioning

Conversation

@vishr

@vishr vishr commented Nov 8, 2026

Copy link
Copy Markdown
Member

Closes #442

Nothing tells an instance that a person was removed: eligibility is checked at login only, so browser sessions and MCP tokens outlive the removal. An install also cannot have its first administrator created by automation. This adds SCIM 2.0 provisioning, authenticated by a new secret setting, FANOUT_SCIM_TOKEN (_FILE supported). It requires OIDC mode and at least 32 characters.

What changed

  • POST /scim/v2/Users creates an account with its role and links (configured issuer, externalId) in one transaction with the audit events.
  • GET /scim/v2/Users?filter= finds an account by externalId eq or userName eq. Any other filter returns invalidFilter. GET /scim/v2/Users/{id} reads one.
  • PATCH /scim/v2/Users/{id} changes active, the role, the email and displayName.
  • Responses and errors use application/scim+json and the RFC 7644 error format.
  • With a token set, no setup banner is printed, /api/auth/setup returns 410, and /api/auth/status reports setup_required: false.
  • Without a token the routes are not registered and SCIM paths are classified exactly as before.
  • Authentication docs and the generated configuration and route references are updated.

Behaviour changes outside SCIM

  • Every transition out of active now revokes the user's OAuth tokens and pending authorization codes, including suspension from the browser route. Before, the per-request status check stopped those tokens during suspension, but they worked again after reactivation.
  • Request logging moved from cmd/fanout to api.RequestLogger. It behaves the same except that /scim/v2 requests are logged without their query string, because a filter holds an email address or subject.

Decisions to review

  • A POST for a known identity changes nothing. It returns the current account with 200. A hosting control plane that retries a delayed create must not undo a later role change or removal, so changes go through PATCH.
  • Repeats write nothing. A PATCH to the current state makes no audit event and no revocation. The exception is repeating active: false on an account that still has live sessions, tokens or codes: those are removed and a session.revoked event is written.
  • Empty database. Provisioning runs in one BEGIN IMMEDIATE transaction and shares the empty-database check with setup. A non-administrator or a suspended administrator gets 409 rather than 403, so a provisioner can retry once the administrator exists. A concurrent administrator that loses the check is created normally.
  • roles is required on POST. A missing role returns 400 rather than falling back to a default.
  • userName is the email address. If emails is sent, its primary value must match.
  • An email held by an unlinked local account returns 409. Fanout does not link by email.
  • Token comparison hashes both sides with SHA-256 before the constant-time compare, so a length difference does not return early.
  • No library. The subset is four routes, one filter shape and a few patch paths. The Go SCIM libraries I know of model the whole protocol and would need adapting to Fanout's transactions, so this is hand-written. I did not run a registry comparison of them.

Not included

There is no PUT, no DELETE, no Groups, and no ServiceProviderConfig, Schemas or ResourceTypes discovery. A GET without a filter returns invalidFilter, and patch paths with a value filter are refused. Some standard clients need one or more of these (for example, a connection test that lists users without a filter). The issue did not ask for them. There is no rate limit on failed token attempts; the token is at least 32 characters.

Verification

Run on the pushed commit:

  • just check passes.
  • just test-race passes for the whole module.
  • The concurrency, SCIM and suspension tests pass 20 times under -race.
  • just e2e was not run.

Atomicity is tested with a SQLite trigger that fails the identity or audit insert inside the real transaction. Race tests use a file database, because the in-memory database has one connection and would hide races. I removed each guard in turn (the write lock, the last-administrator check, OAuth revocation, convergence, the MCP status check and the log redaction) and confirmed a test fails without it.

I did not test against a real identity provider or run the binary end to end. The tests go through HTTP handlers and a real database.

vishr added 2 commits November 8, 2026 11:25
Nothing tells an instance that a person was removed: eligibility is checked
at login only, so browser sessions and MCP tokens outlive the removal. An
install also cannot have its first administrator created by automation.

FANOUT_SCIM_TOKEN enables POST, GET and PATCH on the SCIM Users resource. The
account and its identity (configured issuer, externalId) are written in one
transaction, so a crash cannot leave an unlinked account for a later login
to claim by email. Requests are safe to repeat: a POST for a known identity
returns the account unchanged, and a PATCH that changes nothing writes
nothing.

Deactivation also revokes OAuth tokens. The per-request status check stops
them during suspension but would let them work again after reactivation.

With a token set there is no setup banner and the setup route returns 410.
Without one, SCIM paths are classified as before.

Closes #442
… out of logs

The request log recorded the full URI, so a SCIM filter put an email address
or subject in the logs. SCIM requests are now logged without their query.

Only SCIM deactivation revoked OAuth tokens, so suspending from the browser
route left tokens that worked again after reactivation. Every transition out
of active now revokes them. A repeated SCIM deactivation also removes any
session or credential still live on an already-suspended account.
@vishr
vishr added this pull request to the merge queue Nov 8, 2026
Merged via the queue into main with commit 7f7e9de Nov 8, 2026
31 checks passed
@vishr
vishr deleted the feat/scim-provisioning branch November 8, 2026 22:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SCIM 2.0 user provisioning

1 participant