Come configurare programmaticamente la sincronizzazione cloud a livello di codice usando l'API Graph Microsoft

Il documento seguente descrive come replicare un profilo di sincronizzazione da zero usando solo le API MSGraph.
La struttura di come replicare un profilo di sincronizzazione è costituita dai passaggi seguenti. Sono:

• Come configurare programmaticamente la sincronizzazione cloud a livello di codice usando l'API Graph Microsoft
  • Configurazione di base
    • Abilitare i flag tenant
  • Creare entità servizio
  • Creare un processo di sincronizzazione
  • Aggiornare il dominio di destinazione
  • Abilitare gli hash delle password di sincronizzazione nel pannello di configurazione
  • Writeback della distribuzione ibrida Exchange
  • Eliminazioni accidentali
    • Abilitazione e impostazione della soglia
    • Consenti eliminazioni
  • Avviare il processo di sincronizzazione
  • Esaminare lo stato
  • Passaggi successivi

Usare questi comandi di PowerShell di Microsoft Graph per abilitare la sincronizzazione per un tenant di produzione, un prerequisito per poter chiamare il servizio Web di amministrazione per tale tenant.

Installazione di base

Abilitare i flag tenant

Connect-MgGraph -Scopes "DeviceManagementConfiguration.ReadWrite.All" ('-Environment <AzureEnvironment>')
$organizationId = (Get-MgOrganization).Id
$params = @{
	onPremisesSyncEnabled = $true
}
Update-MgBetaOrganization -OrganizationId $organizationId -BodyParameter $params

Questo cmdlet abilita la sincronizzazione per un tenant. Usa Get-MgOrganization per ottenere l'ID dell'organizzazione.

Creare entità servizio

Successivamente, è necessario creare l'applicazione AD2AAD o l'entità servizio

È necessario usare questo ID applicazione 1a4721b3-e57f-4451-ae87-ef078703ec94. DisplayName è l'URL del dominio AD, se usato nel portale (ad esempio, contoso.com), ma può essere denominato qualcos'altro.

POST https://graph.microsoft.com/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate
Content-type: application/json
{
    displayName: [your app name here]
}

Creare un processo di sincronizzazione

L'output del comando precedente restituisce l'objectId dell'entità servizio creata. Per questo esempio, objectId è aaa-0000-1111-2222-bbbbbbbbbb. Usare Microsoft Graph per aggiungere un processo di sincronizzazione a tale entità servizio.

La documentazione per la creazione di un processo di sincronizzazione è disponibile qui.

Se l'ID non è stato registrato, è possibile trovare l'entità servizio eseguendo la chiamata a MS Graph seguente. Per effettuare la chiamata sono necessarie le autorizzazioni Directory.Read.All:

GET https://graph.microsoft.com/beta/servicePrincipals

Cercare quindi il nome dell'app nell'output.

Eseguire i due comandi seguenti per creare due processi: uno per il provisioning di utenti/gruppi e uno per la sincronizzazione dell'hash delle password. È la stessa richiesta due volte, ma con ID modello diversi.

Chiamare le due richieste seguenti:

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADProvisioning"
} 

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADPasswordHash"
}

Se si vogliono creare entrambe le chiamate, sono necessarie due chiamate.

Valore restituito di esempio (per il provisioning):

HTTP 201/Created
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbc')/synchronization/jobs/$entity",
    "id": "AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da",
    "templateId": "ADDCInPassthrough",
    "schedule": {
        "expiration": null,
        "interval": "PT40M",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "quarantine": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "troubleshootingUrl": null,
        "progress": [],
        "synchronizedEntryCountByType": []
    }
}

Aggiornare il dominio di destinazione

Per questo tenant, l'identificatore dell'oggetto e l'identificatore dell'applicazione dell'entità servizio sono i seguenti:

ObjectId: bbbbbbbb-1111-2222-3333-cccccccccccc
AppId: 00001111-aaaa-2222-bbbb-3333cccc4444
DisplayName: testApp

È necessario aggiornare il dominio di destinazione di questa configurazione, quindi aggiornare i segreti per questo dominio.

Assicurarsi che il nome di dominio usato sia lo stesso URL impostato per il controller di dominio locale.

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

Aggiungere la coppia chiave/valore seguente nella matrice di valori seguente in base a ciò che si sta tentando di eseguire:

• Abilitare i flag del tenant di sincronizzazione e PHS { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Abilitare solo il flag del tenant di sincronizzazione (non attivare PHS) { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

Request body –
{
   "value": [
              {
                "key": "Domain",
                "value": "{\"domain\":\"ad2aadTest.com\"}"
              }
            ]
}

La risposta prevista è ... HTTP 204/Nessun contenuto

In questo caso, il valore "Dominio" evidenziato è il nome del dominio Active Directory locale da cui eseguire il provisioning delle voci in Microsoft Entra ID.

Abilitare gli hash delle password di sincronizzazione nel pannello di configurazione

Questa sezione illustra l'abilitazione degli hash delle password di sincronizzazione per una configurazione specifica. Questa situazione è diversa dal segreto AppKey che abilita il flag di funzionalità a livello di tenant. Questa procedura è solo per un singolo dominio/configurazione. È necessario impostare la chiave dell'applicazione sul phs 1 per questa procedura per terminare la procedura.

1. Afferrare lo schema (avviso, è piuttosto grande):

   GET –https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

2. Eseguire questo mapping di attributi CredentialData:

   {
   "defaultValue": null,
   "exportMissingReferences": false,
   "flowBehavior": "FlowWhenChanged",
   "flowType": "Always",
   "matchingPriority": 0,
   "targetAttributeName": "CredentialData",
   "source": {
   "expression": "[PasswordHash]",
   "name": "PasswordHash",
   "type": "Attribute",
   "parameters": []
   }
   

3. Trovare i mapping degli oggetti seguenti con i nomi seguenti nello schema

   • Effettuare il provisioning di utenti di Active Directory
   • Effettuare il provisioning di Active Directory inetOrgPersons

   I mapping degli oggetti si trovano all'interno di schema.synchronizationRules[0].objectMappings (per il momento è possibile presupporre che sia presente una sola regola di sincronizzazione)

4. Eseguire il mapping di CredentialData dal passaggio (2) e inserirlo nei mapping degli oggetti nel passaggio (3)

   Il mapping degli oggetti è simile al seguente:

   {
   "enabled": true,
   "flowTypes": "Add,Update,Delete",
   "name": "Provision Active Directory users",
   "sourceObjectName": "user",
   "targetObjectName": "User",
   "attributeMappings": [
   ...
   } 
   

   Copiare/incollare il mapping dai processi Create AD2AAADProvisioning e AD2AADPasswordHash nella matrice attributeMappings.

   L'ordine degli elementi in questa matrice non è rilevante (il back-end ordina per l'utente). Prestare attenzione all'aggiunta di questo mapping di attributi se il nome esiste già nella matrice( ad esempio, se è già presente un elemento in attributeMappings con targetAttributeName CredentialData). È possibile che si verifichino errori di conflitto oppure che i mapping nuovi e preesistenti vengano combinati insieme, in genere non il risultato desiderato. Il back-end non deduplica per te.

   Ricordarsi di eseguire questa azione per utenti e inetOrgperson.

5. Salvare lo schema creato:

   PUT –
   https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

Aggiungere lo schema nel corpo della richiesta.

Writeback ibrido di Exchange (anteprima pubblica)

Questa sezione illustra come abilitare/disabilitare e usare il writeback ibrido di Exchange a livello di codice.

L'abilitazione del writeback ibrido di Exchange richiede due passaggi a livello di codice.

1. Verifica dello schema
2. Creare il processo di writeback ibrido di Exchange

Verifica dello schema

Prima di abilitare e usare il writeback ibrido di Exchange, la sincronizzazione cloud deve determinare se il Active Directory locale è stato esteso per includere lo schema di Exchange.

È possibile usare directoryDefinition:discover per avviare l'individuazione dello schema.

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/[AD2AADProvisioningJobId]/schema/directories/[ADDirectoryID]/discover

La risposta prevista è ... HTTP 200/OK

La risposta dovrebbe essere simile all'output seguente:

HTTP/1.1 200 OK
Content-type: application/json
{
  "objects": [
    {
      "name": "user",
      "attributes": [
        {
          "name": "mailNickName",
          "type": "String"
        },
        ...
      ]
    },
    ...
  ]
}

Verificare ora se l'attributo mailNickName è presente. In caso affermativo, lo schema viene verificato e contiene gli attributi di Exchange. In caso contrario, esaminare i prerequisiti per il writeback ibrido di Exchange.

Creare il processo di writeback ibrido di Exchange

Dopo aver verificato lo schema, è possibile creare il processo.

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AAD2ADExchangeHybridWriteback"
}

Eliminazioni accidentali

Questa sezione illustra come abilitare/disabilitare e usare eliminazioni accidentali a livello di codice.

Abilitazione e impostazione della soglia

Sono disponibili due impostazioni per processo che è possibile usare:

• DeleteThresholdEnabled: abilita la prevenzione accidentale dell'eliminazione per il processo quando è impostata su "true". Impostare su "true" per impostazione predefinita.
• DeleteThresholdValue: definisce il numero massimo di eliminazioni consentite in ogni esecuzione del processo quando è abilitata la prevenzione accidentale delle eliminazioni. Il valore è impostato su 500 per impostazione predefinita. Pertanto, se il valore è impostato su 500, il numero massimo di eliminazioni consentite è 499 in ogni esecuzione.

Le impostazioni di eliminazione soglia fanno parte di SyncNotificationSettings e possono essere modificate tramite il grafico.

È necessario aggiornare SyncNotificationSettings per questa configurazione, quindi aggiornare i segreti.

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

Aggiungere la coppia Chiave/valore seguente nella matrice di valori seguente in base a ciò che si sta tentando di eseguire:

Request body -
{
  "value":[
    {
      "key":"SyncNotificationSettings",
      "value": "{\"Enabled\":true,\"Recipients\":\"foobar@xyz.com\",\"DeleteThresholdEnabled\":true,\"DeleteThresholdValue\":50}"
     }
  ]
}

L'impostazione "Abilitato" nell'esempio consiste nell'abilitare/disabilitare i messaggi di posta elettronica di notifica quando il processo viene messo in quarantena.

Attualmente non sono supportate le richieste PATCH per i segreti, quindi è necessario aggiungere tutti i valori nel corpo della richiesta PUT(come nell'esempio) per mantenere gli altri valori.

I valori esistenti per tutti i segreti possono essere recuperati usando:

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

Consenti eliminazioni

Per consentire il flusso di queste eliminazioni dopo che il processo entra in quarantena, è necessario rilasciare un riavvio con solo "ForceDeletes" come ambito.

Request:
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

Request Body:
{
  "criteria": {"resetScope": "ForceDeletes"}
}

Avviare il processo di sincronizzazione

I processi possono essere recuperati di nuovo tramite il comando seguente:

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

La documentazione per il recupero dei processi è disponibile qui.

Per avviare i processi, eseguire questa richiesta usando l'objectId dell'entità servizio creata nel primo passaggio e gli identificatori del processo restituiti dalla richiesta che ha creato il processo.

La documentazione per l'avvio di un processo è disponibile qui.

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

La risposta prevista è ... HTTP 204/Nessun contenuto.

Altri comandi per il controllo del processo sono documentati qui.

Per riavviare un processo, usare:

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/restart
{
  "criteria": {
    "resetScope": "Full"
  }
}

Esaminare lo stato

Recuperare gli stati del processo tramite:

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ 

Per informazioni dettagliate pertinenti, vedere la sezione "status" dell'oggetto restituito

Passaggi successivi

• Cos'è la sincronizzazione cloud di Microsoft Entra?
• Trasformazioni
• API di sincronizzazione