SCIM Integration

​

Overview

As organizations grow, managing user accounts across applications becomes complex. Adding and removing teammates, changing roles, and revoking access all take time and are easy to get wrong. SCIM (System for Cross-domain Identity Management) solves this by making your identity provider (IdP) the single source of truth. You map your IdP groups to Userpilot roles once, and Userpilot keeps teammates and their access in sync automatically. It provisions new users, updates roles, and removes people who leave.

​

Use cases

1. Automatically create, update, and remove Userpilot teammates as your IdP changes.
2. Keep roles consistent by mapping IdP groups (from Okta, Microsoft Entra ID, and others) to Userpilot roles.
3. Revoke access promptly when employees leave or change teams.
4. Eliminate manual teammate management across multiple applications.

​

Prerequisites

1. An Account Owner role, or a role with the Manage SCIM permission.
2. SSO configured and enabled.
3. An active subscription with a SCIM-capable IdP.
4. A Userpilot organization on the Enterprise plan.

---

​

Roles in Userpilot

Userpilot ships four built-in system roles that you can map IdP groups to: You can also map groups to any custom roles you have created in an application. The Admin Console has its own role set (Admin, Billing, View Only, and Account Owner). For more on roles and permissions, see Managing your team in Userpilot.

---

​

Enable SCIM for the organization

​

Creating a custom role

While mapping groups, you can create a new role. Click Create Role, enable the permissions you want, and click Create. The new role becomes available for mapping.

​

Default role for unmapped groups

Each application’s mapping table ends with an Individuals row. This row covers IdP users who belong to no mapped group (and users whose groups are all unmapped). Pick a role to provision them automatically, or choose Skip - don’t add to Userpilot to leave them out.

​

What if a teammate is in multiple groups?

If a teammate belongs to several mapped groups, Userpilot resolves their role automatically by granting the highest-privilege role among those groups. You do not need to restrict people to a single group in your IdP.

---

​

Choosing who owns roles

The Role management cards let you decide whether your IdP or Userpilot controls teammate roles:

• Identity provider. Your directory controls who has access and their roles. Map each group to a role, and unmapped users follow the “All other groups” default.
  • Leave Strictly enforce IdP roles off (recommended) for hybrid behavior. Roles come from your IdP groups, but any role you change in Userpilot is kept across syncs.
  • Turn Strictly enforce IdP roles on for fully provider-owned behavior. Every sync replaces all roles to match your IdP, overwriting changes made in Userpilot.
• Userpilot. SCIM provisions and removes users but never changes roles. You manage every teammate’s role in Userpilot.

---

​

Syncing users

Use Sync Users on the Authentication page to re-sync all mapped groups on demand. Before anything is applied, a preview shows exactly what will change, grouped by application:

• Will be added. New teammates and their roles.
• Role changes. The current role and the new role.
• Not applied (kept as-is). Memberships that are skipped, with the reason.
• Not found in your IdP. Listed for information only. A manual sync never removes anyone. Removals happen only when you re-map.

Confirm the preview to apply the changes.

---

​

Real-time directory events

Once SCIM is set up, Userpilot stays in sync with your IdP in real time by listening to directory events: These events are processed durably and idempotently. Each event is queued and retried until it succeeds, so nothing is lost on a restart, and Userpilot reconciles against the current directory state. This means that out-of-order or duplicate deliveries always converge to the correct result. For example, a “removed” and an “added” event that arrive in the wrong order during a role change still resolve correctly.

---

​

Audit log

Every provisioning action is recorded in the organization’s access logs, alongside sign-ins, invites, and role changes, with one entry per change. You can filter by Source (Web app, SCIM provisioning, SSO sign-in, CSV import) and Activity (Member provisioned, Member deprovisioned, Changed a member’s role, Role sync skipped (set manually), plus sign-in, 2FA, and SSO events), and search by teammate. Each entry shows the teammate, the role before and after, who triggered it, the application, and the reason. See Access and activity logs for more.

​

When a sync fails

If a provisioning run fails, the Authentication page surfaces the error and the SCIM card shows a failure banner. Provisioning is durable and retries automatically, so transient failures usually clear on their own; you can also re-run Sync Users or re-map your groups to recover. Retrying removes no teammates.

---

​

Disable SCIM

Disabling SCIM has the following effects:

1. SCIM configuration and all group mappings are removed from Userpilot.
2. The connection to your IdP directory is disconnected.
3. Manual teammate management is unlocked again.
4. Teammates already provisioned through SCIM keep their access.
5. SSO Mandatory Login remains enforced.

​

FAQs