Postup programové konfigurace cloudové synchronizace pomocí rozhraní MS Graph API

Následující dokument popisuje, jak replikovat synchronizační profil úplně od začátku pomocí pouze rozhraní API MSGraph.
Struktura způsobu replikace synchronizačního profilu se skládá z následujících kroků. Mezi ně patří:

• Postup programové konfigurace cloudové synchronizace pomocí rozhraní MS Graph API
  • Základní nastavení
    • Povolení příznaků tenanta
  • Vytvoření instančních objektů
  • Vytvoření úlohy synchronizace
  • Aktualizace cílové domény
  • Povolení hodnot hash hesel synchronizace v okně konfigurace
  • Hybridní zpětný zápis Exchange
  • Náhodné odstranění
    • Povolení a nastavení prahové hodnoty
    • Povolení odstranění
  • Spuštění úlohy synchronizace
  • Kontrola stavu
  • Další kroky

Pomocí těchto příkazů Prostředí Microsoft Graph PowerShell povolte synchronizaci pro produkčního tenanta. Předpokladem pro volání webové služby Správa istrace pro tohoto tenanta.

Základní nastavení

Povolení příznaků tenanta

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

Tato rutina umožňuje synchronizaci pro tenanta. K získání ID organizace se používá Get-MgOrganization .

Vytvoření instančních objektů

Dále potřebujeme vytvořit aplikaci AD2AAD nebo instanční objekt.

Musíte použít toto ID aplikace 1a4721b3-e57f-4451-ae87-ef078703ec94. DisplayName je adresa URL domény AD, pokud se používá na portálu (například contoso.com), ale může mít název něco jiného.

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

Vytvoření úlohy synchronizace

Výstup předchozího příkazu vrátí objectId vytvořeného instančního objektu. V tomto příkladu je objectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbbbbbbb. Pomocí Microsoft Graphu přidejte do daného instančního objektu synchronizační úlohu.

Dokumentaci k vytvoření úlohy synchronizace najdete tady.

Pokud jste ID nezaznamenali, můžete instanční objekt najít spuštěním následujícího volání MS Graphu. K volání potřebujete oprávnění Directory.Read.All:

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

Pak ve výstupu vyhledejte název vaší aplikace.

Spuštěním následujících dvou příkazů vytvořte dvě úlohy: jednu pro zřizování uživatelů nebo skupin a jednu pro synchronizaci hodnot hash hesel. Jedná se o stejný požadavek dvakrát, ale s různými ID šablony.

Zavolejte následující dva požadavky:

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

Pokud chcete vytvořit obojí, potřebujete dvě volání.

Příklad návratové hodnoty (pro zřizování):

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

Aktualizace cílové domény

Pro tohoto tenanta je identifikátor objektu a identifikátor aplikace instančního objektu následující:

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

Budeme muset aktualizovat doménu, na které tato konfigurace cílí, takže aktualizujte tajné kódy pro tuto doménu.

Ujistěte se, že název domény, který používáte, je stejná adresa URL, kterou jste nastavili pro místní řadič domény.

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

Do pole níže uvedených hodnot přidejte následující dvojici klíč/hodnota na základě toho, co se pokoušíte udělat:

• Povolte příznaky PHS i synchronizace tenanta { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Povolte pouze příznak tenanta synchronizace (nezapínejte PHS) { klíč: "AppKey", hodnota: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Očekávaná odpověď je ... HTTP 204/Žádný obsah

Zvýrazněná hodnota Domain (Doména) je název domény místní Active Directory, ze které se mají položky zřídit pro ID Microsoft Entra.

Povolení hodnot hash hesel synchronizace v okně konfigurace

Tato část popisuje povolení synchronizace hodnot hash hesel pro konkrétní konfiguraci. Tato situace se liší od tajného kódu AppKey, který umožňuje příznak funkce na úrovni tenanta. Tento postup je určen pouze pro jednu doménu nebo konfiguraci. Abyste mohli tento postup ukončit, musíte klíč aplikace nastavit na phS.

1. Chyťte schéma (upozornění, je docela velké):

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

2. Proveďte toto mapování atributů CredentialData:

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

3. Najděte následující mapování objektů s následujícími názvy ve schématu.

   • Zřízení uživatelů služby Active Directory
   • Zřízení služby Active Directory inetOrgPersons

   Mapování objektů se nachází v souboru schema.synchronizationRules[0].objectMappings (Prozatím můžete předpokládat, že existuje pouze jedno pravidlo synchronizace).

4. Proveďte mapování CredentialData z kroku (2) a vložte ho do mapování objektů v kroku (3).

   Mapování objektů vypadá přibližně takto:

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

   Zkopírujte nebo vložte mapování z kroku úlohy Create AD2AAADProvisioning a AD2AADPasswordHash do pole attributeMappings.

   Pořadí prvků v tomto poli nezáleží (back-endové řazení za vás). Pokud název již v poli existuje (pokud již existuje položka atributu attributeMappings, která má targetAttributeName CredentialData), buďte opatrní, pokud název již existuje v poli (například pokud existuje položka atributu attributeMappings, která má targetAttributeName CredentialData) – může dojít ke konfliktům chyb nebo může dojít ke sloučení před existujících a nových mapování, obvykle ne požadovaný výsledek. Back-end pro vás neodvádí.

   Nezapomeňte tuto akci provést pro uživatele i uživatele inetOrgpersons.

5. Uložte schéma, které vytvoříte:

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

Přidejte schéma do textu požadavku.

Hybridní zpětný zápis Exchange (Public Preview)

Tato část popisuje, jak povolit nebo zakázat a používat hybridní zpětný zápis Exchange prostřednictvím kódu programu.

Povolení hybridního zpětného zápisu Exchange prostřednictvím kódu programu vyžaduje dva kroky.

1. Ověření schématu
2. Vytvoření úlohy zpětného zápisu hybridního exchange

Ověření schématu

Než povolíte a použijete hybridní zpětný zápis Exchange, musí synchronizace cloudu určit, jestli byla místní Active Directory rozšířena tak, aby zahrnovala schéma Exchange.

K zahájení zjišťování schématu můžete použít directoryDefinition:discover .

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

Očekávaná odpověď je ... HTTP 200/OK

Odpověď by měla vypadat podobně jako v následujícím výstupu:

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

Teď zkontrolujte, jestli existuje atribut mailNickName . Pokud ano, vaše schéma je ověřeno a obsahuje atributy Exchange. Pokud ne, projděte si požadavky na zpětný zápis hybridního exchange.

Vytvoření úlohy zpětného zápisu hybridního exchange

Jakmile ověříte schéma, můžete vytvořit úlohu.

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

Náhodné odstranění

Tato část popisuje, jak programově povolit nebo zakázat a používat náhodné odstranění prostřednictvím kódu programu.

Povolení a nastavení prahové hodnoty

Existují dvě nastavení pro úlohu, která můžete použít:

• DeleteThresholdEnabled – Povolí pro úlohu neúmyslnou ochranu před odstraněním, pokud je nastavená hodnota true. Ve výchozím nastavení je nastavená hodnota true.
• DeleteThresholdValue – definuje maximální počet odstranění povolených při každém spuštění úlohy, pokud je povolená prevence náhodného odstranění. Ve výchozím nastavení je hodnota nastavená na 500. Pokud je tedy hodnota nastavená na 500, maximální povolený počet odstranění je v každém spuštění 499.

Nastavení prahové hodnoty odstranění je součástí SyncNotificationSettings grafu a lze je upravit.

Budeme muset aktualizovat SyncNotification Nastavení tato konfigurace cílí, takže aktualizujte tajné kódy.

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

Do pole níže uvedených hodnot přidejte následující pár klíč/hodnota na základě toho, co se pokoušíte udělat:

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

Nastavení Povoleno v příkladu slouží k povolení nebo zakázání e-mailů s oznámením, když je úloha v karanténě.

V současné době nepodporujeme požadavky PATCH na tajné kódy, takže je potřeba přidat všechny hodnoty v těle požadavku PUT (jako v příkladu), aby se zachovaly ostatní hodnoty.

Existující hodnoty pro všechny tajné kódy je možné načíst pomocí:

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

Povolení odstranění

Pokud chcete těmto odstraněním umožnit tok po ukončení úlohy do karantény, musíte jako obor vydat restartování jenom s "ForceDeletes".

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

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

Spuštění úlohy synchronizace

Úlohy je možné znovu načíst pomocí následujícího příkazu:

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

Dokumentaci k načítání úloh najdete tady.

Chcete-li spustit úlohy, zadejte tento požadavek pomocí objectId instančního objektu vytvořeného v prvním kroku a identifikátory úloh vrácené z požadavku, který úlohu vytvořil.

Dokumentaci ke spuštění úlohy najdete tady.

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

Očekávaná odpověď je ... HTTP 204/Žádný obsah.

Tady jsou popsané další příkazy pro řízení úlohy.

Pokud chcete úlohu restartovat, použijte:

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

Kontrola stavu

Načtení stavu úloh prostřednictvím:

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

V části Stav návratového objektu vyhledejte relevantní podrobnosti.

Další kroky

• Co je cloudová synchronizace Microsoft Entra?
• Transformace
• Rozhraní API pro synchronizaci