SCIM Provisioning
Provision organization membership from an enterprise identity provider
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.
Organization Scope
A SCIM connection is bound to the current organization. Create and manage separate connections for separate organizations.
Create The Connection
-
Open Enterprise Identity Setup for the organization.
-
Select the Default role template in the Access Policy step and choose Save access policy.
-
In SCIM Provisioning, choose Create SCIM connection.
-
Copy the displayed credential and store it securely in your identity provider. It is displayed once and cannot be recovered later.
-
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.
One-Time Credential
Confirm that the credential is saved before closing the dialog. Legacy SCIM credentials and provisioning tokens are not supported.
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
externalIdmatches the paired provider's validated OIDCsubor signed SAMLNameID. - A Group's
externalIdis 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.
Use Stable Group IDs
Group role mappings are keyed by the provider's stable Group external ID, not its display name. Display names can change; the external ID preserves the mapping.
Personnel Numbers
Map the identity provider's personnel number to employeeNumber in the standard enterprise User extension:
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "employee@example.com",
"externalId": "paired-provider-subject",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "0042"
}
}Once SCIM supplies the attribute, the identity provider owns that employee's personnel number in this organization. Z8 shows it read-only in employee settings; make corrections in the identity provider. Other employee fields retain their existing editing rules. Users provisioned without this attribute keep local editing until the identity provider supplies it.
Z8 trims surrounding whitespace and preserves case and leading zeros. The number can contain at most 50 characters after trimming. It must be unique within the organization, including among former employees; comparisons ignore case. The same number can be used in a different organization.
| Provider operation | Result |
|---|---|
| Create, replace or PATCH with a number | Saves the number and assigns its ownership to the identity provider. |
Explicit null, empty or whitespace-only number | Clears the number and keeps IdP ownership. |
PATCH remove on urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber, or on the enterprise extension | Clears the number and keeps IdP ownership. |
| Full User replacement omitting an IdP-owned number | Clears the number; local editing stays locked. |
| Unrelated PATCH, group update or projection replay | Leaves the number and its ownership unchanged. |
A replacement that omits a number the identity provider has never supplied preserves the existing local number. Credential rotation also preserves ownership. SCIM User reads return the current personnel number from the employee record.
If another current or former employee already holds the number, Z8 returns HTTP 409 with scimType: "uniqueness". The entire User request is refused, including other changes in the same PATCH. Correct the conflict in the identity provider and retry. A personnel-number update never reactivates employment that ended through offboarding; that requires an explicit rehire in Z8.
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
- 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. - Send an authenticated SCIM User or Group request.
- Refresh the connection status and review recent events.
A user is rejected or not linked
- Verify that the SCIM User
externalIdexactly matches the paired OIDCsubor signed SAMLNameID. - Do not substitute an email address for
externalId. - Confirm the user belongs to the intended organization and retry a complete User and Group reprovisioning cycle.
A group mapping changed unexpectedly
- Check that the provider kept the Group
externalIdstable. - Restore the intended stable external ID in the provider mapping.
- Run complete User and Group reprovisioning to reconcile the organization.