Freigeben über

Häufig gestellte Fragen zur API-gesteuerten eingehenden Bereitstellung

In diesem Artikel werden häufig gestellte Fragen (FAQs) zu API-gesteuertem eingehenden Provisioning beantwortet.

Wie unterscheidet sich die neue Inbound-Bereitstellung /bulkUpload-API von der MS Graph Users API?

Es gibt erhebliche Unterschiede zwischen der Bereitstellungs-/BulkUpload-API und dem MS Graph-Benutzer-API-Endpunkt.

  • Nutzlastformat: Der MS Graph-Benutzer-API-Endpunkt erwartet Daten im OData-Format. Das Anforderungsnutzlastformat für die neue eingehende Bereitstellung /bulkUpload-API verwendet SCIM-Schemakonstrukte. Wenn Sie diese API aufrufen, legen Sie den Header "Content-Type" auf application/scim+json.
  • Endergebnis des Vorgangs:
    • Wenn Identitätsdaten an den MS Graph-Benutzer-API-Endpunkt gesendet werden, wird sie sofort verarbeitet, und ein Vorgang zum Erstellen/Aktualisieren/Löschen erfolgt im Microsoft Entra-Benutzerprofil.
    • Anforderungsdaten, die an die Bereitstellungs-/BulkUpload-API gesendet werden, werden asynchron vom Microsoft Entra-Bereitstellungsdienst verarbeitet. Der Bereitstellungsauftrag wendet Bereichsregeln, Attributzuordnung und Transformation an, die vom IT-Administrator konfiguriert wurden. Dadurch wird ein Create/Update/Delete Vorgang im Microsoft Entra-Benutzerprofil oder im lokalen AD-Benutzerprofil initiiert.
  • IT-Administrator behält die Kontrolle: Mit API-gesteuerter eingehender Bereitstellung hat der IT-Administrator mehr Kontrolle darüber, wie die eingehenden Identitätsdaten verarbeitet und Microsoft Entra-Attributen zugeordnet werden. Sie können Bereichsregeln definieren, um bestimmte Arten von Identitätsdaten (z. B. Auftragnehmerdaten) auszuschließen und Transformationsfunktionen zu verwenden, um neue Werte abzuleiten, bevor sie die Attributwerte für das Benutzerprofil festlegen.

Handelt es sich bei der eingehenden Bereitstellung /bulkUpload-API um einen standardmäßigen SCIM-Endpunkt?

Die MS Graph-/bulkUpload-API für die eingehende Bereitstellung verwendet das SCIM-Schema in den Anforderungsnutzdaten, ist aber kein standardisierter SCIM-API-Endpunkt. Dies ist der Grund.

In der Regel verarbeitet ein SCIM-Dienstendpunkt HTTP-Anforderungen (POST, PUT, GET) mit SCIM-Nutzlast und übersetzt sie in die entsprechenden Vorgänge (Create, Update, Lookup) im Identitätsspeicher. Der SCIM-Dienstendpunkt platziert den Onus der Angabe der Vorgangsemantik, ob eine Identität erstellt/aktualisiert/gelöscht werden soll, auf dem SCIM-API-Client. Dieser Mechanismus eignet sich gut für Szenarien, in denen der API-Client weiß, welcher Vorgang für Benutzer im Identitätsspeicher ausgeführt werden soll.

Der MS Graph-/bulkUpload für die eingehende Bereitstellung ist für die Verarbeitung eines anderen Szenarios für die Integration von Unternehmensidentitäten konzipiert, das durch drei eindeutige Anforderungen geprägt ist:

  1. Möglichkeit zum asynchronen Verarbeiten von Datensätzen in Massen (z. B. Verarbeiten von 50K+-Datensätzen)
  2. Möglichkeit, ein beliebiges Identitätsattribut in die Nutzdaten einzuschließen (z. B. costCenter, pay grade, badgeId)
  3. Unterstützen Sie API-Clients, die keine Funktionsemantik kennen. Diese Clients sind Nicht-SCIM-API-Clients, die nur Zugriff auf rohe Quelldaten haben (z. B. Datensätze in CSV-Datei, SQL-Tabelle oder HR-Datensätzen). Diese Clients verfügen nicht über die Verarbeitungsfunktion, um jeden Datensatz zu lesen und die Vorgangsemantik im Identitätsspeicher Create/Update/Delete zu bestimmen.

Das Hauptziel der MS Graph Inbound Provisioning /bulkUpload-API ist es, Kunden das Senden beliebiger Identitätsdaten (z. B. Kostenstelle, Gehaltsstufe, Ausweis-ID) aus einer beliebigen Identitätsdatenquelle (z. B. CSV/SQL/HR) für die spätere Verarbeitung durch den Microsoft Entra-Bereitstellungsdienst zu ermöglichen. Der Microsoft Entra-Bereitstellungsdienst verwendet die an diesem Endpunkt empfangenen Massennutzlastdaten, wendet Attributzuordnungsregeln an, die vom IT-Administrator konfiguriert wurden, und bestimmt, ob die Datennutzlast zum Vorgang (Erstellen, Aktualisieren, Aktivieren, Deaktivieren) im Zielidentitätsspeicher (Microsoft Entra ID / lokales AD) führt.

Unterstützt die Bereitstellungs-/bulkUpload-API lokale Active Directory-Domänen als Ziel?

Ja, die Bereitstellungs-API unterstützt lokale AD-Domänen als Ziel.

Wie erhalten wir den /bulkUpload-API-Endpunkt für unsere Bereitstellungs-App?

Die /bulkUpload-API ist nur für Apps des Typs „API-gesteuerte eingehende Bereitstellung in Microsoft Entra ID“ und „API-gesteuerte eingehende Bereitstellung für lokales Active Directory“ verfügbar. Sie können den eindeutigen API-Endpunkt für jede Bereitstellungsanwendung über die Startseite des Bereitstellungsbereichs abrufen. In "Statistiken bis heute"> und "Technische Informationen anzeigen", kopieren Sie die URL des Bereitstellungs-API-Endpunkts.

Es hat das Format:

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Wie führen wir eine vollständige Synchronisierung mit der Bereitstellungs-/BulkUpload-API aus?

Um eine vollständige Synchronisierung durchzuführen, verwenden Sie Ihren API-Client, um die Daten aller Benutzer aus Ihrer vertrauenswürdigen Quelle als Massenanforderung an den API-Endpunkt zu senden. Nachdem Sie alle Daten an den API-Endpunkt gesendet haben, verarbeitet der nächste Synchronisierungszyklus alle Benutzerdatensätze und ermöglicht es Ihnen, den Fortschritt mithilfe des API-Endpunkts für Bereitstellungsprotokolle nachzuverfolgen.

Wie führen wir die Delta-Synchronisierung mit der Bereitstellungs-/BulkUpload-API aus?

Um eine Delta-Synchronisierung durchzuführen, verwenden Sie Ihren API-Client, um nur Informationen zu Benutzern zu senden, deren Daten in der vertrauenswürdigen Quelle geändert wurden. Nachdem Sie alle Daten an den API-Endpunkt gesendet haben, verarbeitet der nächste Synchronisierungszyklus alle Benutzerdatensätze und ermöglicht es Ihnen, den Fortschritt mithilfe des API-Endpunkts für Bereitstellungsprotokolle nachzuverfolgen.

Wie funktioniert die Neustartbereitstellung?

Verwenden Sie die Option " Bereitstellung neu starten " nur bei Bedarf. So funktioniert es:

Szenario 1: Wenn Sie auf die Schaltfläche " Bereitstellung neu starten " klicken und der Auftrag zurzeit ausgeführt wird, verarbeitet der Auftrag weiterhin die vorhandenen Daten, die bereits bereitgestellt wurden. DerNeustartbereitstellungsvorgang unterbricht keinen vorhandenen Zyklus. Im nachfolgenden Zyklus löscht der Bereitstellungsdienst alle Hinterlegungen und wählt die neue Massenanforderung für die Verarbeitung aus.

Szenario 2: Wenn Sie auf die Schaltfläche "Bereitstellung neu starten" klicken und der Auftrag nicht ausgeführt wird, löscht das Bereitstellungsmodul vor dem nächsten Zyklus die vor dem Neustart hochgeladenen Daten, bereinigt alle Escrows und verarbeitet nur neue eingehende Daten.

Wie erstellen wir Benutzer mithilfe des Bereitstellungs-/bulkUpload-API-Endpunkts?

So verarbeitet der Bereitstellungsauftrag, der dem /bulkUpload-API-Endpunkt zugeordnet ist, eingehende Benutzernutzlasten:

  1. Der Auftrag ruft die Attributzuordnung für den Bereitstellungsauftrag ab und notiert das übereinstimmende Attributpaar (standardmäßig wird das API-Attribut externalId verwendet, um mit employeeId in Microsoft Entra ID übereinzustimmen).
  2. Sie können dieses Standard-Attributabgleichspaar ändern.
  3. Der Auftrag extrahiert jeden Vorgang, der in den Massenanforderungsnutzdaten vorhanden ist.
  4. Die Aufgabe überprüft den Wertabgleichsbezeichner in der Anforderung (standardmäßig das Attribut externalId) und nutzt ihn, um festzustellen, ob ein Benutzer in Microsoft Entra ID mit einem übereinstimmenden Wert employeeId vorhanden ist.
  5. Wenn der Auftrag keinen übereinstimmenden Benutzer findet, wendet der Auftrag die Synchronisierungsregeln an und erstellt einen neuen Benutzer im Zielverzeichnis.

Um sicherzustellen, dass die richtigen Benutzer in Der Microsoft Entra-ID erstellt werden, definieren Sie das richtige passende Attributpaar in Ihrer Zuordnung, das Benutzer in Ihrer Quelle und Microsoft Entra-ID eindeutig identifiziert.

Wie generieren wir eindeutige Werte für UPN?

Der Bereitstellungsdienst bietet nicht die Möglichkeit, nach doppelten userPrincipalName (UPN) zu suchen und Konflikte zu behandeln. Wenn die Standardsynchronisierungsregel für UPN-Attribut einen vorhandenen UPN-Wert generiert, schlägt der Benutzererstellungsvorgang fehl.

Hier sind einige Optionen, die Sie zum Generieren eindeutiger UPNs in Betracht ziehen können:

  1. Fügen Sie die Logik für die eindeutige UPN-Generierung in Ihrem API-Client hinzu.
  2. Aktualisieren Sie die Synchronisierungsregel für das UPN-Attribut, um die RandomString-Funktion zu verwenden, und legen Sie den angewendeten Zuordnungsparameter auf On object creation only. Beispiel:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. Wenn Sie für lokales Active Directory bereitstellen, können Sie die SelectUniqueValue-Funktion verwenden und den Zuordnungsparameter „zuordnen“ auf On object creation only festlegen.

Wie senden wir weitere HR-Attribute an den Bereitstellungs-/BulkUpload-API-Endpunkt?

Standardmäßig unterstützt der API-Endpunkt die Verarbeitung aller Attribute, die Teil des SCIM Core-Benutzer- und Unternehmensbenutzerschemas sind. Wenn Sie weitere Attribute senden möchten, können Sie das Bereitstellungs-App-Schema erweitern, die neuen Attribute den Microsoft Entra-Attributen zuordnen und die Massenanforderung aktualisieren, um diese Attribute zu übermitteln. Weitere Informationen finden Sie im Lernprogramm Zum Erweitern der API-gesteuerten Bereitstellung zum Synchronisieren von benutzerdefinierten Attributen.

Wie schließen wir bestimmte Benutzer aus dem Bereitstellungsfluss aus?

Möglicherweise haben Sie ein Szenario, in dem Sie alle Benutzer an den API-Endpunkt senden möchten, aber nur bestimmte Benutzer in den Bereitstellungsfluss einschließen und den Rest ausschließen möchten.

Sie können dies mithilfe des Bereichsfilters erreichen. In der Konfiguration der Bereitstellungs-App können Sie einen Quellobjektbereich definieren und bestimmte Benutzer von der Verarbeitung ausschließen, indem Sie entweder eine „Einschlussregel“ (z. B. nur Benutzer verarbeiten, bei denen die Abteilung GLEICH Sales ist) oder eine „Ausschlussregel“ (z. B. Ausschließen von Benutzern aus dem Vertrieb, Abteilung NICHT GLEICH Vertrieb) verwenden.

Siehe Eingrenzen von Benutzern oder Gruppen für die Bereitstellung mit Bereichsfiltern.

Wie aktualisieren wir Benutzer mithilfe des Bereitstellungs-/BulkUpload-API-Endpunkts?

So verarbeitet der Bereitstellungsauftrag, der dem /bulkUpload-API-Endpunkt zugeordnet ist, eingehende Benutzernutzlasten:

  1. Der Bereitstellungsauftrag ruft die Attributzuordnung für den Bereitstellungsauftrag ab und notiert das übereinstimmende Attributpaar (standardeingestellt wird das externalId-API-Attribut verwendet, um mit employeeId der Microsoft Entra-ID übereinzustimmen). Sie können dieses Standard-Attributabgleichspaar ändern.
  2. Der Auftrag extrahiert die Vorgänge aus den Massenanforderungsnutzdaten.
  3. Der Auftrag überprüft den Bezeichner für den Wertabgleich in der SCIM-Anforderung (standardmäßig das API-Attribut externalId) und verwendet ihn, um zu überprüfen, ob in Microsoft Entra ID ein Benutzer mit übereinstimmendem employeeId-Wert vorhanden ist.
  4. Wenn der Auftrag einen übereinstimmenden Benutzer findet, wendet er die Synchronisierungsregeln an und vergleicht die Quell- und Zielprofile.
  5. Wenn der Auftrag feststellt, dass einige Werte geändert wurden, wird der entsprechende Benutzerdatensatz im Verzeichnis aktualisiert.

Um sicherzustellen, dass die richtigen Benutzer in der Microsoft Entra-ID aktualisiert werden, müssen Sie das richtige Attributpaar in Ihrer Zuordnung definieren, das Benutzer in Ihrer Quelle und Microsoft Entra-ID eindeutig identifiziert.

Können wir mehr als eine Anwendung erstellen, die API-gesteuerte eingehende Bereitstellung unterstützt?

Ja, das können Sie. Im Folgenden sind einige Szenarien aufgeführt, die möglicherweise mehr als eine Bereitstellungs-App erfordern:

Szenario 1: Angenommen, Sie haben drei vertrauenswürdige Datenquellen: eine für Mitarbeiter, eine für Auftragnehmer und eine für Lieferanten. Sie können drei separate Bereitstellungs-Apps erstellen – eine für jeden Identitätstyp mit einer eigenen eindeutigen Attributzuordnung. Jede Bereitstellungs-App verfügt über einen eindeutigen API-Endpunkt, und Sie können die jeweiligen Nutzlasten an jeden Endpunkt senden.

Sie können den eindeutigen API-Endpunkt für jeden Auftrag auf dem Blatt „Bereitstellung“ der Homepage abrufen. Navigieren Sie zu 'Statistiken bis heute'>technischen Informationen anzeigen, und kopieren Sie dann die Bereitstellungs-API-Endpunkt-URL.

Szenario 2: Angenommen, Sie haben mehrere Quellen der Wahrheit, jedes mit einem eigenen Attributsatz. Beispielsweise stellt HR Jobinfo-Attribute bereit (z. B. jobTitle, employeeType), und das Badgesystem stellt Badge-Informationsattribute bereit (z. B. badgeId, das durch ein Erweiterungsattribut dargestellt wird). In diesem Szenario können Sie zwei Bereitstellungs-Apps konfigurieren:

  • Bereitstellungs-App Nr. 1, die Attribute von Ihrer HR-Quelle empfängt und die benutzende Person erstellt.

  • Bereitstellungs-App Nr. 2, die Attribute vom Badgeverleihungssystem empfängt und nur die Benutzerattribute aktualisiert. Die Attributzuordnung in dieser App ist auf die Badgeinformationsattribute beschränkt, und unter Zielobjektaktionen ist nur „Aktualisieren“ aktiviert.

  • Beide Apps verwenden dasselbe übereinstimmende Bezeichnerpaar (externalId<->employeeId)

Wie verarbeiten wir Beendigungen mithilfe des /bulkUpload-API-Endpunkts?

Um Beendigungen zu verarbeiten, identifizieren Sie ein Attribut in Ihrer Quelle, das zum Festlegen des accountEnabled Flags in der Microsoft Entra-ID verwendet wird. Wenn Sie die Bereitstellung in lokalem Active Directory ausführen, ordnen Sie das Quellattribute dem accountDisabled Attribut zu.

Standardmäßig bestimmt der dem SCIM Core User Schema-Attribut active zugeordnete Wert den Status des Benutzerkontos im Zielverzeichnis.

Wenn das Attribut auf "true" festgelegt ist, aktiviert die Standardzuordnungsregel das Konto. Wenn das Attribut auf "false" festgelegt ist, deaktiviert die Standardzuordnungsregel das Konto.

Wie können wir verhindern, dass Benutzer versehentlich deaktiviert/gelöscht werden?

Um versehentliche Löschungen zu verhindern und wiederherzustellen, empfehlen wir, den Schwellenwert für versehentliche Löschungen in der Bereitstellungs-App zu konfigurieren und den lokalen Active Directory-Papierkorb zu aktivieren. Deaktivieren Sie auf dem Blatt Attributzuordnung Ihrer Bereitstellungs-App unter Zielobjektaktionen den Vorgang Löschen.

Wiederherstellen gelöschter Konten

  • Wenn das Zielverzeichnis für den Vorgang Microsoft Entra ID ist, wird der übereinstimmende Benutzer bzw. die übereinstimmende Benutzerin vorläufig gelöscht. Der Benutzer kann für die nächsten 30 Tage auf der Seite " Gelöschte Benutzer " im Microsoft Entra Admin Center angezeigt werden und kann während dieser Zeit wiederhergestellt werden.
  • Wenn das Zielverzeichnis für den Vorgang das lokale Active Directory ist, wird der übereinstimmende Benutzer endgültig gelöscht. Wenn der Active Directory-Papierkorb aktiviert ist, können Sie das gelöschte lokale AD-Benutzerobjekt wiederherstellen.

Müssen wir alle Benutzer aus dem HR-System in jeder Anfrage senden?

Nein, Sie müssen nicht alle Benutzer aus dem HR-System/der „Quelle der Wahrheit“ in jeder Anforderung senden. Senden Sie einfach die Benutzer, die Sie erstellen oder aktualisieren möchten.

Unterstützt die API alle HTTP-Aktionen (GET/POST/PUT/PATCH)?

Nein, der /bulkUpload-Bereitstellungs-API-Endpunkt unterstützt nur die POST-HTTP-Aktion.

Wenn ich einen Benutzer aktualisieren möchte, muss ich eine PUT/PATCH-Anforderung senden?

Nein, der API-Endpunkt unterstützt keine PUT/PATCH-Anforderung. Um einen Benutzer zu aktualisieren, senden Sie die dem Benutzer zugeordneten Daten in der POST-Massenanforderungsnutzlast.

Der Bereitstellungsauftrag, der vom API-Endpunkt empfangene Daten verarbeitet, erkennt automatisch, ob der in den POST-Anforderungsnutzdaten empfangene Benutzer basierend auf den konfigurierten Synchronisierungsregeln erstellt/aktualisiert/aktiviert/deaktiviert werden muss. Als API-Client müssen Sie keine weiteren Schritte ausführen, wenn ein Benutzerprofil aktualisiert werden soll.

Wie wird das Rückschreiben unterstützt?

Die aktuelle API unterstützt nur eingehende Daten. Hier sind einige Optionen, die Sie in Betracht ziehen können, um das Rückschreiben von Attributen wie E-Mail, Benutzername und Telefon zu implementieren, die von Microsoft Entra ID generiert werden und die Sie wieder in das HR-System übertragen können.

  • Option 1 – SCIM-Konnektivität zum HR-Endpunkt/Proxydienst, der wiederum die HR-Quelle aktualisiert

    • Wenn das Aufzeichnungssystem einen SCIM-Endpunkt für Benutzerupdates bereitstellt, können Sie eine benutzerdefinierte SCIM-Anwendung im Unternehmens-App-Katalog erstellen und die Bereitstellung wie dokumentiert konfigurieren.
    • Wenn das Datensatzsystem keinen SCIM-Endpunkt bereitstellt, erkunden Sie die Möglichkeit, einen Proxy SCIM-Dienst einzurichten, der das Update empfängt und die Änderung an das HR-System weitergibt.

  • Option 2 – Verwenden des Microsoft Entra ECMA-Connectors für das Rückschreibszenario

    • Prüfen Sie je nach Kundenanforderung, ob eines der ECMA-Connectors verwendet werden kann (PowerShell/ SQL / Webdienste).

  • Option 3 – Verwenden der benutzerdefinierten Erweiterungsaufgabe für Lebenszyklus-Workflows in einem Zugangsworkflow

Nächste Schritte

  • Last updated on