Microsoft Entra ID: SAML-Gruppen-Mapping konfigurieren

SAML-Gruppenzuordnung für Apidog-Teams mit Microsoft Entra ID

Die SAML-Gruppenzuordnung weist Apidog-Teamzugriff anhand der Gruppen in der SAML-Assertion eines Benutzers zu. Dadurch sinkt der manuelle Aufwand für die Mitgliedschaft, während Microsoft Entra ID die Quelle der Gruppenzugehörigkeit bleibt.

Apidog jetzt testen

Dieses Tutorial zeigt, wie Sie einen groups-Anspruch hinzufügen, eine Entra-Gruppe einem Apidog-Team zuordnen und die anfänglichen Projektberechtigungen bei der Anmeldung überprüfen.

Voraussetzungen

Sie benötigen:

• eine Apidog-Enterprise-Organisation mit konfiguriertem SAML-SSO;
• Zugriff als Organisationsbesitzer oder Organisationsadministrator in Apidog;
• Administratorzugriff auf die für Apidog verwendete Microsoft-Entra-Unternehmensanwendung;
• mindestens eine Entra-Gruppe und einen Testbenutzer, der dieser Gruppe zugewiesen ist.

Falls SAML noch nicht eingerichtet ist, folgen Sie zuerst Konfigurieren von Microsoft Entra ID.

Wichtig: Die SAML-Gruppenzuordnung steuert den Zugriff auf Apidog-Teams und -Projekte. Sie gewährt keinen Zugriff auf Produktions-APIs und ersetzt keine Laufzeitautorisierung.

Zuordnung des anfänglichen Projektzugriffs

Wenn eine Gruppe übereinstimmt, fügt Apidog den Benutzer dem zugeordneten Team hinzu. Der anfängliche Projektzugriff wird aus der ausgewählten Teamrolle abgeleitet:

Zugeordnete Teamrolle	Anfängliche Projektrolle
Team-Admin	Projektbetreuer
Teammitglied	Projekt (Schreibgeschützt)
Team-Gast	Projekt (Schreibgeschützt)

Apidog erstellt fehlende Projektmitgliedschaften oder aktualisiert Mitgliedschaften ohne vorhandene Rolle. Eine manuell zugewiesene Projektrolle wird bei späteren SAML-Anmeldungen nicht überschrieben.

Schritt 1: groups-Anspruch in Microsoft Entra ID hinzufügen

1. Melden Sie sich beim Microsoft Entra Admin Center an.
2. Öffnen Sie unter Unternehmensanwendungen die für Apidog-SSO verwendete Anwendung.
3. Wählen Sie Einmaliges Anmelden und anschließend Attribute & Ansprüche.
4. Wählen Sie Gruppenanspruch hinzufügen.
5. Wählen Sie Alle Gruppen.
6. Aktivieren Sie Namen des Gruppenanspruchs anpassen und geben Sie groups als Anspruchsnamen ein.
7. Speichern Sie den Anspruch.

Konfigurieren Sie den Gruppenanspruch so, dass Apidog die Entra-Gruppenobjekt-IDs im groups-Attribut erhält.

Apidog verwendet die Gruppenobjekt-IDs aus diesem Anspruch. Weitere Gruppeninformationen werden nicht aus Microsoft Entra ID abgerufen.

Schritt 2: Entra-Gruppenname und Objekt-ID kopieren

1. Öffnen Sie in Microsoft Entra ID Gruppen.
2. Wählen Sie die Gruppe aus, die Zugriff auf Apidog erhalten soll.
3. Kopieren Sie den Namen und die Objekt-ID.

Verwenden Sie die auf der Entra-Gruppenseite angezeigte Objekt-ID. Verwenden Sie nicht die Anwendungs-ID, Mandanten-ID oder den Anzeigenamen.

Lassen Sie diese Seite geöffnet, während Sie die Zuordnung in Apidog konfigurieren.

Schritt 3: Gruppe einem Apidog-Team zuordnen

1. Öffnen Sie die Organisation in Apidog.
2. Wechseln Sie zu den SAML-Gruppen-Einstellungen.
3. Fügen Sie eine Gruppenzuordnung hinzu.
4. Geben Sie den Entra-Gruppennamen ein und fügen Sie die Objekt-ID ein.
5. Wählen Sie die Apidog-Teams aus, auf die die Gruppe zugreifen soll.
6. Legen Sie für jedes Team die erforderliche Teamrolle fest.
7. Speichern Sie die Zuordnung.

Ordnen Sie die Entra-Gruppenobjekt-ID den erforderlichen Apidog-Teams und Teamrollen zu.

Die SAML-Gruppenzuordnung bietet keine separate Auswahl für Projektrollen. Die anfängliche Projektrolle ergibt sich aus der Teamrolle. Wenn ein anderer Zugriff erforderlich ist, ändern Sie die Projektrolle später in den Projekteinstellungen.

Schritt 4: Zuordnung testen

Verwenden Sie ein Testkonto, kein Administratorkonto:

1. Bestätigen Sie, dass der Testbenutzer Mitglied der zugeordneten Entra-Gruppe ist.
2. Melden Sie sich von Apidog ab.
3. Melden Sie sich über den SSO-Einstiegspunkt der Organisation an.
4. Öffnen Sie das zugeordnete Team und prüfen Sie, ob es verfügbar ist.
5. Überprüfen Sie die Teamrolle des Benutzers.
6. Öffnen Sie die Teamprojekte und prüfen Sie die anfängliche Projektrolle.

Wenn der Benutzer bereits eine manuell zugewiesene Projektrolle hatte, prüfen Sie, ob diese nach einer erneuten SSO-Anmeldung unverändert bleibt.

Entfernung von Mitgliedschaften überprüfen

Testen Sie die Gruppenentfernung vor dem Rollout:

1. Entfernen Sie den Testbenutzer aus der zugeordneten Entra-Gruppe.
2. Warten Sie, bis die Änderung im Identitätsanbieter abgeschlossen ist.
3. Lassen Sie den Benutzer sich erneut über SSO anmelden.
4. Überprüfen Sie die Team- und Projektmitgliedschaften.

Wenn ein Benutzer nicht mehr Mitglied einer zugeordneten Gruppe ist, kann Apidog ihn während der SAML-Synchronisierung aus dem entsprechenden Team entfernen. Mit der Teammitgliedschaft werden auch die Projektmitgliedschaften in diesem Team entfernt.

Verwenden Sie für den ersten Entfernungstest kein Produktionskonto. Dokumentieren Sie das beobachtete Verhalten für Ihre Identitätskonfiguration und Ihr Offboarding-Verfahren.

Fehlerbehebung

Problem	Was Sie prüfen sollten
Der Benutzer meldet sich an, wird aber nicht zum Team hinzugefügt.	Prüfen Sie, ob der Anspruch genau groups heißt, die Assertion die erwartete Objekt-ID enthält und die Objekt-ID in Apidog keine zusätzlichen Leerzeichen enthält.
Die Assertion enthält keine Gruppenwerte.	Prüfen Sie, ob der Benutzer Mitglied der Gruppe ist und die Entra-Unternehmensanwendung Gruppenansprüche sendet. Bei vielen Gruppenmitgliedschaften beachten Sie Microsofts Anleitung zur Überschreitung von Gruppenansprüchen.
Der Benutzer hat die falsche Projektrolle.	Prüfen Sie die zugeordnete Teamrolle. Bereits zugewiesene Projektrollen werden durch spätere SAML-Synchronisierungen nicht überschrieben.
Eine Gruppenänderung wird nicht übernommen.	Bestätigen Sie, dass die Änderung Entra erreicht hat, und starten Sie anschließend eine neue SSO-Anmeldung, damit Apidog die aktuelle Assertion synchronisieren kann.
Der Benutzer bleibt in der Organisation.	Die SAML-Gruppenzuordnung verwaltet den Zugriff auf zugeordnete Teams. Die Organisationsmitgliedschaft kann zusätzlich über Einladungen, SSO oder SCIM verwaltet werden.

Wichtige Einschränkungen

• Apidog erstellt oder löscht keine Identitätsanbietergruppen über SCIM.
• Die SAML-Gruppenzuordnung bietet keine separate Rolleneinstellung pro Projekt.
• Bestehende Projektrollen werden bei späteren SSO-Anmeldungen nicht zurückgesetzt.
• Wenn mehrere Zuordnungen für denselben Benutzer und dasselbe Team gelten könnten, testen Sie das Ergebnis vor dem Rollout. Gehen Sie nicht von einer Vorrangregel aus.
• Arbeitsbereichsrollen autorisieren keine Aufrufe an bereitgestellte APIs.

Verwandte API-Governance-Tutorials

Diese Tutorials behandeln ergänzende Kontrollen für die Verwaltung eines Unternehmens-API-Arbeitsbereichs:

• API-Governance-Framework — verbindet Eigentum, Kontrollen, Nachweise und Lebenszyklusentscheidungen.
• SAML-Gruppenzuordnung mit Microsoft Entra ID — weist Teamzugriff anhand von Identitätsanbietergruppen zu.
• Geheimnis-Scanner — prüft unterstützte Apidog-Assets auf möglicherweise offengelegte Anmeldedaten.
• Audit-Protokolle — untersucht und exportiert administrative Organisationsaktivitäten.
• SCIM-Bereitstellung — verwaltet Organisationsbenutzer über den Identitätslebenszyklus.
• Unternehmensrichtlinien — konfiguriert Anmeldedaten, Mitgliedschaft, SSO-Sitzungen und Einladungen.
• Self-Service-API-Teams — ermöglicht von Mitgliedern erstellte Teams unter Wahrung der Eigentumsaufsicht.
• GitHub-Enterprise-Cloud-Integration — verbindet unterstützte GHE.com-Repositories für OpenAPI-Workflows.

Verwandte offizielle Dokumentation

• Gruppen Teams zuordnen
• Konfigurieren von Microsoft Entra ID
• Einführung in die SCIM-Bereitstellung
• Organisationsrollen und Berechtigungen