Bagikan melalui

Gambaran umum panduan autentikasi beban kerja di Microsoft Fabric

Artikel ini menyediakan panduan tentang cara bekerja dengan autentikasi saat Anda membangun beban kerja Microsoft Fabric. Ini termasuk informasi tentang bekerja dengan token dan persetujuan.

Sebelum memulai, pastikan Anda terbiasa dengan konsep dalam gambaran umum Autentikasi dan penyiapan Autentikasi .

API lapisan data dan lapisan kontrol

  • API layer data adalah API yang diekspos oleh beban kerja backend. Frontend beban kerja dapat memanggilnya secara langsung. Untuk API data plane, backend beban kerja dapat memutuskan API apa yang akan diekspos.

  • API bidang kontrol adalah API yang melewati Fabric. Proses dimulai dengan frontend beban kerja yang memanggil API JavaScript, dan berakhir dengan Fabric memanggil backend beban kerja. Contoh API tersebut adalah Buat Item.

    Untuk API pesawat pengendali, beban kerja harus mengikuti kontrak yang ditentukan dalam backend beban kerja dan mengimplementasikan API tersebut.

Mengekspos tab API pada aplikasi beban kerja di ID Microsoft Entra

Pada tab Mengekspos API, Anda perlu menambahkan ruang lingkup untuk API kontrol dan ruang lingkup untuk API data:

  • Cakupan yang ditambahkan untuk API control plane harus mempraotorisasi aplikasi "Fabric Client for Workloads" dengan ID aplikasi d2450708-699c-41e3-8077-b0c8341509aa. Cakupan tersebut disertakan dalam token yang diterima backend beban kerja saat Fabric memanggilnya.

    Anda perlu menambahkan setidaknya satu cakupan untuk API bidang kontrol agar alur berfungsi.

  • Cakupan yang ditambahkan untuk API lapisan data harus melakukan pra-otorisasi Microsoft Power BI dengan ID aplikasi 871c010f-5e61-4fb1-83ac-98610a7e9110. Mereka disertakan dalam token yang dikembalikan acquireAccessToken JavaScript API.

    Untuk data plane API, Anda dapat menggunakan tab ini untuk mengelola izin terperinci untuk setiap API yang diekspos oleh beban kerja Anda. Idealnya, Anda harus menambahkan sekumpulan scope untuk setiap API yang diekspos oleh backend beban kerja dan memvalidasi bahwa token yang diterima mencakup scope tersebut ketika API tersebut dipanggil dari klien. Misalnya:

    • Beban kerja mengekspos dua API ke klien, ReadData dan WriteData.
    • Beban kerja memaparkan dua cakupan bidang data, data.read dan data.write.
    • Dalam API ReadData, beban kerja memvalidasi bahwa cakupan data.read disertakan dalam token sebelum berlanjut dengan alur. Hal yang sama berlaku untuk WriteData.

Tab izin API pada aplikasi beban kerja di Microsoft Entra ID

Pada tab izin API , Anda perlu menambahkan semua cakupan yang dibutuhkan oleh beban kerja Anda untuk menukarkan sebuah token. Cakupan wajib yang harus ditambahkan adalah Fabric.Extend di bawah layanan Power BI. Permintaan ke Fabric mungkin gagal tanpa cakupan ini.

Bekerja dengan token dan persetujuan

Saat Anda bekerja dengan API data plane, frontend workload perlu memperoleh token untuk panggilan ke backend workload.

Bagian berikut menjelaskan bagaimana beban kerja pada bagian frontend harus menggunakan API JavaScript dan aliran OBO untuk memperoleh token untuk beban kerja dan layanan eksternal, dan dalam bekerja dengan persetujuan.

Langkah 1: Memperoleh token

Beban kerja dimulai dengan meminta token dengan menggunakan JAVAScript API tanpa menyediakan parameter apa pun. Panggilan ini dapat menghasilkan dua skenario:

  • Pengguna melihat jendela persetujuan dari semua dependensi statis (apa yang dikonfigurasi pada tab izin API ) yang dikonfigurasi untuk beban kerja. Skenario ini terjadi jika pengguna bukan bagian dari penyewa utama aplikasi, dan pengguna belum memberikan izin ke Microsoft Graph untuk aplikasi ini sebelumnya.

  • Pengguna tidak melihat jendela persetujuan. Skenario ini terjadi jika pengguna sudah menyetujui setidaknya sekali aplikasi ini ke Microsoft Graph, atau jika pengguna adalah bagian dari penyewa utama aplikasi.

Dalam kedua skenario, beban kerja tidak boleh peduli apakah pengguna memberikan persetujuan penuh untuk semua dependensi atau tidak (dan tidak dapat mengetahui saat ini). Token yang diterima memiliki audiens backend beban kerja dan dapat digunakan untuk mengakses langsung backend beban kerja dari antarmuka depan beban kerja.

Langkah 2: Coba akses layanan eksternal

Beban kerja mungkin perlu mengakses layanan yang memerlukan autentikasi. Untuk akses itu, perlu melakukan alur OBO , di mana ia menukar token yang diterimanya dari kliennya atau dari Fabric ke layanan lain. Pertukaran token mungkin gagal karena kurangnya persetujuan atau adanya beberapa kebijakan Akses Bersyarat Microsoft Entra yang dikonfigurasi pada sumber daya yang sedang dicoba untuk ditukarkan token oleh beban kerja.

Untuk mengatasi masalah ini, beban kerja bertanggung jawab untuk menyebarluaskan kesalahan kepada klien saat bekerja dengan panggilan langsung antara frontend dan backend. Ini juga tanggung jawab beban kerja untuk menyebarluaskan kesalahan kepada klien saat bekerja dengan panggilan dari Fabric dengan menggunakan penyebaran kesalahan yang dijelaskan dalam komunikasi beban kerja .

Setelah beban kerja menyebarkan kesalahan, beban kerja dapat memanggil acquireAccessToken JavaScript API untuk menyelesaikan masalah kebijakan persetujuan atau Akses Bersyarat dan mencoba kembali operasi.

Untuk kegagalan API lapisan data, lihat Menangani autentikasi multifaktor, Akses Bersyarat, dan persetujuan bertahap. Untuk kegagalan API sarana kontrol, lihat Komunikasi beban kerja.

Contoh skenario

Mari kita lihat beban kerja yang perlu mengakses tiga API Fabric:

  • Daftar ruang kerja: GET https://api.fabric.microsoft.com/v1/workspaces

  • Buat gudang: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

  • Menulis ke file lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Agar dapat bekerja dengan API tersebut, backend beban kerja perlu bertukar token dengan cakupan berikut:

  • Untuk mencantumkan ruang kerja: https://analysis.windows.net/powerbi/api/Workspace.Read.All atau https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
  • Untuk membuat gudang: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All atau https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
  • Untuk menulis ke dalam file lakehouse: https://storage.azure.com/user_impersonation

Catatan

Anda dapat menemukan cakupan yang diperlukan untuk setiap Fabric API di artikel referensi ini.

Cakupan yang disebutkan sebelumnya perlu dikonfigurasi pada aplikasi beban kerja di bawah izin API .

Mari kita lihat contoh skenario yang mungkin ditemui beban kerja.

Contoh 1

Mari kita asumsikan bahwa sistem backend untuk beban kerja memiliki API lapisan data yang mengambil ruang kerja pengguna dan mengembalikannya ke klien.

  1. Frontend beban kerja meminta token dengan menggunakan JAVAScript API.

  2. Frontend beban kerja memanggil API backend beban kerja untuk mendapatkan ruang kerja pengguna dan melampirkan token ke dalam permintaan.

  3. Backend beban kerja memvalidasi token dan mencoba menukarnya dengan cakupan yang diperlukan (katakanlah https://analysis.windows.net/powerbi/api/Workspace.Read.All).

  4. Beban kerja gagal menukar token dengan sumber daya yang ditentukan karena pengguna tidak menyetujui aplikasi untuk mengakses sumber daya ini (lihat kode kesalahan AADSTS).

  5. Backend beban kerja menyebarluaskan kesalahan ke frontend beban kerja dengan menentukan bahwa ia memerlukan persetujuan untuk sumber daya tersebut. Antarmuka depan beban kerja memanggil acquireAccessToken JavaScript API dan menyediakan additionalScopesToConsent:

    workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

    Atau, beban kerja dapat memutuskan untuk meminta persetujuan untuk semua dependensi statisnya yang dikonfigurasi pada aplikasinya, sehingga memanggil JAVAScript API dan menyediakan promptFullConsent:

    workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

Panggilan ini meminta jendela persetujuan terlepas dari apakah pengguna telah menyetujui beberapa dependensi atau tidak. Setelah itu, beban kerja frontend dapat mencoba operasi kembali.

Catatan

Jika pertukaran token masih gagal pada kesalahan persetujuan, itu berarti bahwa pengguna tidak memberikan persetujuan. Beban kerja perlu menangani skenario tersebut; misalnya, beri tahu pengguna bahwa API ini memerlukan persetujuan dan tidak akan berfungsi tanpanya.

Contoh 2

Mari kita asumsikan bahwa bagian backend dari beban kerja perlu mengakses OneLake pada API Buat Item (panggilan dari Fabric menuju beban kerja):

  1. Antarmuka beban kerja memanggil API Buat Item JavaScript.

  2. Backend beban kerja menerima panggilan dari Fabric dan mengekstrak token yang didelegasikan serta memvalidasinya.

  3. Beban kerja mencoba menukar token untuk https://storage.azure.com/user_impersonation, tetapi gagal karena autentikasi multifaktor yang dikonfigurasi oleh administrator penyewa diperlukan untuk mengakses Azure Storage (lihat kode kesalahan AADSTS).

  4. Beban kerja mengirimkan kesalahan bersamaan dengan klaim yang dikembalikan dalam kesalahan dari Microsoft Entra ID ke klien dengan menggunakan penyebaran kesalahan seperti dijelaskan di komunikasi beban kerja .

  5. Frontend beban kerja memanggil acquireAccessToken JavaScript API dan memberikan klaim sebagai claimsForConditionalAccessPolicy, di mana claims merujuk pada klaim yang disebarkan dari backend beban kerja.

    workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

Setelah itu, beban kerja dapat mencoba ulang proses operasi.

Menangani kesalahan saat meminta persetujuan

Terkadang pengguna tidak dapat memberikan persetujuan karena berbagai kesalahan. Setelah permintaan persetujuan, respons dikembalikan ke URI pengalihan. Dalam contoh kami, kode ini bertanggung jawab untuk menangani respons. (Anda dapat menemukannya di file index.ts.)

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

Frontend beban kerja dapat mengekstrak kode kesalahan dari URL dan menanganinya dengan sesuai.

Catatan

Dalam kedua skenario (kesalahan dan keberhasilan), proses harus selalu menutup jendela aplikasi segera, tanpa penundaan.

  • Last updated on