gigamcp/ docs

Directory Sync (SCIM)

Directory Sync mirrors users and groups from your IdP into gigamcp automatically. New hires appear within seconds; folks who leave are deprovisioned by the IdP without manual cleanup in gigamcp. We use WorkOS Directory Sync as the SCIM endpoint.

Supported IdPs (SCIM v2)

  • Okta
  • Microsoft Entra ID / Azure AD
  • Google Workspace
  • OneLogin, JumpCloud, Rippling
  • Generic SCIM 2.0

Setup

  1. From Enterprise → Single Sign-On, press Configure SCIM provisioning.
  2. The WorkOS Admin Portal opens. Pick your IdP and follow the rotating-bearer-token flow; the Portal generates a SCIM endpoint URL + bearer token your IdP can post against.
  3. Paste the resulting directory_… id into Directory id (SCIM) on the SSO page and press Save.
  4. On the IdP side, assign users + groups to the gigamcp app. Within ~30 seconds you should see them appear under Enterprise → Directory Sync.

What gets synced

  • Users: email (primary), display name, active flag. Inactive users are removed from memberships but the row is preserved for audit history.
  • Groups: name, member list. The local group keeps the IdP's group id in directory_group_id; this lets us round-trip updates idempotently.

What does NOT get synced

  • Roles. SCIM has no concept of gigamcp-specific roles (member / admin / owner); the first synced user keeps whatever role the inviter set, and you assign roles in the gigamcp UI as usual.
  • Audience filters on knowledge sources. Audiences reference groups by id, so if you delete a synced group from the IdP, any knowledge source whose audience pinned that group becomes invisible until you fix the audience filter.

Webhook endpoint

WorkOS posts SCIM events to POST /api/webhooks/workos/directory-sync on gigamcp. The body is HMAC-signed with the per-deployment WORKOS_WEBHOOK_SECRET; we reject any request with an invalid signature.

Provenance and immutability

Rows mirrored from the directory carry a provenance: directorytag and are read-only in the gigamcp UI. To rename a synced group or change a synced user's name, edit it in the IdP — the change propagates to gigamcp automatically.

Disabling Directory Sync

Clear the Directory id field on the SSO page. New SCIM events are then dropped on the floor. The mirrored users + groups remain in gigamcp; you can convert them to local rows manually with the help of support.