API-gesteuerte eingehende Bereitstellung mit einem PowerShell-Skript

Artikel
10/18/2024

In diesem Tutorial wird beschrieben, wie Sie ein PowerShell-Skript verwenden, um die API-gesteuerte eingehende Bereitstellung von Microsoft Entra ID zu implementieren. Mit den Schritten in diesem Tutorial können Sie eine CSV-Datei mit Personaldaten in eine Massenanforderungspayload konvertieren und diese an den Microsoft Entra-API-Endpunkt /bulkUpload für die Bereitstellung senden. Der Artikel enthält auch Anweisungen dazu, wie dasselbe Integrationsmuster mit jedem Datensatzsystem verwendet werden kann.

Integrationsszenario

Geschäftsanforderung

Ihr Datensatzsystem generiert in regelmäßigen Abständen CSV-Dateiexporte mit Workerdaten. Sie möchten eine Integration implementieren, die Daten aus der CSV-Datei liest und automatisch Benutzerkonten in Ihrem Zielverzeichnis bereitstellt (lokales Active Directory für Hybridbenutzer*innen und Microsoft Entra ID für reine Cloudbenutzer*innen).

Implementierungsanforderung

Aus Sicht der Implementierung:

Sie möchten ein unbeaufsichtigtes PowerShell-Skript verwenden, um Daten aus den CSV-Dateiexporten zu lesen und an den API-Endpunkt der eingehenden Bereitstellung zu senden.
In Ihrem PowerShell-Skript möchten Sie nicht die komplexe Logik zum Vergleichen von Identitätsdaten zwischen Ihrem Datensatzsystem und dem Zielverzeichnis implementieren.
Sie möchten den Microsoft Entra-Bereitstellungsdienst verwenden, um Ihre von der IT verwalteten Bereitstellungsregeln anzuwenden, um Konten im Zielverzeichnis automatisch zu erstellen/zu aktualisieren/zu aktivieren/zu deaktivieren (lokales Active Directory oder Microsoft Entra-ID).

Variationen des Integrationsszenarios

Während in diesem Tutorial eine CSV-Datei als Datensatzsystem verwendet wird, können Sie das PowerShell-Beispielskript anpassen, um Daten aus einem beliebigen Datensatzsystem zu lesen. Im Folgenden finden Sie eine Liste der Variationen von Unternehmensintegrationsszenarien, bei denen die API-gesteuerte eingehende Bereitstellung mit einem PowerShell-Skript implementiert werden kann.

#	Datensatzsystem	Integrationsleitfaden zur Verwendung von PowerShell zum Lesen von Quelldaten
1	Datenbanktabelle	Wenn Sie eine Azure SQL-Datenbank- oder eine lokale SQL Server-Instanz verwenden, können Sie das Cmdlet Read-SqlTableData verwenden, um in einer Tabelle einer SQL-Datenbank gespeicherte Daten zu lesen. Sie können das Cmdlet Invoke-SqlCmd verwenden, um Transact-SQL- oder XQuery-Skripts auszuführen. Wenn Sie eine Oracle-/MySQL-/Postgres-Datenbank verwenden, können Sie ein vom Anbieter veröffentlichtes oder ein im PowerShell-Katalog verfügbares PowerShell-Modul nutzen. Verwenden Sie das Modul, um Daten aus Ihrer Datenbanktabelle zu lesen.
2	LDAP-Server	Verwenden Sie die .NET-API `System.DirectoryServices.Protocols` oder eines der im PowerShell-Katalog verfügbaren LDAP-Module, um Ihren LDAP-Server abzufragen. Machen Sie sich mit dem LDAP-Schema und der Hierarchie zum Abrufen von Benutzerdaten vom LDAP-Server vertraut.
3	Alle Systeme, die REST-APIs verfügbar machen	Zum Lesen von Daten von einem REST-API-Endpunkt mithilfe von PowerShell können Sie das Cmdlet Invoke-RestMethod aus dem Modul `Microsoft.PowerShell.Utility` verwenden. Sehen Sie sich die Dokumentation Ihrer REST-API an, um zu erfahren, welche Parameter und Header sie erwartet, welches Format sie zurückgibt und welche Authentifizierungsmethode sie verwendet. Anschließend können Sie den Befehl `Invoke-RestMethod` entsprechend anpassen.
4	Alle Systeme, die SOAP-APIs verfügbar machen	Zum Lesen von Daten von einem SOAP-API-Endpunkt mithilfe von PowerShell können Sie das Cmdlet New-WebServiceProxy aus dem Modul `Microsoft.PowerShell.Management` verwenden. Sehen Sie sich die Dokumentation Ihrer SOAP-API an, um zu erfahren, welche Parameter und Header sie erwartet, welches Format sie zurückgibt und welche Authentifizierungsmethode sie verwendet. Anschließend können Sie den Befehl `New-WebServiceProxy` entsprechend anpassen.

Wenden Sie nach dem Lesen der Quelldaten Ihre Vorverarbeitungsregeln an, und konvertieren Sie die Ausgabe Ihres Datensatzsystems in eine Massenanforderung, die an den Microsoft Entra-API-Endpunkt bulkUpload für die Bereitstellung gesendet werden kann.

Wichtig

Wenn Sie Ihr PowerShell-Integrationsskript für die Community freigeben möchten, veröffentlichen Sie es im PowerShell-Katalog, und benachrichtigen Sie uns im GitHub-Repository entra-id-inbound-provisioning, damit wir einen Verweis darauf hinzufügen können.

Zur Verwendung dieses Lernprogramms

Das PowerShell-Beispielskript, das im GitHub-Repository für die eingehende Bereitstellung von Microsoft Entra veröffentlicht wurde, automatisiert verschiedene Aufgaben. Sie enthält Logik für die Verarbeitung großer CSV-Dateien und das Aufteilen der Massenanforderung, sodass pro Anforderung 50 Datensätze gesendet werden. Hier erfahren Sie, wie Sie sie testen und an Ihre Integrationsanforderungen anpassen können.

Hinweis

Das PowerShell-Beispielskript wird in der vorliegenden Form als Referenz für die Implementierung bereitgestellt. Wenn Sie Fragen zu diesem Skript haben oder den Workflow erweitern möchten, verwenden Sie das GitHub-Projektrepository.

#	Automatisierungstask	Implementierungsleitfaden	Erweiterte Anpassung
1	Liest Workerdaten aus der CSV-Datei.	Herunterladen des PowerShell-Skripts. Verfügt über sofort einsatzbereite Logik zum Lesen von Daten aus einer beliebigen CSV-Datei. Informationen zu den verschiedenen Ausführungsmodi dieses Skripts finden Sie unter Csv2SCIM PowerShell-Nutzungsdetails.	Wenn Ihr Datensatzsystem anders ist, lesen Sie die Anleitungen zum Anpassen des PowerShell-Skripts im Abschnitt Variationen des Integrationsszenarios.
2	Vorverarbeiten und Konvertieren von Daten in das SCIM-Format.	Standardmäßig konvertiert das PowerShell-Skript jeden Datensatz in der CSV-Datei in eine SCIM Core User- und Enterprise User-Darstellung. Führen Sie die Schritte im Abschnitt Generieren der Massenanforderungsnutzdaten mit dem Standardschema aus, um sich mit diesem Prozess vertraut zu machen.	Wenn Ihre CSV-Datei unterschiedliche Felder enthält, optimieren Sie die Datei AttributeMapping.psd, um einen gültigen SCIM-Benutzer zu generieren. Sie können auch Massenanforderungen mit einem benutzerdefinierten SCIM-Schema generieren. Aktualisieren Sie das PowerShell-Skript, um beliebige benutzerdefinierte CSV-Datenüberprüfungslogik einzubinden.
3	Verwenden Sie ein Zertifikat für die Authentifizierung bei Microsoft Entra ID.	Erstellen Sie einen Dienstprinzipal, der auf die API für eingehende Bereitstellung zugreifen kann. Informationen zur Verwendung des Clientzertifikats für die Authentifizierung finden Sie in den Schritten im Abschnitt Konfigurieren des Clientzertifikats für die Authentifizierung des Dienstprinzipals.	Wenn Sie eine verwaltete Identität anstelle eines Dienstprinzipals für die Authentifizierung verwenden möchten, überprüfen Sie die Verwendung von `Connect-MgGraph` im Beispielskript, und aktualisieren Sie dieses Element, um verwaltete Identitäten zu verwenden.
4	Bereitstellen von Konten in einer lokalen Active Directory-Instanz oder Microsoft Entra ID.	Konfigurieren der API-gesteuerten eingehenden Bereitstellungs-App. Dadurch wird ein eindeutiger /bulkUpload-API-Endpunkt generiert. Informationen zum Ausführen des Skripts mithilfe eines Dienstprinzipals mit zertifikatbasierter Authentifizierung finden Sie in den Schritten im Abschnitt "Massenanforderungsnutzlast mithilfe der Clientzertifikatauthentifizierung hochladen". Überprüfen Sie den Attributfluss, und passen Sie die Attributzuordnungen gemäß Ihren Integrationsanforderungen an.	Wenn Sie planen, eine Massenanforderung mit benutzerdefiniertem SCIM-Schema zu verwenden, dann erweitern Sie das Schema der Bereitstellungsanwendung, um Ihre benutzerdefinierten SCIM-Schemaelemente einzubeziehen.
5	Überprüfen Sie die Bereitstellungsprotokolle, und wiederholen Sie die Bereitstellung für fehlerhafte Datensätze.	Lesen Sie die Schritte im Abschnitt Abrufen von Bereitstellungsprotokollen der neuesten Synchronisierungszyklen, um zu erfahren, wie Sie Bereitstellungsprotokolldaten abrufen und analysieren. Identifizieren Sie fehlerhafte Benutzerdatensätze, und schließen Sie sie in den nächsten Uploadzyklus ein.	-
6	Stellen Sie Ihre PowerShell-basierte Automatisierung in der Produktion bereit.	Nachdem Sie Ihren API-gesteuerten Bereitstellungsflow überprüft und das PowerShell-Skript an Ihre Anforderungen angepasst haben, können Sie die Automatisierung als PowerShell-Workflowrunbook in Azure Automation oder als Serverprozess bereitstellen, der für die Ausführung auf einem Windows-Server geplant ist.	-

Herunterladen des PowerShell-Skripts

Zugreifen auf das GitHub-Repository entra-id-inbound-provisioning.
Verwenden Sie die Option Code ->Clone oder Code ->Download ZIP, um Inhalte dieses Repositorys in Ihren lokalen Ordner zu kopieren.
Navigieren Sie zum Ordner PowerShell/CSV2SCIM. Er weist die folgende Verzeichnisstruktur auf:
- src
  - CSV2SCIM.ps1 (Hauptskript)
  - ScimSchemaRepresentations (Ordner mit SCIM-Standardschemadefinitionen zum Überprüfen von AttributeMapping.psd1-Dateien)
    - EnterpriseUser.json, Group.json, Schema.json, User.json
- Beispiele
  - AttributeMapping.psd1 (Beispielzuordnung von Spalten in der CSV-Datei zu SCIM-Standardattributen)
  - csv-with-2-records.csv (CSV-Beispieldatei mit zwei Datensätzen)
  - csv-with-1000-records.csv (CSV-Beispieldatei mit 1.000 Datensätzen)
  - Test-ScriptCommands.ps1 (Beispielsyntaxbefehle)
  - UseClientCertificate.ps1 (Skript zum Generieren eines selbstsignierten Zertifikats und Hochladen des Zertifikats als Dienstprinzipalanmeldeinformationen zur Verwendung im OAuth-Flow)
  - Sample1 (Ordner mit weiteren Beispielen, wie CSV-Dateispalten SCIM-Standardattributen zugeordnet werden können. Wenn Sie verschiedene CSV-Dateien für Mitarbeiter, Auftragnehmer und Praktikanten erhalten, können Sie für jede Entität eine separate Datei „AttributeMapping.psd1“ erstellen.)
Laden Sie die aktuelle Version von PowerShell herunter, und installieren Sie sie.
Führen Sie den Befehl aus, um die Ausführung von remote signierten Skripts zu aktivieren:
```
set-executionpolicy remotesigned
```

Installieren Sie die folgenden erforderlichen Module:

Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports

Generieren von Massenanforderungsnutzdaten mit einem Standardschema

In diesem Abschnitt wird erläutert, wie Sie Massenanforderungsnutzsdaten mit standardmäßigen SCIM Core User- und Enterprise User-Attributen aus einer CSV-Datei generieren. Um die Prozedur zu veranschaulichen, verwenden wir die CSV-Datei Samples/csv-with-2-records.csv.

Öffnen Sie die CSV-Datei Samples/csv-with-2-records.csv in Editor++ oder Excel, um die in der Datei vorhandenen Spalten zu überprüfen.

Öffnen Sie in Editor++ oder in einem Quellcode-Editor wie Visual Studio Code die PowerShell-Datendatei Samples/AttributeMapping.psd1, die die Zuordnung von CSV-Dateispalten zu SCIM-Standardschemaattributen ermöglicht. Die standardmäßig enthaltene Datei verfügt bereits über eine vorkonfigurierte Zuordnung von CSV-Dateispalten zu den entsprechenden SCIM-Schemaattributen.

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

Öffnen Sie PowerShell, und navigieren Sie zum Verzeichnis CSV2SCIM\src.
Führen Sie den folgenden Befehl aus, um die Variable AttributeMapping zu initialisieren.
```
$AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
```
Führen Sie den folgenden Befehl aus, um zu überprüfen, ob die Datei AttributeMapping über gültige SCIM-Schemaattribute verfügt. Dieser Befehl gibt TRUE zurück, wenn die Überprüfung erfolgreich ist.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
```
Angenommen, die Datei AttributeMapping verfügt über ein ungültiges SCIM-Attribut namens userId. Dann zeigt der ValidateAttributeMapping-Modus den folgenden Fehler an.
Nachdem Sie überprüft haben, ob die Datei AttributeMapping gültig ist, führen Sie den folgenden Befehl aus, um eine Massenanforderung in der Datei BulkRequestPayload.json zu generieren, die die beiden Datensätze enthält, die in der CSV-Datei vorhanden sind.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
```
Sie können den Inhalt der Datei BulkRequestPayload.json öffnen, um zu überprüfen, ob die SCIM-Attribute gemäß der in der Datei AttributeMapping.psd1 definierten Zuordnung festgelegt sind.
Sie können die oben generierte Datei unverändert an den API-Endpunkt /bulkUpload senden, der mit Ihrer Bereitstellungsanwendung verbunden ist, indem Sie Graph-Tester oder cURL verwenden. Referenz:
- Schnellstart mit Graph-Explorer
- Schnellstart mit cURL
Informationen zum direkten Hochladen der generierten Nutzdatean in den API-Endpunkt mithilfe desselben PowerShell-Skripts finden Sie im nächsten Abschnitt.

Konfigurieren eines Clientzertifikats zur Authentifizierung des Dienstprinzipals

Hinweis

Die Anweisungen hier erläutern, wie Sie ein selbstsigniertes Zertifikat generieren. Selbstsignierten Zertifikaten wird standardmäßig nicht vertraut, und es kann schwierig sein, sie zu verwalten. Außerdem kann es sein, dass für sie veraltete Hash- und Verschlüsselungssammlungen verwendet werden, die möglicherweise nicht stark sind. Um eine bessere Sicherheit zu erreichen, sollten Sie ein Zertifikat kaufen, das von einer bekannten Zertifizierungsstelle signiert ist.

Führen Sie das folgende PowerShell-Skript aus, um ein selbstsigniertes Zertifikat zu generieren. Sie können diesen Schritt überspringen, wenn Sie ein von einer bekannten Zertifizierungsstelle signiertes Zertifikat erworben haben.
```
$ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
$ThumbPrint = $ClientCertificate.ThumbPrint
```
Das generierte Zertifikat wird unter Current User\Personal\Certificates gespeichert. Sie können es mit der Option Systemsteuerung ->Benutzerzertifikate verwalten anzeigen.
Um dieses Zertifikat einem gültigen Dienstprinzipal zuzuordnen, melden Sie sich beim Microsoft Entra Admin Center als Anwendungsadministrator an.
Öffnen Sie den Dienstprinzipal, den Sie unter App-Registrierungen konfiguriert haben.
Kopieren Sie die Objekt-ID vom Blatt Übersicht. Verwenden Sie den Wert, um die Zeichenfolge <AppObjectId> zu ersetzen. Kopieren Sie die Anwendungs-ID (Client-ID). Sie wird später verwendet und wird als <AppClientId> referenziert.

Führen Sie den folgenden Befehl aus, um Ihr Zertifikat in den registrierten Dienstprinzipal hochzuladen.

Connect-MgGraph -Scopes "Application.ReadWrite.All"
Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{
   Type = "AsymmetricX509Cert"
   Usage = "Verify"
   Key = $ClientCertificate.RawData
}

Das Zertifikat sollte auf dem Blatt Zertifikate und Geheimnisse Ihrer registrierten App angezeigt werden.

Fügen Sie der Dienstprinzipal-App die folgenden beiden Anwendungsberechtigungsbereiche hinzu: Application.Read.All und Synchronization.Read.All. Diese sind erforderlich, damit das PowerShell-Skript die Bereitstellungs-App nach ServicePrincipalId nachschlagen und die Bereitstellungs-JobId abrufen kann.

Hochladen der Massenanforderungsnutzdaten mithilfe von Clientzertifikatauthentifizierung

In diesem Abschnitt wird erläutert, wie Sie die generierten Massenanforderungsnutzdaten an Ihren API-Endpunkt für die eingehende Bereitstellung mithilfe eines vertrauenswürdigen Clientzertifikats senden.

Öffnen Sie die API-gesteuerte Bereitstellungs-App, die Sie konfiguriert haben. Kopieren Sie die ServicePrincipalId, die mit Ihrer Bereitstellungs-App verbunden ist, aus Bereitstellungs-App>Eigenschaften>Objekt-ID.

Führen Sie den folgenden Befehl aus, indem Sie die richtigen Werte für ServicePrincipalId, ClientId und TenantId bereitstellen.

$ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
$ThumbPrint = $ClientCertificate.ThumbPrint

.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -TenantId "contoso.onmicrosoft.com" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)

Besuchen Sie das Blatt Bereitstellungsprotokolle Ihrer Bereitstellungs-App, um die Verarbeitung der oben genannten Anforderung zu überprüfen.

Generieren von Massenanforderungen mit einem benutzerdefinierten SCIM-Schema

In diesem Abschnitt wird beschrieben, wie Sie eine Massenanforderung mit einem benutzerdefinierten SCIM-Schemanamespace generieren, der aus Feldern in der CSV-Datei besteht.

Öffnen Sie in Editor++ oder in einem Quellcode-Editor wie Visual Studio Code die PowerShell-Datendatei Samples/AttributeMapping.psd1, die die Zuordnung von CSV-Dateispalten zu SCIM-Standardschemaattributen ermöglicht. Die standardmäßig enthaltene Datei verfügt bereits über eine vorkonfigurierte Zuordnung von CSV-Dateispalten zu den entsprechenden SCIM-Schemaattributen.
Öffnen Sie PowerShell, und navigieren Sie zum Verzeichnis CSV2SCIM\src.
Führen Sie den folgenden Befehl aus, um die Variable AttributeMapping zu initialisieren.
```
$AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
```
Führen Sie den folgenden Befehl aus, um zu überprüfen, ob die Datei AttributeMapping über gültige SCIM-Schemaattribute verfügt. Dieser Befehl gibt TRUE zurück, wenn die Überprüfung erfolgreich ist.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
```
Führen Sie zusätzlich zu den SCIM Core User- und Enterprise User-Attributen den folgenden Befehl aus, um eine Flatlist aller CSV-Felder unter einem benutzerdefinierten SCIM-Schemanamespace urn:ietf:params:scim:schemas:extension:contoso:1.0:User abzurufen.
```
 .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"  > BulkRequestPayloadWithCustomNamespace.json
```
Die CSV-Felder werden unter dem benutzerdefinierten SCIM-Schemanamespace angezeigt.

Erweitern des Bereitstellungsauftragsschemas

Häufig enthält die von HR-Teams gesendete Datendatei weitere Attribute, die keine direkte Darstellung im SCIM-Standardschema besitzen. Um solche Attribute darzustellen, empfehlen wir das Erstellen eines SCIM-Erweiterungsschemas und das Hinzufügen von Attributen unter diesem Namespace.

Das CSV2SCIM-Skript bietet einen Ausführungsmodus namens UpdateSchema, der alle Spalten in der CSV-Datei liest, sie unter einem Erweiterungsschemanamespace hinzufügt und das Schema der Bereitstellungs-App aktualisiert.

Hinweis

Wenn die Attributerweiterungen bereits im Bereitstellungs-App-Schema vorhanden sind, gibt dieser Modus nur eine Warnung aus, dass die Attributerweiterung bereits vorhanden ist. Es gibt also kein Problem beim Ausführen des CSV2SCIM-Skripts im UpdateSchema-Modus, wenn der CSV-Datei neue Felder hinzugefügt werden und Sie diese als Erweiterung hinzufügen möchten.

Um das Verfahren zu veranschaulichen, verwenden wir die CSV-Datei Samples/csv-with-2-records.csv, die im Ordner CSV2SCIM vorhanden ist.

Öffnen Sie die CSV-Datei Samples/csv-with-2-records.csv im Editor, in Excel oder TextPad, um die in der Datei vorhandenen Spalten zu überprüfen.

Führen Sie den folgenden Befehl aus:

.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -UpdateSchema -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"

Sie können die Aktualisierung Ihres Bereitstellungs-App-Schemas überprüfen, indem Sie die Seite Attributzuordnung öffnen und unter Erweiterte Optionen auf die Option Attributliste für API bearbeiten zugreifen.
Die Attributliste zeigt Attribute unter dem neuen Namespace an.

Abrufen von Bereitstellungsprotokollen der neuesten Synchronisierungszyklen

Nach dem Senden der Massenanforderung können Sie die Protokolle der neuesten Synchronisierungszyklen abfragen, die von Microsoft Entra ID verarbeitet wurden. Sie können die Synchronisierungsstatistiken und Verarbeitungsdetails mit dem PowerShell-Skript abrufen und zur Analyse speichern.

Führen Sie den folgenden Befehl aus, um die Protokolldetails und Synchronisierungsstatistiken in der Konsole anzuzeigen:
```
.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
```
Hinweis

NumberOfCycles ist standardmäßig 1. Geben Sie eine Zahl an, um weitere Synchronisierungszyklen abzurufen.
Führen Sie den folgenden Befehl aus, um Synchronisierungsstatistiken in der Konsole anzuzeigen und die Protokolldetails in einer Variablen zu speichern:
```
$logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs
```
Um den Befehl mithilfe von Clientzertifikatauthentifizierung auszuführen, führen Sie den Befehl aus, indem Sie die richtigen Werte für ServicePrincipalId, ClientId und TenantId bereitstellen:
```
$ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
$ThumbPrint = $ClientCertificate.ThumbPrint

$logs=.\CSV2SCIM.ps1 -ServicePrincipalId "<ProvisioningAppObjectId>" -TenantId "contoso.onmicrosoft.com" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint) -GetPreviousCycleLogs -NumberOfCycles 1
```
- Um die Details eines bestimmten Datensatzes anzuzeigen, können wir eine Schleife in die Sammlung einfügen oder einen bestimmten Index auswählen, z. B. $logs[0].
- Wir können auch die where-object-Anweisung verwenden, um mit sourceID oder DisplayName nach einem bestimmten Datensatz zu suchen. In der ProvisioningLogs-Eigenschaft finden Sie alle Details des Vorgangs, der für diesen bestimmten Datensatz ausgeführt wurde.
```
$user = $logs | where sourceId -eq '1222'
$user.ProvisioningLogs | fl
```
- Die spezifischen benutzerseitig betroffenen Eigenschaften werden im ModifiedProperties-Attribut angezeigt. $user.ProvisioningLogs.ModifiedProperties

Anhang

PowerShell-Syntaxdetails von CSV2SCIM

Hier finden Sie eine Liste der Befehlszeilenparameter, die vom CSV2SCIM-PowerShell-Skript akzeptiert werden.

PS > CSV2SCIM.ps1 -Path <path-to-csv-file> 
[-ScimSchemaNamespace <customSCIMSchemaNamespace>] 
[-AttributeMapping $AttributeMapping] 
[-ServicePrincipalId <spn-guid>] 
[-ValidateAttributeMapping]
[-UpdateSchema]
[-ClientId <client-id>]
[-ClientCertificate <certificate-object>]
[-RestartService]

Hinweis

Die Befehlszeilenparameter AttributeMapping und ValidateAttributeMapping beziehen sich auf die Zuordnung von CSV-Spaltenattributen zu den SCIM-Standardschemaelementen. Sie beziehen sich nicht auf die Attributzuordnungen, die Sie in der Bereitstellungs-App im Microsoft Entra Admin Center zwischen SCIM-Quellschemaelementen und Zielattributen von Microsoft Entra/lokalen Active Directory-Attributen ausführen.

Parameter	BESCHREIBUNG	Verarbeitungsbemerkungen
Pfad	Der vollständige oder relative Pfad zur CSV-Datei. Beispiel: `.\Samples\csv-with-1000-records.csv`	Erforderlich: Ja
ScimSchemaNamespace	Der benutzerdefinierte SCIM-Schemanamespace, der verwendet werden soll, um alle Spalten in der CSV-Datei als benutzerdefinierte SCIM-Attribute zu senden, die zu einem bestimmten Namespace gehören. Zum Beispiel, `urn:ietf:params:scim:schemas:extension:csv:1.0:User`	Erforderlich: Nur wenn Sie: – das Schema der Bereitstellungsanwendung aktualisieren oder benutzerdefinierte SCIM-Attribute in die Nutzdaten einbeziehen möchten.
AttributeMapping	Verweist auf eine PowerShell-Datendatei (PSD1-Erweiterung), die Spalten in der CSV-Datei SCIM Core User- und Enterprise User-Attributen zuordnet. Siehe Beispiel: Datei „AttributeMapping.psd“ für das CSV2SCIM-Skript. Beispiel: powershell $AttributeMapping = Import-PowerShellDataFile '.\Samples\AttributeMapping.psd1'`-AttributeMapping $AttributeMapping	Erforderlich: Ja Das einzige Szenario, in dem Sie dies nicht angeben müssen, ist die Verwendung des `UpdateSchema`-Schalters.
ValidateAttributeMapping	Verwenden Sie dieses Schalterflag, um zu überprüfen, ob die AttributeMapping-Datei Attribute enthält, die dem SCIM Core- und Enterprise-Benutzerschema entsprechen.	Erforderlich: Nein Verwendung wird empfohlen, um Konformität sicherzustellen.
ServicePrincipalId	Der GUID-Wert der Dienstprinzipal-ID Ihrer Bereitstellungs-App, den Sie aus Bereitstellungs-App>Eigenschaften>Objekt-ID abrufen können	Erforderlich: Nur, wenn Sie Folgendes ausführen möchten: – Aktualisieren des Bereitstellungs-App-Schemas oder – Senden der generierten Massenanforderung an den API-Endpunkt.
UpdateSchema	Verwenden Sie diesen Schalter, um das Skript anzuweisen, die CSV-Spalten zu lesen und als benutzerdefinierte SCIM-Attribute in Ihrem Bereitstellungs-App-Schema hinzuzufügen.
ClientId	Die Client-ID einer in Microsoft Entra registrierten App, die für den OAuth-Authentifizierungsflow verwendet werden soll. Diese App muss über gültige Zertifikatanmeldeinformationen verfügen.	Erforderlich: Nur beim Ausführen von zertifikatbasierter Authentifizierung.
ClientCertificate	Das Clientauthentifizierungszertifikat, das während des OAuth-Flows verwendet werden soll.	Erforderlich: Nur beim Ausführen von zertifikatbasierter Authentifizierung.
GetPreviousCycleLogs	Abrufen von Bereitstellungsprotokollen der neuesten Synchronisierungszyklen.
NumberOfCycles	Angeben, wie viele Synchronisierungszyklen abgerufen werden sollen. Dieser Wert ist standardmäßig 1.
RestartService	Mit dieser Option hält das Skript den Bereitstellungsauftrag vorübergehend an, bevor die Daten hochgeladen werden, lädt die Daten hoch und startet den Auftrag dann erneut, um die sofortige Verarbeitung der Nutzdaten sicherzustellen.	Verwenden Sie diese Option nur in der Testphase.

Datei „AttributeMapping.psd“

Diese Datei wird zum Zuordnen von Spalten in der CSV-Datei zu standardmäßigen SCIM Core User- und Enterprise User-Attributschemaelementen verwendet. Die Datei generiert auch eine geeignete Darstellung des CSV-Dateiinhalts als Massenanforderungsnutzdaten.

Im nächsten Beispiel haben wir die folgenden Spalten in der CSV-Datei den entsprechenden SCIM Core User- und Enterprise User-Attributen zugeordnet.

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

Freigeben über

API-gesteuerte eingehende Bereitstellung mit einem PowerShell-Skript

Integrationsszenario

Geschäftsanforderung

Implementierungsanforderung

Variationen des Integrationsszenarios

Zur Verwendung dieses Lernprogramms

Herunterladen des PowerShell-Skripts

Generieren von Massenanforderungsnutzdaten mit einem Standardschema

Konfigurieren eines Clientzertifikats zur Authentifizierung des Dienstprinzipals

Hochladen der Massenanforderungsnutzdaten mithilfe von Clientzertifikatauthentifizierung

Generieren von Massenanforderungen mit einem benutzerdefinierten SCIM-Schema

Erweitern des Bereitstellungsauftragsschemas

Abrufen von Bereitstellungsprotokollen der neuesten Synchronisierungszyklen

Anhang

PowerShell-Syntaxdetails von CSV2SCIM

Datei „AttributeMapping.psd“

Nächste Schritte

Feedback

Zusätzliche Ressourcen