API-gesteuerte eingehende Bereitstellung mit einem PowerShell-Skript
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 Hochladen von Daten auf diesen Endpunkt finden Sie in den Schritten im Abschnitt Generieren und Hochladen von Massenanforderungsnutzdaten als Administratorbenutzer. Überprüfen Sie den Attributfluss, und passen Sie die Attributzuordnungen gemäß Ihren Integrationsanforderungen an. Informationen zum Ausführen des Skripts mithilfe eines Dienstprinzipals mit zertifikatbasierter Authentifizierung finden Sie in den Schritten im Abschnitt Hochladen der Massenanforderungsnutzdaten mithilfe von Clientzertifikatauthentifizierung. | 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.)
- src
- 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.csvin 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
AttributeMappingzu 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 -ValidateAttributeMappingAngenommen, die Datei
AttributeMappingverfügt über ein ungültiges SCIM-Attribut namens userId. Dann zeigt derValidateAttributeMapping-Modus den folgenden Fehler an.
Nachdem Sie überprüft haben, ob die Datei
AttributeMappinggültig ist, führen Sie den folgenden Befehl aus, um eine Massenanforderung in der DateiBulkRequestPayload.jsonzu 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.jsonSie können den Inhalt der Datei
BulkRequestPayload.jsonöffnen, um zu überprüfen, ob die SCIM-Attribute gemäß der in der DateiAttributeMapping.psd1definierten Zuordnung festgelegt sind.Sie können die oben generierte Datei unverändert im /bulkUpload-API-Endpunkt veröffentlichen, der Ihrer Bereitstellungs-App zugeordnet ist, indem Sie Graph Explorer, Postman oder cURL verwenden. Referenz:
Informationen zum direkten Hochladen der generierten Nutzdatean in den API-Endpunkt mithilfe desselben PowerShell-Skripts finden Sie im nächsten Abschnitt.
Generieren und Hochladen der Massenanforderungsnutzdaten als Administratorbenutzer
In diesem Abschnitt wird erläutert, wie Sie die generierten Massenanforderungsnutzdaten an Ihren API-Endpunkt für die eingehende Bereitstellung senden.
Melden Sie sich beim Microsoft Entra Admin Center mindestens als Anwendungsadministrator an.
Wechseln Sie zu Bereitstellungs-App>Eigenschaften>Objekt-ID, und kopieren Sie die
ServicePrincipalId, die Ihrer Bereitstellungs-App zugeordnet ist.
Führen Sie als Benutzer*in mit der Rolle „Globaler Administrator“ den folgenden Befehl aus, indem Sie die richtigen Werte für
ServicePrincipalIdundTenantIdangeben. Sie werden zur Authentifizierung aufgefordert, wenn für diesen Mandanten noch keine authentifizierte Sitzung vorhanden ist. Geben Sie Ihre Zustimmung zu Berechtigungen ein, zu der Sie während der Authentifizierung aufgefordert werden..\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com"Besuchen Sie das Blatt Bereitstellungsprotokolle Ihrer Bereitstellungs-App, um die Verarbeitung der oben genannten Anforderung zu überprüfen.
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.
Das generierte Zertifikat wird unter Current User\Personal\Certificates gespeichert. Sie können es mit der Option Systemsteuerung ->Benutzerzertifikate verwalten anzeigen.$ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My $ThumbPrint = $ClientCertificate.ThumbPrint - 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.
Das Zertifikat sollte auf dem Blatt Zertifikate und Geheimnisse Ihrer registrierten App angezeigt werden.Connect-MgGraph -Scopes "Application.ReadWrite.All" Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{ Type = "AsymmetricX509Cert" Usage = "Verify" Key = $ClientCertificate.RawData }
- 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
ServicePrincipalIdnachschlagen und die Bereitstellungs-JobIdabrufen 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,ClientIdundTenantIdbereitstellen.$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
AttributeMappingzu 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 -ValidateAttributeMappingFü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:Userabzurufen..\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User" > BulkRequestPayloadWithCustomNamespace.jsonDie 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.csvim 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" -GetPreviousCycleLogsUm den Befehl mithilfe von Clientzertifikatauthentifizierung auszuführen, führen Sie den Befehl aus, indem Sie die richtigen Werte für
ServicePrincipalId,ClientIdundTenantIdbereitstellen:$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 1Um 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'
}
}
}
Nächste Schritte
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für