Så här konfigurerar du molnsynkronisering programmatiskt med MS Graph API

I följande dokument beskrivs hur du replikerar en synkroniseringsprofil från grunden med endast MSGraph-API:er.
Strukturen för hur du replikerar en synkroniseringsprofil består av följande steg. Dessa är:

• Så här konfigurerar du molnsynkronisering programmatiskt med MS Graph API
  • Grundläggande konfiguration
    • Aktivera hyregästflaggor
  • Skapa tjänsthuvudnamn
  • Skapa synkroniseringsjobb
  • Uppdatera måldomän
  • Aktivera synkronisering av lösenordshashvärden på konfigurationsbladet
  • Tillbakaskrivning av Exchange Hybrid
  • Oavsiktliga borttagningar
    • Aktivera och ställa in tröskelvärdet
    • Tillåta borttagningar
  • Starta synkroniseringsjobb
  • Status för granskning
  • Nästa steg

Använd dessa Microsoft Graph PowerShell-kommandon för att aktivera synkronisering för en produktionsklientorganisation, en förutsättning för att kunna anropa administrationswebbtjänsten för den klientorganisationen.

Grundläggande konfiguration

Aktivera klientflaggor

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

Den här cmdleten möjliggör synkronisering för en klientorganisation. Den använder Get-MgOrganization för att hämta organisationens ID.

Skapa tjänsthuvudnamn

Därefter måste vi skapa AD2AAD-programmet/tjänstens huvudnamn

Du måste använda det här program-ID:t 1a4721b3-e57f-4451-ae87-ef078703ec94. DisplayName är AD-domänens URL om den används i portalen (till exempel contoso.com), men den kan namnges något annat.

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

Skapa synkroniseringsjobb

Utdata från föregående kommando returnerar objectId för tjänstens huvudobjekt som skapades. I det här exemplet är objectId aaaaaaaaa-0000-1111-2222-bbbbbbbbbbbbbb. Använd Microsoft Graph för att lägga till ett synkroniseringsjobb till tjänstehuvudet.

Dokumentation för att skapa ett synkroniseringsjobb finns här.

Om du inte har sparat ID:t hittar du tjänstens huvudnamn genom att köra följande MS Graph-anrop. Du behöver Directory.Read.All-behörigheter för att göra det anropet:

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

Leta sedan efter appnamnet i utdata.

Kör följande två kommandon för att skapa två jobb: ett för användare/gruppetablering och ett för synkronisering av lösenordshash. Det är samma begäran, men två gånger med olika mall-ID:n.

Anropa följande två begäranden:

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"
}

Du behöver två anrop om du vill skapa båda.

Exempel på returvärde (för provisionering):

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": []
    }
}

Uppdatera måldomän

För denna hyresgäst är objektidentifieraren och programidentifieraren för tjänsthuvudnamnet följande:

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

Vi måste uppdatera domänen som den här konfigurationen är inriktad på, så uppdatera hemligheterna för den här domänen.

Kontrollera att domännamnet du använder är samma URL som du angav för den lokala domänkontrollanten.

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

Lägg till följande nyckel/värde-par i följande värdematris baserat på vad du försöker göra:

• Aktivera både PHS- och synkroniseringsklientflaggor { nyckel: "AppKey", värde: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Aktivera endast synkroniseringsklientflagga (aktivera inte PHS) { nyckel: "AppKey", värde: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Det förväntade svaret är ... HTTP 204/Inget innehåll

Här är det markerade värdet "Domän" namnet på den lokala Active Directory-domän från vilken poster ska etableras till Microsoft Entra ID.

Aktivera synkronisering av lösenordshashvärden på konfigurationsbladet

Det här avsnittet beskriver hur du aktiverar synkronisering av lösenordshashvärden för en viss konfiguration. Den här situationen skiljer sig från den AppKey-hemlighet som aktiverar funktionsflaggan på klientnivå. Den här proceduren gäller endast för en enda domän/konfiguration. Du måste ange programnyckeln till PHS för att den här proceduren ska fungera från slutpunkt till slutpunkt.

1. Hämta schemat (varning, det är ganska stort):

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

2. Ta den här CredentialData-attributmappningen:

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

3. Hitta följande objektmappningar med följande namn i schemat

   • Etablera Active Directory-användare
   • Tillhandahålla Active Directory inetOrgPersons

   Objektmappningar finns i schema.synchronizationRules[0].objectMappings (för tillfället kan du anta att det bara finns en synkroniseringsregel)

4. Ta CredentialData-mappningen från steg (2) och infoga den i objektmappningarna i steg (3)

   Objektmappningen ser ut ungefär så här:

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

   Kopiera/klistra in mappningen från steget Skapa AD2AADProvisioning- och AD2AADPasswordHash-jobb i matrisen attributeMappings.

   Ordningen på element i den här matrisen spelar ingen roll (serverdelen sorterar åt dig). Var försiktig med att lägga till den här attributmappningen om namnet redan finns i matrisen. Om det till exempel redan finns ett objekt i attributeMappings som har targetAttributeName CredentialData kan du få konfliktfel, eller så kan befintliga och nya mappningar kombineras. Vanligtvis är detta inte det önskade resultatet. Backend sker inte dedupliceringen åt dig.

   Kom ihåg att göra den här åtgärden för både Användare och InetOrgpersoner.

5. Spara schemat som du skapar:

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

Lägg till schemat i begärandetexten.

Tillbakaskrivning av Exchange Hybrid (offentlig förhandsversion)

Det här avsnittet beskriver hur du aktiverar/inaktiverar och använder exchange hybrid writeback programmatiskt.

Att aktivera Exchange Hybrid-tillbakaskrivning programmatiskt kräver två steg.

1. Schemaverifiering
2. Skapa återskrivningsjobbet för Exchange Hybrid

Verifiering av schema

Innan du aktiverar och använder Exchange Hybrid-tillbakaskrivning måste molnsynkronisering avgöra om den lokala Active Directory har utökats för att inkludera Exchange-schemat.

Du kan använda directoryDefinition:discover för att initiera schemaidentifiering.

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

Det förväntade svaret är ... HTTP 200/OK

Svaret bör se ut ungefär så här:

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

Kontrollera nu om attributet mailNickName finns. Om det är det verifieras schemat och innehåller Exchange-attributen. Om inte granskar du kraven för tillbakaskrivning av Exchange Hybrid.

Skapa jobbet för hybrid-återskrivning i Exchange

När du har verifierat schemat kan du skapa jobbet.

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

Oavsiktliga borttagningar

Det här avsnittet beskriver hur du programmatiskt aktiverar/inaktiverar och använder oavsiktliga borttagningar programmatiskt.

Aktivera och ställa in tröskelvärdet

Det finns två inställningar per jobb som du kan använda, de är:

• DeleteThresholdEnabled – Aktiverar skydd mot oavsiktlig borttagning för jobbet när det är inställt på "true". Ställ in på "true" som standard.
• DeleteThresholdValue – definierar det högsta antalet borttagningar som tillåts vid varje körning av jobbet när skydd mot oavsiktliga borttagningar är aktiverat. Värdet är inställt på 500 som standard. Så om värdet är inställt på 500 är det maximala antalet borttagningar som tillåts 499 i varje körning.

Inställningarna för borttagningströskeln är en del av SyncNotificationSettings och kan ändras via grafen.

Vi kommer att behöva uppdatera de SyncNotificationSettings som den här konfigurationen riktar sig till, så uppdatera hemligheterna.

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

Lägg till följande nyckel/värde-par i följande värdematris baserat på vad du försöker göra:

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

Inställningen "Aktiverad" i exemplet är för att aktivera/inaktivera e-postmeddelanden när jobbet sätts i karantän.

För närvarande stöds inte PATCH-begäranden för hemligheter. Därför måste du lägga till alla värden i brödtexten i PUT-begäran, som i exemplet, för att bevara de andra värdena.

Befintliga värden för alla hemligheter kan hämtas med hjälp av:

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

Tillåta borttagningar

Om du vill tillåta att dessa borttagningar flödar igenom när jobbet hamnar i karantän måste du göra en omstart med bara "ForceDeletes" som omfång.

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

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

Starta synkroniseringsjobb

Jobben kan hämtas igen via följande kommando:

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

Dokumentation för att hämta jobb finns här.

Starta jobben genom att utfärda den här begäran med hjälp av objectId för tjänstens huvudnamn som skapades i det första steget och jobbidentifierarna som returnerades från begäran som skapade jobbet.

Dokumentation om hur du startar ett jobb finns här.

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

Det förväntade svaret är ... HTTP 204/Inget innehåll.

Andra kommandon för att kontrollera jobbet dokumenteras här.

Om du vill starta om ett jobb använder du:

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

Statusöversikt

Hämta jobbstatusar via:

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

Leta efter relevant information under avsnittet status i returobjektet

Nästa steg

• Vad är Microsoft Entra molnsynkronisering?
• Transformationer
• Synkroniserings-API