> ## Documentation Index > Fetch the complete documentation index at: https://docs.sazabi.com/llms.txt > Use this file to discover all available pages before exploring further. # SCIM provisioning > Let your identity provider add, update and remove the people in your Sazabi organization over SCIM 2.0. SCIM provisioning lets your identity provider (IdP), such as Okta or Microsoft Entra ID, add people to your Sazabi organization, keep their names up to date and remove the ones who leave. It runs on your [Single sign-on](https://docs.sazabi.com/guides/administer/single-sign-on.md) connection: you turn it on for the connection, then give your IdP the SCIM base URL and a token. Sazabi supports SCIM 2.0 **Users** only. Groups aren't supported, so roles aren't synced: everyone SCIM adds joins with the connection's **Default role**, and you change roles in Sazabi. ## Plans SCIM is part of single sign-on, so it needs a plan that includes single sign-on; [contact Sazabi](https://docs.sazabi.com/guides/administer/support.md) to enable it. See [Single sign-on](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md#plan-changes) for what happens when you lose it. ## Who can do what | Action | Who | | - | - | | Turn SCIM on or off, rotate its token, pause and resume it, set the deactivation threshold | Owners, or a secret key with permission to manage SSO (`can_manage_sso`) | | See whether SCIM is on, its tokens, the mismatch report and the SCIM member list | Owners and admins | Sazabi support, signed in as one of your owners, can't turn SCIM on, rotate its token or turn it off. ## How it fits with SSO * **SSO signs people in; SCIM decides who is a member.** SCIM never signs anyone in. People it adds sign in through your connection, as everyone else does. See [Single sign-on](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md#how-people-sign-in). * **Adding people on first sign-in keeps working.** With SCIM on, the connection's **Add people on their first sign-in** setting still applies to anyone your IdP hasn't pushed yet. Turning that setting off doesn't stop SCIM adding people. To let in only people your IdP has pushed, turn on [SCIM only](#scim-only). * **Enforcement is separate.** Requiring SSO for a domain changes how people sign in, not who is a member. See [SSO enforcement](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md). SCIM can never remove an owner, so break-glass owners keep their way back in. * **One identifier for both.** Set up your IdP so the person's immutable ID is both the SSO subject and the SCIM `externalId`. Sazabi then recognizes a pushed person on their first sign-in, whatever their email address becomes. [Connect your identity provider](https://docs.sazabi.com/guides/administer/single-sign-on/scim-setup.md#connect-your-identity-provider) shows the mapping for each IdP. ## Setup order 1. Set up and test your SSO connection. See [Configure SSO](https://docs.sazabi.com/guides/administer/single-sign-on/setup.md). 2. Turn SCIM on and copy the token. See [Set up SCIM](https://docs.sazabi.com/guides/administer/single-sign-on/scim-setup.md#turn-scim-on). 3. Configure your IdP. See [Connect your identity provider](https://docs.sazabi.com/guides/administer/single-sign-on/scim-setup.md#connect-your-identity-provider). 4. Optionally, turn on [SCIM only](#scim-only). ## How people are matched When your IdP pushes a person, Sazabi first looks for someone it already knows, so turning SCIM on never duplicates your existing members. Sazabi refuses any address that isn't on one of your organization's verified domains before it looks anyone up, with `400 invalidValue`. A domain that has lapsed but is still in its grace period counts. See [Add SSO domains](https://docs.sazabi.com/guides/administer/single-sign-on/domains.md). ### The order Sazabi matches in For each `POST /Users`, Sazabi tries these in order and stops at the first match: 1. **A SCIM record with the same `externalId`**, or failing that, a SCIM record whose person has the same email address. See [Re-hires](#re-hires). 2. **A member who has signed in through your connection with an SSO subject equal to the `externalId`.** They're adopted: Sazabi writes their SCIM record and leaves their membership and role as they are. 3. **The one member whose email address matches**, ignoring case. They're adopted the same way. 4. **Nobody.** Sazabi adds the person with the connection's **Default role**. If a Sazabi account already exists for the address, for example because they belong to another organization, that account joins; otherwise a new account is created. It has no password; they sign in through SSO. When your IdP looks someone up first with `GET /Users?filter=userName eq "…"` or `externalId eq "…"`, a member who has already signed in through your connection is adopted on the lookup and returned, so the IdP gets an ID for them without a create. Other members are adopted by the create that follows. While SCIM is paused, lookups adopt nobody. Matching on the immutable ID first is why an email change never forks a person. If your IdP maps different attributes to the SSO subject and `externalId`, Sazabi falls back to email matching, and the [mismatch report](https://docs.sazabi.com/guides/administer/single-sign-on/scim-manage.md#the-mismatch-report) shows people it couldn't connect. ### People who already sign in through SSO Pick the identifier before you turn SCIM on, and keep it. When your IdP looks up a member who has already signed in through your connection, Sazabi adopts them under the SSO subject they sign in with today: their SCIM record's `externalId` is that subject, not the `externalId` your IdP maps. A record's `externalId` never changes afterward, because Sazabi ignores `externalId` in updates. The one exception is a record created without an `externalId`: it uses the `userName` as a stand-in, and the first `externalId` your IdP sends replaces it once. So if your connection's name ID is the email address: * **Keep the email name ID**, and map the SCIM `externalId` to the same email attribute. The subject and `externalId` then agree for everyone, including people SCIM adds later. The trade-off: when someone's email address changes, their next sign-in no longer matches their SCIM record. * **Don't switch the name ID to the immutable ID afterward.** Members adopted under their email keep it as their `externalId`, so their sign-in under the new name ID isn't recognized by subject. With [SCIM only](#scim-only) on, it's refused. Before you turn on SCIM only, check the [mismatch report](https://docs.sazabi.com/guides/administer/single-sign-on/scim-manage.md#the-mismatch-report), and have one existing member and one person SCIM added sign in through SSO. ### Already matched * **The person's SCIM record is active on your connection.** The create answers `409 uniqueness`, so a retried create is safe; your IdP looks the person up with a filter instead. * **It's active, but matched only by email under a different `externalId`.** Also `409 uniqueness`, and owners get a notice: two directory objects claim one person. * **It's inactive or deleted.** The person is reactivated (see [Reactivation](#reactivation)) and the record takes the new `externalId`. ### Re-hires A person who leaves and comes back is matched to their old SCIM record, so they get back the same Sazabi account. When Entra ID permanently deletes a user, the re-hire arrives with a new object ID; Sazabi matches the old record by email and re-keys it to the new `externalId`. Someone an admin removed from the organization stays removed. Their create answers `409 uniqueness` with "removed by an admin", and setting them active answers `400 mutability`, until an admin invites them again. After the invite, the next push adopts them. ### Replacing your connection A SCIM record belongs to one connection. If its connection is deleted or has SCIM turned off, the record moves to whichever connection's IdP next claims the person, by `externalId` or email on a create, or by a filter lookup. A moved record keeps its old `externalId` unless it was inactive, and a create matched by email to an active record answers `409 uniqueness` and sends owners a notice. So replacing a connection needs no clean-up only when the new IdP sends the same identifiers, for example the email address. If it uses new immutable IDs, such as a new Okta org or Entra tenant, people's sign-ins won't match their SCIM records by subject, and with [SCIM only](#scim-only) on, a person who has never signed in is refused. ### Conflicts and owner notices Every owner gets a **SCIM request refused** email, and the request is refused, when: | Situation | Answer | | - | - | | More than one member has the address | `409 uniqueness` | | Two directory objects claim one person, as in [Already matched](#already-matched) | `409 uniqueness` | | Your plan's member limit is reached | `403` | | Your plan doesn't allow the connection's default role | `403` | Fix the cause in Sazabi or in your IdP, then retry the person from your IdP. ## Deactivation Your IdP deactivates a person by setting `active` to false or by deleting them. Okta sends the first. Entra ID sends the first, then a delete after its soft-delete period. Either way, Sazabi removes the person from your organization. ### What ends * **Their membership.** They're removed from the organization, as if an admin removed them, and the removal is recorded as SCIM's. * **Their sessions**, in every organization they belong to, because sessions belong to the account. Dashboard and CLI sessions end, and a CLI sign-in waiting for approval can't finish. In other organizations they can sign in again. * **Their MCP access** in your organization. People's AI tools lose access to it. * **Their connected accounts and vendor grants** in your organization, removed as an admin's removal removes them. ### What stays * **The account.** Sazabi never deletes it, and their memberships in other organizations stay. * **The SCIM record**, marked inactive. After a delete it's hidden from your IdP's lookups, but kept so a re-hire is recognized. To bring someone back, reactivate them in your IdP, or have an admin invite them again. See [Members](https://docs.sazabi.com/guides/administer/members.md). ### Reactivation When your IdP sets a person active again: * If SCIM removed them and nobody changed their membership since, it's restored with their previous role. If your plan no longer allows that role, or has no free seat, the request answers `403`, nothing is restored, and every owner gets a **SCIM request refused** email. * If an admin has invited them back in the meantime, their current membership is kept as it is. * If an admin removed them after SCIM did, the request answers `400 mutability`, and they stay removed until an admin invites them again. ### Protected members SCIM can't deactivate: * an **owner**; * a **break-glass owner**; * the organization's **last admin**. The request answers `400 mutability`, nothing changes, and every owner gets a **SCIM request refused** email. To remove one of these people, change their role or remove them yourself in Sazabi. This keeps an IdP mistake from locking your owners out, and keeps break-glass sign-in working. See [SSO enforcement](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md). ### Repeats and retries Deactivating someone already inactive answers success and changes nothing. If part of a deactivation fails after the membership is removed, Sazabi finishes it on your IdP's retry, and keeps retrying the clean-up of connected accounts on its own. Large numbers of deactivations in an hour pause SCIM. See [Manage SCIM](https://docs.sazabi.com/guides/administer/single-sign-on/scim-manage.md#safety-limits). ## SCIM only By default, someone your IdP lets sign in to Sazabi but hasn't pushed yet is added on their first sign-in, if **Add people on their first sign-in** is on. **SCIM only** makes your IdP's pushes the only way in: a person must have a SCIM record before their first sign-in. ### What it refuses With SCIM only on, a sign-in through your connection is refused unless the person is already linked to the connection, or has a SCIM record whose `externalId` is their SSO subject, and they have a live SCIM record on the connection. A matching email address alone never lets someone in. A refused person sees "Your organization hasn't added you yet" and is asked to have their IT admin give them access to Sazabi. That's why the immutable ID should be both the SSO subject and the SCIM `externalId`: a person SCIM pushed but who has never signed in is recognized only by subject. See [Connect your identity provider](https://docs.sazabi.com/guides/administer/single-sign-on/scim-setup.md#connect-your-identity-provider). ### With enforcement SCIM only and [enforcement](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md) do different things and stack: | SCIM only | Enforcement | A new person | | - | - | - | | Off | Off | Joins on their first SSO sign-in, or when your IdP pushes them | | On | Off | Must be pushed by your IdP before their first SSO sign-in | | Off | On | Joins on their first SSO sign-in, or when pushed; must sign in through SSO | | On | On | Must be pushed first, and must sign in through SSO | SCIM never signs anyone in, so the people it adds sign in through your connection like everyone else. Break-glass owners are owners, which SCIM can't remove, so they keep their way in. ### On a plan downgrade During the 30-day grace period after your plan stops including single sign-on, SCIM keeps working, so leavers are still removed. When the connection turns off at the end, SCIM stops working with it: every request answers `401`. SCIM's own setting and tokens are kept, so turning the connection back on restores it. See [Single sign-on](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md#plan-changes). ## Further reading > [card] [Single sign-on](https://docs.sazabi.com/guides/administer/single-sign-on.md) > > How SSO connections, sign-in and plans work. > [card] [SSO enforcement](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md) > > Require SSO for a domain and keep break-glass owners. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.