Provisioning in ingresso basato su API con uno script di PowerShell

Questa esercitazione descrive come usare uno script di PowerShell per implementare il provisioning in ingresso basato su API di Microsoft Entra ID. Usando la procedura descritta in questa esercitazione, è possibile convertire un file CSV contenente i dati HR in un payload della richiesta in blocco e inviarlo all'endpoint API di provisioning /bulkUpload di Microsoft Entra. L'articolo fornisce anche indicazioni su come usare lo stesso modello di integrazione con qualsiasi sistema di registrazione.

Scenario di integrazione

Requisito di business

Il sistema di registrazione in uso genera periodicamente esportazioni di file CSV contenenti dati sui dipendenti. Si vuole implementare un'integrazione che legge i dati dal file CSV ed effettua automaticamente il provisioning degli account utente nella directory di destinazione (Active Directory locale per utenti ibridi e Microsoft Entra ID per gli utenti solo cloud).

Requisito per l'implementazione

Dal punto di vista dell'implementazione:

• Si vuole usare uno script automatico di PowerShell per leggere i dati delle esportazioni di file CSV e inviarli all'endpoint API di provisioning in ingresso.
• Nello script di PowerShell non si vuole implementare la logica complessa del confronto dei dati di identità tra il sistema di registrazione e la directory di destinazione.
• Si vuole usare il servizio di provisioning di Microsoft Entra per applicare le regole di provisioning gestito dall'IT per creare/aggiornare/abilitare/disabilitare automaticamente gli account nella directory di destinazione (Active Directory locale o Microsoft Entra ID).

Varianti dello scenario di integrazione

Anche se questa esercitazione usa un file CSV come sistema di registrazione, è possibile personalizzare lo script di PowerShell di esempio per leggere i dati da qualsiasi sistema di registrazione. Ecco un elenco delle varianti dello scenario di integrazione aziendale, in cui è possibile implementare il provisioning in ingresso basato su API con uno script di PowerShell.

Dopo aver letto i dati di origine, applicare le regole di pre-elaborazione e convertire l'output del sistema di registrazione in una richiesta in blocco che può essere inviata all'endpoint API di provisioning bulkUpload di Microsoft Entra.

Come usare questa esercitazione

Lo script di PowerShell pubblicato nel repository GitHub del provisioning in ingresso di Microsoft Entra automatizza diverse attività. Include la logica per la gestione di file CSV di grandi dimensioni e la suddivisione in blocchi della richiesta in blocco per inviare 50 record in ogni richiesta. Ecco come testarlo e personalizzarlo in base ai requisiti di integrazione.

Scaricare lo script di PowerShell

1. Accedere al repository GitHub entra-id-inbound-provisioning.
2. Usare l'opzione Code ->Clone o Code ->Download ZIP per copiare il contenuto di questo repository nella cartella locale.
3. Passare alla cartella PowerShell/CSV2SCIM. La struttura di directory è la seguente:
   • src
     • CSV2SCIM.ps1 (script principale)
     • ScimSchemaRepresentations (cartella contenente le definizioni dello schema SCIM standard per la convalida dei file AttributeMapping.psd1)
       • EnterpriseUser.json, Group.json, Schema.json, User.json
   • Esempi
     • AttributeMapping.psd1 (mapping di esempio delle colonne del file CSV agli attributi SCIM standard)
     • csv-with-2-records.csv (file CSV di esempio con due record)
     • csv-with-1000-records.csv (file CSV di esempio con 1.000 record)
     • Test-ScriptCommands.ps1 (comandi di utilizzo di esempio)
     • UseClientCertificate.ps1 (script per generare il certificato autofirmato e caricarlo come credenziali dell'entità servizio da usare nel flusso OAuth)
     • Sample1 (cartella con altri esempi di mapping delle colonne del file CSV agli attributi SCIM standard. Se si ottengono file CSV diversi per dipendenti, terzisti, utenti interni, è possibile creare un file AttributeMapping.psd1 separato per ogni entità).
4. Scaricare e installare l'ultima versione di PowerShell.
5. Eseguire il comando per abilitare l'esecuzione di script firmati remoti:

   set-executionpolicy remotesigned
   

6. Installare i moduli prerequisiti seguenti:

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

Generare payload della richiesta bulk con lo schema standard

Questa sezione illustra come generare un payload della richiesta in blocco con gli attributi utente di base e utente aziendale SCIM standard da un file CSV. Per illustrare la procedura, si userà il file CSV Samples/csv-with-2-records.csv.

1. Aprire il file CSV Samples/csv-with-2-records.csv in Notepad++ o Excel per controllare le colonne presenti nel file.

2. In Notepad++ o in un editor di codice sorgente come Visual Studio Code aprire il file di dati di PowerShell Samples/AttributeMapping.psd1 che consente di eseguire il mapping delle colonne del file CSV agli attributi dello schema SCIM standard. Il file fornito contiene già il mapping preconfigurato delle colonne del file CSV agli attributi dello schema SCIM corrispondenti.

       @{
       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'
           }
       }
   }
   

3. Aprire PowerShell e passare alla directory CSV2SCIM\src.

4. Eseguire il comando seguente per inizializzare la variabile AttributeMapping.

   $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
   

5. Eseguire il comando seguente per verificare se il file AttributeMapping contiene attributi dello schema SCIM validi. Se la convalida ha esito positivo, questo comando restituisce true.

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
   

6. Si supponga che il file AttributeMapping includa un attributo SCIM non valido denominato userId, quindi la modalità ValidateAttributeMapping visualizza l'errore seguente.

   

7. Dopo aver verificato che il file AttributeMapping è valido, eseguire il comando seguente per generare una richiesta in blocco nel file BulkRequestPayload.json che include i due record presenti nel file CSV.

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
   

8. È possibile aprire il contenuto del file BulkRequestPayload.json per verificare se gli attributi SCIM sono impostati in base al mapping definito nel file AttributeMapping.psd1.

9. È possibile pubblicare il file generato in precedenza così come è nell'endpoint dell'API /bulkUpload associato all'app di provisioning usando Graph Explorer o cURL. Reference:

   • Avvio rapido con Graph explorer
   • Avvio rapido con cURL

10. Per caricare direttamente il payload generato nell'endpoint API usando lo stesso script di PowerShell, vedere la sezione successiva.

Generare e caricare il payload della richiesta in blocco come utente amministratore

Questa sezione illustra come inviare il payload della richiesta in blocco generata all'endpoint API di provisioning in ingresso.

1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come amministratore applicazione.

2. Passare a App di provisioning>Proprietà>ID oggetto e copiare il valore di ServicePrincipalId associato all'app di provisioning.

   

3. Come utente con ruolo amministratore globale, eseguire il comando seguente specificando i valori corretti per ServicePrincipalId e TenantId. Verrà richiesta l'autenticazione se non esiste già una sessione autenticata per questo tenant. Fornire il consenso alle autorizzazioni richieste durante l'autenticazione.

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com"
   

4. Aprire il pannello Log di provisioning dell'app di provisioning per verificare l'elaborazione della richiesta precedente.

Configurare il certificato client per l'autenticazione dell'entità servizio

1. Eseguire lo script di PowerShell seguente per generare un nuovo certificato autofirmato. È possibile ignorare questo passaggio se è stato acquistato un certificato firmato da un'autorità di certificazione nota.

   $ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
   $ThumbPrint = $ClientCertificate.ThumbPrint
   

   Il certificato generato viene archiviato in Utente corrente\Personale\Certificati. È possibile visualizzarlo con l'opzione Pannello di controllo ->Gestire i certificati utente.
2. Per associare questo certificato a un'entità servizio valida, accedere all'Interfaccia di amministrazione di Microsoft Entra come amministratore applicazione.
3. Aprire l'entità servizio configurata in Registrazioni app.
4. Copiare il valore di ID oggetto dal pannello Panoramica. Usare il valore per sostituire la stringa <AppObjectId>. Copiare il valore di ID applicazione (client). Verrà usato in seguito e vi viene fatto riferimento come <AppClientId>.
5. Eseguire il comando seguente per caricare il certificato nell'entità servizio registrata.

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

   Il certificato dovrebbe essere visualizzato nel pannello Certificati e segreti dell'app registrata.
6. Aggiungere i due ambiti di autorizzazione di Application seguenti all'app dell'entità servizio: Application.Read.All e Synchronization.Read.All. Tali ambiti sono necessari per consentire allo script di PowerShell di cercare l'app di provisioning in base a ServicePrincipalId e recuperare il valore di JobId di provisioning.

Caricare il payload della richiesta in blocco con l'autenticazione del certificato client

Questa sezione illustra come inviare il payload della richiesta in blocco generata all'endpoint API di provisioning in ingresso usando un certificato client attendibile.

1. Aprire l'app di provisioning basato su API configurata. Copiare il valore di ServicePrincipalId associato all'app di provisioning da App di provisioning>Proprietà>ID oggetto.

   

2. Eseguire il comando seguente specificando i valori corretti per ServicePrincipalId, ClientId e TenantId.

   $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)
   

3. Aprire il pannello Log di provisioning dell'app di provisioning per verificare l'elaborazione della richiesta precedente.

Generare una richiesta in blocco con lo schema SCIM personalizzato

Questa sezione descrive come generare una richiesta in blocco con lo spazio dei nomi dello schema SCIM personalizzato costituito da campi nel file CSV.

1. In Notepad++ o in un editor di codice sorgente come Visual Studio Code aprire il file di dati di PowerShell Samples/AttributeMapping.psd1 che consente di eseguire il mapping delle colonne del file CSV agli attributi dello schema SCIM standard. Il file fornito contiene già il mapping preconfigurato delle colonne del file CSV agli attributi dello schema SCIM corrispondenti.

2. Aprire PowerShell e passare alla directory CSV2SCIM\src.

3. Eseguire il comando seguente per inizializzare la variabile AttributeMapping.

   $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
   

4. Eseguire il comando seguente per verificare se il file AttributeMapping contiene attributi dello schema SCIM validi. Se la convalida ha esito positivo, questo comando restituisce true.

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
   

5. Oltre agli attributi dell'utente aziendale e dell'utente di base SCIM, per ottenere un elenco semplice di tutti i campi CSV in uno spazio dei nomi personalizzato urn:ietf:params:scim:schemas:extension:contoso:1.0:User dello schema SCIM, eseguire il comando seguente.

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"  > BulkRequestPayloadWithCustomNamespace.json
   

   I campi CSV verranno visualizzati nello spazio dei nomi dello schema SCIM personalizzato.

Estensione dello schema del processo di provisioning

Spesso il file di dati inviato dai team HR contiene più attributi per i quali non esiste una rappresentazione diretta nello schema SCIM standard. Per rappresentare tali attributi, è consigliabile creare uno schema di estensione SCIM e aggiungere attributi in questo spazio dei nomi.

Lo script CSV2SCIM fornisce una modalità di esecuzione denominata UpdateSchema, che legge tutte le colonne presenti nel file CSV, le aggiunge in uno spazio dei nomi dello schema di estensione e aggiorna lo schema dell'app di provisioning.

Per illustrare la procedura, si userà il file CSV Samples/csv-with-2-records.csv presente nella cartella CSV2SCIM.

1. Aprire il file CSV Samples/csv-with-2-records.csv in Blocco note, Excel o TextPad per controllare le colonne presenti nel file.

   

2. Esegui questo comando:

   .\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"
   

3. Per verificare l'aggiornamento dello schema dell'app di provisioning, aprire la pagina Mapping attributi e accedere all'opzione Modifica elenco attributi per API in Opzioni avanzate.

4. In Elenco attributi sono visualizzati gli attributi presenti nel nuovo spazio dei nomi.

Ottenere i log di provisioning dei cicli di sincronizzazione più recenti

Dopo aver inviato la richiesta in blocco, è possibile eseguire query sui log dei cicli di sincronizzazione più recenti elaborati da Microsoft Entra ID. È possibile recuperare le statistiche di sincronizzazione e i dettagli di elaborazione con lo script di PowerShell e salvarli per l'analisi.

1. Per visualizzare i dettagli dei log e sincronizzare le statistiche nella console, eseguire il comando seguente:

   .\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
   

   

   Nota

   Il valore di NumberOfCycles è 1 per impostazione predefinita. Specificare un numero per recuperare più cicli di sincronizzazione.

2. Per visualizzare le statistiche di sincronizzazione nella console e salvare i dettagli dei log in una variabile, eseguire il comando seguente:

   $logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs
   

   Per eseguire il comando usando l'autenticazione del certificato client, eseguire il comando specificando i valori corretti per ServicePrincipalId, ClientId e TenantId:

   $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
   

   • Per visualizzare i dettagli di un record specifico, è possibile eseguire il ciclo nella raccolta o selezionare un indice specifico, ad esempio: $logs[0]

     

   • È anche possibile usare l'istruzione where-object per cercare un record specifico usando sourceID o DisplayName. Nella proprietà ProvisioningLogs è possibile trovare tutti i dettagli dell'operazione eseguita per tale record specifico.

     $user = $logs | where sourceId -eq '1222'
     $user.ProvisioningLogs | fl
     

     

   • È possibile visualizzare le proprietà interessate dall'utente specifiche nell'attributo ModifiedProperties. $user.ProvisioningLogs.ModifiedProperties

     

Appendice

Dettagli sull'utilizzo di PowerShell per CSV2SCIM

Ecco un elenco di parametri della riga di comando accettati dallo script di PowerShell CSV2SCIM.

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

File AttributeMapping.psd

Questo file viene usato per eseguire il mapping delle colonne del file CSV agli elementi dello schema degli attributi utente aziendale e utente di base SCIM standard. Il file genera anche una rappresentazione appropriata del contenuto del file CSV come payload della richiesta in blocco.

Nell'esempio seguente è stato eseguito il mapping delle colonne seguenti presenti nel file CSV agli attributi utente di base e utente aziendale SCIM corrispondenti.

    @{
    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'
        }
    }
}

Passaggi successivi

• Risolvere i problemi relativi all'API di provisioning in ingresso
• Concetti relativi al provisioning in ingresso basato su API
• Domande frequenti sul provisioning in ingresso basato su API