Setting up SCIM provisioning

SCIM (System for Cross-domain Identity Management) keeps your MotherDuck users in sync with your identity provider. When you assign, update, or remove a user in your IdP, the change is automatically applied in MotherDuck.

note

SCIM provisioning is available on Business and Enterprise plans, and requires an active SSO connection.

How SCIM complements SSO

SSO and SCIM solve different problems:

	SSO	SCIM
Purpose	Authentication — controls how users sign in	Provisioning — controls which users exist
Handles	Sign-in redirects, session management	Account creation, updates, deprovisioning
Trigger	User-initiated (at sign-in)	IdP-initiated (when staff changes)

With SSO alone, MotherDuck uses just-in-time (JIT) provisioning to create accounts on first sign-in. JIT does not handle changes after the account is created — if an employee leaves your company, their MotherDuck account stays active until an admin deprovisions or removes them manually.

SCIM closes that gap by making your IdP the source of truth for who has access. SCIM replaces JIT as the auto-provisioning mode and disables manual invite flows, so the IdP becomes the only place where members are added or removed.

Prerequisites

Before you enable SCIM, confirm:

• Admin role in MotherDuck.
• A Business or Enterprise plan.
• An SSO connection that is active (not pending). SCIM cannot be enabled on a pending connection.
• Admin access to the IdP application that's already linked to your SSO connection.

Configuring SCIM uses your existing SSO connection, so any of the supported enterprise SSO connection types work — SAML, OIDC, Okta Workforce, or Microsoft Entra ID (Azure AD).

Supported operations

IdP action	Effect in MotherDuck
Assign user to the MotherDuck application	Creates a MotherDuck user with the Member role on first SCIM event
Update user attributes (name, email)	Updates the MotherDuck user record
Deprovision user	Deprovisions the user — sign-in is blocked, all access tokens are revoked, but data is retained and the account can be reprovisioned
Reprovision user	Restores a deprovisioned user to active status
Unassign / delete user	Removes the user from the organization (hard delete)

Role assignment through SCIM is not yet supported — all SCIM-provisioned users start with the Member role. Use the MotherDuck Members page to change a user's role after provisioning.

Attribute mapping

MotherDuck reads the following attributes from each SCIM request:

SCIM attribute	Required	Description
userName	Yes	The user's email address. Must be on a verified domain of the SSO connection.
emails[].value	Yes (if userName is not set to email)	Used as a fallback for the email address.
name.givenName	No	The user's first name.
name.familyName	No	The user's last name.
active	Yes	Drives deprovisioning and reprovisioning.

User email addresses with aliases (for example, user+tag@company.com) are not supported, matching the SSO requirement.

Enabling SCIM

Step 1: Generate the SCIM endpoint and token in MotherDuck

1. In the MotherDuck UI, click your organization name in the top left and select Settings.
2. Open the Authentication tab.
3. In the SCIM section, click Enable SCIM.
4. Confirm in the dialog. MotherDuck generates a SCIM endpoint URL and a SCIM token.

The endpoint URL has this shape:

https://auth.motherduck.com/scim/v2/connections/<connection_id>

warning

The SCIM token is shown once. Copy it immediately and store it in your IdP — MotherDuck cannot show it again. If you lose the token, you can regenerate it (which revokes the previous token).

Step 2: Configure SCIM provisioning in your identity provider

In your IdP's admin console, open the application that's linked to your MotherDuck SSO connection and turn on SCIM provisioning. The exact path depends on the IdP:

• Okta: open the application's Provisioning tab and switch to SCIM.
• Microsoft Entra ID: open the application's Provisioning blade and set the mode to Automatic.

When prompted, supply:

• Tenant URL (also called SCIM endpoint URL or Base URL): paste the URL from Step 1.
• Secret token (also called Bearer token): paste the SCIM token from Step 1.

Use the IdP's Test Connection button to verify connectivity before assigning users.

Step 3: Map attributes in your identity provider

Map your IdP's user attributes to the SCIM attributes listed above. Most IdPs ship a default mapping that already covers userName, emails, name.givenName, name.familyName, and active.

Step 4: Assign users

Assign users (or groups) to the MotherDuck application in your IdP. Each assignment triggers a SCIM create request, which provisions the user in MotherDuck with the Member role.

For ongoing changes, your IdP automatically sends:

• A SCIM update request when a user's attributes change.
• A SCIM update or patch request with active=false when a user is deprovisioned or unassigned.
• A SCIM delete request when the user is fully removed.

Managing SCIM after enablement

Regenerating the token

If the SCIM token is lost or compromised, regenerate it from Settings → Authentication → SCIM → Regenerate token. The previous token is revoked immediately, so update the new token in your IdP right away to avoid provisioning failures.

Disabling SCIM

To stop SCIM provisioning, click Disable SCIM on the Authentication page. Disabling:

• Removes the SCIM connection from MotherDuck's identity layer (your IdP can no longer make SCIM requests).
• Switches auto-provisioning back to JIT.
• Leaves existing user accounts untouched. Previously deprovisioned users remain deprovisioned.

You can re-enable SCIM later, but a new endpoint URL and token will be issued.

Manual invites are disabled and JIT is replaced

When SCIM is enabled, MotherDuck switches the auto-provisioning mode from JIT to SCIM and disables manual invite flows, so the IdP stays the single source of truth for who can sign in:

• The Invite action in the org menu and on the Members page is disabled.
• The Invite policy setting on the org details page is disabled.

To grant a new user access, assign them to the MotherDuck application in your IdP.

Deprovisioned users on the members page

Deprovisioned users appear on the Members page with a deprovisioned badge. Hover the badge for a reminder that the user can no longer sign in and that all of their access tokens have been revoked.

The Members page status filter lets you narrow the list to active, invited, or deprovisioned users. Admins can impersonate deprovisioned users and service accounts — useful for inspecting their data before deciding whether to reprovision or delete the account. Admins cannot impersonate active users.

Deletion vs. deprovisioning

Deprovisioning and deletion are distinct user states with different recovery semantics:

State	What happens	How to enter	How to exit
Deprovisioned	The user record and data are retained, the identity is disabled, and all PATs and short-lived tokens are revoked. The user cannot sign in. Admins can still impersonate the account.	IdP sends active=false (PATCH or PUT)	Reprovision the user in your IdP — works at any time, including past the deletion fail-safe window
Deleted	The user is removed from the organization. Email is freed for reuse. No one can impersonate a deleted account.	IdP sends a SCIM delete request	Restore the account within the 7-day fail-safe window through MotherDuck support

How deletion is triggered

• From the IdP (SCIM orgs): removing the user from the MotherDuck application — or deleting them from the IdP entirely — sends a SCIM delete event when your IdP is configured to forward delete events. SCIM-enabled organizations cannot hard-delete users from inside MotherDuck; the IdP is the only authoritative path.
• From inside MotherDuck (non-SCIM orgs only): the in-app Remove member action is available only when SCIM is disabled.

note

Some IdPs do not forward delete events to applications by default — they only mark the user inactive on their side. In that case, MotherDuck sees the inactive signal and the user appears as deprovisioned rather than deleted. Configure your IdP to forward delete events if you want hard deletes to flow through.

Restoring after deprovisioning or deletion

• A deprovisioned user can be reprovisioned at any time from your IdP. The next SCIM event will restore their account. Their data is preserved, but issued access tokens are not — affected users need to mint new tokens.
• A deleted user can be restored within the 7-day fail-safe window by contacting MotherDuck support. After the window elapses, the account and its data are gone.

Limitations

• One SCIM connection per organization: SCIM uses the same Auth0 connection as SSO. Each MotherDuck organization can have only one SCIM connection, matching its single SSO connection.
• No role mapping yet: SCIM-provisioned users start as Member. Adjust roles in MotherDuck after provisioning.
• No aliased emails: Addresses like user+tag@company.com are rejected, the same as for SSO.
• PATCH remove operations are ignored: MotherDuck handles SCIM add and replace operations on active. remove operations are logged and skipped to keep behavior predictable across IdPs.

Related

• Setting up SSO
• Managing organizations