Skip to main content
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. 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 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.
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 or 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

1

Confirm a break-glass admin

  • 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.
2

Create the organization API key

  • 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.
3

Copy the SCIM base URL

  • 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.
4

Check the sign-in settings

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

Okta

Configure the Okta SCIM connector and push users and groups to Plerion in near real time.

Microsoft Entra ID

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.