`
4. Click Test Connection — you should get a green success banner
5. Click Save
### Step 4 - Configure for Attribute Mappings
Entra's defaults work but need minor cleanup. Under Mappings, open Provision Entra ID Users.
Required user attributes (keep these):
| Entra attribute | SCIM attribute | |
|---|
| userPrincipleName | userName | |
| IsSoftDeleted | active | |
| mail | emails[type eq "work"].value | |
| givenName | name.givenName | |
| surname | name.familyName | |
| displayName | displayName | |
| objectId | externalId | |
| | |
Important: externalId mapped to objectId is what blockbrain uses for idempotency — if a user is re-provisioned, blockbrain finds the existing record by Entra object ID and returns 200 instead of creating a duplicate.
For Groups, open Provision Entra ID Groups:
| Entra attribute | SCIM attribute | |
|---|
| displayName | displayName | |
| objectId | externalId | |
| members | members | |
Entra automatically flattens nested group hierarchies server-side before sending — blockbrain's Entra adapter expects this and treats all members entries as direct user IDs.
### Step 5 - Scope which users/groups get provisioned
Under Settings → Scope, choose one of:
* "Sync only assigned users and groups" — recommended; you control who is provisioned by assigning them to this Enterprise App
* "Sync all users and groups" — provisions your entire directory
To assign users/groups: go to Users and groups → Add user/group.
### Step 6 - Start provisioning
1. Under Provisioning, set Provisioning Status to On
2. Click Save
3. Click Provision on demand to test with a specific user before the full cycle runs
### What happens when Entra provisions a user
Entra POST /scim/v2/Users → blockbrain checks MongoDB for existing userName or externalId (idempotent)\
→ if new: creates identity in Zitadel, writes to MongoDB mapping\_user\
→ user auto-added to tenant's general group\
→ effectiveRole computed and synced to Zitadel project grant\
→ returns 201 (or 200 if already existed)
### When a user is disabled in Entra (or removed from the app scope):
Entra PATCH /scim/v2/Users/{id}
{ "Operations": [{ "op": "replace", "path": "active", "value": false }] }
→ MongoDB status → "inactive"\
→ Zitadel: POST /v2/users/{id}/deactivate\
→ user can no longer log in to blockbrain
▎ Note: Entra sometimes sends active: "False" as a string — the handler covers both false (boolean) and "False" (string).
### What happens when Entra provisions a group
```
Entra POST /scim/v2/Groups
{ "displayName": "KB Builders", "externalId": "", "members": [...] }
```
→ blockbrain checks by externalId (idempotent)\
→ creates group\_user record in MongoDB with isAutoSync: true\
→ members list contains Zitadel user IDs (Entra flattens nesting automatically)\
→ returns 201
Groups in blockbrain default to the consumer role. To elevate a group to builder, admin, etc., update the group's role via the blockbrain admin interface — that role is then applied as the effectiveRole for all members.
### Provisioning cycle
Entra runs an incremental sync every \~40 minutes. A full cycle runs every \~24 hours. You can trigger Provision on demand anytime for a specific user/group.
### Troubleshooting
| Symptom | Check | |
|---|
| Test Connection fails 401 | Token is wrong or provider mismatch — regenerate with "provider": "entra" | |
| Test Connection fails 404 | Tenant URL wrong — must end in /scim/v2 not /scim/v2/ | |
| Duplicate users | externalId → objectId mapping missing from attribute map | |
### Role Provisioning
#### The core problem
SCIM has no standard for roles. Entra sends roles through an AppRoleAssignmentsComplex attribute using a non-obvious format. The code handles this in parseSCIMRoleValue inside repository.ts:9.
What Entra actually sends
When you assign an App Role to a user in Entra, it arrives in the SCIM PATCH body like this:
{
"Operations": [{
"op": "replace",
"path": "roles[primary eq "True"].value",
"value": "{"id":"some-uuid","value":"admin","displayName":"Blockbrain Admin"}"
}]
}
The value field is a stringified JSON object, not a plain string. The code at repository.ts:13 detects this, parses it, and extracts the inner value field ("admin") as the actual role key.
Entra may also send roles as an array of objects (without the filter path), in which case value\[0].value is used.
#### Blockbrain role names
The valid roles are defined in role-engine.ts. They must match exactly (case-insensitive):
* consumer
* builder
* pro-user
* admin
* superadmin
Anything that doesn't match falls back to consumer.
#### How to configure this in Entra
**Step 1 — Define App Roles in your Enterprise Application**
In Azure Portal, go to your Enterprise App → App roles → Create app role. Create one role per blockbrain role level:
Display name: Blockbrain Consumer\
Value: consumer\
Description: Read-only access Allowed: Users/Groups
Display name: Blockbrain Builder\
Value: builder\
...
Display name: Blockbrain Admin Value: admin ...
The Value field is what blockbrain reads. It must be exactly consumer, builder, pro-user, admin, or superadmin.
**Step 2 — Add the attribute mapping in Entra SCIM**
In the Enterprise App → Provisioning → Attribute Mappings → Provision Entra ID Users, add a new mapping:
* Mapping type: Expression
* Expression: AppRoleAssignmentsComplex(\[appRoleAssignments])
* Target attribute: roles
This is what causes Entra to send the stringified JSON object format the code expects.
**Step 3 — Assign roles to users or groups**
In the Enterprise App → Users and groups, when you assign a user or group, Entra will ask you to select a role. Pick the appropriate blockbrain role. Users with no role assignment get consumer by default.