Autentikasi untuk Aplikasi Fabric

Fabric Apps menyertakan layanan autentikasi bawaan yang memasukkan pengguna, mengelola sesi mereka, dan melampirkan identitas mereka ke setiap panggilan data dan penyimpanan yang dilakukan aplikasi Anda. Artikel ini menjelaskan konsep yang perlu Anda pahami sebelum mengonfigurasi autentikasi untuk proyek Anda.

Untuk detail implementasi, lihat:

Modus autentikasi

Aplikasi Fabric yang diterapkan diautentikasi dengan Microsoft Entra ID. Pilih jalur integrasi berdasarkan di mana aplikasi berjalan dan siapa yang memperoleh token Entra:

Environment Metode yang didukung Kapan harus menggunakannya
Aplikasi browser menggunakan portal Fabric Popup SSO Fabric atau handoff tersemat Biarkan Fabric melakukan login interaktif, atau login di aplikasi yang tertanam di dalam Fabric.
Browser atau aplikasi Node.js yang sudah memiliki token Entra yang didelegasikan signInWithEntraToken() Tukarkan token yang disediakan dengan sesi Rayfin tanpa popup atau pengalihan.
Aplikasi yang disematkan dalam portal induk eksternal createEmbedHost() di induk dan initEmbeddedAuth() di iframe Biarkan broker induk terpercaya yang terautentikasi Entra melakukan handoff tanpa mengirim tokennya ke iframe.
Pengembangan lokal dengan backend lokal Email dan kata sandi Uji terhadap backend lokal; metode ini tidak berfungsi pada backend Fabric yang telah di-deploy.

Konsep utama:

  • Fabric SSO menggunakan portal Fabric untuk mengautentikasi pengguna browser. Aplikasi dapat berjalan di dalam Fabric atau menggunakan popup dari halaman mandiri, termasuk frontend lokal yang menargetkan backend yang telah di-deploy.
  • Direct Entra exchange dan handoff eksternal-parent-host adalah jalur tambahan Microsoft Entra, bukan dukungan untuk penyedia identitas arbitrer atau masuk dengan perwakilan layanan khusus aplikasi.
  • Email dan kata sandi hanya ditujukan untuk pengembangan lokal. Ini tidak berfungsi setelah penyebaran.
  • Saat pertama kali masuk, sistem menyiapkan pengguna. Dengan SSO Fabric, tidak ada langkah pendaftaran terpisah—pengguna dibuat secara otomatis saat pertama kali masuk.
  • Autentikasi diperlukan untuk penyebaran Fabric. Menyetel services.auth.enabled ke false menyebabkan npx rayfin up gagal.

Untuk persyaratan token dan contoh implementasi, lihat Direct Entra token sign-in dan Embed in an external parent portal.

Sesi dan identitas

Setelah pengguna masuk, SDK membuat sesi yang mewakili pengguna yang masuk. Sesi tidak transparan—aplikasi Anda tidak boleh menginspeksi token yang mendasarinya. Sebagai gantinya, aplikasi Anda membaca sekumpulan kecil properti tingkat tinggi:

  • Apakah sesi saat ini diautentikasi.
  • id dan email milik pengguna.
  • Klaim kustom yang telah Anda konfigurasi di rayfin.yml.

Instans klien yang sama yang secara otomatis membuat pengguna login juga secara otomatis menyertakan identitas pengguna dalam setiap panggilan data dan penyimpanan. Anda tidak perlu memberikan token secara manual.

Sesi juga meningkatkan peristiwa perubahan, sehingga UI Anda dapat bereaksi saat pengguna masuk atau keluar tanpa memuat ulang halaman.

Untuk integrasi sisi server, gunakan klien terpisah dan sesi Auth hanya-memori per pengguna (authStorage: false pada RayfinClient, atau { storage: false } pada Auth). Jangan pernah membagikan klien yang sedang login dan dapat diubah antar pengguna. Hapus instance autentikasi ketika permintaan atau cakupan khusus pengguna berakhir.

Mengaktifkan autentikasi di proyek Anda

Autentikasi dikonfigurasi di rayfin/rayfin.yml. Contoh berikut memungkinkan SSO Fabric (untuk aplikasi yang disebarkan) dan masuk email/kata sandi (untuk pengembangan lokal):

services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: true  # Local development only

Apa yang dikontrol setiap pengaturan:

  • services.auth.enabled – Mengaktifkan layanan autentikasi. Diperlukan untuk penyebaran Fabric apa pun.
  • allowedRedirectUris – Asal-usul yang diizinkan untuk menerima pengguna setelah masuk. Tambahkan URL dev lokal Anda di sini. npx rayfin up menambahkan asal aplikasi yang disebarkan secara otomatis.
  • fabric.enabled – Mengaktifkan SSO Fabric. Diperlukan untuk aplikasi yang disebarkan.
  • fabric.externalEntraExchange – Memungkinkan pertukaran token Entra yang didelegasikan secara langsung dan handoff ke host induk eksternal. Lingkungan Fabric target juga harus mendukung pertukaran tersebut.
  • password.enabled – Mengaktifkan masuk dengan email dan kata sandi untuk pengembangan lokal.

Important

Penerapan Fabric mengharuskan autentikasi diaktifkan. npx rayfin up gagal ketika services.auth.enabled diatur ke false.

Setelah mengedit rayfin.yml, mulai ulang backend lokal atau jalankan npx rayfin up untuk menerapkan perubahan.

Prasyarat untuk token Entra yang diperoleh secara eksternal

Pertukaran langsung dan autentikasi host induk eksternal memerlukan token pengguna yang didelegasikan untuk audiens Fabric/Power BI yang diterima oleh deployment target, dengan Item.Execute.All, yang dikeluarkan dalam tenant pemilik item. Pengguna juga harus memiliki izin Execute pada item aplikasi. Token khusus aplikasi tidak didukung oleh alur masuk ini.

Pustaka identitas Anda memperoleh token dan menangani persetujuan. SDK Rayfin menukarnya dengan sesi Rayfin; SDK ini tidak memperoleh token Entra. Klien berbasis browser juga membutuhkan kebijakan CORS layanan untuk mengizinkan origin permintaan dan header Authorization.

Klaim khusus

Klaim kustom memungkinkan Anda melampirkan metadata khusus aplikasi ke setiap sesi—misalnya, nama penyewa, bendera fitur, atau versi aplikasi. Fitur ini berguna untuk kontrol akses berbasis peran dan pembatasan fitur tanpa mengubah model data Anda.

services:
  auth:
    enabled: true
    customClaims:
      tenant: default
      app_version: 1.0.0

Klaim kustom muncul di dalam objek sesi dan dapat dirujuk dari aturan izin data Anda.

Apa yang disediakan SDK

Saat Anda menggunakan RayfinClient, layanan autentikasi tersedia di client.auth. Pada tingkat konseptual, ini menyediakan:

  • Mendaftar dan masuk dengan email dan kata sandi selama pengembangan lokal.
  • Masuk dan mendaftar melalui Fabric SSO untuk aplikasi yang diterapkan. Panggilan yang sama menangani pengguna baru dan yang kembali.
  • Pertukaran token Entra yang didelegasikan secara langsung dalam kode browser atau Node.js, plus serah terima ke host induk eksternal tepercaya untuk aplikasi tertanam.
  • Keluar untuk mengakhiri sesi saat ini.
  • Pembacaan sesi dan langganan sehingga UI Anda tetap sinkron dengan status autentikasi pengguna.

Untuk kode yang menghubungkan fitur-fitur ini ke dalam aplikasi nyata, lihat Konfigurasikan autentikasi Fabric SSO untuk aplikasi Fabric Anda. Untuk panduan tentang daftar yang diizinkan untuk callback dan handoff, lihat Konfigurasikan URI pengalihan autentikasi.

Konten terkait

  • Terakhir diperbarui pada