Bagikan melalui

Tanya jawab umum tentang provisi masuk berbasis API

  • Artikel

Artikel ini menjawab tanya jawab umum (FAQ) tentang provisi masuk berbasis API.

Bagaimana provisi masuk baru /bulkUpload API berbeda dari MS Graph Users API?

Ada perbedaan signifikan antara API provisi /bulkUpload dan titik akhir API Pengguna MS Graph.

  • Format payload: Titik akhir API Pengguna MS Graph mengharapkan data dalam format OData. Format payload permintaan untuk provisi masuk baru /bulkUpload API menggunakan konstruksi skema SCIM. Saat memanggil API ini, atur header 'Content-Type' ke application/scim+json.
  • Hasil akhir operasi:
    • Saat data identitas dikirim ke titik akhir API Pengguna MS Graph, data tersebut segera diproses, dan operasi Buat/Perbarui/Hapus terjadi di profil pengguna Microsoft Entra.
    • Data permintaan yang dikirim ke API provisi /bulkUpload diproses secara asinkron oleh layanan provisi Microsoft Entra. Pekerjaan provisi menerapkan aturan cakupan, pemetaan atribut, dan transformasi yang dikonfigurasi oleh admin TI. Ini memulai Create/Update/Delete operasi pada profil pengguna Microsoft Entra atau profil pengguna AD lokal.
  • Admin TI mempertahankan kontrol: Dengan provisi masuk berbasis API, admin TI memiliki kontrol lebih besar tentang bagaimana data identitas masuk diproses dan dipetakan ke atribut Microsoft Entra. Mereka dapat menentukan aturan cakupan untuk mengecualikan jenis data identitas tertentu (misalnya, data kontraktor) dan menggunakan fungsi transformasi untuk memperoleh nilai baru sebelum mengatur nilai atribut pada profil pengguna.

Apakah provisi masuk /bulkUpload API adalah titik akhir SCIM standar?

API provisi masuk /bulkUpload MS Graph menggunakan skema SCIM dalam payload permintaan, tetapi bukan titik akhir API SCIM standar. Ini alasannya.

Biasanya, titik akhir layanan SCIM memproses permintaan HTTP (POST, PUT, GET) dengan payload SCIM dan menerjemahkannya ke operasi masing-masing (Buat, Perbarui, Cari) di penyimpanan identitas. Titik akhir layanan SCIM menempatkan onus untuk menentukan semantik operasi, apakah akan Membuat/Memperbarui/Menghapus identitas, pada klien API SCIM. Mekanisme ini bekerja dengan baik untuk skenario di mana klien API mengetahui operasi apa yang ingin dilakukan untuk pengguna di penyimpanan identitas.

MS Graph provisi masuk /bulkUpload dirancang untuk menangani skenario integrasi identitas perusahaan yang berbeda yang dibentuk oleh tiga persyaratan unik:

  1. Kemampuan untuk memproses rekaman secara asinkron secara massal (misalnya, memproses 50K+ rekaman)
  2. Kemampuan untuk menyertakan atribut identitas apa pun dalam payload (misalnya, costCenter, pay grade, badgeId)
  3. Klien API dukungan tidak menyadari semantik operasi. Klien ini adalah klien API non-SCIM yang hanya memiliki akses ke data sumber mentah (misalnya, rekaman dalam file CSV, tabel SQL, atau catatan SDM). Klien ini tidak memiliki kemampuan pemrosesan untuk membaca setiap rekaman dan menentukan semantik Create/Update/Delete operasi di penyimpanan identitas.

Tujuan utama penyediaan masuk MS Graph /bulkUpload API adalah untuk memungkinkan pelanggan mengirim data identitas apa pun (misalnya, costCenter, pay grade, badgeId) dari sumber data identitas apa pun (misalnya, CSV/SQL/HR) untuk pemrosesan akhir oleh layanan provisi Microsoft Entra. Layanan provisi Microsoft Entra menggunakan data payload massal yang diterima di titik akhir ini, menerapkan aturan pemetaan atribut yang dikonfigurasi oleh admin TI dan menentukan apakah payload data mengarah ke operasi (Buat, Perbarui, Aktifkan, Nonaktifkan) di penyimpanan identitas target (MICROSOFT Entra ID/ AD lokal).

Apakah API provisi /bulkUpload mendukung domain Active Directory lokal sebagai target?

Ya, API provisi mendukung domain AD lokal sebagai target.

Bagaimana cara mendapatkan titik akhir /bulkUpload API untuk aplikasi provisi kami?

API /bulkUpload hanya tersedia untuk aplikasi jenis: "Provisi masuk berbasis API ke MICROSOFT Entra ID" dan "Provisi masuk berbasis API ke Active Directory lokal". Anda dapat mengambil titik akhir API unik untuk setiap aplikasi provisi dari beranda bilah Provisi. Dalam Statistik hingga saat ini>Lihat informasi teknis, salin URL Titik Akhir API Provisi.

Ini memiliki format:

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

Bagaimana cara melakukan sinkronisasi penuh menggunakan API provisi /bulkUpload?

Untuk melakukan sinkronisasi penuh, gunakan klien API Anda untuk mengirim data semua pengguna dari sumber tepercaya Anda ke titik akhir API sebagai permintaan massal. Setelah Anda mengirim semua data ke titik akhir API, siklus sinkronisasi berikutnya memproses semua rekaman pengguna dan memungkinkan Anda melacak kemajuan menggunakan titik akhir API log provisi.

Bagaimana cara melakukan sinkronisasi delta menggunakan API provisi /bulkUpload?

Untuk melakukan sinkronisasi delta, gunakan klien API Anda untuk hanya mengirim informasi tentang pengguna yang datanya telah berubah di sumber tepercaya. Setelah Anda mengirim semua data ke titik akhir API, siklus sinkronisasi berikutnya memproses semua rekaman pengguna dan memungkinkan Anda melacak kemajuan menggunakan titik akhir API log provisi.

Bagaimana cara kerja mulai ulang provisi?

Gunakan opsi Mulai ulang provisi hanya jika diperlukan. Berikut adalah cara kerjanya:

Skenario 1: Saat Anda mengklik tombol Mulai ulang provisi dan pekerjaan saat ini berjalan, pekerjaan terus memproses data yang ada yang sudah ditahapkan. OperasiMulai ulang provisi tidak mengganggu siklus yang ada. Dalam siklus berikutnya, layanan provisi menghapus escrow apa pun dan memilih permintaan massal baru untuk diproses.

Skenario 2: Saat Anda mengklik tombol Mulai ulang provisi dan pekerjaan tidak berjalan, maka sebelum menjalankan siklus berikutnya, mesin provisi menghapus menyeluruh data yang diunggah sebelum menghidupkan ulang, menghapus escrow apa pun, dan hanya memproses data masuk baru.

Bagaimana cara membuat pengguna menggunakan titik akhir API provisi /bulkUpload?

Berikut adalah cara pekerjaan provisi yang terkait dengan titik akhir API /bulkUpload memproses payload pengguna yang masuk:

  1. Pekerjaan mengambil pemetaan atribut untuk pekerjaan provisi dan mencatat pasangan atribut yang cocok (secara default externalId atribut API digunakan untuk mencocokkan dengan employeeId di MICROSOFT Entra ID).
  2. Anda dapat mengubah pasangan pencocokan atribut default ini.
  3. Pekerjaan mengekstrak setiap operasi yang ada dalam payload permintaan massal.
  4. Pekerjaan memeriksa pengidentifikasi pencocokan nilai dalam permintaan (secara default atribut externalId) dan menggunakannya untuk memeriksa apakah ada pengguna di ID Microsoft Entra dengan nilai yang employeeId cocok.
  5. Jika pekerjaan tidak menemukan pengguna yang cocok, maka pekerjaan menerapkan aturan sinkronisasi dan membuat pengguna baru di direktori target.

Untuk memastikan bahwa pengguna yang tepat dibuat di ID Microsoft Entra, tentukan pasangan atribut pencocokan yang tepat dalam pemetaan Anda yang secara unik mengidentifikasi pengguna di sumber dan ID Microsoft Entra Anda.

Bagaimana cara menghasilkan nilai unik untuk UPN?

Layanan provisi tidak memberikan kemampuan untuk memeriksa duplikat userPrincipalName (UPN) dan menangani konflik. Jika aturan sinkronisasi default untuk atribut UPN menghasilkan nilai UPN yang ada, maka operasi pembuatan pengguna gagal.

Berikut adalah beberapa opsi yang dapat Anda pertimbangkan untuk menghasilkan UPN unik:

  1. Tambahkan logika untuk pembuatan UPN unik di klien API Anda.
  2. Perbarui aturan sinkronisasi untuk atribut UPN untuk menggunakan fungsi RandomString dan atur parameter terapkan pemetaan ke On object creation only. Contoh:

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

  1. Jika Anda menyediakan untuk Active Directory lokal, Anda dapat menggunakan fungsi SelectUniqueValue dan mengatur parameter terapkan pemetaan ke On object creation only.

Bagaimana cara mengirim lebih banyak atribut HR ke titik akhir API provisi /bulkUpload?

Secara default, titik akhir API mendukung pemrosesan atribut apa pun yang merupakan bagian dari skema Pengguna Inti SCIM dan Pengguna Perusahaan. Jika ingin mengirim lebih banyak atribut, Anda dapat memperluas skema aplikasi provisi, memetakan atribut baru ke atribut Microsoft Entra dan memperbarui permintaan massal untuk mengirim atribut tersebut. Lihat tutorial Memperluas provisi berbasis API untuk menyinkronkan atribut kustom.

Bagaimana cara mengecualikan pengguna tertentu dari alur provisi?

Anda mungkin memiliki skenario di mana Anda ingin mengirim semua pengguna ke titik akhir API, tetapi hanya menyertakan pengguna tertentu dalam alur provisi dan mengecualikan sisanya.

Anda dapat mencapai ini menggunakan filter Cakupan. Dalam konfigurasi aplikasi provisi, Anda dapat menentukan cakupan objek sumber dan mengecualikan pengguna tertentu untuk memproses baik menggunakan "aturan inklusi" (misalnya, hanya memproses pengguna di mana departemen EQUALS Sales) atau "aturan pengecualian" (misalnya, mengecualikan pengguna milik Penjualan, departemen NOT EQUALS Sales).

Lihat Cakupan pengguna atau grup yang akan disediakan dengan filter cakupan.

Bagaimana cara memperbarui pengguna menggunakan titik akhir API provisi /bulkUpload?

Berikut adalah cara pekerjaan provisi yang terkait dengan titik akhir API /bulkUpload memproses payload pengguna yang masuk:

  1. Pekerjaan provisi mengambil pemetaan atribut untuk pekerjaan provisi dan mencatat pasangan atribut yang cocok (secara default externalId atribut API digunakan untuk mencocokkan dengan employeeId di MICROSOFT Entra ID). Anda dapat mengubah pasangan pencocokan atribut default ini.
  2. Pekerjaan mengekstrak operasi dari payload permintaan massal.
  3. Pekerjaan memeriksa pengidentifikasi pencocokan nilai dalam permintaan SCIM (secara default: atribut externalIdAPI ) dan menggunakannya untuk memeriksa apakah ada pengguna di ID Microsoft Entra dengan nilai yang employeeId cocok.
  4. Jika pekerjaan menemukan pengguna yang cocok, maka itu menerapkan aturan sinkronisasi dan membandingkan profil sumber dan target.
  5. Jika pekerjaan menentukan bahwa beberapa nilai telah berubah, maka akan memperbarui rekaman pengguna yang sesuai di direktori.

Untuk memastikan bahwa pengguna yang tepat diperbarui di ID Microsoft Entra, pastikan Anda menentukan pasangan atribut yang cocok yang tepat dalam pemetaan Anda yang secara unik mengidentifikasi pengguna di sumber Anda dan ID Microsoft Entra.

Dapatkah kita membuat lebih dari satu aplikasi yang mendukung provisi masuk berbasis API?

Ya, Anda dapat. Berikut adalah beberapa skenario yang mungkin memerlukan lebih dari satu aplikasi provisi:

Skenario 1: Katakanlah Anda memiliki tiga sumber data tepercaya: satu untuk karyawan, satu untuk kontraktor dan satu untuk vendor. Anda dapat membuat tiga aplikasi provisi terpisah - satu untuk setiap jenis identitas dengan pemetaan atributnya sendiri yang berbeda. Setiap aplikasi provisi memiliki titik akhir API yang unik, dan Anda dapat mengirim payload masing-masing ke setiap titik akhir.

Anda dapat mengambil titik akhir API unik untuk setiap pekerjaan dari beranda bilah Provisi. Navigasi ke Statistik hingga saat ini>Lihat informasi teknis, lalu salin URL Titik Akhir API Provisi.

Skenario 2: Katakanlah Anda memiliki beberapa sumber kebenaran, masing-masing dengan set atributnya sendiri. Misalnya, HR menyediakan atribut info pekerjaan (misalnya jobTitle, employeeType), dan Sistem Badging menyediakan atribut informasi lencana (misalnya badgeId yang diwakili menggunakan atribut ekstensi). Dalam skenario ini, Anda dapat mengonfigurasi dua aplikasi provisi:

  • Memprovisikan Aplikasi #1 yang menerima atribut dari sumber SDM Anda dan membuat pengguna.

  • Memprovisikan Aplikasi #2 yang menerima atribut dari sistem Badging dan hanya memperbarui atribut pengguna. Pemetaan atribut di aplikasi ini dibatasi untuk atribut Informasi Lencana dan di bawah Tindakan Objek Target hanya diperbarui diaktifkan.

  • Kedua aplikasi menggunakan pasangan pengidentifikasi pencocokan yang sama (externalId<->employeeId)

Bagaimana cara memproses penghentian menggunakan titik akhir /bulkUpload API?

Untuk memproses penghentian, identifikasi atribut di sumber Anda yang akan digunakan untuk mengatur accountEnabled bendera di ID Microsoft Entra. Jika Anda memprovisikan ke Active Directory lokal, maka petakan atribut sumber tersebut ke accountDisabled atribut .

Secara default, nilai yang terkait dengan atribut active skema Scim Core User menentukan status akun pengguna di direktori target.

Jika atribut diatur ke true, aturan pemetaan default akan mengaktifkan akun. Jika atribut diatur ke false, maka aturan pemetaan default akan menonaktifkan akun.

Bagaimana cara mencegah pennonaktifkan/penghapusan pengguna yang tidak disengaja?

Untuk mencegah dan memulihkan dari penghapusan yang tidak disengaja, sebaiknya konfigurasikan ambang penghapusan yang tidak disengaja di aplikasi provisi dan mengaktifkan keranjang sampah Active Directory lokal. Di bilah Pemetaan Atribut aplikasi provisi Anda, di bawah Tindakan objek target menonaktifkan operasi Hapus.

Memulihkan akun yang dihapus

  • Jika direktori target untuk operasi adalah ID Microsoft Entra, maka pengguna yang cocok akan dihapus sementara. Pengguna dapat dilihat di halaman Pengguna yang dihapus pusat admin Microsoft Entra selama 30 hari ke depan dan dapat dipulihkan selama waktu tersebut.
  • Jika direktori target untuk operasi Active Directory lokal, maka pengguna yang cocok akan dihapus secara permanen. Jika Keranjang Sampah Direktori Aktif diaktifkan, Anda dapat memulihkan objek pengguna AD lokal yang dihapus.

Apakah kita perlu mengirim semua pengguna dari sistem SDM di setiap permintaan?

Tidak, Anda tidak perlu mengirim semua pengguna dari sistem SDM / "sumber kebenaran" di setiap permintaan. Cukup kirim pengguna yang ingin Anda buat atau perbarui.

Apakah API mendukung semua tindakan HTTP (GET/POST/PUT/PATCH)?

Tidak, titik akhir API provisi /bulkUpload hanya mendukung tindakan HTTP POST.

Jika saya ingin memperbarui pengguna, apakah saya perlu mengirim permintaan PUT/PATCH?

Tidak, titik akhir API tidak mendukung permintaan PUT/PATCH. Untuk memperbarui pengguna, kirim data yang terkait dengan pengguna dalam payload permintaan massal POST.

Pekerjaan provisi yang memproses data yang diterima oleh titik akhir API secara otomatis mendeteksi apakah pengguna yang diterima dalam payload permintaan POST perlu dibuat/diperbarui/aktifkan/dinonaktifkan berdasarkan aturan sinkronisasi yang dikonfigurasi. Sebagai klien API, Anda tidak perlu mengambil langkah-langkah lagi jika Anda ingin profil pengguna diperbarui.

Bagaimana writeback didukung?

API saat ini hanya mendukung data masuk. Berikut adalah beberapa opsi yang perlu dipertimbangkan untuk menerapkan tulis balik atribut seperti email / nama pengguna / telepon yang dihasilkan oleh ID Microsoft Entra, yang dapat Anda mengalirkan kembali ke sistem SDM:

  • Opsi 1 – Konektivitas SCIM ke titik akhir SDM/layanan proksi yang pada gilirannya memperbarui sumber SDM

    • Jika sistem rekaman menyediakan titik akhir SCIM untuk pembaruan pengguna, Anda dapat membuat aplikasi SCIM kustom di galeri aplikasi perusahaan dan mengonfigurasi provisi seperti yang didokumentasikan.
    • Jika sistem rekaman tidak menyediakan titik akhir SCIM, jelajahi kemungkinan pengaturan layanan SCIM proksi, yang menerima pembaruan dan menyebarkan perubahan ke sistem SDM.

  • Opsi 2 - Gunakan konektor Microsoft Entra ECMA untuk skenario tulis balik

    • Tergantung pada persyaratan pelanggan, jelajahi apakah salah satu konektor ECMA dapat digunakan (PowerShell / SQL / Web Services).

  • Opsi 3 - Gunakan tugas ekstensi kustom Alur Kerja Siklus Hidup dalam alur kerja Joiner

    • Dalam Alur Kerja Siklus Hidup, tentukan alur kerja Joiner dan tentukan tugas ekstensi kustom yang memanggil proses Logic Apps, yang memperbarui sistem SDM atau menghasilkan file CSV yang digunakan oleh sistem SDM.

Langkah berikutnya