> ## Documentation Index > Fetch the complete documentation index at: https://docs.plerion.com/llms.txt > Use this file to discover all available pages before exploring further. # SCIM provisioning > Provision users and user groups automatically from your identity provider using SCIM 2.0 With **SCIM provisioning**, you can let your identity provider (IdP) create, update, deactivate, and delete Plerion users automatically, and keep your directory groups in sync as Plerion **user groups**. Plerion exposes a SCIM 2.0 endpoint that Okta, Microsoft Entra ID, and any other SCIM 2.0 client can connect to, so a person who joins, changes, or leaves your directory is reflected in Plerion without an administrator inviting or removing anyone by hand. SCIM carries users and groups, not roles. You grant roles to the synced user groups in Plerion, and every member holds them. See [User groups](/guides/administration/user-groups). Your identity provider needs two things from Plerion: the SCIM base URL, shown in the `SCIM provisioning` section of your single sign-on settings, and a **readWrite** organization API key to authenticate with. The [steps below](#steps-to-set-up-provisioning-in-plerion) walk through both. *** ## Provisioning and single sign-on are separate Provisioning maintains user records. Single sign-on authenticates people. Each is configured on its own, and neither changes how the other behaves. * **Provisioning** happens when your identity provider pushes users over SCIM, or when you call the organization API yourself. Both use the same endpoints and the same organization API key. * **SAML single sign-on** decides who may sign in and what the assertion says about them. * **Attribute mapping** applies at every sign-in of a user who already exists. Whatever you map under `Attribute mapping`, display name and roles included, is written when that user signs in, whether or not your identity provider also maintains them over SCIM. * **Just-in-time provisioning** is its own setting. `Create users at first sign-in`, on the `Trust` section, decides whether a sign-in may create a user who does not exist yet. Turn it off when your identity provider, or your own API calls, should be the only thing that creates users. See [Create users at first sign-in](/guides/administration/sso/okta#create-users-at-first-sign-in). Display name is the one field both can write. The SCIM sync writes it when your identity provider pushes a change, and the display name mapping writes it again at each sign-in, so leave that mapping off if the sync should own the name. Role mapping is a separate hazard, and SCIM plays no part in it: at each sign-in it replaces every role the user holds directly, including roles an admin granted in the console, except for break-glass admins, whose roles it never touches. Grant roles through user groups, or leave the role mapping off. *** ## Before you start You need all of the following: * The **Organization Admin** role in Plerion. * An active SAML single sign-on connection, so the users your IdP provisions can sign in. Set one up first with the [Okta](/guides/administration/sso/okta) or [Azure](/guides/administration/sso/azure) guide. * Permission in your IdP to create and configure a provisioning application. Use two browser sessions, or two separate browsers, while you configure your IdP and Plerion side by side. This avoids conflicts caused by sharing one login session. *** ## Steps to set up provisioning in Plerion * Go to `Admin` > `Security` > `Single sign-on` and open the `Break-glass admins` section. * Check that it lists at least one active organization admin. The list is rarely empty: if the organization had no break-glass admin when SAML single sign-on was activated, whoever activated it was enrolled. * Sign in as a break-glass admin for the next step. Deprovisioning a user revokes the API keys that user created, so a key created by an ordinary account stops working the moment your IdP deprovisions that account, and provisioning stops with it. * Go to `Admin` > `Security` > `Organization API keys` and click `Create API key`. * Enter a name, for example **Okta SCIM**. * Set the access level to **readWrite**. SCIM writes users, so a `read` key is rejected. * Click `Create` and copy the key. Plerion shows it once and stores only a digest of it. * Go to `Admin` > `Security` > `Single sign-on` and open the `SCIM provisioning` section. * Copy the **SCIM base URL**. It is specific to your Plerion region. * Keep it and the organization API key at hand. Your IdP needs both. * On the `Trust` section, turn off `Create users at first sign-in`, so your identity provider is the only thing that creates users. * On the `Attribute mapping` section, review the display name and role mappings. They apply at every sign-in, including for users your IdP maintains over SCIM. *** ## Connect your identity provider With the base URL and key in hand, configure provisioning in your IdP. Configure the Okta SCIM connector and push users and groups to Plerion in near real time. Set up automatic provisioning of users and groups in an Entra ID enterprise application. Any other SCIM 2.0 client works too. Point it at the base URL, authenticate with the organization API key as a bearer token, and see the `SCIM API` group in the API reference for the supported endpoints. *** ## How the user lifecycle behaves Plerion derives the user's email address from the SCIM payload. It uses `userName` when that value is an email address, and otherwise the primary or work email in the payload. Email matching is case-insensitive, and an email address is unique across all Plerion organizations. A user your identity provider maintains carries a **SCIM managed** badge in the console. The badge is a marker, not a lock. Plerion warns you before you edit such a record, because the next sync may overwrite the change, but it does not stop you. The `Add user` control stays available to every organization admin, though letting your IdP create users keeps the two directories in step. ### Create A user your IdP pushes for the first time is created in Plerion with no roles. They can sign in through your SAML connection as soon as something grants them a role, whether one of their user groups or a direct grant. ### Adopt an existing user If the derived email matches a Plerion user who already exists, Plerion adopts that user rather than creating a second record. The user keeps their user ID and their history. Nobody has to be deleted and re-invited. Adoption leaves the roles the user held exactly as they are, whether they were granted directly or through a user group. An adopted user can be granted a role directly at any time, and their effective permissions are the union of their direct roles and the roles their user groups grant. ### Update Attribute changes in your IdP flow through to the Plerion user record. The email address is the exception: no write through this API can move it, because it anchors sign-in, adoption matching, and cross-region lookup. Renaming a user's email or user principal name in the IdP surfaces as a provisioning error until you resolve it. Contact Plerion support if a managed user's email has to change. ### Deactivate Deactivating or unassigning the user in your IdP removes their access to Plerion in near real time: * Their Plerion sessions end, so anyone signed in is signed out. * Every API key that user created is revoked. * The user record stays in Plerion as inactive, so audit history keeps its attribution. Reactivating the user in your IdP lets them sign in again. The API keys revoked at deactivation stay revoked, so they create new ones if they need them. ### Delete Deleting the user in your IdP is treated as a soft delete. The user disappears from SCIM reads and cannot sign in, but the underlying record is kept. Provisioning the same email address again revives the same user rather than creating a new one. How quickly a change reaches Plerion depends on your IdP, not on Plerion. Okta pushes changes as they happen; Entra ID syncs in cycles that can take up to about 40 minutes. Once a change arrives, Plerion applies it within seconds. *** ## How user groups behave Each group your IdP pushes becomes a Plerion **user group** marked as managed by your identity provider. * **Name and membership come from the IdP.** Rename the group or change its members in your IdP and the change syncs across. Plerion warns you before the same edit in the console, because your IdP may overwrite it on the next sync, but it does not refuse it. A SCIM-managed user can also be added to a user group you created by hand. * **Roles are granted in Plerion.** Open the group under `Admin` > `Directory` > `User groups` and grant it built-in or custom roles. Every member holds them through the group, and a member who is removed loses them. * **Deleting the group in your IdP** removes it from Plerion along with what it granted. Members keep whatever their other user groups grant. An organization admin can also delete an IdP-managed group in Plerion. *** ## Break-glass admins A break-glass admin is an organization admin who can always sign in with a password, so a misconfigured IdP or a mistaken deprovisioning can never lock your organization out of Plerion. * **At least one is required** while SAML single sign-on is active. Plerion refuses to demote the last one. * **You are enrolled automatically** when the organization has none. Whoever activates SAML single sign-on becomes a break-glass admin. * **Only active organization admins qualify.** The role can be held directly or through a user group. A deactivated or invited-but-not-yet-active user is refused, because they could not sign in to recover the organization. * **SCIM-managed users can be break-glass**, and a break-glass admin can be adopted by SCIM. Neither state rules out the other. * **SCIM cannot lock them out.** SCIM keeps syncing their attributes, such as their name, but it can never deactivate or delete them. A deactivation or delete addressed to a break-glass admin is refused and reported back to your IdP as a sync error. * **Their Organization admin role is locked.** Promoting a user to break-glass places the Organization admin role on them directly, so a change to their user groups can never take it away. While they are break-glass, nobody can add or remove that role: not SCIM, not another admin. Attribute mapping goes further and leaves every role they hold alone. * **Their display name is not locked.** The name your identity provider sends replaces it at sign-in, as it does for everyone else. * **Demotion leaves their roles alone.** A demoted break-glass admin keeps every role they held, the Organization admin role included, and those roles become editable again. Take the role away yourself if they should no longer hold it. * **The password form stays open to them.** A break-glass admin who signs in with single sign-on keeps the password form as well. One who has never set a password creates one from the forgot password link when they need it. Manage the list in the `Break-glass admins` section of `Admin` > `Security` > `Single sign-on`. Sign-in looks a little different for a break-glass admin. After they enter their email address they land on the password form. A break-glass admin who is also a single sign-on user sees a `Continue with single sign-on` button there as well, so they choose which method to use. Everyone else covered by single sign-on is sent straight to your identity provider. If single sign-on fails, the error page reminds break-glass admins that they can sign in with a password instead. *** ## Troubleshooting Provisioning problems surface in your IdP's own log: the Okta system log or the Entra ID provisioning logs. Plerion returns a SCIM error with a message describing the cause. | What you see | Cause | What to do | | - | - | - | | `A break-glass admin cannot be deactivated through SCIM` or `A break-glass admin cannot be deleted through SCIM`, returned as a forbidden response | The user is a break-glass admin. SCIM can never deactivate or delete one, though it keeps syncing their other attributes. | Demote the user in the `Break-glass admins` section first, making sure another break-glass admin remains, then retry the sync. | | Changing a user's email is refused as immutable | Email is fixed for every user. No write through this API can move it, whether or not the record is SCIM managed. | Restore the original address in the IdP to clear the error. Contact Plerion support if the address genuinely has to change. | | Every request is rejected as unauthorized | The organization API key was revoked, or it belongs to a user who has since been deprovisioned, which revokes every key they created. | Create a new **readWrite** organization API key as a break-glass admin and update the credential in your IdP. | | Every write is rejected as forbidden | The organization API key was created with `read` access. | Create a new **readWrite** organization API key and update the credential in your IdP. | | A provisioned user cannot sign in | The user was deactivated or deleted in the IdP, or the assignment was removed. A deactivated Plerion user is refused at SAML sign-in. | Confirm the user is active and assigned to the application in your IdP. | | A user's display name changed after they signed in | Display name mapping is on, so the name in the SAML assertion is written at every sign-in, whether or not the record is maintained over SCIM. | Turn the display name mapping off under `Attribute mapping` if your identity provider's SCIM sync should own the name. | | A user's roles changed after they signed in | Role mapping is on, so the roles the assertion produces replace the roles held directly by that user at every sign-in. Roles held through a user group are not affected. | Grant roles through user groups, or turn the role mapping off under `Attribute mapping`. | | A provisioned user is told they do not have access to Plerion yet | They hold no roles. A user your IdP creates starts with none, and nothing has granted them one yet. | Grant roles to one of their user groups under `Admin` > `Directory` > `User groups`, add them to a group that already has roles, or grant a role to the user directly. | | Adding or removing the Organization admin role is refused | The user is a break-glass admin. That role is locked while they are break-glass; their other roles stay editable. | Demote them in the `Break-glass admins` section first, making sure another break-glass admin remains, then change the role. | | A group edit you made in Plerion is undone | The group is pushed by your IdP, which owns its name and members, and the next sync overwrote your change. | Make the change in your IdP instead. Roles on the group are still granted in Plerion. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.