SCIM 2.0 (IdP provisioning)
SCIM 2.0 implementation (RFC 7643/7644) for Microsoft Entra ID and Okta to create, update and deactivate users and groups. The endpoints live under /api/scim/v2 (outside /api/v1):
Base URL: https://www.etershield.com/api/scim/v2 (the tenant URL appears in Settings → SSO, next to the "Generate SCIM token" button).
Authentication
Authorization: Bearer <token_scim>: only this header (SCIM does not accept x-api-key). The token is a named key (SHA-256 hash, 365-day validity, revocable in the API keys list) with the explicit scope /api/scim/v2. It is generated by an ADMIN in Settings → SSO and is shown only once.
- The tenant's single key and named keys without scopes (full access) are refused on SCIM: creating and deactivating accounts is too much power for a key meant, for example, to send Wazuh alerts.
- The reverse also holds: the SCIM token, because it has the scope
/api/scim/v2, is refused on any other route (/api/v1/*). - Missing, unknown, expired or revoked token, one without the SCIM scope, or one for an inactive tenant →
401. - Rate limit: 600 requests/min per tenant (Entra sends bursts in the initial cycle); exceeded →
429withscimType: tooMany.
Endpoints
| Method | Route | Description |
|---|---|---|
| GET | /ServiceProviderConfig |
Capabilities: patch and filter (max. 100 results) supported; bulk, sort, etag and changePassword not supported |
| GET | /ResourceTypes · /Schemas |
Discovery of the User and Group types and of the attributes read/returned |
| GET | /Users |
Lists users (startIndex / count pagination, max. 100 per page) |
| POST | /Users |
Creates a user → 201 |
| GET · PUT · PATCH · DELETE | /Users/{id} |
Read · replace · modify (PatchOp) · deactivate (204) |
| GET | /Groups |
Lists groups |
| POST | /Groups |
Creates a group (with optional members) → 201 |
| GET · PUT · PATCH · DELETE | /Groups/{id} |
Read · replace name and members · modify name/members · delete (204) |
Responses use Content-Type: application/scim+json. The {id} is the EterShield one (returned on POST and in the listing).
Mapping
- User = the user's membership (
Membership) in this tenant.userNameandemails[primary]= email;name/displayName= name;title= job title;externalId= identifier in the IdP;active= membership status;groups= read-only (this tenant's departments). - Group = tenant department (
TenantDepartment);displayName= name;members= the tenant's users.
Filters
Only eq (it is what Entra and Okta send to find a resource before creating it); the attribute name is case-insensitive, and so is the comparison of email and group name.
| Resource | Filterable attributes | Example |
|---|---|---|
| Users | userName, externalId |
GET /Users?filter=userName eq "ana@empresa.pt" |
| Groups | displayName, externalId |
GET /Groups?filter=displayName eq "Direcção" |
Any other filter (co, sw, and, or, other attributes…) responds 400 with scimType: invalidFilter.
Behavior
- Create user (
POST /Users): requires a validuserName(or primary email). If the tenant's SSO hasemailDomains, the email domain must be on the list. The initial role is the SSO'sdefaultJitRole(defaultUSER). It respects the plan's user limit (403if reached). Withactive: falseit creates the membership already inactive. DELETE /Users/{id}deactivates: it does not delete. The account and history remain, and GDPR anonymization is a separate operation.PATCH/PUTwithactive: falsehas the same effect;active: truereactivates. The tenant's last administrator is never deactivated (400,scimType: mutability).- Users PATCH (
replace/add, with or withoutpath):active(also accepts"True"/"False"as text, as Entra sends it),userName,displayName,name.*,title,externalIdandemails[…].value.removeoperations on optional attributes are ignored. - Groups PATCH:
displayName,externalIdandmemberswithadd,remove(includingmembers[value eq "id"]) andreplace. Members must be users of the tenant (400otherwise).PUTreplaces the name and the member list. - Group → role map: if the tenant's SSO has "Role per group" (
groupRoleMap, group name → role), the role of users created by SCIM follows group membership: same rule as JIT, with precedence ADMIN > MANAGER > USER > AUDITOR > VIEWER; with no mapped group,defaultJitRoleapplies. It never assignsSUPER_ADMIN, never changes the role of anyone not created by SCIM and never removes the last administrator. - External members: a
POST /Userswith the email of an account that already exists in another organization does not create a new account: it creates (or reactivates) that account's membership in this tenant, as an external member. An external member's name and email belong to the home organization and are not changed by this customer's IdP (the request is accepted and those fields are ignored, so as not to break the IdP sync). The job title,externalIdand status belong to the membership and update normally. Deactivating an external member only removes their access to this tenant. The tenant can refuse external members (allowExternalMembers, Settings → Security) and an external member's entry requires MFA on their account. - Auditing: each creation, change, deactivation and role change is recorded in the audit log as
scim:<token name>.
Errors
Format urn:ietf:params:scim:api:messages:2.0:Error, with status, detail and, where applicable, scimType.
| Code | When |
|---|---|
400 |
Invalid JSON or PatchOp without Operations (invalidSyntax); unsupported filter (invalidFilter); missing userName / displayName, domain outside the SSO domains or member not in the tenant (invalidValue); deactivating the last administrator (mutability) |
401 |
Missing, invalid, expired or revoked token, one without the /api/scim/v2 scope, or one for an inactive tenant |
403 |
Plan user limit reached; tenant that refuses external members; external account blocked on the platform |
404 |
User or group does not exist in this tenant |
409 |
userName already exists (or is already an active member), duplicate externalId, duplicate group displayName (uniqueness) |
429 |
Rate limit (tooMany) |
500 |
Internal error (no detail) |
IdP Configuration
Microsoft Entra ID (Enterprise application → Provisioning → Automatic mode):
| Field | Value |
|---|---|
| Tenant URL | https://www.etershield.com/api/scim/v2 |
| Secret Token | the SCIM token generated in Settings → SSO |
After "Test Connection", the usual mappings are userPrincipalName → userName, displayName → displayName, jobTitle → title, objectId → externalId and the account status → active. Removing a user's assignment in Entra arrives as active: false (or DELETE) and deactivates them.
Okta (SCIM 2.0 application → Provisioning → Integration): SCIM connector base URL = https://www.etershield.com/api/scim/v2; Unique identifier field for users = userName; Authentication Mode = HTTP Header, with the SCIM token in the format Bearer <token_scim>; actions to enable: Push New Users, Push Profile Updates and Push Groups.
After configuring the IdP, validate with Microsoft's SCIM Validator. The SCIM token must never be kept in versioned files or tickets: only in the IdP's secret vault.