SCIM Provisioning

SCIM provisioning connects one enterprise identity provider to one Z8 organization. Organization owners and admins configure it in Settings -> Enterprise -> Enterprise Identity Setup.

---

Before You Start

Configure and test the paired OIDC or SAML single sign-on provider first. Every SCIM User externalId must equal the validated OIDC sub or the signed SAML NameID from that paired provider. Z8 does not fall back to email matching.

Choose a mandatory default role template before creating the connection. It defines the initial organization role for provisioned users; a connection cannot be created without an eligible template.

---

Create The Connection

1. Open Enterprise Identity Setup for the organization.

2. In SCIM Provisioning, select the default role template and choose Create SCIM connection.

3. Copy the displayed credential and store it securely in your identity provider. It is displayed once and cannot be recovered later.

4. Configure the identity provider with this SCIM endpoint:

   https://your-z8-domain.example/api/auth/scim/v2

The credential expires after one year. Do not put credentials in tickets, documentation, chat, or screenshots.

---

Verify And Operate

Send authenticated SCIM User or Group traffic from the identity provider, then refresh the connection status. Z8 marks the connection verified only after it observes authenticated provider traffic. Review the recent events list when diagnosing setup or lifecycle changes.

Rotate credentials before expiry or whenever a credential may be exposed. Rotation creates an overlap period so you can update the identity provider before revoking the old credential. Revoke a credential when it must stop provisioning immediately.

---

Provisioning Behavior

SCIM provisioning supports Users and Groups. For a complete correction after a provider-side change, run a full User and Group reprovisioning cycle from the identity provider.

• A User is provisioned only when its externalId matches the paired provider's validated OIDC sub or signed SAML NameID.
• A Group's externalId is the stable key for its role mapping. Do not change it when renaming the group.
• Deactivation is organization-local and reversible: it removes access in this organization without deleting the underlying user or affecting another organization.
• Re-enabling a user through SCIM restores the organization-local lifecycle state when the provider sends the corresponding update.

Review resulting organization members and employee records in Employee Management.

---

Decommission A Connection

Choose Decommission only when the organization will no longer use this SCIM connection. Decommissioning is irreversible: it retires the managed connection and prevents further provisioning. It is not a temporary pause; use credential rotation or revocation for operational changes instead.

If creation or decommissioning is interrupted, use Refresh creation status or refresh the connection status to reconcile the recorded lifecycle state before retrying other changes.

---

Troubleshooting

The connection is not verified

1. Confirm the identity provider uses the absolute endpoint shown in Enterprise Identity Setup, such as https://your-z8-domain.example/api/auth/scim/v2, and the current credential.
2. Send an authenticated SCIM User or Group request.
3. Refresh the connection status and review recent events.

A user is rejected or not linked

1. Verify that the SCIM User externalId exactly matches the paired OIDC sub or signed SAML NameID.
2. Do not substitute an email address for externalId.
3. Confirm the user belongs to the intended organization and retry a complete User and Group reprovisioning cycle.

A group mapping changed unexpectedly

1. Check that the provider kept the Group externalId stable.
2. Restore the intended stable external ID in the provider mapping.
3. Run complete User and Group reprovisioning to reconcile the organization.