System zur domänenübergreifenden Identitätsverwaltung (SCIM)

Voraussetzungen

1. Du musst Entra-ID-Administrator sein

2. Du musst Blockbrain-Administrator sein

Schritt 1 - SCIM-Token in Blockbrain generieren

1. Gehe zum Tab Admin → Integrationen → SCIM Provisioning → Verwalten → Token generieren

2. Kopiere den Token für die nächsten Schritte

Schritt 2 - Eine Enterprise-Anwendung in Azure erstellen

1. Gehe zum Azure-Portal → Entra ID → Enterprise-Anwendungen

2. Klicke auf Neue Anwendung → Eigene Anwendung erstellen

3. Benenne sie blockbrain (oder den Namen deiner Organisation), wähle „Integriere jede andere Anwendung, die du nicht in der Galerie findest“

4. Klicke auf Erstellen

Schritt 3 - Bereitstellung konfigurieren

1. Gehe zu Bereitstellung → Los geht's

2. Setze den Bereitstellungsmodus auf Automatisch

3. Unter Administrator-Anmeldeinformationen:

   1. Mandanten-URL, Wert: https://integrations.theblockbrain.ai/scim/v2

   2. Geheimer Token, Wert: <Token aus Schritt 1>

4. Klicke auf Verbindung testen — du solltest ein grünes Erfolgsbanner erhalten

5. Klicke auf Speichern

Schritt 4 - Für Attributzuordnungen konfigurieren

Entras Standardwerte funktionieren, brauchen aber etwas Bereinigung. Öffne unter Zuordnungen Entra-ID-Benutzer bereitstellen.

Erforderliche Benutzerattribute (diese beibehalten):

Entra-Attribut	SCIM-Attribut
userPrincipleName	userName
IsSoftDeleted	active
mail	emails[type eq "work"].value
givenName	name.givenName
surname	name.familyName
displayName	displayName
objectId	externalId

Wichtig: Das auf objectId gemappte externalId ist das, was blockbrain für die Idempotenz verwendet — wenn ein Benutzer erneut bereitgestellt wird, findet blockbrain den vorhandenen Datensatz über die Entra-Objekt-ID und gibt 200 zurück, statt ein Duplikat zu erstellen.

Für Gruppen öffne Bereitstellung von Entra-ID-Gruppen:

Entra-Attribut	SCIM-Attribut
displayName	displayName
objectId	externalId
members	members

Entra glättet verschachtelte Gruppenhierarchien serverseitig automatisch, bevor es sendet — der Entra-Adapter von blockbrain erwartet das und behandelt alle members-Einträge als direkte Benutzer-IDs.

Schritt 5 - Festlegen, welche Benutzer/Gruppen bereitgestellt werden

Unter Einstellungen → Bereich wähle eine der folgenden Optionen:

• "Nur zugewiesene Benutzer und Gruppen synchronisieren" — empfohlen; du bestimmst, wer bereitgestellt wird, indem du sie dieser Enterprise-App zuweist

• "Alle Benutzer und Gruppen synchronisieren" — stellt dein gesamtes Verzeichnis bereit

Um Benutzer/Gruppen zuzuweisen: gehe zu Benutzer und Gruppen → Benutzer/Gruppe hinzufügen.

Schritt 6 - Bereitstellung starten

1. Setze unter Bereitstellung den Bereitstellungsstatus auf Ein

2. Klicke auf Speichern

3. Klicke auf Bereitstellung bei Bedarf, um vor dem vollständigen Zyklus mit einem bestimmten Benutzer zu testen

Was passiert, wenn Entra einen Benutzer bereitstellt

Entra POST /scim/v2/Users → blockbrain prüft MongoDB auf vorhandenen userName oder externalId (idempotent) → wenn neu: erstellt Identität in Zitadel, schreibt Zuordnung in MongoDB mapping_user → Benutzer wird automatisch zur allgemeinen Gruppe des Mandanten hinzugefügt → effectiveRole wird berechnet und mit dem Projekt-Grant von Zitadel synchronisiert → gibt 201 zurück (oder 200, wenn bereits vorhanden)

Wenn ein Benutzer in Entra deaktiviert wird (oder aus dem App-Bereich entfernt wird):

Entra PATCH /scim/v2/Users/{id}
{ "Operations": [{ "op": "replace", "path": "active", "value": false }] }

→ MongoDB-Status → „inactive“ → Zitadel: POST /v2/users/{id}/deactivate → Der Benutzer kann sich nicht mehr bei blockbrain anmelden

▎ Hinweis: Entra sendet manchmal active: "False" als String — der Handler berücksichtigt sowohl false (Boolean) als auch "False" (String).

Was passiert, wenn Entra eine Gruppe bereitstellt

Entra POST /scim/v2/Groups
    { "displayName": "KB Builders", "externalId": "<objectId>", "members": [...] } 

→ blockbrain prüft anhand von externalId (idempotent) → erstellt in MongoDB einen group_user-Datensatz mit isAutoSync: true → die Mitgliederliste enthält Zitadel-Benutzer-IDs (Entra glättet Verschachtelungen automatisch) → gibt 201 zurück

Gruppen in blockbrain haben standardmäßig die Rolle consumer. Um eine Gruppe auf builder, admin usw. hochzustufen, aktualisiere die Rolle der Gruppe über die Blockbrain-Adminoberfläche — diese Rolle wird dann als effectiveRole für alle Mitglieder angewendet.

Bereitstellungszyklus

Entra führt etwa alle 40 Minuten eine inkrementelle Synchronisierung durch. Ein vollständiger Zyklus läuft etwa alle 24 Stunden. Du kannst jederzeit Bereitstellung bei Bedarf für einen bestimmten Benutzer/eine bestimmte Gruppe auslösen.

Fehlerbehebung

Symptom	Prüfen
Verbindungstest schlägt mit 401 fehl	Token ist falsch oder der Provider stimmt nicht überein — mit "provider": "entra" neu generieren
Verbindungstest schlägt mit 404 fehl	Mandanten-URL falsch — muss auf /scim/v2 enden, nicht auf /scim/v2/
Doppelte Benutzer	externalId → objectId-Zuordnung fehlt in der Attributzuordnung

Rollenbereitstellung

Das Kernproblem

SCIM hat keinen Standard für Rollen. Entra sendet Rollen über ein AppRoleAssignmentsComplex-Attribut in einem nicht offensichtlichen Format. Der Code behandelt das in parseSCIMRoleValue in repository.ts:9.

Was Entra tatsächlich sendet

Wenn du einem Benutzer in Entra eine App-Rolle zuweist, kommt sie im SCIM-PATCH-Body so an:

{
"Operations": [{
    "op": "replace",
    "path": "roles[primary eq \"True\"].value", 
    "value": "{\"id\":\"some-uuid\",\"value\":\"admin\",\"displayName\":\"Blockbrain Admin\"}"
}]
}

Das Wertfeld ist ein Stringified JSON-Objekt, kein einfacher String. Der Code in repository.ts:13 erkennt das, parst es und extrahiert das innere value-Feld ("admin") als den tatsächlichen Rollenschlüssel.

Entra kann Rollen auch als Array von Objekten senden (ohne den Filterpfad); in diesem Fall wird value[0].value verwendet.

Blockbrain-Rollennamen

Die gültigen Rollen sind in role-engine.ts definiert. Sie müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert):

• consumer

• builder

• pro-user

• admin

• superadmin

Alles, was nicht passt, fällt auf consumer zurück.

So konfigurierst du das in Entra

Schritt 1 — App-Rollen in deiner Enterprise-Anwendung definieren

Im Azure-Portal gehe zu deiner Enterprise-App → App-Rollen → App-Rolle erstellen. Erstelle eine Rolle pro blockbrain-Rollenstufe:

Anzeigename: Blockbrain Consumer Wert: consumer Beschreibung: Nur-Lese-Zugriff Zulässig: Benutzer/Gruppen

Anzeigename: Blockbrain Builder Wert: builder ...

Anzeigename: Blockbrain Admin Wert: admin ...

Das Feld Wert ist das, was blockbrain liest. Es muss exakt consumer, builder, pro-user, admin oder superadmin sein.

Schritt 2 — Die Attributzuordnung in Entra SCIM hinzufügen

In der Enterprise-App → Bereitstellung → Attributzuordnungen → Entra-ID-Benutzer bereitstellen, füge eine neue Zuordnung hinzu:

• Zuordnungstyp: Ausdruck

• Ausdruck: AppRoleAssignmentsComplex([appRoleAssignments])

• Zielattribut: roles

Dadurch sendet Entra das Stringified-JSON-Objektformat, das der Code erwartet.

Schritt 3 — Rollen Benutzern oder Gruppen zuweisen

Wenn du im Enterprise-App-Bereich → Benutzer und Gruppen einem Benutzer oder einer Gruppe zuweist, fordert Entra dich auf, eine Rolle auszuwählen. Wähle die passende blockbrain-Rolle. Benutzer ohne Rollenzuweisung erhalten standardmäßig consumer.