Articles in this section

Provision end users with SCIM

Michelle Welch
Updated

Connect your identity provider (IdP) to Celigo to automatically create end users, manage their group memberships, and revoke access—including their MCP tokens—when they leave the company. You enable SCIM provisioning for an external identity provider, configure it with the provider's base URL and a token, and map the user and group attributes. Because SCIM configurations are managed per identity provider, an account using Okta for one domain and Microsoft Entra ID for another will have two separate configurations.

This article covers the Celigo side of the setup. For how SCIM relates to just-in-time (JIT) provisioning and group sync, see SCIM provisioning overview.

Prerequisites

  • You are signed in as the account owner or an administrator.
  • Your account uses the multi-environment structure. End-user features aren't available on legacy sandbox-only accounts.
  • Your subscription includes SCIM provisioning and single sign-on (SSO).
  • An external identity provider exists under End users > Authentication. See Configure end user authentication.
  • Your IdP supports SCIM 2.0 and can provision to a custom application.

Turn on SCIM provisioning

  1. Go to Account avatar-icon.png, and then select Security.
  2. On the left side under End users, select Authentication.
  3. Under External identity providers, select the identity provider.
  4. In the SCIM provisioning section, select the SCIM provisioning checkbox. The help text beside it reads Provision, update, and deactivate end users in real time from your Identity provider (IdP).
  5. Select Save.

The section now shows SCIM base URL, with the hint Add this URL to your IdP's SCIM application, and two token slots under SCIM tokens. The base URL has the form https://<your account's host>/scim/v2/end-users/{idpConfigId}/, where {idpConfigId} identifies this identity provider. Select the copy icon beside it rather than typing the URL — the host is specific to your account's region, so the URL you copy is the one to use.

Note: You can select SCIM provisioning while adding a new identity provider, but the base URL and tokens are available only after you save it. Save the identity provider first, then reopen it to generate tokens.

Generate a SCIM token

Each identity provider's configuration has two token slots so that you can rotate a token without downtime.

  1. In the identity provider's SCIM provisioning section, select Generate next to Token 1.
  2. Select Copy, and store the token in your password manager. Celigo shows the token once and confirms with the message Token copied to clipboard. Save it now — you won't be able to view it again. After you leave the drawer, the slot shows only the first characters followed by dots.

Your identity provider sends the SCIM token as an HTTP bearer token:

Authorization: Bearer <token>

A token starts with scim_. Celigo accepts it only with the Bearer scheme. Most identity provider fields take the bare token and add the scheme themselves; a few send the field value verbatim and need you to enter Bearer, a space, and then the token. The setup guide for each identity provider says which kind its field is.

Celigo shows a token once, when you generate it, and stores only a hash. After that, the slot shows the first characters followed by dots. A token works for one configuration only: a workspace token can't provision end users, and an end-user token works only for its identity provider.

Generate into Token 2 only when you rotate. An occupied slot offers Revoke only; after you revoke it, the slot reads Token 1 - No token generated and Generate appears again.

Configure your identity provider

Create a SCIM 2.0 application in your IdP for this identity provider and point it at Celigo. The setup guides in the Learn more section at the end of this article give the field names for each product.

  1. Create a generic SCIM 2.0 provisioning application. Most IdPs need it to be separate from the OpenID Connect (OIDC) application that signs end users in.
  2. Enter the SCIM base URL as the connector or tenant URL, and the SCIM token as the bearer token or secret token.
  3. Map the user attributes listed in the following table.
  4. To push group memberships, turn on group provisioning in the IdP — Push Groups in Okta, the groups mapping in Microsoft Entra ID — and select the groups to push.
  5. Turn on provisioning for creates, updates, and deactivations, and assign the people who should have access.

Celigo reads the following attributes from a SCIM user and ignores every other attribute, including title, phone numbers, department, manager, employee number, and locale. Leaving those mappings in place in your identity provider does no harm.

SCIM attribute Celigo field Write rule
userName Email Required, and must be an email address. Celigo lowercases it and uses it to match existing users. It can't be changed through SCIM.
emails Email Ignored on create — Celigo copies userName into emails. A PATCH that replaces emails is rejected.
name.givenName, name.familyName Name Set when Celigo creates the user. For an existing user, set only if the name is blank.
name.formatted Name Used when present; otherwise Celigo joins the given and family names. Same fill-if-blank rule.
timezone Time zone A time zone name such as America/Los_Angeles. Set only if blank.
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization Company Set only if blank.
externalId External ID Your identity provider's identifier for the person. Celigo stores it for reconciliation.
active Active false disables the user and revokes their tokens. true re-enables them. Reconciled on every push that carries it.
password — Ignored. Okta sends a random password on every create.

End-user SCIM reads two attributes beyond the shared user profile.

SCIM attribute Celigo field Write rule
groups End-user group memberships Celigo matches each entry's display value to an end-user group by exact, case-sensitive name. A list, including an empty one, replaces every membership the identity provider manages. A push with no groups attribute leaves memberships unchanged.
urn:ietf:params:scim:schemas:celigo:2.0:EndUser:roles End-user roles Multi-valued. Celigo matches each value to an existing end-user role by exact, case-sensitive name; a value that matches no role is ignored. Replaces the roles that came from the identity provider.

Celigo doesn't resolve a groups entry's value as a group ID, so an entry that carries only a value creates a group named after that ID. Map the group name to display.

On the /Groups endpoint, available on the end-user configuration only, Celigo reads displayName as the matching key and members as the membership list. A changed displayName on an existing group is ignored. Celigo accepts externalId and doesn't return it, so an identity provider re-sends it on every update, which is harmless.

About group membership mapping

Group memberships are what give an end user access to MCP servers, so this is the mapping that matters most. Your IdP can send memberships two ways, and both behave the same in Celigo.

  • Through a group push. The IdP creates each group by name, the SCIM displayName, and pushes its member list. Okta's Push Groups and Microsoft Entra ID's group provisioning both work this way. When the IdP pushes a name that already exists, Celigo uses the existing group and replaces the members it manages from the IdP with the pushed list.
  • On the user. The IdP includes a groups attribute on the user, with a group name in each entry's display field.

Either way, Celigo matches each name to an end-user group by exact, case-sensitive name — Finance doesn't match finance. If no group with that name exists, Celigo creates one. The new group has no MCP servers assigned, so it grants nothing until you open it under Account > Users > End users > Groups and assign servers and capabilities. To avoid stray groups, create the Celigo groups first with names that match your IdP groups, or push only the IdP groups that map to Celigo groups.

Celigo manages only the memberships that came from the IdP. When the IdP drops a person from a group, Celigo removes that membership. A membership an administrator added directly in Celigo stays until an administrator removes it, even if the IdP never mentions that group.

The Users list and a group's member list don't show where a membership came from. The Access via column on an end user's MCP servers shows how the person reaches each server, Direct or through a named group, not whether the IdP or an administrator added the membership. To see that history, go to Account > Audit log and filter by source SSO.

Note: If you edit a SCIM-managed end user's groups in Celigo, the IdP's next push restores the memberships it manages. Change group membership in the IdP.

If you delete a Celigo group that the IdP still pushes, the next push finds no group with that name and Celigo creates a new one with no MCP servers assigned. Stop pushing the group in the IdP before you delete it in Celigo.

Group memberships are not the same as capability sets. SCIM pushes group memberships only. Assign capability sets from the group's own configuration or from the capability set's Access tab. See Create and manage capability sets on MCP servers.

About roles mapping

An end-user role bundles MCP server access into one assignable name, so a role can grant several servers in one step. The roles attribute in the urn:ietf:params:scim:schemas:celigo:2.0:EndUser schema lets your IdP assign roles the way it assigns groups.

  • Celigo matches each value to an existing end-user role by exact, case-sensitive name and assigns the matched roles.
  • A name that matches no role is ignored. SCIM never creates a role, so create the roles in Celigo before you map the attribute. Create and manage end-user roles through the Celigo REST API, at /v1/roles. See Celigo API reference.
  • Each push that carries roles replaces the roles that came from the IdP with what the IdP now sends. A role an administrator assigned directly stays.
  • The attribute is multi-valued, and your IdP needs it added as a custom attribute in the same way as the workspace accessLevel attribute.

If you don't use end-user roles, leave the attribute unmapped.

IdP push outcomes

When you assign someone to the application, the IdP pushes them, and Celigo responds in one of four ways.

  • The person is new to Celigo. Celigo creates the end user and their membership in your account and applies the pushed groups. They can connect an MCP client and sign in through this identity provider at once, without an invitation.
  • The person already exists as an end user in your account, from an invitation or from JIT provisioning. Celigo adopts the record, replaces the IdP-sourced memberships with what the IdP sent, and leaves direct memberships and direct MCP server assignments alone. The IdP sees a success.
  • The person is already managed by a different identity provider's SCIM configuration. Celigo rejects the push with User already exists under a different IdP configuration and changes nothing. One identity provider manages each end user.
  • The person's email domain isn't routed to this identity provider. If the identity provider routes Specific email domains and the pushed email is outside them, Celigo rejects the push with Email domain is not allowed for this IdP configuration. Add the domain to the identity provider, or fix the assignment in the IdP. An identity provider set to All end users accepts any domain. Celigo checks the domain first, so a person who fails both checks sees only the domain error.

If the same person is also a workspace user in your account, their workspace access is untouched. End-user SCIM manages end-user memberships only, though the two share one user record, so a name that is already set stays as it is.

Email verification for provisioned end users

When SCIM creates an end-user membership for someone whose email address isn't yet verified with Celigo, Celigo sends them the standard Verify your email address email at the moment of provisioning — the same email an invitation sends. Someone who is already verified, for example because JIT provisioning created them earlier, receives nothing.

Two things keep a provisioned person from getting stuck before they have verified.

  • A trusted identity provider's own verification is honored. When the person signs in through an identity provider Celigo treats as trusted, and that provider's token confirms the address is verified, Celigo accepts it and asks for no separate verification.
  • An expired link is recoverable at sign-in. If the verification link from provisioning has expired by the time the person first signs in, Celigo gives them a fallback in the sign-in flow — a fresh link or a one-time code — instead of turning them away.

Celigo sends no email for updates or deactivations, and none to administrators.

Deactivate and reactivate an end user

Unassign the person from the application in your IdP, or disable them there. When the IdP pushes the deactivation, Celigo does the following.

  • Disables the end user in your account. Their status changes to Disabled, and they can't sign in to any MCP server in the account.
  • Revokes the MCP OAuth access and refresh tokens their AI clients hold for this account. The client's next call or token refresh fails. Without SCIM, a deactivated person's MCP client keeps working on its refresh token for weeks.
  • Records the change in the audit log with source SSO.

Group memberships and direct MCP server assignments stay on the record. When the IdP reactivates the person, Celigo re-enables the end user with the same access, and they sign in again from their client. Revoked tokens aren't restored. Other accounts where the person is an end user aren't affected.

Deleting a person in your IdP is not the same as deactivating them. Celigo rejects a delete request with 501 Not Implemented and leaves the end user as they were.

Rotate or revoke a token

  1. Go to Account avatar-icon.png, and then select Security > End users > Authentication, and select the identity provider.
  2. Under SCIM provisioning, select Generate next to the empty slot, the one that reads No token generated, and copy the new token.
  3. In your IdP, replace the bearer token, and confirm in the IdP's provisioning log that pushes succeed.
  4. Select Revoke next to the old token. The slot reads No token generated again.

Revoking takes effect at once. If you revoke the only active token, every push fails with an authentication error until you generate a new one and update the IdP.

Turn off SCIM provisioning

  1. Go to Account avatar-icon.png, and then select Security > End users > Authentication, and select the identity provider.
  2. Under SCIM provisioning, clear the SCIM provisioning checkbox, and then select Save.

Celigo revokes both tokens and rejects further SCIM requests for this identity provider. End users the IdP provisioned stay, with their groups, and sign in as before. Group sync and JIT provisioning on the same identity provider aren't affected. Deleting the identity provider removes its SCIM configuration with it. Disabling the identity provider stops sign-ins but not SCIM pushes, so to pause provisioning, clear the checkbox.

Learn more