Cara mengkonfigurasi sinkronisasi cloud secara terprogram menggunakan MS Graph API

Dokumen berikut menjelaskan cara mereplikasi profil sinkronisasi dari awal hanya menggunakan MSGraph APIs.
Struktur cara mereplikasi profil sinkronisasi terdiri dari langkah-langkah berikut. Yaitu:

• Cara mengkonfigurasi sinkronisasi cloud secara terprogram menggunakan MS Graph API
  • Konfigurasi dasar
    • Mengaktifkan bendera penyewa
  • Buat prinsipal layanan
  • Membuat tugas sinkronisasi
  • Memperbarui domain yang ditargetkan
  • Mengaktifkan hash sandi sinkronisasi pada bilah konfigurasi
  • Exchange Hybrid Writeback
  • Penghapusan yang tidak disengaja
    • Mengaktifkan dan mengatur ambang batas
    • Memperbolehkan penghapusan
  • Memulai tugas sinkronisasi
  • Status peninjauan
  • Langkah berikutnya

Gunakan perintah Microsoft Graph PowerShell ini untuk mengaktifkan sinkronisasi untuk penyewa produksi, prasyarat untuk dapat memanggil Layanan Web Administrasi untuk penyewa tersebut.

Konfigurasi dasar

Mengaktifkan bendera penyewa

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

Cmdlet ini memungkinkan sinkronisasi untuk penyewa. Ini menggunakan Get-MgOrganization untuk mendapatkan ID organisasi.

Membuat prinsipal layanan

Selanjutnya, kita perlu membuat prinsipal aplikasi/layanan AD2AAD

Anda perlu menggunakan ID aplikasi 1a4721b3-e57f-4451-ae87-ef078703ec94. Nama Tampilan adalah URL domain AD jika digunakan di portal (misalnya, contoso.com), tapi mungkin diberi nama yang lain.

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

Membuat tugas sinkronisasi

Output perintah sebelumnya mengembalikan objectId dari service principal yang dibuat. Untuk contoh ini, objectId adalah aaaaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Gunakan Microsoft Graph untuk menambahkan pekerjaan sinkronisasi ke prinsipal layanan tersebut.

Dokumentasi untuk membuat tugas sinkronisasi dapat ditemukan di sini.

Jika Anda tidak merekam ID, Anda dapat menemukan perwakilan layanan dengan menjalankan panggilan MS Graph berikut. Anda memerlukan izin Directory.Read.All untuk melakukan panggilan tersebut:

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

Kemudian cari nama aplikasi Anda di output.

Jalankan dua perintah berikut untuk membuat dua pekerjaan: satu untuk penyediaan pengguna/grup, dan satu untuk sinkronisasi hash sandi. Ini adalah permintaan yang sama dua kali tetapi dengan ID template yang berbeda.

Panggil dua permintaan berikut ini:

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

Anda memerlukan dua panggilan jika ingin membuat keduanya.

Contoh nilai balik (untuk penyediaan):

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

Memperbarui domain yang ditargetkan

Untuk penyewa ini, pengidentifikasi objek serta pengidentifikasi aplikasi dari prinsipal layanan adalah sebagai berikut:

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

Kita perlu memperbarui domain yang ditargetkan konfigurasi ini, jadi perbarui rahasia untuk domain ini.

Pastikan nama domain yang Anda gunakan adalah URL yang sama dengan yang Anda tetapkan untuk pengontrol domain lokal Anda.

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

Tambahkan pasangan kunci/nilai berikut dalam array nilai berikut berdasarkan apa yang coba Anda lakukan:

• Aktifkan PHS dan flag tenant sinkronisasi { key: "AppKey", nilai: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Aktifkan hanya indikator sinkronisasi tenant (jangan aktifkan PHS) { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Respon yang diharapkan adalah … HTTP 204/Tidak ada Konten

Di sini, nilai "Domain" yang disorot adalah nama domain Active Directory lokal tempat entri akan disediakan ke ID Microsoft Entra.

Mengaktifkan hash sandi sinkronisasi pada bilah konfigurasi

Bagian ini mencakup mengaktifkan sinkronisasi hash kata sandi untuk konfigurasi tertentu. Situasi ini berbeda dengan rahasia AppKey yang memungkinkan pengaturan fitur tingkat penyewa. Prosedur ini hanya untuk satu domain/konfigurasi. Anda perlu mengatur kunci aplikasi ke PHS agar prosedur ini berfungsi secara menyeluruh.

1. Ambil skema ini (peringatan: cukup besar).

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

2. Ambil pemetaan atribut CredentialData ini:

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

3. Temukan pemetaan objek berikut dengan nama berikut dalam skema

   • Penyediaan Pengguna Active Directory
   • Penyediaan inetOrgPersons Active Directory

   Pemetaan objek berada dalam schema.synchronizationRules[0].objectMappings (Untuk saat ini Anda dapat berasumsi hanya ada satu Aturan Sinkronisasi)

4. Ambil Pemetaan CredentialData dari Langkah (2) dan sisipkan ke dalam pemetaan objek di Langkah (3)

   Pemetaan objek Anda terlihat seperti ini:

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

   Salin/tempel pemetaan dari langkah Create AD2AADProvisioning dan AD2AADPasswordHash jobs ke dalam array attributeMappings.

   Urutan elemen dalam array ini tidak masalah (backend mengurutkan untuk Anda). Berhati-hatilah dengan menambahkan pemetaan atribut ini jika nama sudah ada dalam array. Misalnya, jika sudah ada item di dalam attributeMappings yang memiliki targetAttributeName CredentialData, Anda mungkin mendapatkan kesalahan konflik, atau pemetaan yang sudah ada sebelumnya maupun baru mungkin digabungkan bersama-sama. Biasanya, ini bukan hasil yang diinginkan. Backend tidak melakukan deduplikasi untuk Anda.

   Ingatlah untuk melakukan tindakan ini untuk Pengguna dan inetOrgpersons.

5. Simpan skema yang Anda buat:

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

Tambahkan Skema dalam Badan Permintaan.

Tulis balik hibrid Exchange (Pratinjau Umum)

Bagian ini membahas cara mengaktifkan/menonaktifkan dan menggunakan tulis balik hibrid Exchange secara terprogram.

Mengaktifkan tulis balik hibrid Exchange secara terprogram memerlukan dua langkah.

1. Verifikasi skema
2. Membuat tugas tulis balik hibrida Exchange

Verifikasi skema

Sebelum Anda mengaktifkan dan menggunakan tulis balik hibrid Exchange, sinkronisasi cloud perlu menentukan apakah Active Directory lokal diperluas untuk menyertakan skema Exchange.

Anda dapat menggunakan directoryDefinition:discover untuk memulai penemuan skema.

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

Respon yang diharapkan adalah … HTTP 200/OK

Respons akan terlihat mirip dengan output berikut:

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

Sekarang periksa untuk melihat apakah atribut mailNickName ada. Jika ya, maka skema Anda diverifikasi dan berisi atribut Exchange. Jika tidak, tinjau prasyarat untuk tulis balik hibrid Exchange.

Membuat tugas tulis balik hibrida Exchange

Setelah memverifikasi skema, Anda dapat membuat tugas.

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

Penghapusan tidak disengaja

Bagian ini mencakup cara mengaktifkan/menonaktifkan dan menggunakan penghapusan yang tidak disengaja secara otomatis.

Mengaktifkan dan mengatur ambang batas

Ada dua pengaturan per pekerjaan yang dapat Anda gunakan, mereka adalah:

• DeleteThresholdEnabled - Memungkinkan pencegahan penghapusan tidak disengaja untuk pekerjaan tertentu ketika diatur ke 'true'. Atur ke 'true' secara default.
• DeleteThresholdValue - Menentukan jumlah maksimum penghapusan yang diizinkan dalam setiap eksekusi pekerjaan ketika pencegahan penghapusan yang tidak disengaja diaktifkan. Nilai diatur ke 500 secara default. Jadi, jika nilai diatur ke 500, jumlah maksimum penghapusan yang diizinkan adalah 499 di setiap eksekusi.

Pengaturan ambang batas penghapusan adalah bagian dari SyncNotificationSettings dan dapat dimodifikasi melalui grafik.

Kita perlu memperbarui SyncNotificationSettings yang ditargetkan konfigurasi ini, jadi perbarui rahasia-rahasia tersebut.

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

Tambahkan pasangan Kunci/nilai berikut dalam array nilai berikut berdasarkan apa yang coba Anda lakukan:

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

Pengaturan "Diaktifkan" dalam contoh adalah untuk mengaktifkan/menonaktifkan email pemberitahuan saat pekerjaan dikarantina.

Saat ini, permintaan PATCH untuk data rahasia tidak didukung. Jadi, Anda perlu menambahkan semua nilai dalam isi permintaan PUT, seperti dalam contoh, untuk mempertahankan nilai lainnya.

Nilai yang sudah ada untuk semua rahasia dapat diambil dengan menggunakan:

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

Mengizinkan penghapusan

Untuk memungkinkan penghapusan ini diteruskan setelah pekerjaan masuk ke dalam masa karantina, Anda perlu melakukan restart dengan hanya menggunakan "ForceDeletes" sebagai cakupannya.

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

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

Memulai tugas sinkronisasi

Pekerjaan dapat diambil lagi melalui perintah berikut:

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

Dokumentasi untuk mengambil pekerjaan dapat ditemukan di sini.

Untuk memulai tugas, buat permintaan ini, gunakan objectId dari perwakilan layanan yang dibuat pada langkah pertama, dan pengidentifikasi tugas yang diperoleh dari permintaan yang membuat tugas.

Dokumentasi tentang cara memulai pekerjaan dapat ditemukan di sini.

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

Respon yang diharapkan adalah … HTTP 204/Tidak ada Konten.

Perintah lain untuk mengendalikan pekerjaan didokumentasikan di sini.

Untuk memulai ulang tugas, gunakan:

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

Status Peninjauan

Ambil status pekerjaan Anda melalui:

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

Lihat di bawah bagian 'status' dari objek yang dikembalikan untuk detail yang relevan

Langkah berikutnya

• Apa itu Sinkronisasi Cloud Microsoft Entra?
• Transformasi
• API Sinkronisasi