SCIM Provisioning

Shorebird supports SCIM 2.0 user provisioning for companies on the Enterprise plan. 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, a beta Google offers to some organizations. It attaches to a SAML app, so first set up Shorebird as one (SAML), then enter the base URL and key from Before you start in the app’s Autoprovisioning settings.

If your IdP isn’t listed here, email contact@shorebird.dev.

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; 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, 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, and an admin of your IdP who can create applications.

1. In the Shorebird Console, 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 with the SCIM account as the actor.

Setting up in Okta

If you already have a Shorebird app in Okta for 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 to the people and groups who should have Shorebird accounts.

Okta documents these screens in Add SCIM provisioning to app integrations.

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.

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 contact@shorebird.dev.