Memasukkan pengguna dan memanggil API web dalam sampel aplikasi web Node.js

Panduan ini menggunakan sampel kode untuk menunjukkan kepada Anda cara menambahkan autentikasi dan otorisasi dalam aplikasi web Node.js. Contoh aplikasi memasukkan pengguna ke aplikasi web Node.js, yang kemudian memanggil .NET API. Anda mengaktifkan autentikasi dan otorisasi dengan menggunakan detail penyewa eksternal Anda. Aplikasi web sampel menggunakan Microsoft Authentication Library (MSAL) untuk Node untuk menangani autentikasi.

Di artikel ini, Anda menyelesaikan tugas-tugas berikut:

• Daftarkan dan konfigurasikan API web di pusat admin Microsoft Entra.

• Perbarui contoh aplikasi web Node dan api web ASP.NET untuk menggunakan detail penyewa eksternal Anda.

• Jalankan dan uji sampel aplikasi web dan API.

Prasyarat

• Selesaikan langkah-langkah dalam artikel Memasukkan pengguna dan memanggil API dalam sampel Node.js aplikasi web. Artikel ini memperlihatkan kepada Anda cara memasukkan pengguna dengan menggunakan sampel Node.js aplikasi web.
• Visual Studio Code, atau editor kode lainnya.
• Node.js.
• .NET 7.0 atau yang lebih baru.
• Penyewa eksternal. Untuk membuatnya, pilih dari metode berikut:
  • (Disarankan) Gunakan ekstensi ID Eksternal Microsoft Entra untuk menyiapkan penyewa eksternal langsung di Visual Studio Code.
  • Buat penyewa eksternal baru di pusat admin Microsoft Entra.

Mendaftarkan API web

Pada langkah ini, Anda membuat web dan pendaftaran aplikasi API web, dan Anda menentukan cakupan API web Anda.

Mendaftarkan aplikasi API web

1. Masuk ke pusat admin Microsoft Entra setidaknya sebagai Pengembang Aplikasi.

2. Jika Anda memiliki akses ke beberapa penyewa, gunakan ikon Pengaturan di menu atas untuk beralih ke penyewa eksternal Anda dari menu Direktori + langganan.

3. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.

4. Pilih + Pendaftaran baru.

5. Di halaman Daftarkan aplikasi yang muncul, masukkan informasi pendaftaran aplikasi Anda:

   1. Di bagian Nama, masukkan nama aplikasi yang bermakna yang akan ditampilkan kepada pengguna aplikasi, misalnya ciam-ToDoList-api.

   2. Di bawah Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini.

6. Pilih Daftar untuk membuat aplikasi.

7. Panel Gambaran Umum aplikasi ditampilkan saat pendaftaran selesai. Rekam ID Direktori (penyewa) dan ID Aplikasi (klien) yang akan digunakan dalam kode sumber aplikasi Anda.

Mengonfigurasi cakupan API

API ini perlu mengekspos izin, yang perlu diperoleh klien untuk memanggil API:

API perlu menerbitkan minimal satu cakupan, juga disebut Izin Yang Didelegasikan, agar aplikasi klien mendapatkan token akses bagi pengguna dengan sukses. Untuk menerbitkan cakupan, ikuti langkah-langkah berikut:

1. Dari halaman Pendaftaran aplikasi, pilih aplikasi API yang Anda buat (ciam-ToDoList-api) untuk membuka halaman Gambaran Umumnya.

2. Di bagian Kelola, pilih Ekspos API.

3. Di bagian atas halaman, di samping URI ID Aplikasi, pilih tautan Tambahkan untuk menghasilkan URI yang unik untuk aplikasi ini.

4. Terima URI ID Aplikasi yang diusulkan seperti api://{clientId}, dan pilih Simpan. Saat aplikasi web Anda meminta token akses untuk API web, aplikasi web menambahkan URI sebagai awalan untuk setiap cakupan yang Anda tentukan untuk API.

5. Di bagian Cakupan yang ditentukan oleh API ini, pilih Tambahkan cakupan.

6. Masukkan nilai berikut yang menentukan akses baca ke API, lalu pilih Tambahkan cakupan untuk menyimpan perubahan Anda:

   Properti	Nilai
   Nama cakupan	ToDoList.Read
   Siapa yang dapat menyetujui	Hanya Admin
   Nama tampilan persetujuan admin	Membaca daftar Pengguna ToDo menggunakan 'TodoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca daftar ToDo pengguna menggunakan 'TodoListApi'.
   Status	Diaktifkan

7. Pilih Tambahkan cakupan lagi, dan masukkan nilai berikut yang menentukan cakupan akses baca dan tulis ke API. Pilih Tambahkan cakupan untuk menyimpan perubahan Anda:

   Properti	Nilai
   Nama cakupan	ToDoList.ReadWrite
   Siapa yang dapat menyetujui	Hanya Admin
   Nama tampilan persetujuan admin	Membaca dan menulis daftar ToDo pengguna menggunakan 'ToDoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca dan menulis daftar ToDo pengguna menggunakan 'ToDoListApi'
   Status	Diaktifkan

8. Di bawah Kelola, pilih Manifes untuk membuka editor manifes API.

9. Atur accessTokenAcceptedVersion properti ke 2.

10. Pilih Simpan.

Pelajari selengkapnya tentang prinsip hak istimewa paling sedikit saat menerbitkan izin untuk API web.

Mengonfigurasi peran aplikasi

API perlu menerbitkan minimal satu peran aplikasi untuk aplikasi, juga disebut Izin Aplikasi, agar aplikasi klien mendapatkan token akses sebagai diri mereka sendiri. Izin aplikasi adalah jenis izin yang harus diterbitkan API ketika mereka ingin memungkinkan aplikasi klien berhasil mengautentikasi sebagai diri mereka sendiri dan tidak perlu memasukkan pengguna. Untuk menerbitkan izin aplikasi, ikuti langkah-langkah berikut:

1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-ToDoList-api) untuk membuka halaman Gambaran Umumnya.

2. Di bawah Kelola, pilih Peran aplikasi.

3. Pilih Buat peran aplikasi, lalu masukkan nilai berikut, lalu pilih Terapkan untuk menyimpan perubahan Anda:

   Properti	Nilai
   Nama tampilan	ToDoList.Read.All
   Jenis anggota yang diizinkan	Aplikasi
   Nilai	ToDoList.Read.All
   Deskripsi	Izinkan aplikasi membaca daftar ToDo setiap pengguna menggunakan 'TodoListApi'

4. Pilih Buat peran aplikasi lagi, lalu masukkan nilai berikut untuk peran aplikasi kedua, lalu pilih Terapkan untuk menyimpan perubahan Anda:

   Properti	Nilai
   Nama tampilan	ToDoList.ReadWrite.All
   Jenis anggota yang diizinkan	Aplikasi
   Nilai	ToDoList.ReadWrite.All
   Deskripsi	Izinkan aplikasi membaca dan menulis daftar ToDo setiap pengguna menggunakan 'ToDoListApi'

Konfigurasikan klaim opsional

Anda dapat mengklaim opsional idtyp untuk membantu API web menentukan apakah token adalah token aplikasi atau token aplikasi + pengguna. Meskipun Anda dapat menggunakan kombinasi klaim scp dan peran untuk tujuan yang sama, menggunakan klaim idtyp adalah cara term mudah untuk memberi tahu token aplikasi dan token aplikasi + pengguna terpisah. Misalnya, nilai klaim ini adalah aplikasi saat token adalah token khusus aplikasi.

Gunakan langkah-langkah dalam artikel Mengonfigurasi klaim opsional untuk menambahkan klaim idtyp ke token akses:

• Untuk jenis Token, pilih Akses.
• Dari daftar klaim opsional, pilih idtyp.

Memberikan izin API ke aplikasi web

Untuk memberikan izin API aplikasi klien Anda (ciam-client-app), ikuti langkah-langkah berikut:

1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-client-app) untuk membuka halaman Gambaran Umumnya.

2. Di bagian Kelola, pilih Izin API.

3. Di Izin yang dikonfigurasi, pilih Tambahkan izin.

4. Pilih tab API yang digunakan organisasi saya.

5. Dalam daftar API, pilih API seperti ciam-ToDoList-api.

6. Pilih opsi Izin yang didelegasikan.

7. Dari daftar izin, pilih ToDoList.Read, ToDoList.ReadWrite (gunakan kotak pencarian jika perlu).

8. Pilih tombol Tambahkan izin akses. Pada titik ini, Anda telah menetapkan izin dengan benar. Namun, karena penyewa adalah penyewa pelanggan, pengguna konsumen itu sendiri tidak dapat menyetujui izin ini. Untuk mengatasi masalah ini, Anda sebagai admin harus menyetujui izin ini atas nama semua pengguna di penyewa:

   1. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda, lalu pilih Ya.

   2. Pilih Refresh, lalu verifikasi bahwa Diberikan untuk <nama> penyewa Anda muncul di bawah Status untuk kedua cakupan.

9. Dari daftar Izin yang dikonfigurasi, pilih izin ToDoList.Read dan ToDoList.ReadWrite, satu per satu, lalu salin URI lengkap izin untuk digunakan nanti. URI izin lengkap terlihat mirip dengan api://{clientId}/{ToDoList.Read} atau api://{clientId}/{ToDoList.ReadWrite}.

Mengkloning atau mengunduh sampel aplikasi web dan API web

Untuk mendapatkan aplikasi sampel, Anda dapat mengkloningnya dari GitHub atau mengunduhnya sebagai file .zip.

• Untuk mengkloning sampel, buka prompt perintah dan navigasi ke tempat Anda ingin membuat proyek, dan masukkan perintah berikut:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

• Unduh file .zip. Ekstrak ke jalur file di mana panjang nama kurang dari 260 karakter.

Menginstal dependensi proyek

1. Buka jendela konsol, dan ubah ke direktori yang berisi aplikasi sampel Node.js/Express:

   cd 2-Authorization\4-call-api-express\App
   

2. Jalankan perintah berikut untuk menginstal dependensi aplikasi web:

   npm install && npm update
   

Mengonfigurasi contoh aplikasi web dan API

Untuk menggunakan pendaftaran aplikasi Anda di sampel aplikasi web klien:

1. Di editor kode Anda, buka App\authConfig.js file.

2. Temukan tempat penampung:

   • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) aplikasi yang Anda daftarkan sebelumnya.
   • Enter_the_Tenant_Subdomain_Here dan ganti dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda adalah contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki nama penyewa, pelajari cara membaca detail penyewa Anda.
   • Enter_the_Client_Secret_Here dan ganti dengan nilai rahasia aplikasi yang Anda salin sebelumnya.
   • Enter_the_Web_Api_Application_Id_Here dan ganti dengan ID Aplikasi (klien) API web yang Anda salin sebelumnya.

Untuk menggunakan pendaftaran aplikasi Anda dalam sampel API web:

1. Di editor kode Anda, buka API\ToDoListAPI\appsettings.json file.

2. Temukan tempat penampung:

   • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) API web yang Anda salin.
   • Enter_the_Tenant_Id_Here dan ganti dengan ID Direktori (penyewa) yang Anda salin sebelumnya.
   • Enter_the_Tenant_Subdomain_Here dan ganti dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda adalah contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki nama penyewa, pelajari cara membaca detail penyewa Anda.

Menjalankan dan menguji sampel aplikasi web dan API

1. Buka jendela konsol, lalu jalankan API web dengan menggunakan perintah berikut:

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. Jalankan klien aplikasi web dengan menggunakan perintah berikut:

   cd 2-Authorization\4-call-api-express\App
   npm start
   

3. Buka browser Anda, lalu buka http://localhost:3000.

4. Pilih tombol Masuk . Anda diminta untuk masuk.

   

5. Pada halaman masuk, ketik alamat Email Anda, pilih Berikutnya, ketik Kata Sandi Anda, lalu pilih Masuk. Jika Anda tidak memiliki akun, pilih Tidak ada akun? Buat satu tautan, yang memulai alur pendaftaran.

6. Jika Anda memilih opsi pendaftaran, setelah mengisi email, kode sandi satu kali, kata sandi baru, dan detail akun lainnya, Anda menyelesaikan seluruh alur pendaftaran. Anda melihat halaman yang mirip dengan cuplikan layar berikut. Anda akan melihat halaman serupa jika Anda memilih opsi masuk.

   

Panggil API

1. Untuk memanggil API, pilih tautan Tampilkan todolist Anda. Anda melihat halaman yang mirip dengan cuplikan layar berikut.

   

2. Manipulasi daftar tugas dengan membuat dan menghapus item.

Cara kerjanya

Anda memicu panggilan API setiap kali Anda melihat, menambahkan, atau menghapus tugas. Setiap kali Anda memicu panggilan API, aplikasi web klien memperoleh token akses dengan izin (cakupan) yang diperlukan untuk memanggil titik akhir API. Misalnya, untuk membaca tugas, aplikasi web klien harus memperoleh token akses dengan ToDoList.Read izin/cakupan.

Titik akhir API web perlu memeriksa apakah izin atau cakupan dalam token akses, yang disediakan oleh aplikasi klien, valid. Jika token akses valid, titik akhir merespons permintaan HTTP, jika tidak, token tersebut merespons dengan 401 Unauthorized kesalahan HTTP.

Konten terkait

• Masuk pengguna dan panggil API di aplikasi web Node.js Anda sendiri.
• Aktifkan reset kata sandi.
• Sesuaikan branding default.
• Mengonfigurasi rincian masuk dengan Google.