# Provisioning with SCIM

> Let Microsoft Entra ID create, update and remove Botyard members over SCIM 2.0: token, Tenant URL, the required externalId mapping, group-to-role mapping and health.

Canonical URL: https://docs.botyard.io/docs/sso/entra-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](/docs/sso/entra-saml) or [OpenID Connect](/docs/sso/entra-oidc) 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**.

> [!WARNING]
> **The token is shown once**
>
> This is the only time the token is shown. Botyard stores only a hash of it. Copy both values
> before you click **I've copied it**. If you lose the token, rotate it to get a new one.

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](https://entra.microsoft.com), 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**:

| Health       | Meaning                                                                                                                            |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Healthy**  | Nothing is held back.                                                                                                              |
| **Degraded** | Some changes are held back by policy, or Entra sent people whose email belongs to another Botyard account. The rest still applies. |
| **Error**    | Some changes failed, or changes have not been applied for a while.                                                                 |

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**:

| Reason                                               | What to do                                                                                                                                |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| No free seats on your plan                           | Free a seat or upgrade your plan.                                                                                                         |
| Would remove the organization's last owner           | Make someone else an owner first.                                                                                                         |
| Email already belongs to a different Botyard account | The email Entra sent belongs to an existing Botyard account that this connection doesn't manage. Botyard doesn't merge accounts by email. |
| Owner role is protected (owner sync is off)          | Turn on **Let groups grant the owner role**, or change the mapping.                                                                       |
| Entra sent a change we couldn't interpret            | Check the user's attribute mappings in Entra.                                                                                             |
| Failed to apply                                      | Contact Botyard support.                                                                                                                  |

## 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.