Condividi tramite

Domande frequenti sul provisioning in ingresso basato su API

  • Articolo

Questo articolo contiene le risposte a domande frequenti sul provisioning in ingresso basato su API.

In che cosa la nuova API di provisioning in ingresso /bulkUpload si differenzia dall'API Utenti di Microsoft Graph?

Esistono differenze significative tra l'API di provisioning /bulkUpload e l'endpoint API Utenti di Microsoft Graph.

  • Formato del payload: nell'endpoint API Utenti di Microsoft Graph i dati devono essere in formato OData. Il formato del payload della richiesta per la nuova API di provisioning in ingresso /bulkUpload usa i costrutti dello schema SCIM. Quando si richiama questa API, impostare l'intestazione "Content-Type" su application/scim+json.
  • Risultato finale dell'operazione:
    • Quando i dati di identità vengono inviati all'endpoint API Utenti di Microsoft Graph, vengono elaborati immediatamente e viene eseguita un'operazione Create/Update/Delete nel profilo utente di Microsoft Entra.
    • I dati della richiesta inviati all'API di provisioning /bulkUpload vengono elaborati in modo asincrono dal servizio di provisioning di Microsoft Entra. Il processo di provisioning applica regole di ambito, mapping degli attributi e trasformazione configurati dall'amministratore IT. Viene avviata un'operazione Create/Update/Delete sul profilo utente di Microsoft Entra o sul profilo utente di Active Directory locale.
  • L'amministratore IT mantiene il controllo: con il provisioning in ingresso basato su API l'amministratore IT ha maggiore controllo sull'elaborazione dei dati di identità in ingresso e sul mapping di tali dati agli attributi di Microsoft Entra. Può definire regole di definizione dell'ambito per escludere determinati tipi di dati di identità, ad esempio i dati terzisti, e usare funzioni di trasformazione per derivare nuovi valori prima di impostare i valori degli attributi nel profilo utente.

L'API di provisioning in ingresso /bulkUpload è un nuovo endpoint SCIM standard?

L'API di provisioning in ingresso /bulkUpload di Microsoft Graph usa lo schema SCIM nel payload della richiesta, ma non è un endpoint API SCIM standardizzato. Ecco perché.

In genere, un endpoint servizio SCIM elabora le richieste HTTP (POST, PUT, GET) con payload SCIM e le converte nelle rispettive operazioni (Create, Update, Lookup) nell'archivio identità. Con l'endpoint servizio SCIM, l'onere di specificare la semantica dell'operazione, se creare/aggiornare/eliminare un'identità rispettivamente con Create/Update/Delete, spetta al client dell'API SCIM. Questo meccanismo è ottimale per gli scenari in cui il client API riconosce l'operazione da eseguire per gli utenti nell'archivio identità.

L'API di provisioning in ingresso /bulkUpload di Microsoft Graph è progettata per gestire uno scenario diverso di integrazione delle identità aziendali in base a tre requisiti univoci:

  1. Capacità di elaborare in modo asincrono i record in blocco (ad esempio, l'elaborazione di oltre 50.000 record)
  2. Capacità di includere qualsiasi attributo di identità nel payload (ad esempio, costCenter, pay grade, badgeId)
  3. Supporto di client API non a conoscenza della semantica delle operazioni. Questi client sono client API non SCIM che hanno accesso solo a dati di origine non elaborati (ad esempio, record in file CSV, tabella SQL o record HR). Questi client non hanno la capacità di elaborazione per leggere ogni record e determinare la semantica delle operazioni di Create/Update/Delete nell'archivio identità.

L'obiettivo principale dell'API di provisioning in ingresso /bulkUpload di Microsoft Graph è consentire ai clienti di inviare qualsiasi tipo di dati di identità (ad esempio, costCenter, pay grade, badgeId) da qualsiasi origine dati di identità (ad esempio CSV/SQL/HR) per l'elaborazione finale da parte del servizio di provisioning di Microsoft Entra. Il servizio di provisioning di Microsoft Entra utilizza i dati del payload in blocco ricevuti in questo endpoint, applica regole di mapping degli attributi configurate dall'amministratore IT e determina se il payload dei dati implica un'operazione (Create, Update, Enable, Disable) nell'archivio identità di destinazione (ID Microsoft Entra/Active Directory locale).

L'API di provisioning /bulkUpload supporta come destinazione i domini di Active Directory locale?

Sì, l'API di provisioning supporta come destinazione i domini di Active Directory locale.

Come è possibile ottenere l'endpoint API /bulkUpload per l'app di provisioning?

L'API /bulkUpload è disponibile solo per le app di tipo: "Provisioning in ingresso basato su API in Microsoft Entra ID" e "Provisioning in ingresso basato su API in Active Directory locale". È possibile recuperare l'endpoint API univoco per ogni app di provisioning dalla home page del riquadro Provisioning. In Statistiche a oggi>Visualizza le informazioni tecniche copiare l'URL indicato in Endpoint dell'API di provisioning.

Il formato è il seguente:

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

Come è possibile eseguire una sincronizzazione completa usando l'API di provisioning /bulkUpload?

Per eseguire una sincronizzazione completa, usare il client API per inviare i dati di tutti gli utenti dall'origine attendibile all'endpoint API come richiesta in blocco. Dopo aver inviato tutti i dati all'endpoint API, il ciclo di sincronizzazione successivo elabora tutti i record utente e consente di tenere traccia dello stato usando l'endpoint API dei log di provisioning.

Come si esegue la sincronizzazione differenziale usando l'API di provisioning /bulkUpload?

Per eseguire una sincronizzazione differenziale, usare il client API solo per inviare informazioni sugli utenti i cui dati sono cambiati nell'origine attendibile. Dopo aver inviato tutti i dati all'endpoint API, il ciclo di sincronizzazione successivo elabora tutti i record utente e consente di tenere traccia dello stato usando l'endpoint API dei log di provisioning.

Come funziona il riavvio del provisioning?

Usare l'opzione Riavvia provisioning solo se necessario. Ecco come funziona:

Scenario 1: quando si fa clic sul pulsante Riavvia provisioning e il processo è attualmente in esecuzione, il processo continua a elaborare i dati esistenti già sottoposti a gestione temporanea. L'operazione Riavvia provisioning non interrompe un ciclo esistente. Nel ciclo successivo il servizio di provisioning cancella gli eventuali depositi e seleziona la nuova richiesta in blocco per l'elaborazione.

Scenario 2: quando si fa clic sul pulsante Riavvia provisioning e il processo non è in esecuzione, quindi prima di eseguire il ciclo successivo, il motore di provisioning elimina i dati caricati prima del riavvio, cancella eventuali depositi ed elabora solo i nuovi dati in ingresso.

Come si creano utenti usando l'endpoint API di provisioning /bulkUpload?

Ecco come il processo di provisioning associato all'endpoint API /bulkUpload elabora i payload utente in ingresso:

  1. Il processo recupera il mapping degli attributi per il processo di provisioning e prende nota della coppia di attributi corrispondenti. Per impostazione predefinita si usa l'attributo API externalId per la corrispondenza con employeeId in Microsoft Entra ID.
  2. È possibile modificare questa coppia di attributi corrispondenti predefinita.
  3. Il processo estrae ogni operazione presente nel payload della richiesta in blocco.
  4. Il processo controlla il valore corrispondente all'identificatore nella richiesta (per impostazione predefinita l'attributo externalId) e lo usa per verificare se in Microsoft Entra ID è presente un utente con il valore employeeId corrispondente.
  5. Se non trova un utente corrispondente, il processo applica le regole di sincronizzazione e crea un nuovo utente nella directory di destinazione.

Per assicurarsi che in Microsoft Entra ID vengano creati gli utenti corretti, definire nel mapping la coppia di attributi corrispondenti corretta che identifica in modo univoco gli utenti nell'origine e in Microsoft Entra ID.

Come si generano valori univoci per l'UPN?

Il servizio di provisioning non consente di verificare la presenza di valori userPrincipalName (UPN) duplicati e di gestire i conflitti. Se la regola di sincronizzazione predefinita per l'attributo UPN genera un valore di UPN esistente, l'operazione di creazione dell'utente non riesce.

Ecco alcune opzioni che è possibile prendere in considerazione per generare UPN univoci:

  1. Aggiungere la logica per la generazione di UPN univoci nel client API.
  2. Aggiornare la regola di sincronizzazione per l'attributo UPN per usare la funzione RandomString e impostare il parametro di applicazione mapping su On object creation only. Esempio:

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

  1. Se si effettua il provisioning in Active Directory locale, è possibile usare la funzione SelectUniqueValue e impostare il parametro di applicazione mapping su On object creation only.

Come è possibile inviare altri attributi HR all'endpoint API di provisioning /bulkUpload?

Per impostazione predefinita, l'endpoint API supporta l'elaborazione di qualsiasi attributo che fa parte dello schema utente aziendale e utente di base SCIM standard. Se si vogliono inviare altri attributi, è possibile estendere lo schema dell'app di provisioning, eseguire il mapping dei nuovi attributi agli attributi di Microsoft Entra e aggiornare la richiesta in blocco per inviare tali attributi. Vedere l'esercitazione Estendere il provisioning in ingresso basato su API per sincronizzare gli attributi personalizzati.

Come si escludono determinati utenti dal flusso di provisioning?

Si immagini uno scenario in cui si vogliono inviare tutti gli utenti all'endpoint API, ma includere solo determinati utenti nel flusso di provisioning escludendo quelli rimanenti.

A tale scopo, è possibile usare il filtro di ambito. Nella configurazione dell'app di provisioning è possibile definire un ambito degli oggetti di origine ed escludere dall'elaborazione determinati utenti usando una "regola di inclusione" (ad esempio per elaborare gli utenti in cui department EQUALS Sales) o una "regola di esclusione" (ad esempio, per escludere gli utenti appartenenti a Sales, department NOT EQUALS Sales).

Vedere Definire l'ambito di utenti o gruppi di cui effettuare il provisioning con i filtri di ambito.

Come si aggiornano gli utenti usando l'endpoint API di provisioning /bulkUpload?

Ecco come il processo di provisioning associato all'endpoint API /bulkUpload elabora i payload utente in ingresso:

  1. Il processo di provisioning recupera il mapping degli attributi per il processo di provisioning e prende nota della coppia di attributi corrispondenti. Per impostazione predefinita si usa l'attributo API externalId per la corrispondenza con employeeId in Microsoft Entra ID. È possibile modificare questa coppia di attributi corrispondenti predefinita.
  2. Il processo estrae le operazioni dal payload della richiesta in blocco.
  3. Il processo controlla il valore corrispondente all'identificatore nella richiesta SCIM (per impostazione predefinita l'attributo API externalId) e lo usa per verificare in Microsoft Entra ID è presente un utente con il valore employeeId corrispondente.
  4. Se trova un utente corrispondente, il processo applica le regole di sincronizzazione e confronta i profili di origine e di destinazione.
  5. Se determina che alcuni valori sono stati modificati, il processo aggiorna quindi il record utente corrispondente nella directory.

Per assicurarsi che in Microsoft Entra ID vengano aggiornati gli utenti corretti, definire nel mapping la coppia di attributi corrispondenti corretta che identifica in modo univoco gli utenti nell'origine e in Microsoft Entra ID.

È possibile creare più app che supportano il provisioning in ingresso basato su API?

Si, puoi. Ecco alcuni scenari che potrebbero richiedere più app di provisioning:

Scenario 1: si supponga di avere tre origini dati attendibili: una per i dipendenti, una per i terzisti e una per i fornitori. È possibile creare tre app di provisioning separate, una per ogni tipo di identità con il proprio mapping di attributi distinti. Ogni app di provisioning ha un endpoint API univoco, al quale è possibile inviare i rispettivi payload.

È possibile recuperare l'endpoint API univoco per ogni processo dalla home page del riquadro Provisioning. Passare a Statistiche a oggi>Visualizza le informazioni tecniche e quindi copiare l'URL indicato in Endpoint dell'API di provisioning.

Scenario 2: si supponga di avere più origini di riferimento, ognuna con un proprio set di attributi. Ad esempio, HR fornisce gli attributi relativi alle informazioni sul lavoro (ad esempio jobTitle, employeeType), mentre il sistema di notifiche fornisce gli attributi relativi alle informazioni sulle notifiche (ad esempio badgeId, che viene rappresentato con un attributo di estensione). In questo scenario è possibile configurare due app di provisioning:

  • App di provisioning 1 che riceve gli attributi dall'origine HR e crea l'utente.

  • App di provisioning 2 che riceve gli attributi dal sistema di notifiche e aggiorna solo gli attributi utente. Il mapping degli attributi in questa app è limitato agli attributi delle informazioni sulle notifiche e in Azioni oggetto di destinazione è abilitato solo l'aggiornamento.

  • Entrambe le app usano la stessa coppia di identificatori corrispondenti (externalId<->employeeId).

Come si elaborano le terminazioni con l'endpoint API /bulkUpload?

Per elaborare le terminazioni, identificare nell'origine un attributo che verrà usato per impostare il flag accountEnabled in Microsoft Entra ID. Se si effettua il provisioning in Active Directory locale, eseguire il mapping dell'attributo dell'origine all'attributo accountDisabled.

Per impostazione predefinita, il valore associato all'attributo active dello schema utente di base SCIM determina lo stato dell'account dell'utente nella directory di destinazione.

Se l'attributo è impostato su true, la regola di mapping predefinita abilita l'account. Se l'attributo è impostato su false, la regola di mapping predefinita disabilita l'account.

Come è possibile impedire la disabilitazione o l'eliminazione accidentale degli utenti?

Per impedire e recuperare eliminazioni accidentali, è consigliabile configurare la soglia di eliminazione accidentale nell'app di provisioning e abilitare il cestino di Active Directory locale. Nel riquadro Mapping attributi dell'app di provisioning disabilitare l'operazione Elimina in Azioni oggetto di destinazione.

Recuperare account eliminati

  • Se la directory di destinazione per l'operazione è Microsoft Entra ID, l'utente corrispondente viene eliminato temporaneamente. L'utente è visibile nella pagina Utenti eliminati dell'Interfaccia di amministrazione di Microsoft Entra per i 30 giorni successivi e durante tale periodo può essere ripristinato.
  • Se la directory di destinazione per l'operazione è Active Directory locale, l'utente corrispondente viene eliminato definitivamente. Se la funzionalità Cestino di Active Directory locale è abilitata, è possibile ripristinare l'oggetto utente di Active Directory locale eliminato.

È necessario inviare tutti gli utenti del sistema HR in ogni richiesta?

No, non è necessario inviare tutti gli utenti del sistema HR o dell'origine di riferimento in ogni richiesta. È sufficiente inviare gli utenti da creare o aggiornare.

L'API supporta tutte le azioni HTTP (GET/POST/PUT/PATCH)?

No, l'endpoint API di provisioning /bulkUpload supporta solo l'azione HTTP POST.

Per aggiornare un utente, è necessario inviare una richiesta PUT/PATCH?

No, l'endpoint API non supporta la richiesta PUT/PATCH. Per aggiornare un utente, inviare i dati associati all'utente nel payload della richiesta in blocco POST.

Il processo di provisioning che elabora i dati ricevuti dall'endpoint API rileva automaticamente se l'utente ricevuto nel payload della richiesta POST deve essere creato/aggiornato/abilitato/disabilitato in base alle regole di sincronizzazione configurate. Come client API, non è necessario eseguire altri passaggi se si vuole aggiornare un profilo utente.

In che modo è supportato il writeback?

L'API corrente supporta solo i dati in ingresso. Ecco alcune opzioni da considerare per implementare il writeback di attributi come email/username/phone generati da Microsoft Entra ID, che è possibile ritrasmettere al sistema HR:

  • Opzione 1 - Connettività SCIM all'endpoint o al servizio proxy di HR che a sua volta aggiorna l'origine HR

    • Se il sistema di registrazione fornisce un endpoint SCIM per gli aggiornamenti utente, è possibile creare un'applicazione SCIM personalizzata nella raccolta di app aziendali e configurare il provisioning come documentato.
    • Se il sistema di registrazione non fornisce un endpoint SCIM, esplorare la possibilità di configurare un servizio SCIM proxy, che riceve l'aggiornamento e propaga la modifica al sistema HR.

  • Opzione 2 - Usare il connettore ECMA di Microsoft Entra per lo scenario di writeback

    • A seconda del requisito del cliente, esaminare se è possibile usare uno dei connettori ECMA (PowerShell/SQL/Servizi Web).

  • Opzione 3 - Usare l'attività dell'estensione personalizzata di Flussi di lavoro del ciclo di vita in un flusso di lavoro di entrata

Passaggi successivi