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.

Introduction

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.

Mit apigesteuerter eingehender Bereitstellung unterstützt der Microsoft Entra Bereitstellungsdienst jetzt die Integration mit jedem Datensatzsystem. Kunden und Partner können jedes Automatisierungstool ihrer Wahl verwenden, um Mitarbeiterdaten aus dem Datensatzsystem abzurufen und in Microsoft Entra ID aufzunehmen. 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, kann der IT-Administrator geeignete Joiner-mover-leaver-Geschäftsprozesse mithilfe von Lifecycle-Workflows 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

1. IT-Administrator*innen konfigurieren eine API-gesteuerte App für die Bereitstellung eingehender Benutzer*innen aus dem Microsoft Entra Enterprise-App-Katalog.
2. IT-Administrator*innen gewähren Zugriffsberechtigungen und stellen API-Entwickler*innen/Partnern/Systemintegratoren Endpunktzugriffsdetails bereit.
3. API-Entwickler*innen/Partner*innen/Systemintegrator*innen erstellen einen API-Client, um autorisierende Identitätsdaten an Microsoft Entra ID zu senden.
4. Der API-Client liest Identitätsdaten aus der maßgeblichen Quelle.
5. Der API-Client sendet eine POST-Anforderung an die Bereitstellung des /bulkUpload-API-Endpunkts , der der Bereitstellungs-App zugeordnet ist.

   Note

   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.

6. Bei erfolgreicher Ausführung wird ein Accepted 202 Status zurückgegeben.
7. Der Microsoft Entra-Bereitstellungsdienst verarbeitet die empfangenen Daten, wendet die Attributzuordnungsregeln an und schließt die Benutzerbereitstellung ab.
8. 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.
9. Der API-Client fragt dann den API-Endpunkt der Bereitstellungsprotokolle nach dem Status jedes gesendeten Datensatzes ab.
10. 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.
11. 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 Microsoft Graph Bereitstellungs-/bulkUpload-API-Endpunkt verfügbar macht, auf den mithilfe eines gültigen OAuth-Tokens zugegriffen wird.
• Mandantenadministratoren müssen API-Clients gewähren, die mit dieser Bereitstellungs-App interagieren, die Graph-Berechtigungen SynchronizationData-User.Upload, SynchronizationData-User.Upload.OwnedBy (für ISVs) und ProvisioningLog.Read.All.
• Der Graph-API-Endpunkt akzeptiert gültige Massenanforderungsnutzdaten mithilfe von SCIM-Schemakonstrukten.
• Mit SCIM-Schemaerweiterungen können Sie jedes Attribut in den Massenanforderungsnutzdaten senden.
• Sie können die Bereitstellung so konfigurieren, dass Attributwerte (Vorschau) gelöscht werden, wenn die Anforderungsnutzlast NULL- oder leere Werte enthält.
• Fügen Sie einen vollständigen Benutzerdatensatz in jede Massenanforderung für die vollständige und die Delta-Synchronisierung ein. Wenn clear attribute values (Preview) aktiviert ist, werden die entsprechenden Werte im Zielsystem durch NULL oder leere Werte für zugeordnete Attribute gelöscht. Das Löschen kann auch auftreten, wenn Sie ein Attribut weglassen, für das der Nullfluss aktiviert ist. Eine unvollständige Nutzlast kann daher unbeabsichtigt vorhandene Attributwerte löschen. Verwenden Sie eine explizite JSON- null oder leere Zeichenfolge, um deterministisches Löschen durchzuführen.
• Der /bulkUpload API-Endpunkt erzwingt die folgenden Einschränkungsgrenzwerte:
  • Es gibt eine Beschränkung von 40 API-Aufrufen innerhalb eines beliebigen 5-Sekunden-Fensters. Wenn dieser Schwellenwert überschritten wird, gibt der Dienst eine HTTP 429 -Antwort (Zu viele Anforderungen) zurück. Um Drosselung zu vermeiden, implementieren Sie Pacinglogik im Client, um Anforderungen für das Leerzeichen freizuspeichern , z. B. Das Hinzufügen von Verzögerungen oder die Behandlung von Ratenbeschränkungen zwischen Übermittlungen.
  • Es gibt einen Grenzwert auf Mandantenebene von 2.000 API-Aufrufen pro 24-Stunden-Zeitraum unter der Entra ID P1/P2-Lizenz und 6.000 API-Aufrufe unter der Entra ID Governance-Lizenz. Das Überschreiten dieser Grenzwerte führt zu einer HTTP 429-Antwort (Zu viele Anforderungen). Um innerhalb des Kontingents zu bleiben, stellen Sie sicher, dass Ihre SCIM-Massennutzlasten optimiert sind, um bis zu 50 Vorgänge pro API-Aufruf einzuschließen.
• 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.

Empfohlener Lernpfad

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.

• Videolernprogramme

  • 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 Christian Frohn erklärt, wie die API-gesteuerte Bereitstellung mit Azure SQL Datenbank als Wahrheitsquelle verwendet wird
  • 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

Nächste Schritte

• Konfigurieren der API-gesteuerten eingehenden Bereitstellungs-App
• Häufig gestellte Fragen zur API-gesteuerten eingehenden Bereitstellung