How It Works
Ultra receives webhook events from the SSO service whenever your identity provider makes SCIM changes (user created, group updated, etc.). This event-driven approach means changes propagate to Ultra Hub in near real-time.Setting Up Directory Sync
Open the setup wizard
Navigate to Settings > Security in the Ultra Hub dashboard. Under Directory Sync, you will see a setup link URL. Open this link in your browser to launch the guided configuration wizard.
Connect your directory provider
The wizard walks you through connecting your identity provider step by step. Select your directory provider from the list (Okta, Azure AD, JumpCloud, etc.) and follow the provider-specific instructions to configure SCIM provisioning.
Verify sync is active
Once complete, the Directory Sync section in Settings > Security shows an Enabled badge and displays provisioning stats:
- SCIM Users — Count of users provisioned via SCIM (out of total users)
- SCIM Teams — Count of teams provisioned via SCIM (out of total teams)
Setup links have an expiration date displayed below the URL. You can click Revoke to invalidate an active link and generate a new one at any time.
User Provisioning
Creating Users
When a user is created in your IdP’s SCIM directory, Ultra Hub automatically:- Creates an identity in the authentication system
- Creates a user account in Ultra Hub
- Adds the user to your organization with the Member role
- Marks the user’s onboarding as complete (SCIM users skip the onboarding wizard)
Updating Users
When a user’s profile is updated in your IdP (name, email, active status), the changes sync to Ultra Hub automatically. If a user is deactivated in the IdP, Ultra deactivates their authentication identity first (blocking login immediately), then updates their Hub account.Deprovisioning Users
When a user is deleted from your IdP’s directory, Ultra Hub soft-deletes the user:- The user’s authentication identity is deactivated (they can no longer log in)
- The user’s account is marked as inactive
- The user’s data, audit trails, and team memberships are preserved
Ultra never hard-deletes SCIM-deprovisioned users. This preserves audit trails and allows reactivation if the user is re-provisioned later.
Reactivation
If a previously deprovisioned user is re-provisioned in your IdP (e.g., an employee returns), Ultra Hub automatically reactivates their account and authentication identity. The user regains access with their previous memberships intact.Group-to-Team Mapping
SCIM groups from your identity provider map to teams in Ultra Hub. This lets you manage team structure from your IdP instead of manually creating teams in Ultra.Creating Groups
When a group is created in your IdP, Ultra Hub creates a corresponding team in your organization. Initial group members are synced as team members.Updating Groups
When a group is updated (renamed, members added or removed), Ultra Hub syncs the changes:- Group rename — The team name and slug are updated
- Full member sync — On group update events, the team membership is reconciled against the IdP’s member list. Members not in the IdP list are removed; new members are added.
- Incremental member changes — Individual member add/remove events are processed immediately without a full reconciliation
Deleting Groups
When a group is deleted in your IdP, Ultra Hub does not auto-delete the corresponding team. This prevents accidental data loss from IdP misconfigurations. A warning is logged, and the team can be manually removed by an admin if needed. SCIM-provisioned teams are tagged with a SCIM badge in the Teams list.Idempotency and Ordering
Ultra Hub handles duplicate and out-of-order webhook events gracefully:- Deduplication — Each webhook payload is assigned a deterministic delivery ID. If the same event is received twice, the duplicate is silently ignored.
- Stale event detection — Events include a signature timestamp. If an event’s timestamp is older than the last processed event for that user, it is skipped. This prevents out-of-order events from reverting newer changes.
- Upsert semantics — User and group creation events are idempotent. If the user or team already exists (matched by external ID or email), the event is treated as a no-op or update.
Webhook Security
SCIM webhooks are secured with HMAC-SHA256 signature verification:- Every webhook request includes an
Ory-Signatureheader with a timestamp and HMAC signature - The signature is computed over the timestamp and request body using a shared secret
- Ultra Hub verifies the signature and rejects requests that fail verification
- Replay protection — Webhook timestamps older than 5 minutes are rejected, preventing captured payloads from being replayed
Supported Events
| Event | Action |
|---|---|
user.created | Creates authentication identity + Hub user + org membership |
user.updated | Updates user profile; handles activate/deactivate transitions |
user.deleted | Soft-deletes: deactivates identity, marks user inactive |
group.created | Creates team with initial member sync |
group.updated | Updates team name + full member reconciliation |
group.deleted | Logs warning (no auto-delete to prevent data loss) |
group.user_added | Adds user to team (incremental) |
group.user_removed | Removes user from team (incremental) |
Viewing SCIM Status
Navigate to Settings > Security in the Ultra Hub dashboard. The Directory Sync section shows an Enabled badge when SCIM is active, along with provisioning stats:- SCIM Users — Count of users provisioned via SCIM (out of total users)
- SCIM Teams — Count of teams provisioned via SCIM (out of total teams)
Audit Trail
All SCIM provisioning events are recorded in the Admin Log as security events:scim.user_provisioned— New user created via SCIMscim.user_updated— User profile updated via SCIMscim.user_deactivated— User deprovisioned via SCIMscim.group_created— Team created from IdP groupscim.group_updated— Team updated from IdP groupscim.group_deleted— IdP group deletion receivedscim.group_member_added— User added to team via SCIMscim.group_member_removed— User removed from team via SCIMscim.webhook_failed— Webhook processing error (includes error details)
Supported Directory Providers
| Provider | Protocol |
|---|---|
| Entra ID (Azure AD) | SCIM v2.0 |
| Google Workspace | Native integration |
| JumpCloud | SCIM v2.0 |
| Okta | SCIM v2.0 |
| OneLogin | SCIM v2.0 |
| Generic SCIM 2.0 | SCIM v2.0 |