Skip to content

Inbound SCIM

Floh supports inbound SCIM 2.0 endpoints for enterprise directory provisioning. The first implementation focuses on directory-managed users and groups while preserving Floh's OIDC login model.

Looking to push lifecycle events from Floh to an external IdP instead? See the Outbound SCIM Connector.

Base URL

SCIM endpoints are served under:

/scim/v2

Every endpoint requires a SCIM bearer token:

Authorization: Bearer <scim-token>

SCIM tokens are stored hashed in scim_client. Raw token values must only be shown once when an admin management flow creates them.

Supported Endpoints

  • GET /ServiceProviderConfig
  • GET /ResourceTypes
  • GET /Schemas
  • POST /Users
  • GET /Users
  • GET /Users/:id
  • PUT /Users/:id
  • PATCH /Users/:id
  • POST /Groups
  • GET /Groups
  • GET /Groups/:id
  • PUT /Groups/:id
  • PATCH /Groups/:id

Unsupported in this release:

  • SCIM Bulk
  • /Me
  • Password changes
  • Direct RBAC role, permission, business role, or entitlement management
  • Hard delete through SCIM

Identity Policy

SCIM does not own Floh's login identity. Floh users still authenticate through OIDC and are identified by (iss, sub).

For inbound SCIM:

  • userName maps to the user's email address by default.
  • emails[type eq "work"].value or the primary email maps to user.email.
  • externalId is stored on scim_user_identity.external_id.
  • externalId is never copied to user.sub.
  • New SCIM users are created as unconfirmed Floh users. Their first OIDC login confirms the real (iss, sub) identity.

Deactivation Policy

PATCH /Users/:id with active: false sets user.active = false. It does not hard-delete the user and does not mutate iss or sub.

Reactivation with active: true re-enables the user when the SCIM identity still belongs to the same SCIM client. If product policy later requires directory deprovisioning to hide users from normal user lists, this behavior should be changed deliberately to call Floh's soft-delete path and the docs should be updated in the same PR.

Groups Policy

SCIM Groups map to Floh user_group rows and user_group_membership rows.

SCIM Groups do not grant:

  • Floh system RBAC roles in user_role
  • Permission overrides
  • Business role_assignment rows
  • Entitlements

Those mappings must be configured explicitly in a later release if needed.

Filters

The MVP supports equality filters used by common IdP provisioning clients:

  • userName eq "alice@example.com"
  • emails.value eq "alice@example.com"
  • externalId eq "00u123"
  • displayName eq "Engineering" for groups

Unsupported filter operators return a SCIM 400 invalidFilter response.

Audit

SCIM write operations are audited as service-client actions with the SCIM client ID in metadata. Audit entries must never include bearer tokens or raw credential payloads.

Current audit actions:

  • scim.user.created
  • scim.user.linked_existing
  • scim.user.updated
  • scim.group.created
  • scim.group.updated
  • scim.group.member_added
  • scim.group.members_replaced

IdP Setup Notes

For Okta and Entra-style clients:

  1. Configure the SCIM base URL as https://<floh-host>/scim/v2.
  2. Use bearer-token authentication.
  3. Map userName and primary work email to the same email value unless a customer-specific mapping is approved.
  4. Enable user create, update, and deactivate first.
  5. Enable group push after user provisioning has been validated.