Panduan Cepat - Masuk sebagai pengguna dan panggil API web dalam sampel aplikasi web Node.js

Berlaku untuk: Penyewa eksternal (pelajari selengkapnya)

Dalam Panduan Cepat ini, Anda akan mempelajari cara masuk pengguna dan memanggil API web dari aplikasi web Node.js pada penyewa eksternal Anda. Aplikasi sampel memanggil .NET API. Aplikasi web sampel menggunakan Microsoft Authentication Library (MSAL) untuk Node guna menangani autentikasi.

Prasyarat

• Selesaikan langkah-langkah dan prasyarat di artikel Mulai Cepat: Memasukkan pengguna dalam contoh aplikasi web. Artikel ini memperlihatkan kepada Anda cara masuk pengguna dengan menggunakan aplikasi web sampel Node.js.
• Penyewa eksternal. Untuk membuatnya, pilih dari metode berikut:
  • (Disarankan) Gunakan ekstensi Microsoft Entra External ID untuk menyiapkan tenant eksternal langsung di Visual Studio Code.
  • Buat penyewa eksternal baru di pusat admin Microsoft Entra.
• Daftarkan aplikasi baru untuk API web Anda di pusat admin Microsoft Entra, dikonfigurasi hanya untuk Akun di direktori organisasi ini. Lihat Mendaftarkan aplikasi untuk detail selengkapnya. Rekam nilai berikut dari halaman Gambaran Umum aplikasi untuk digunakan nanti:
  • ID Aplikasi (klien)
  • ID Direktori (Penyewa)
• Visual Studio Code atau editor kode lainnya.
• Node.js.
• .NET 7.0 atau yang lebih baru.

Mengonfigurasi cakupan dan peran API

Dengan mendaftarkan API web, Anda harus mengonfigurasi cakupan API untuk menentukan izin yang dapat diminta aplikasi klien untuk mengakses API web. Selain itu, Anda perlu menyiapkan peran aplikasi untuk menentukan peran yang tersedia untuk pengguna atau aplikasi, dan memberikan izin API yang diperlukan ke aplikasi web untuk memungkinkannya memanggil API web.

Konfigurasi cakupan API

API perlu menerbitkan minimal satu cakupan, juga disebut Delegated Permission, agar aplikasi klien berhasil mendapatkan token akses bagi pengguna. 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 Umum.

2. Di bawah Kelola, pilih Mengekspos 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 bawah 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:

   Harta benda	Nilai
   Nama cakupan	DaftarTugas.Baca
   Siapa yang dapat menyetujui	Hanya untuk Admin
   Nama tampilan persetujuan admin	Membaca daftar ToDo pengguna menggunakan 'TodoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi untuk membaca daftar ToDo pengguna dengan menggunakan'TodoListApi'.
   Negara	Diaktifkan

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

   Harta benda	Nilai
   Nama cakupan	DaftarTugas.BacaTulis
   Siapa yang dapat menyetujui	Hanya untuk Admin
   Nama tampilan persetujuan admin	Mengelola daftar tugas pengguna menggunakan 'ToDoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca dan menulis daftar ToDo milik pengguna tersebut menggunakan 'ToDoListApi'
   Negara	Diaktifkan

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, yang juga disebut sebagai izin aplikasi , sehingga aplikasi klien dapat mendapatkan token akses atas nama 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 Umum.

2. Di bawah Kelola, pilih peran Aplikasi .

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

   Harta benda	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'
   Apakah Anda ingin mengaktifkan peran aplikasi ini?	Tetap periksa

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

   Harta benda	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'
   Apakah Anda ingin mengaktifkan peran aplikasi ini?	Tetap periksa

Mengonfigurasi klaim opsional

Anda dapat menambahkan klaim opsional idtyp untuk membantu web API menentukan apakah token adalah token aplikasi atau token aplikasi + pengguna. Meskipun Anda dapat menggunakan kombinasi scp dan klaim peran untuk tujuan yang sama, menggunakan klaim idtyp adalah cara termudah untuk membedakan token aplikasi dan token aplikasi + pengguna. Misalnya, nilai klaim ini 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 Umum.

2. Di bawah Kelola, pilih izin API .

3. Di bawah Izin yang sudah dikonfigurasi, pilih opsi 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. Pada titik ini, Anda telah menetapkan izin dengan benar. Namun, karena pihak penyewa adalah pelanggan, pengguna konsumen itu sendiri tidak dapat menyetujui izin-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-izin tersebut 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 file App\authConfig.js.

2. Temukan pengganti:

   • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) aplikasi klien yang Anda daftarkan sebelumnya. Aplikasi klien adalah aplikasi yang Anda daftarkan dalam prasyarat.
   • Enter_the_Tenant_Subdomain_Here dan ganti dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki nama penyewa, pelajari cara membaca detail penyewa Anda.
   • Enter_the_Client_Secret_Here dan gantikan 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 sebagai bagian dari prasyarat.

Untuk menggunakan pendaftaran aplikasi Anda dalam sampel API web:

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

2. Temukan pengganti:

   • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) API web yang Anda salin. Aplikasi API web adalah aplikasi yang Anda daftarkan sebelumnya sebagai bagian dari prasyarat.
   • 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 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 install
   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 SandiAnda, 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.

   

Panggilan API

1. Untuk memanggil API, pilih tautan Lihat daftar tugas Anda. Anda melihat halaman yang mirip dengan cuplikan layar berikut.

   

2. Manipulasi daftar to-do 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, agar dapat membaca tugas, aplikasi web klien harus mendapatkan token akses dengan cakupan izin ToDoList.Read.

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 kesalahan HTTP 401 Unauthorized.

Konten terkait

• Tutorial : Mengamankan API web ASP.NET Core yang terdaftar di penyewa eksternal.