API-gesteuerte Konzepte für die eingehende Bereitstellung
Dieses Dokument bietet einen konzeptionellen Überblick über die von der Microsoft Entra-API gesteuerte Bereitstellung eingehender Benutzer*innen.
Einführung
Unternehmen verfügen heute über verschiedene maßgebliche Aufzeichnungssysteme. Um den End-to-End-Identitätslebenszyklus einzurichten, den Sicherheitsstatus zu stärken und mit Vorschriften konform zu bleiben, müssen Identitätsdaten in Microsoft Entra ID mit den in diesen Aufzeichnungssystemen verwalteten Personaldaten synchron gehalten werden. Bei dem Aufzeichnungssystem kann es sich um eine HR-App, eine App für die Lohnabrechnung, ein Arbeitsblatt oder SQL-Tabellen in einer Datenbank handeln, die entweder lokal oder in der Cloud gehostet wird.
Bei der API-gesteuerten eingehenden Bereitstellung unterstützt der Bereitstellungsdienst von Microsoft Entra jetzt die Integration in jedes Aufzeichnungssystem. Kunden und Partner können jedes Automatisierungstool ihrer Wahl verwenden, um Mitarbeiterdaten aus dem Aufzeichnungssystem abzurufen und in Microsoft Entra ID zu erfassen. Der IT-Administrator hat die volle Kontrolle darüber, wie die Daten mit Attributzuordnungen verarbeitet und transformiert werden. Sobald die Mitarbeiterdaten in Microsoft Entra ID verfügbar sind, können IT-Administrator*innen mithilfe von Lebenszyklusworkflows geeignete Geschäftsprozesse für Eintritt/Wechsel/Austritt konfigurieren.
Unterstützte Szenarios
Mehrere Szenarien für die Bereitstellung eingehender Benutzer werden mithilfe der API-gesteuerten eingehenden Bereitstellung ermöglicht. In diesem Diagramm werden die gängigsten Szenarien veranschaulicht.
Szenario 1: IT-Teams das Importieren von HR-Datenextrakten mithilfe eines beliebigen Automatisierungstools ermöglichen
Flatfiles, CSV-Dateien und SQL-Stagingtabellen werden häufig in Unternehmensintegrationsszenarien verwendet. Mitarbeiter-, Auftragnehmer- und Lieferanteninformationen werden regelmäßig in eines dieser Formate exportiert, und es wird ein Automatisierungstool verwendet, um diese Daten mit den Identitätsverzeichnissen des Unternehmens zu synchronisieren. Bei der API-gesteuerten eingehenden Bereitstellung können IT-Teams jedes Automatisierungstool ihrer Wahl (z. B. PowerShell-Skripts oder Azure Logic Apps) verwenden, um diese Integration zu modernisieren und zu vereinfachen.
Szenario 2: ISVs die Erstellung einer direkten Integration in Microsoft Entra ermöglichen
Mit der API-gesteuerten eingehenden Bereitstellung können ISVs für Personalsoftware native Synchronisierungsfunktionen bereitstellen, sodass Änderungen im Personalsystem automatisch in Microsoft Entra ID und verbundene lokale Active Directory-Domänen einfließen. Beispielsweise kann eine Personal-App oder eine App für ein Studenteninformationssystem Daten an Microsoft Entra ID senden – direkt nach Abschluss einer Transaktion oder als Massenaktualisierung am Ende des Tages.
Szenario 3: Systemintegratoren ermöglichen, weitere Connectors für Aufzeichnungssysteme zu erstellen
Partner können benutzerdefinierte HR-Connectors erstellen, um verschiedene Integrationsanforderungen für den Datenfluss von Aufzeichnungssystemen zu Microsoft Entra ID zu erfüllen.
In allen oben beschriebenen Szenarien wird die Integration vereinfacht, da der Microsoft Entra-Bereitstellungsdienst die Verantwortung für Folgendes übernimmt: Durchführung eines Identitätsprofilvergleichs, Beschränkung der Datensynchronisierung auf die von der IT-Administration konfigurierte Bereichslogik und Ausführung des regelbasierten Attributflows sowie der im Microsoft Entra Admin Center verwalteten Transformation.
Der vollständige Ablauf
Schritte des Workflows
- IT-Administrator*innen konfigurieren eine API-gesteuerte App für die Bereitstellung eingehender Benutzer*innen aus dem Microsoft Entra Enterprise-App-Katalog.
- IT-Administrator*innen gewähren Zugriffsberechtigungen und stellen API-Entwickler*innen/Partnern/Systemintegratoren Endpunktzugriffsdetails bereit.
- API-Entwickler*innen/Partner*innen/Systemintegrator*innen erstellen einen API-Client, um autorisierende Identitätsdaten an Microsoft Entra ID zu senden.
- Der API-Client liest Identitätsdaten aus der maßgeblichen Quelle.
- Der API-Client sendet eine POST-Anforderung an den /bulkUpload-API-Endpunkt für die Bereitstellung, welcher der Bereitstellungs-App zugeordnet ist.
Hinweis
Der API-Client muss keine Vergleiche zwischen den Quellattributen und den Werten der Zielattribute durchführen, um festzustellen, welcher Vorgang (erstellen/aktualisieren/aktivieren/deaktivieren) aufgerufen werden soll. Dies wird automatisch vom Bereitstellungsdienst durchgeführt. Der API-Client lädt einfach die aus dem Quellsystem gelesenen Identitätsdaten hoch, indem er sie als Massenanforderung mithilfe von SCIM-Schemakonstrukten verpackt.
- Bei erfolgreicher Ausführung wird ein
Accepted 202 Status
zurückgegeben. - Der Microsoft Entra-Bereitstellungsdienst verarbeitet die empfangenen Daten, wendet die Attributzuordnungsregeln an und schließt die Benutzerbereitstellung ab.
- Je nach konfigurierter Bereitstellungs-App werden die Benutzer und Benutzerinnen entweder in einer lokalen Active Directory-Instanz (für Hybridbenutzer und Hybridbenutzerinnen) oder in Microsoft Entra ID (für reine Cloudbenutzer und Cloudbenutzerinnen) bereitgestellt.
- Der API-Client fragt dann den API-Endpunkt der Bereitstellungsprotokolle nach dem Status jedes gesendeten Datensatzes ab.
- Wenn bei der Verarbeitung eines Datensatzes ein Fehler auftritt, kann der API-Client die Fehlerdetails überprüfen und Datensätze, die den fehlgeschlagenen Vorgängen entsprechen, in der nächsten Massenanforderung (Schritt 5) einschließen.
- Die IT-Administrator kann jederzeit den Status des Bereitstellungsauftrags überprüfen und Ereignisse in den Bereitstellungsprotokollen anzeigen.
Wichtige Features der API-gesteuerten Bereitstellung eingehender Benutzer
- Verfügbar als Bereitstellungs-App, die einen asynchronen/bulkUpload-API-Endpunkt von Microsoft Graph für die Bereitstellung verfügbar macht, auf den mithilfe eines gültigen OAuth-Tokens zugegriffen wird.
- Die Mandantenadministratoren müssen den API-Clients, die mit dieser Bereitstellungs-App interagieren, die Graph-Berechtigung
SynchronizationData-User.Upload
zuweisen. - Der Graph-API-Endpunkt akzeptiert gültige Massenanforderungsnutzdaten mithilfe von SCIM-Schemakonstrukten.
- Mit SCIM-Schemaerweiterungen können Sie jedes Attribut in den Massenanforderungsnutzdaten senden.
- Das Ratenlimit für die API für eingehende Bereitstellungen beträgt 40 Massenuploadanforderungen pro Sekunde. Jede Massenanforderung kann maximal 50 Benutzerdatensätze enthalten, wodurch eine Uploadrate von 2000 Datensätzen pro Sekunde unterstützt wird.
- Jeder API-Endpunkt ist einer bestimmten Bereitstellungs-App in Microsoft Entra ID zugeordnet. Sie können mehrere Datenquellen integrieren, indem Sie eine Bereitstellungs-App für jede Datenquelle erstellen.
- Eingehende Massenanforderungsnutzdaten werden in Quasi-Echtzeit verarbeitet.
- Administratoren können den Bereitstellungsfortschritt überprüfen, indem sie die Bereitstellungsprotokolle anzeigen.
- API-Clients können den Fortschritt nachverfolgen, indem sie die API für Bereitstellungsprotokolle abfragen.
Lizenzanforderungen
Dieses Feature ist mit Microsoft Entra ID P1-, P2- und Microsoft Entra ID Governance-Lizenzen verfügbar. Die richtige Lizenz für Ihre Anforderungen finden Sie unter Microsoft Entra ID Governance-Lizenzierungsgrundlagen.
Leitfaden zur API-Verwendung
Der API-Endpunkt /bulkUpload
erweitert die Anzahl der Möglichkeiten, wie Sie Benutzer und Benutzerinnen in Microsoft Entra ID verwalten können. Um festzustellen, ob der API-Endpunkt /bulkUpload
für Ihr Integrationsszenario geeignet ist, sehen Sie sich diese Tabelle an, in der er mit anderen API-basierten Integrationsoptionen verglichen wird.
Anwendungsszenario zur API-Zuordnung | Benutzererstellungs-API | HR-Eingehender-Massenvorgang-API | Benutzereinladungs-API | Direkte Zuweisungs-API |
---|---|---|---|---|
Wenn Ihr Identitätserstellungsszenario folgender Beschreibung entspricht... | Ad-hoc-Benutzererstellung in Microsoft Entra ID für ein Benutzerkonto, das keinem Mitarbeiter bzw. keiner Mitarbeiterin in einer HR-Quelle zugeordnet ist | Beschaffung von Mitarbeiterdatensätzen aus einer maßgeblichen HR-Quelle, und Sie möchten, dass diese Mitarbeiter bzw. Mitarbeiterinnen „Mitgliedskonten“ in Microsoft Entra ID oder in der lokalen Active Directory-Instanz haben | Ad-hoc-Gastbenutzererstellung in Microsoft Entra ID für Freigabezwecke, wobei die Gäste jeweils über eindeutige Zugriffsrechte verfügen | Zugriffszuweisung für vorhandene Benutzer und Gasterstellung in Microsoft Entra ID (Vorschau), um den neuen standardisierten Gastzugriff zu gewähren |
...verwenden Sie die API... | Benutzer erstellen | bulkUpload durchführen. | Einladung erstellen | accessPackageAssignmentRequest erstellen |
Das resultierende Benutzerkonto wird zuerst erstellt in... | Microsoft Entra ID | Lokale Active Directory- oder Microsoft Entra ID | Microsoft Entra ID | Microsoft Entra ID |
Der resultierende Benutzer authentifiziert sich bei... | Microsoft Entra ID mit dem Kennwort, das Sie angeben | Lokale Active Directory-Instanz von Microsoft Entra ID mit einem temporären Zugriffspass, der von Entra-Lifecycle-Workflows bereitgestellt wird | Home-Mandant oder anderer Identitätsanbieter | Home-Mandant oder anderer Identitätsanbieter |
Nachfolgende Aktualisierungen des Benutzers können erfolgen über | Graph-API oder Microsoft Entra Admin Center | Graph-API oder HR-Eingehender-Massenvorgang-API oder Microsoft Entra Admin Center | Graph-API oder Microsoft Entra Admin Center | Graph-API oder Microsoft Entra Admin Center |
Der Benutzerlebenszyklus zu Beschäftigungsbeginn wird bestimmt durch... | Manuelle Prozesse | Entra Onboarding-Lebenszyklusworkflows, die basierend auf dem Attribut employeeHireDate ausgelöst werden |
Berechtigungsverwaltung | Automatische Zuweisung mithilfe von Zugriffspaketen für die Berechtigungsverwaltung |
Der Benutzerlebenszyklus am Beschäftigungsende wird bestimmt durch... | Manuelle Prozesse | Entra-Offboarding-Lebenszyklusworkflows, die basierend auf dem Attribut employeeLeaveDateTime ausgelöst werden |
Zugriffsüberprüfungen | Berechtigungsverwaltung, wenn der Benutzer oder die Benutzerin die letzte Zugriffspaketzuweisung verliert, wird er bzw. sie entfernt. |
Empfohlener Lernpfad
# | Lernziel | Anleitungen |
---|---|---|
1. | Sie möchten mehr über die API-Spezifikationen für die eingehende Bereitstellung erfahren. | Weitere Informationen finden Sie im API-Spezifikationsdokument /bulkUpload. |
2. | Sie möchten sich mit den API-gesteuerten Bereitstellungskonzepten, Szenarien und Einschränkungen vertraut machen. | Weitere Informationen finden Sie unter Häufig gestellte Fragen zur API-gesteuerten eingehenden Bereitstellung. |
3. | Als Administratorbenutzer*in möchten Sie die API für die eingehende Bereitstellung schnell testen. | * Erstellen der API-gesteuerten eingehenden Bereitstellungs-App * Testen der API mit Graph Explorer |
4. | Mit einem Dienstkonto oder einer verwalteten Identität möchten Sie die API für die eingehende Bereitstellung schnell testen. | * Erstellen der API-gesteuerten eingehenden Bereitstellungs-App * Erteilen von API-Berechtigungen * Testen der API mit cURL |
5. | Sie möchten die API-gesteuerte Bereitstellungs-App erweitern, um mehr benutzerdefinierte Attribute zu verarbeiten. | Weitere Informationen finden Sie im Tutorial Erweitern der API-gesteuerten Bereitstellung zur Synchronisierung benutzerdefinierter Attribute. |
6. | Sie möchten den Datenupload von Ihrem Datensatzsystem auf den API-Endpunkt für die eingehende Bereitstellung automatisieren. | Weitere Informationen finden Sie in den folgenden Tutorials * Schnellstart mit PowerShell * Schnellstart mit Azure Logic Apps |
7. | Sie möchten Probleme mit der API für die eingehende Bereitstellung beheben. | Weitere Informationen finden Sie im Leitfaden zur Problembehandlung. |
Externe Lernressourcen
Die folgenden Inhalte, die von unseren Partnern und Microsoft MVPs erstellt wurden, bieten zusätzliche Anleitungen zum Bereitstellen und Konfigurieren der API-gesteuerten Bereitstellung für verschiedene Integrationsszenarien.
Videotutorials
- John Savill erklärt, wie die API-gesteuerte Bereitstellung funktioniert.
- Microsoft MVP Nick Ross erläutert, wie die API-gesteuerte Bereitstellung konfiguriert wird.
- Microsoft MVP Nick Ross erläutert, wie HR-Daten aus einer Excel-Datei in SharePoint mithilfe von Power Automate und der API-gesteuerten Bereitstellung bezogen werden.
- Microsoft Partner IdentityXP bietet eine 4-teilige Serie zur API-gesteuerten Bereitstellung
Blogbeiträge, Präsentationen und andere nützliche Links
- Microsoft MVP Pim Jacobs Artikel erläutert, wie die API-gesteuerte Bereitstellung von Bamboo HR in der lokalen Active Directory-Instanz ausgeführt wird
- Microsoft MVP Pim Jacobs Präsentation zum Konfigurieren des Beitritts- und Austrittsprozesses mithilfe der API-gesteuerten Bereitstellung und Lebenszyklusworkflows
- Microsoft MVP Marius Solbakkens Artikel erläutert, wie Excel-Daten mithilfe von PowerShell-Skripts und der API-gesteuerten Bereitstellung bezogen werden.
- Suryendu Bhattacharyyas Artikel zum Aufrufen der API-gesteuerten Bereitstellung mit benutzerdefinierter GitHub Action
- Microsoft MVP Jan Vidar Elvens Bicep-Vorlage für die API-gesteuerte Bereitstellung