SCIM outbound (provisioning)

Push the account lifecycle from Obexal to your downstream applications, with automatic deprovisioning at suspension and audited failures.

Outbound provisioning is the other half of lifecycle management: Obexal pushes account creation, reactivation and deactivation to the applications you use. Its main value is security: a user suspended in Obexal is deactivated everywhere, automatically. It works with any application exposing a SCIM 2.0 endpoint.

Register a target

A target is a downstream SCIM endpoint of your organization, managed at /v1/admin/scim-targets (tenant management permission):

curl -sS -X POST https://accounts.obexal.com/v1/admin/scim-targets \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"name\":\"Wiki\",\"baseUrl\":\"https://wiki.example.eu/scim/v2\",\"token\":\"$TARGET_TOKEN\",\"enabled\":true}"
# 200 -> {"id":"scimtgt_9f2e...","name":"Wiki","baseUrl":"https://wiki.example.eu/scim/v2","enabled":true,"hasToken":true}

Field	Meaning
`name`	Label shown in the console and in audit events
`baseUrl`	The target's SCIM base; HTTPS is mandatory (a bearer token transits on it)
`token`	The target's bearer token; required at creation, encrypted at rest, never returned
`enabled`	Disabled targets are skipped by every push

GET lists targets (with hasToken instead of the secret), PUT /v1/admin/scim-targets/{id} updates one (an empty token keeps the stored one), DELETE /v1/admin/scim-targets/{id} removes it. Outbound calls go through an anti-SSRF HTTP client that refuses internal and loopback addresses, on top of the HTTPS-only rule.

Idempotent creation and account adoption

When Obexal pushes a user to a target for the first time, it sends POST /Users with userName set to the email, active: true and the email in emails. The remote id is stored and drives all future operations for that user on that target.

If the target answers 409 (the account already exists there), Obexal adopts the existing account: it looks it up with filter=userName eq "..." and keeps its id, but only if the search returns exactly one result whose userName matches the requested email exactly (case-insensitive). Any ambiguity is refused, because a wrongly adopted id would later deprovision somebody else's account, or leave the real account active at offboarding.

Automatic deprovisioning

When an admin suspends a user, Obexal automatically sends PATCH /Users/{id} with active: false to every enabled target where the user is known. Reactivating the user pushes them back (active: true, or a fresh creation if the target never had the account). No extra step, no manual checklist: the offboarding you perform in Obexal propagates by itself.

The push is best-effort by design: a target being down never blocks the suspension itself, which has already succeeded in Obexal.

Backfill an existing directory

When you add a target, existing users are not there yet. Trigger a synchronous backfill:

curl -sS -X POST https://accounts.obexal.com/v1/admin/scim-targets/<id>/sync \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN"
# 200 -> {"pushed": 42}

The sync pushes every active user of the organization to that target (suspended users are skipped) and returns the count. A disabled target answers 409 target_disabled. The backfill is capped at 10000 users per run.

Failures are audited, never silent

A deprovisioning that fails silently would give a false sense of security. Every outcome, success or failure, is written to the audit log:

Event	Meaning
`scim.provisioned`	User created or reactivated on a target
`scim.provision_failed`	Push failed (with the cause: HTTP status or network error)
`scim.deprovisioned`	User deactivated on a target
`scim.deprovision_failed`	Deprovisioning failed; treat it as an open offboarding task
`scim.synced`	Backfill completed for a target

Failure entries carry the target name and the error cause, never the bearer token. Delivery is not durable across a restart of the service: if you suspect missed pushes, run a sync on the target.

Warning

Monitor scim.deprovision_failed events (via the audit stream or a webhook pipeline): each one means an account may still be active on a downstream application after an offboarding.

Limits

Outbound pushes the account lifecycle (create, activate, deactivate). Profile field changes are not propagated to targets.
Users only: no group provisioning to downstream applications.
For the opposite direction (your IdP provisioning Obexal), see SCIM inbound.