--- sidebar_position: 3 title: Setting up SCIM provisioning description: Automate user lifecycle management in MotherDuck using SCIM with your identity provider. keywords: [scim, provisioning, deprovisioning, okta, entra, identity provider] --- 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](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/). ::: ## 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](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#just-in-time-jit-user-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 removes it 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](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/) 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](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#step-6-verify-your-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: ```text https://auth.motherduck.com/scim/v2/connections/ ``` :::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](#attribute-mapping). 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](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#just-in-time-jit-user-provisioning). - 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](mailto:support@motherduck.com). 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](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/) - [Managing organizations](/docs/key-tasks/managing-organizations/) --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. Payload: ```json { "page_path": "/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/scim/", "page_title": "Setting up SCIM provisioning", "text": "", "source": "" } ``` `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed payloads, and `429` when rate-limited.