> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/de/for-admins/classic-microsoft-integrations/system-for-cross-domain-identity-management-scim.md). # 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: `` 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-AttributSCIM-Attribut
userPrincipleNameuserName
IsSoftDeletedactive
mailemails[type eq "work"].value
givenNamename.givenName
surnamename.familyName
displayNamedisplayName
objectIdexternalId
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-AttributSCIM-Attribut
displayNamedisplayName
objectIdexternalId
membersmembers
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": "", "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
SymptomPrüfen
Verbindungstest schlägt mit 401 fehlToken ist falsch oder der Provider stimmt nicht überein — mit "provider": "entra" neu generieren
Verbindungstest schlägt mit 404 fehlMandanten-URL falsch — muss auf /scim/v2 enden, nicht auf /scim/v2/
Doppelte BenutzerexternalId → 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.blockbrain.ai/de/for-admins/classic-microsoft-integrations/system-for-cross-domain-identity-management-scim.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.