SCIM Directory Sync

Bulwark implements SCIM 2.0 (RFC 7644) for automated user and group provisioning. Connect your Okta, Azure AD, or any SCIM-compliant identity provider to keep Bulwark users and roles in sync with your corporate directory.

Why SCIM?

Manual user management doesn't scale. SCIM automates:

  • Provisioning — new users in the IdP appear in Bulwark automatically
  • Updates — name or department changes sync without manual intervention
  • Deprovisioning — when a user is deactivated or offboarded in the IdP, their Bulwark account and all active sessions are revoked within seconds

Without SCIM, offboarding requires coordinated manual steps across every SaaS tool. With SCIM, it's handled by the IdP's lifecycle management in one place.

How Directory Sync Works

IdP (Okta / Azure AD / etc.)
  ↓ SCIM 2.0 HTTP requests
Bulwark SCIM endpoint (/scim/v2)
  ↓
User/Group records created or updated
  ↓
Group membership → role mapping applied
  ↓
Audit event written

The IdP initiates all SCIM requests — Bulwark is a passive SCIM service provider. Most enterprise IdPs include a built-in SCIM connector. You configure the base URL and bearer token, and the IdP handles scheduling and retry.

Setup

  1. Go to Settings → Directory Sync in the Bulwark dashboard.
  2. Click Enable SCIM to generate a bearer token.
  3. Configure your IdP:
    • SCIM base URL: https://api.bulwarkauth.com/scim/v2
    • Bearer token: the token generated in step 2
  4. Assign the app in your IdP to the users and groups you want to provision.
  5. Trigger an initial sync from the IdP to push existing users.

Each tenant has its own SCIM bearer token. Rotate it from the dashboard without disrupting the sync — the IdP will receive a 401 on the next request and you update the token there.

JIT Provisioning vs. SCIM

Bulwark supports two provisioning strategies:

| Strategy | When users are created | Source of truth | |----------|----------------------|-----------------| | JIT provisioning | On first SSO login | IdP assertion | | SCIM | Before first login (push) | IdP directory |

SCIM is preferred for larger organizations because users exist in Bulwark before they log in. This enables pre-assigning roles, granting agent permissions, and auditing who has access without waiting for a first login.

Both strategies can coexist: SCIM handles bulk provisioning, JIT handles edge cases for users not yet pushed by SCIM.

Group-to-Role Mapping

SCIM groups can be mapped to Bulwark roles. Configure the mapping on the SCIM connection:

{
  "group_role_mapping": [
    { "group_id": "grp_01j_eng...", "role": "member" },
    { "group_id": "grp_01j_admin...", "role": "admin" },
    { "group_id": "grp_01j_viewer...", "role": "viewer" }
  ]
}

When a user's group membership changes in the IdP, the IdP sends a SCIM PATCH to update the group's member list. Bulwark re-evaluates role assignments immediately.

Users can belong to multiple groups. If groups map to different roles, the highest-privilege role is applied.

Deprovisioning

When the IdP sends PATCH /scim/v2/Users/{id} with active: false, or DELETE /scim/v2/Users/{id}, Bulwark:

  1. Marks the user as inactive
  2. Revokes all active sessions
  3. Revokes all agent tokens owned by the user
  4. Writes a deprovisioning event to the audit log

Deprovisioning is immediate — there is no grace period. If the user re-authenticates (e.g. via a cached session token), Bulwark rejects the token and requires re-authentication.

Supported IdPs

Bulwark's SCIM endpoint is compatible with any RFC 7644 implementation. Tested configurations:

| IdP | Integration Type | |-----|-----------------| | Okta | SCIM 2.0 (built-in connector) | | Microsoft Azure AD / Entra ID | Automatic provisioning (SCIM 2.0) | | Google Workspace | SCIM 2.0 via third-party bridge | | OneLogin | SCIM 2.0 connector | | Ping Identity | SCIM 2.0 |

Bearer Token Security

The SCIM bearer token grants full read/write access to your tenant's users and groups. Treat it as a high-privilege credential:

  • Store it in your IdP's secret management, not in config files
  • Rotate it at least annually, or immediately after a suspected exposure
  • Monitor the SCIM audit events for unexpected writes