--- title: "SCIM Provisioning" description: "Add and deactivate the people in your Shorebird enterprise from Okta, Microsoft Entra ID or Google Workspace over SCIM 2.0" --- Shorebird supports SCIM 2.0 user provisioning for companies on the [Enterprise plan](/enterprise/). Your identity provider (IdP) adds people to your enterprise when you assign them the Shorebird app, keeps their names current, and deactivates them when they leave or are unassigned. Shorebird is tested with Okta and Microsoft Entra ID. Other IdPs that send standard SCIM 2.0, such as OneLogin and JumpCloud, use the same settings. Google Workspace provisions over SCIM through [custom SCIM profiles](https://knowledge.workspace.google.com/admin/users/advanced/automated-user-provisioning-with-custom-scim-profiles), a beta Google offers to some organizations. It attaches to a SAML app, so first set up Shorebird as one ([SAML](/enterprise/saml/)), then enter the base URL and key from [Before you start](#before-you-start) in the app’s **Autoprovisioning** settings. If your IdP isn’t listed here, email . ## What provisioning does | Your IdP | Shorebird | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Assigns someone with no account | Creates their account as a Member of your enterprise and emails them an invitation. Their first sign-in with Google, Microsoft or your SAML connection attaches to it. | | Assigns someone who already signed in | Finds their account by email address and links it. They are already a Member, because everyone who signs in at your domains is. | | Changes a name | Updates the name on their account. | | Removes, suspends or deletes them | Deactivates them, as the **Deactivate** button in the console does. | | Assigns or reactivates them again | Reactivates them: they can sign in again. | Deactivating someone removes them from every organization and app in your enterprise, revokes their sessions, API keys and invitations, and blocks their sign-in. Their account is kept, never deleted, whether your IdP sends `active: false` or `DELETE`. Someone reactivated rejoins your [default organizations](/enterprise/roles/#enterprise-roles); add them back to any others from the console. People your IdP manages are marked **SCIM** on the **People** tab of the **Enterprise** page. ### What stays in Shorebird * **Roles and organizations.** Shorebird provisions users, not groups. Everyone your IdP creates is an enterprise Member. Owners change [enterprise roles](/enterprise/roles/), and organization admins add people to organizations, in the console. * **Email addresses.** An email address is how Shorebird finds an account at sign-in, so it can’t be changed over SCIM. To move someone to a new address, deactivate them in your IdP and assign the new address. * **Your domains only.** Your IdP can only add people at your enterprise’s email domains. Invite anyone else to an organization as a guest. * **Enterprise Owners.** Your IdP can’t deactivate an enterprise Owner, so an enterprise always keeps one. Another Owner makes them an Admin or Member first. Someone who owns an organization is still deactivated, and stays its owner until an enterprise Admin or Owner gives the organization a new one. ## Before you start You need the **Owner** [enterprise role](/enterprise/roles/), and an admin of your IdP who can create applications. 1. In the [Shorebird Console](https://console.shorebird.dev), open the **Enterprise** page from the organization switcher, then its **Security** tab. 2. In **SCIM provisioning**, copy the **Base URL**: `https://api.shorebird.dev/scim/v2`. 3. Click **Create SCIM account**, name it after your IdP (for example, “Okta”), and create a key. Copy the key: it is shown only once, and it is the bearer token your IdP sends. The SCIM account belongs to your enterprise, not to you, so provisioning keeps working if you leave. If you give its key an expiry, create a new key and paste it into your IdP before then. Every change your IdP makes is recorded in the [audit log](/enterprise/audit-logs/) with the SCIM account as the actor. ## Setting up in Okta If you already have a Shorebird app in Okta for [SAML](/enterprise/saml/), add provisioning to it. Otherwise, create one as the SAML page describes. 1. On the app’s **General** tab, edit **App Settings**, set **Provisioning** to **SCIM**, and click **Save**. 2. On the new **Provisioning** tab, under **Integration**, click **Edit** and set: | Setting | Value | | --------------------------------- | ----------------------------------------------- | | SCIM connector base URL | `https://api.shorebird.dev/scim/v2` | | Unique identifier field for users | `userName` | | Supported provisioning actions | **Push New Users** and **Push Profile Updates** | | Authentication Mode | **HTTP Header** | | Authorization (Bearer) | The key of your SCIM account | Leave the import and group actions unchecked. 3. Click **Test Connector Configuration**, then **Save**. 4. Under **Provisioning → To App**, click **Edit**, enable **Create Users**, **Update User Attributes** and **Deactivate Users**, and click **Save**. 5. Check that the app’s **Application username format** is **Email**, as the SAML setup sets it. 6. [Assign the app](https://help.okta.com/en-us/content/topics/provisioning/lcm/lcm-assign-app-user.htm) to the people and groups who should have Shorebird accounts. Okta documents these screens in [Add SCIM provisioning to app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm). ## Setting up in Microsoft Entra ID 1. In the Microsoft Entra admin center, go to **Enterprise applications → New application → Create your own application**. Name it (for example, “Shorebird”), choose **Integrate any other application you don’t find in the gallery (Non-gallery)**, and click **Create**. If you already have a Shorebird app for SAML, use that one instead. 2. Open **Provisioning**, set **Provisioning Mode** to **Automatic**, and under **Admin Credentials** set **Tenant URL** to `https://api.shorebird.dev/scim/v2` and **Secret Token** to the key of your SCIM account. Click **Test Connection**, then **Save**. 3. Under **Mappings**, open **Provision Microsoft Entra ID Groups** and set **Enabled** to **No**. Shorebird provisions users only. 4. Open **Provision Microsoft Entra ID Users**, edit the `userName` mapping, and change its source attribute from `userPrincipalName` to `mail`. Shorebird identifies people by email address, and a user principal name isn’t always one. Save. 5. Under **Settings**, set **Scope** to **Sync only assigned users and groups**. 6. Under **Users and groups**, assign the people and groups who should have Shorebird accounts. 7. Back in **Provisioning**, set **Provisioning Status** to **On** and click **Save**. Entra provisions in cycles, about every 40 minutes. To try one person straight away, use **Provision on demand**. Microsoft documents these screens in [Integrate your SCIM endpoint with the Microsoft Entra provisioning service](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#integrate-your-scim-endpoint-with-the-microsoft-entra-provisioning-service). ## Troubleshooting | What your IdP reports | What to do | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` when testing the connection | The token is missing or wrong, or its key was revoked or has expired. Create a new key for the SCIM account and paste it again. | | “SCIM is only for an enterprise service account with the SCIM role” | The token is a personal API key or another service account’s key. Use the key of an account made with **Create SCIM account**. | | “isn’t on one of the enterprise’s domains” | The person’s email address is at a domain your enterprise doesn’t own. Invite them to an organization as a guest. | | “A user’s email can’t be changed over SCIM” | Their email changed in your IdP. Deactivate them and assign their new address. In Entra, also check that `userName` is mapped from `mail`. | | “This user is an owner of the enterprise in Shorebird” | Your IdP tried to deactivate an enterprise Owner. Another Owner gives them the Admin or Member role in the console; your IdP’s next attempt then succeeds. | | `404` for `/Groups` | Group provisioning is on. Turn it off as described above. | Anything else is worth an email to .