SCIM provisioning

With SCIM provisioning, your identity provider (such as Okta or Microsoft Entra ID) manages your organization’s people and groups over SCIM 2.0. It creates and updates users, suspends and removes them, and pushes groups and their members. You attach policies to the provisioned groups in EZGH Cloud.

SCIM is on while your organization has at least one SCIM token.

Before you start

• SCIM provisions only people whose email address is in a domain, or a subdomain of a domain, verified on one of your organization’s SSO providers. Verify the domain in the console under IAM > Directory first. See Directory.
• Creating and deleting SCIM tokens needs scim.tokens.create and scim.tokens.delete, which are in IAMFullAccess. A SCIM token provisions and suspends people, so treat these as administrator permissions.

Turn SCIM on

Create a SCIM token. The first token turns SCIM on.

ezgh iam scim tokens create okta
ezgh iam scim status

curl https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/scim/tokens \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "okta"}'

Configure your identity provider

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

Turn on creating, updating and deactivating users, and push the groups you want to manage. The Setup tab of IAM > SCIM has steps and attribute mappings for Okta and Microsoft Entra ID.

Then attach policies to the provisioned groups. See Attach policies to a group.

What SCIM changes

While SCIM is on:

• Your identity provider adds, updates, suspends and removes people in your verified domains.
• Signing in through your SSO provider no longer adds people, and no longer syncs SSO group mappings. Someone your identity provider hasn’t provisioned can’t sign in through SSO.
• You can’t remove provisioned users, or rename, delete or change the members of provisioned groups, in EZGH Cloud. These requests return 409 with managed_by_scim.
• You can’t invite email addresses in your verified domains. You can still invite people from other domains.
• You still manage policies for provisioned users and groups, provisioned users’ membership in groups you created, your own groups, bots and API keys.

Provisioned users and groups show Managed by SCIM in the console.

Users

A provisioned user’s email address is their primary email, else their work email, else their first email, else userName. It must be in a verified domain.

• If an account with that email address exists and isn’t in another organization, it’s linked and joins your organization. A person in another organization is refused with 409.
• A provisioned user’s email address counts as verified.
• active: false suspends the user: they can’t sign in by any method, they’re signed out everywhere, and their API keys are revoked. They stay in the organization with their groups and policies. active: true restores their sign-in; revoked API keys don’t come back.
• DELETE deprovisions the user: they’re suspended, then removed from the organization with their group memberships, policies and API keys.
• The root user can’t be suspended or deleted through SCIM (400, mutability). Make someone else root first.

Stored attributes: userName (unique in the organization, 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.

Groups

A provisioned group is an ordinary group whose name (displayName) and members come from your identity provider. Members are users only; groups can’t contain groups. displayName is unique among provisioned groups, compared without case. Deleting a group through SCIM removes its memberships and policy attachments.

Supported operations

• /Users and /Groups list only what SCIM provisioned. Lists take startIndex, count (default 100, at most 200), 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.
• Not supported: bulk operations, /Me, POST /.search, sorting, ETags, password changes and nested groups.

Errors use the SCIM error format:

Every change your identity provider makes is recorded in Trails.

Rotate a token

Tokens don’t expire. To rotate one, create a second token, switch your identity provider to it, then delete the first. The token list shows when each token was Last used.

Turn SCIM off

Deleting your organization’s last SCIM token turns SCIM off. In the console, select Delete next to the token on IAM > SCIM, then Delete and turn off SCIM. With the CLI, run ezgh iam scim tokens delete <token>. See DeleteScimToken.

When SCIM turns off:

• Your identity provider can no longer change anything.
• Provisioned groups become ordinary groups, and active provisioned users ordinary members, that you manage in EZGH Cloud.
• Suspended users stay suspended until you reactivate them: open the user’s page and select Reactivate (users.reactivate), or call ReactivateUser.
• Signing in through your SSO provider adds people again and syncs SSO group mappings on every sign-in.