Inbound SCIM

With inbound SCIM, your identity provider (such as Okta or Microsoft Entra ID) manages your directory’s users and groups over SCIM 2.0. It creates and updates users, suspends and deprovisions them, and pushes groups and their members. Suspending someone there ends their access to every application that trusts your directory, on their next request.

This is separate from IAM’s SCIM provisioning, which provisions your organization’s members for the console. The two have different base URLs and tokens. An organization can use both, with a separate app for each at the identity provider.

Before you start

• Add the identity provider your people sign in through, and route your verified email domains to it. SCIM provisions only people whose email address is in a verified domain routed to the token’s identity provider.
• Creating and deleting directory SCIM tokens needs sso.scimTokens.create and sso.scimTokens.delete, which are in SsoFullAccess. A SCIM token provisions and suspends people, so treat these as administrator permissions.

Create a SCIM token

A directory SCIM token names the identity provider whose people it provisions. Everything the token creates belongs to that identity provider, and the token sees and changes only that identity provider’s users and groups.

ezgh sso scim-tokens create okta-scim --identity-provider Okta > scim-token.txt

curl -X POST https://sso.ezghcloud.com/v1/organizations/$ORG_ID/sso/scim/tokens \
  -H "Authorization: Bearer $EZGH_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "okta-scim", "identityProviderId": "<identity provider ID>" }'

A token that names no identity provider can’t provision users (400, invalidValue): no domain routes to it.

Configure your identity provider

In your identity provider’s SCIM 2.0 settings, set:

The SCIM app can be the same app your people sign in with, or a separate one: the token decides which identity provider the users belong to.

What SCIM changes

While a live SCIM token names an identity provider:

• It creates, updates, suspends and deprovisions users in the domains routed to it, and pushes groups.
• Only provisioned users sign in through it. Signing in through that identity provider admits only users its SCIM provisioned. That includes people who signed in before SCIM was turned on: they sign in again once SCIM provisions their email address, which takes their existing user over. Nobody is created on first sign-in (no JIT users), and someone it hasn’t provisioned sees an error page. The identity provider’s provisioning shows { "jit": false, "scim": true }.
• Its users and groups are locked (locked: true). You can’t update, suspend, reactivate or delete its users, or rename, delete or change the members of its groups, in EZGH SSO. These requests return 409 with managed_by_scim. The console shows Managed by your identity provider.
• You still manage their assignments, their sessions, and provisioned users’ membership in groups you created.
• The identity provider’s group mappings apply only to groups you created.

Users

A provisioned user is a directory user with source: scim. Their SCIM id is the user’s ID.

• Email address: the primary email, else the work email, else the first email, else userName, in lowercase. It must be in a verified domain routed to the token’s identity provider (400, invalidValue), checked on every write: a domain that loses its verification or routing stops provisioning at once. acme.com doesn’t cover eu.acme.com. An email address another user of the directory has is 409, uniqueness.
• Name: displayName, else name.formatted, else name.givenName and name.familyName, else the email address. givenName and familyName come from name, and department from the enterprise extension.
• Existing users: creating a user whose email address the directory already has takes that user over when they’re hosted, created by JIT, or provisioned by a token that no longer exists. They become source: scim, sign in only through the identity provider, and lose their password, TOTP, passkeys and unused activation links; a pending user becomes active. A user that this identity provider already provisioned, or that another identity provider’s live token manages, is 409, uniqueness.
• New users count against sso.users.count. A full quota is 403 (quota_exceeded).
• active: false suspends the user: their sessions, sign-ins in progress, unused links, application grants and refresh tokens, and EZGH resource tokens end on their next request, and applications with a back-channel logout URI are told. They can’t sign in. active: true restores their sign-in; ended sessions and grants don’t come back. A PUT without active leaves it unchanged.
• DELETE deprovisions the user: they’re removed as DeleteUser removes a user, with their groups, assignments, sessions, grants and IAM policy attachments, and their quota is freed.

Stored attributes: userName (unique in the directory, compared without case), externalId, name, displayName, emails (up to 10), active, and the enterprise extension’s department and manager. groups is read-only. Other attributes are accepted and ignored.

Changes are pushed on to applications that provision the user. See Outbound provisioning.

Groups

A provisioned group is a directory group with source: scim. Its SCIM id is the group’s ID, and displayName its name.

• Group names are unique in the directory, including groups you created: pushing a group whose name another group has is 409, uniqueness.
• Members are users only, and each must be a user this identity provider provisioned (400, invalidValue). Groups can’t contain groups. A PUT without members leaves them unchanged.
• New groups count against sso.groups.count.
• Provisioned groups work like any other group: in the groups claim, SAML attributes and assignments.

Supported operations

• /Users and /Groups list only what the token’s identity provider provisioned, oldest first. Lists take startIndex, count (default 100, at most 200; 0 returns only the total), attributes and excludedAttributes.
• filter takes eq comparisons joined with and. Users can be filtered by userName, externalId, id, displayName, active and emails (emails.value, emails[type eq "work"].value). Groups can be filtered by displayName, externalId, id and members (members.value, members[value eq "…"]).
• PATCH supports add, replace and remove, in the forms Okta and Microsoft Entra ID send. It applies all operations or none. A group PATCH returns 204.
• Request bodies are at most 1 MiB.
• Not supported: bulk operations, /Me, POST /.search, sorting, ETags (If-Match is ignored), password changes and nested groups.

Errors use the SCIM error format:

Activity in Trails

Every change your identity provider makes, and every refused change, is recorded in Trails with eventSource sso.ezghcloud.com: ProvisionUser, UpdateProvisionedUser, SuspendUser, ReactivateUser, DeprovisionUser, ProvisionGroup, UpdateProvisionedGroup, UpdateGroupMembership and DeprovisionGroup. userIdentity is the EzghService scim.ezghcloud.com, with the token’s ID and name. Reads aren’t recorded, and the token never is.

Rotate a token

Tokens don’t expire. To rotate one, create a second token for the same identity provider, switch your identity provider to it, then delete the first. Both name the same identity provider, so nothing changes for its users and groups.

Turn SCIM off

Deleting the last token that names an identity provider turns SCIM off for it. Deleting the identity provider revokes its tokens too.

ezgh sso scim-tokens delete okta-scim

When SCIM turns off for an identity provider:

• It can no longer change anything: the token fails from its next request.
• Its users and groups stay, unlocked: you can edit, suspend, reactivate and delete them in EZGH SSO. Suspended users stay suspended until you reactivate them.
• Signing in through the identity provider creates people on their first sign-in again, and links existing users by email address.
• A new token for the identity provider manages its users and groups again.