Tutorial: Menetapkan peran kustom dengan fungsi dan Microsoft Graph

Artikel ini menunjukkan cara menggunakan fungsi untuk meminta Microsoft Graph dan menetapkan peran kustom kepada pengguna berdasarkan keanggotaan grup Azure Active Directory yang dimilikinya.

Dalam tutorial ini, Anda mempelajari caranya:

• Menerapkan aplikasi web statik.
• Buat pendaftaran aplikasi Microsoft Entra.
• Siapkan autentikasi kustom dengan ID Microsoft Entra.
• Mengonfigurasi fungsi tanpa server yang mengajukan kueri tentang keanggotaan grup Azure Active Directory dari pengguna dan mengembalikan daftar peran kustom.

Catatan

Tutorial ini mengharuskan Anda untuk menggunakan fungsi guna menetapkan peran. Manajemen peran berbasis fungsi saat ini sedang dalam pratinjau. Tingkat izin yang diperlukan untuk menyelesaikan tutorial ini adalah "User.Read.All".

Ada fungsi bernama GetRoles di API aplikasi. Fungsi ini menggunakan token akses pengguna untuk mengkueri Active Directory dari Microsoft Graph. Jika pengguna adalah anggota grup apa pun yang ditentukan dalam aplikasi, maka peran kustom yang sesuai dipetakan ke pengguna.

Prasyarat

Persyaratan	Komentar
Akun Azure aktif	Jika Anda tidak memilikinya, Anda dapat membuatnya secara gratis.
Izin Microsoft Entra	Anda harus memiliki izin yang memadai untuk membuat aplikasi Microsoft Entra.

Menyiapkan repositori GitHub

1. Buat repositori berdasarkan templat fungsi peran. Buka lokasi berikut untuk membuat repositori baru.

   https://github.com/staticwebdev/roles-function/generate

2. Beri nama repositori Anda my-custom-roles-app.

3. Pilih Buat repositori dari templat.

Menerapkan aplikasi web statis ke Azure

1. Di jendela browser baru, buka portal Azure.

2. Dari sudut kiri atas, pilih Buat sumber daya.

3. Dalam kotak pencarian, ketik aplikasi web statis.

4. Pilih Static Web Apps.

5. Pilih Buat.

6. Konfigurasikan aplikasi web statis Anda dengan informasi berikut:

   Pengaturan	Nilai	Catatan
   Langganan	Pilih langganan Azure Anda.
   Grup sumber daya	Buat grup baru bernama my-custom-roles-app-group.
   Nama	my-custom-roles-app
   Jenis paket	Standard	Menyesuaikan autentikasi dan menetapkan peran menggunakan fungsi memerlukan paket Standar .
   Wilayah untuk API	Pilih wilayah yang terdekat dengan Anda.

7. Di bagian Detail penyebaran:

   Pengaturan	Nilai
   Sumber	Pilih GitHub.
   Organization	Pilih organisasi tempat Anda membuat repositori.
   Repositori	Pilih my-custom-roles-app.
   Cabang	Pilih utama.

8. Di bagian Detail Build, tambahkan detail konfigurasi untuk aplikasi ini.

   Pengaturan	Nilai	Catatan
   Preset build	Pilih Kustom.
   Lokasi aplikasi	Masukkan /frontend.	Folder ini berisi aplikasi ujung depan.
   Lokasi API	/api	Folder di repositori yang berisi fungsi API.
   Lokasi output	Biarkan kosong.	Aplikasi ini tidak memiliki output build.

9. Pilih Tinjau + buat.

10. Pilih Buat memulai penyebaran pertama.

11. Setelah proses selesai, pilih Buka sumber daya untuk membuka aplikasi web statis baru Anda.

12. Di bagian ringkasan, temukan URL aplikasi Anda. Salin nilai ini ke editor teks untuk digunakan dalam langkah-langkah mendatang untuk menyiapkan autentikasi Direktori Aktif.

Membuat aplikasi Microsoft Entra

1. Di portal Azure, cari dan buka ID Microsoft Entra.

2. Dari menu Kelola, pilih Pendaftaran aplikasi.

3. Pilih Pendaftaran baru untuk membuka jendela Daftarkan aplikasi . Masukkan nilai berikut:

   Pengaturan	Nilai	Catatan
   Nama	Masukkan MyStaticWebApp.
   Jenis akun yang didukung	Pilih Akun yang hanya dalam direktori organisasi ini.
   URI Pengalihan	Pilih Web dan masukkan URL panggilan balik autentikasi Microsoft Entra dari aplikasi web statis Anda. <YOUR_SITE_URL>/.auth/login/aad/callback Ganti <YOUR_SITE_URL> dengan URL aplikasi web statis Anda.	URL ini adalah apa yang Anda salin ke editor teks di langkah sebelumnya.

   

4. Pilih Daftarkan.

5. Setelah pendaftaran aplikasi dibuat, salin ID Aplikasi (klien) dan ID Direktori (penyewa) di bagian Penting ke editor teks.

   Anda memerlukan nilai-nilai ini untuk mengonfigurasi autentikasi Direktori Aktif di aplikasi web statis Anda.

Aktifkan token ID

1. Dari pengaturan pendaftaran aplikasi, pilih Autentikasi di bawah Kelola.

2. Di bagian Izin implisit dan aliran hibrid, pilih Token ID (digunakan untuk aliran implisit dan hibrid).

   Runtime Static Web Apps memerlukan konfigurasi ini untuk mengautentikasi pengguna Anda.

3. Pilih Simpan.

Membuat rahasia klien

1. Di pengaturan pendaftaran aplikasi, pilih Sertifikat & rahasia di bawah Kelola.

2. Di bagian Rahasia klien, pilih Rahasia klien baru.

3. Untuk bidang Deskripsi, masukkan MyStaticWebApp.

4. Untuk bidang Kedaluwarsa, biarkan nilai default 6 bulan.

   Catatan

   Anda harus memutar rahasia sebelum tanggal kedaluwarsa dengan menghasilkan rahasia baru dan memperbarui aplikasi dengan nilainya.

5. Pilih Tambahkan.

6. Salin Nilai rahasia klien yang Anda buat ke editor teks.

   Anda memerlukan nilai ini untuk mengonfigurasi autentikasi Direktori Aktif di aplikasi web statis Anda.

   

Mengonfigurasi autentikasi Azure Active Directory

1. Di browser, buka repositori GitHub yang berisi aplikasi web statis yang Anda sebarkan.

   Buka file konfigurasi aplikasi di frontend/staticwebapp.config.json. File ini berisi bagian berikut:

   "auth": {
     "rolesSource": "/api/GetRoles",
     "identityProviders": {
       "azureActiveDirectory": {
         "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
         "registration": {
           "openIdIssuer": "https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID>",
           "clientIdSettingName": "AAD_CLIENT_ID",
           "clientSecretSettingName": "AAD_CLIENT_SECRET"
         },
         "login": {
           "loginParameters": [
             "resource=https://graph.microsoft.com"
           ]
         }
       }
     }
   },
   

   Konfigurasi ini terdiri dari pengaturan berikut:

   Properti	Deskripsi
   rolesSource	URL tempat proses masuk mendapatkan daftar peran yang tersedia. Untuk aplikasi sampel, URL adalah /api/GetRoles.
   userDetailsClaim	URL skema yang digunakan untuk memvalidasi permintaan masuk.
   openIdIssuer	Rute masuk Microsoft Entra, ditambahkan dengan ID penyewa Anda.
   clientIdSettingName	ID klien Microsoft Entra Anda.
   clientSecretSettingName	Nilai rahasia klien Microsoft Entra Anda.
   loginParameters	Guna mendapatkan token akses untuk Microsoft Graph, bidang loginParameters harus dikonfigurasi dengan resource=https://graph.microsoft.com.

2. Pilih Edit untuk memperbarui file.

3. Perbarui nilai https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID> openIdIssuer dengan mengganti <YOUR_AAD_TENANT_ID> dengan ID direktori (penyewa) ID Microsoft Entra Anda.

4. Pilih Terapkan perubahan....

5. Masukkan pesan penerapan, dan pilih Terapkan perubahan.

   Menerapkan perubahan ini memulai GitHub Actions yang dijalankan untuk memperbarui aplikasi web statis.

6. Buka sumber daya aplikasi web statis Anda di portal Azure.

7. Pilih Konfigurasi di bilah menu.

8. Di bagian Pengaturan aplikasi, tambahkan pengaturan berikut:

   Nama	Nilai
   AAD_CLIENT_ID	ID aplikasi Direktori Aktif (klien) Anda.
   AAD_CLIENT_SECRET	Nilai rahasia klien aplikasi Direktori Aktif Anda.

9. Pilih Simpan.

Buat peran

1. Buka pendaftaran aplikasi Active Directory Anda di portal Azure.

2. Di bawah Kelola, pilih Peran aplikasi.

3. Pilih Buat peran aplikasi dan masukkan nilai berikut:

   Pengaturan	Nilai
   Nama tampilan	Masukkan admin.
   Jenis anggota yang diizinkan	Pilih Pengguna/Grup.
   Value	Masukkan admin.
   Deskripsi	Masukkan Administrator.

4. Centang kotak untuk Apakah Anda ingin mengaktifkan peran aplikasi ini?

5. Pilih Terapkan.

6. Sekarang ulangi proses yang sama untuk peran bernama pembaca.

7. Salin nilai ID untuk setiap peran dan sisihkan di editor teks.

Memverifikasi peran kustom

Aplikasi sampel berisi fungsi API (api/GetRoles/index.js) yang meminta Microsoft Graph untuk menentukan apakah pengguna berada dalam grup yang telah ditentukan sebelumnya.

Berdasarkan keanggotaan grup pengguna, fungsi ini menetapkan peran kustom kepada pengguna. Aplikasi ini dikonfigurasi untuk membatasi rute tertentu berdasarkan peran kustom ini.

1. Di repositori GitHub Anda, buka fungsi GetRoles yang terletak di api/GetRoles/index.js.

   Di dekat bagian atas, ada roleGroupMappings objek yang memetakan peran pengguna kustom ke grup Microsoft Entra.

2. Pilih Edit.

3. Perbarui objek dengan ID grup dari penyewa Microsoft Entra Anda.

   Misalnya, jika Anda memiliki grup dengan ID 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 dan b6059db5-9cef-4b27-9434-bb793aa31805 ID, Anda akan memperbarui objek menjadi:

   const roleGroupMappings = {
     'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
     'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
   };
   

   Fungsi GetRoles dipanggil setiap kali pengguna berhasil diautentikasi dengan ID Microsoft Entra. Fungsi ini menggunakan token akses pengguna untuk mengajukan kueri terkait keanggotaan grup Azure Active Directory yang ia miliki dari Microsoft Graph. Jika pengguna adalah anggota dari grup apa pun yang ditentukan dalam roleGroupMappings objek, maka peran kustom yang sesuai dikembalikan.

   Dalam contoh di atas, jika pengguna adalah anggota grup Direktori Aktif dengan ID b6059db5-9cef-4b27-9434-bb793aa31805, mereka akan diberikan peran tersebut reader .

4. Pilih Terapkan perubahan....

5. Tambahkan pesan penerapan dan pilih Terapkan perubahan.

   Membuat perubahan ini memulai build in untuk memperbarui aplikasi web statis.

6. Ketika penyebaran selesai, Anda dapat memverifikasi perubahan Anda dengan membuka URL aplikasi.

7. Masuk ke aplikasi web statis Anda menggunakan ID Microsoft Entra.

8. Saat Anda masuk, aplikasi sampel menampilkan daftar peran yang Anda tetapkan berdasarkan keanggotaan grup Direktori Aktif identitas Anda.

   Bergantung pada peran ini, Anda diizinkan atau dilarang mengakses beberapa rute di aplikasi.

Catatan

Beberapa kueri terhadap Microsoft Graph mengembalikan beberapa halaman data. Saat diperlukan lebih dari satu permintaan kueri, Microsoft Graph mengembalikan @odata.nextLink properti dalam respons yang berisi URL ke halaman hasil berikutnya. Untuk informasi selengkapnya, lihat Halaman data Microsoft Graph di aplikasi Anda

Membersihkan sumber daya

Bersihkan sumber daya yang telah Anda sebarkan dengan menghapus grup sumber daya.

1. Dari portal Azure, pilih Grup sumber daya dari menu sebelah kiri.

2. Masukkan nama grup sumber daya di bidang Filter menurut nama.

3. Pilih nama grup sumber daya yang Anda gunakan dalam tutorial ini.

4. Pilih Hapus grup sumber daya dari menu atas.

Langkah berikutnya

Autentikasi dan Otorisasi