Provisioning with SCIM

With SCIM provisioning, Entra's provisioning service creates, updates and removes the members of your Botyard organization, and sets their roles from Entra groups. You need to be a Botyard organization owner.

Set up SAML or OpenID Connect sign-in first, and provision through the same Entra application. A provisioned user is then linked to their SSO identity when they first sign in.

1. Turn on provisioning in Botyard

1. In Botyard, open User menu › Settings › General › Single sign-on.
2. On the Provisioning (SCIM) card, click Turn on provisioning.
3. A dialog, Copy your SCIM token, shows the Tenant URL and the Secret Token.

The Tenant URL has the form …/api/auth/scim/v2. It is also shown on the card at any time.

2. Connect Entra's provisioning service

1. In the Microsoft Entra admin center, open Enterprise applications → your Botyard application → Provisioning.
2. Set Provisioning Mode to Automatic.
3. Under Admin Credentials, paste the Tenant URL and the Secret Token.
4. Click Test Connection, then Save.

3. Remap the user externalId (required)

Entra's default mapping sends a user's mailNickname as their SCIM externalId. A mailNickname is neither unique nor permanent, and Botyard uses externalId to link a provisioned user to their SSO sign-in. You must map it to the user's object ID instead:

1. Under Mappings, open Provision Microsoft Entra ID Users.
2. Edit the attribute mapping whose Target attribute is externalId.
3. Change Source attribute from mailNickname to objectId, and save.

Without this change, provisioned users are not recognised when they sign in through SSO.

Groups need no change: Provision Microsoft Entra ID Groups already sends the group's object ID as its externalId. Leave group provisioning enabled if you want to map groups to roles.

4. Assign users and groups, then start

1. Under Users and groups, assign the users and groups to provision. Members of an assigned group are provisioned too.
2. Back on Provisioning, set Provisioning Status to On and save.

Entra provisions on its own schedule. The Last request row on the Provisioning (SCIM) card shows when Botyard last heard from it.

What provisioning does

• Create and update. Each assigned user becomes a member of your organization. New members get the Member role unless a group mapping says otherwise.
• Deprovision. When a user is unassigned, disabled or deleted in Entra, Botyard removes them from the organization. Their Botyard account is kept. Removal also:
  • revokes every organization API key they created in this organization;
  • removes them from this organization's bots;
  • denies their existing sessions access to the organization.
• Sign-ins still admit people. Someone who signs in through your identity provider before Entra has sent them still joins as a member. Once Entra has sent a user, their membership follows what Entra says.

Provisioning is authoritative for the members it manages. While a member is managed by provisioning, their role can't be changed by hand in Botyard. Change their Entra groups or the group mappings instead.

Map Entra groups to roles

The Group → role mappings card appears once provisioning is on.

1. Under Entra group, choose a group Entra has already sent. For a group Entra hasn't sent yet, click Group not listed? Enter its object ID and enter its Entra group object ID (a GUID, from Entra → Groups → your group → Overview).
2. Choose a Role: Member, Viewer, or Owner.
3. Click Add mapping.

When a member is in several mapped groups, the highest role wins. Groups are matched by object ID, so renaming a group in Entra doesn't break its mapping.

The owner role

By default, a group can't grant the owner role, so a change in Entra can't make or unmake owners. To allow it, turn on Let groups grant the owner role on the Provisioning (SCIM) card. You can only turn it off again after removing every mapping to Owner.

Health

The card shows the connection's Health:

Entra is told a held-back change succeeded, so Entra's provisioning logs won't show it. This card is the only place you see it. Email conflicts are the exception: Entra also gets a conflict error for those users. Each held-back change lists the Entra user (their object ID), the Reason and Since:

Rotate the token

1. On the Provisioning (SCIM) card, click Rotate token and confirm.
2. Copy the new Secret Token from the dialog.
3. Paste it into Entra under Provisioning → Admin Credentials and save.

The old token stops working immediately, and provisioning pauses until Entra has the new one.

Turn off provisioning

Click Turn off provisioning and type your organization's slug to confirm.

• The token stops working immediately, and Entra can no longer change members.
• Members that provisioning managed keep their membership and role. From now on, they are managed by hand in Botyard.
• Changes Entra sent that have not been applied yet are dropped.

Group mappings of the old connection stop granting anything. If you turn provisioning on again, you get a new token and add the mappings again.