Group Mapping
Diese Seite beschreibt, wie Sie Group Mapping in FirstSpirit Cloud konfigurieren, wenn eine externe Identity-Provider-Verbindung (IdP) eingerichtet ist. Group Mapping weist Ihnen als Benutzer automatisch die korrekten Gruppen in Keycloak zu, basierend auf den Gruppen oder Rollen, die Sie im IdP Ihres Unternehmens besitzen.
Was ist Group Mapping?
Bei der Authentifizierung über einen Identity Provider (IdP) übermittelt der IdP Informationen über Ihren Benutzer an Keycloak. Dazu gehören Ihre Gruppen- oder Rollenzugehörigkeiten im Unternehmenssystem. Group Mapping definiert Regeln, die diese eingehenden Informationen in Gruppenzugehörigkeiten innerhalb von Keycloak übersetzen.
Ohne Group Mapping wird ein Benutzer ohne Gruppenzuweisung in Keycloak aufgenommen und muss manuell durch einen User-Manager einer Gruppe zugewiesen werden. Mit konfiguriertem Group Mapping erfolgt diese Zuweisung automatisch bei jeder Anmeldung.
Um Group Mapping verwenden zukönnen müssen Sie:
- die Zielgruppe in Keycloak erstellen
- den Mapper definieren
- und anschließend die FirstSpirit Gruppe konfigurieren.
Um diese Schritte auszuführen benötigen Sie einen Benutzer mit der Rolle identity-provider-manager.
Wie funktioniert die Mapping-Kette?
Group Mapping wirkt über drei Systeme:
- IdP (Quelle): Der IdP Ihres Unternehmens enthält Informationen zu Ihren Gruppen- oder Rollenzugehörigkeiten, zum Beispiel eine Admin-Gruppe oder eine Abteilungsgruppe.
- Keycloak (Zwischenschicht): Ein Mapper liest den eingehenden Claim aus dem IdP-Token und weist Sie einer entsprechenden Gruppe in Keycloak zu. Der Name der Keycloak-Gruppe muss nicht mit dem Namen der IdP-Gruppe oder -Rolle übereinstimmen.
- FirstSpirit Anwendung (Ziel), z.B. FirstSpirit: Keycloak-Gruppen werden über externe Gruppen in FirstSpirit verknüpft.
Rolle identity-provider-manager
Für die Konfiguration von Group Mappern benötigen Sie die Keycloak-Rolle identity-provider-manager. Diese Rolle ist von der Rolle User-Manager getrennt und gewährt dem Benutzer Zugriff auf den Menüpunkt Identity Providers in Keycloak.
identity-provider-manager muss vom FirstSpirit-Team aktiviert werden, bevor diese vom User-Manager an andere Benutzer vegeben werden kann.Gruppen in Keycloak erstellen
Die Keycloak-Gruppen, die Sie als Mapping-Ziel verwenden möchten, müssen vor der Einrichtung von Mappern bereits vorhanden sein.
Standardgruppen wie < Tenant >-users-dev werden automatisch erstellt. Alle weiteren benutzerdefinierten Gruppen, wie Gruppen für Abteilungen oder Regionen, müssen Sie als User-Manager manuell anlegen, bevor Sie diese in einem Mapper referenzieren können.
Mapper erstellen
Ein Mapper definiert eine Regel, nach der ein bestimmter Wert aus dem IdP-Token ausgelesen und auf eine Gruppe in Keycloak übertragen wird. Mapper müssen einmalig vom Benutzer mit der Rolle identity-provider-manager angelegt werden.
Sie können Mapper in Keycloak unter Identity Providers, im Tab Mappers der jeweiligen IdP-Verbindung konfigurieren.
Erstellen Sie einen Mapper:
- Klicken Sie auf Add Mapper.
- Im Feld Name vergeben Sie einen Namen, der Quelle und Ziel des Mappers eindeutig erkennbar macht.
< Quellsystem >-< Zielrolle/-gruppe >.Beispiel:
testtenant_idP-users_devWählen Sie das Namensschema sorgfältig. Die Anzahl der Mapper kann mit der Zeit erheblich wachsen. Der Suchfilter in Keycloak unterstützt die Suche anhand des Mappernamens.
- Setzen Sie den Sync-Modus auf Force.
→ Der Mapper wird bei jeder Authentifizierung ausgeführt. Die Gruppenzugehörigkeiten des Benutzers in Keycloak werden bei jeder Anmeldung aktualisiert. - Wählen Sie den passenden Mapper-Typ aus.
Mapper-Typen
| Mapper-Typ | Definition | Konfigurierbare Felder |
|---|---|---|
| Advanced Claim to Group | Liest einen bestimmten Wert aus dem IdP-Token und weist den Benutzer bei Übereinstimmung einer definierten Keycloak-Gruppe zu | Claim: Name des Claim-Felds im IdP-Token; muss exakt mit dem vom IdP gesendeten Feld übereinstimmen Claim-Wert: Der gesuchte Wert innerhalb des Claims Gruppe: Zielgruppe in Keycloak, der der Benutzer zugewiesen wird |
| Hardcoded Group | Weist allen Benutzern, die sich über den IdP authentifizieren, eine fest definierte Keycloak-Gruppe zu unabhängig von den im IdP vorhandenen Rollen | Gruppe: Zielgruppe in Keycloak, der der Benutzer zugewiesen wird |
| Advanced Claim to Role | Weist dem Benutzer eine Keycloak-Rolle zu, basierend auf einem bestimmten Wert im IdP-Token. Ermöglicht die automatische Vergabe administrativer Rollen über den IdP. | Claim: Name des Claim-Felds im IdP-Token; muss exakt mit dem vom IdP gesendeten Feld übereinstimmen Claim-Wert: Der gesuchte Wert innerhalb des Claims Rolle: Rolle in Keycloak, die dem Benutzer zugewiesen wird |
| Hardcoded Role | Weist allen Benutzern, die sich über den IdP authentifizieren, eine fest definierte Keycloak-Rolle zu unabhängig von den im IdP vorhandenen Rollen | Rolle: Rolle in Keycloak, die dem Benutzer zugewiesen wird |
Externe Gruppen in FirstSpirit-Projekt konfigurieren
Die Mapper-Konfiguration in Keycloak schließt die Einrichtung nicht ab. Legen Sie zusätzlich eine externe Gruppe in FirstSpirit an und setzen Sie das Feld Externer Name auf den exakten Namen der Keycloak-Gruppe.