Memanggil API web ASP.NET Core dengan Insomnia

Artikel ini menunjukkan kepada Anda cara memanggil API web ASP.NET Core yang dilindungi menggunakan Insomnia. Insomnia adalah aplikasi yang memungkinkan Anda mengirim permintaan HTTP ke API web untuk menguji kebijakan otorisasi dan kontrol akses (autentikasi). Dalam artikel ini, Anda mendaftarkan aplikasi web dan API web di penyewa. Aplikasi web digunakan untuk mendapatkan token akses yang dihasilkan oleh platform identitas Microsoft. Selanjutnya, Anda menggunakan token untuk melakukan panggilan resmi ke API web menggunakan Insomnia.

Artikel ini menunjukkan kepada Anda cara memanggil API web ASP.NET Core yang dilindungi menggunakan Insomnia. Insomnia adalah aplikasi yang memungkinkan Anda mengirim permintaan HTTP ke API web untuk menguji kebijakan otorisasi dan kontrol akses (autentikasi). Mengikuti dari Tutorial: Menerapkan titik akhir yang dilindungi ke API Anda, tempat Anda membuat API yang dilindungi, Anda perlu mendaftarkan aplikasi web dengan platform identitas Microsoft untuk menghasilkan token akses. Selanjutnya, Anda menggunakan token untuk melakukan panggilan resmi ke API menggunakan Insomnia.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• Akun Azure ini harus memiliki izin untuk mengelola aplikasi. Salah satu peran Microsoft Entra berikut ini menyertakan izin yang diperlukan:
  • Administrator Aplikasi
  • Pengembang Aplikasi
  • Admin Aplikasi Cloud
• Unduh dan instal Insomnia. Anda menggunakan Insomnia untuk mendapatkan token akses untuk permintaan API Anda.
• Persyaratan minimum .NET 8.0 SDK.

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• Akun Azure ini harus memiliki izin untuk mengelola aplikasi. Salah satu peran Microsoft Entra berikut ini menyertakan izin yang diperlukan:
  • Administrator Aplikasi
  • Pengembang Aplikasi
  • Admin Aplikasi Cloud
• Penyelesaian seri tutorial:
  • Tutorial: Mendaftarkan API web dengan platform identitas Microsoft.
  • Tutorial: Membuat dan mengonfigurasi proyek ASP.NET Core untuk autentikasi.
  • Tutorial: Menerapkan titik akhir yang dilindungi ke API Anda.
• Unduh dan instal Insomnia.

Daftarkan aplikasi

platform identitas Microsoft mengharuskan aplikasi Anda didaftarkan sebelum menyediakan layanan manajemen identitas dan akses. Pendaftaran aplikasi memungkinkan Anda menentukan nama dan jenis aplikasi dan audiens masuk. Audiens masuk menentukan jenis akun pengguna yang diizinkan masuk ke aplikasi tertentu.

Mendaftarkan API web

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Ikuti langkah-langkah berikut untuk membuat pendaftaran 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 tempat Anda ingin mendaftarkan aplikasi dari menu Direktori + langganan.

3. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.

4. Pilih Pendaftaran baru.

5. Masukkan Nama untuk aplikasi, seperti NewWebAPI1.

6. Untuk Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini. Untuk informasi tentang jenis akun yang berbeda, pilih opsi Bantu saya memilih .

7. Pilih Daftarkan.

   

8. Anda dapat melihat panel Gambaran Umum aplikasi saat pendaftaran selesai. Rekam ID Direktori (penyewa) dan ID Aplikasi (klien) yang akan digunakan dalam langkah-langkah selanjutnya.

   

Catatan

Jenis akun yang didukung dapat diubah dengan merujuk ke Ubah akun yang didukung oleh aplikasi.

Mengekspos API

Setelah API terdaftar, Anda dapat mengonfigurasi izinnya dengan menentukan cakupan yang diekspos API ke aplikasi klien. Aplikasi klien meminta izin untuk melakukan operasi dengan meneruskan token akses bersama dengan permintaannya ke API web yang dilindungi. API web kemudian melakukan operasi yang diminta hanya jika token akses yang diterimanya valid.

1. Di bawah Kelola, pilih Ekspos API > Tambahkan cakupan. Terima URI (api://{clientId}) ID Aplikasi yang diusulkan dengan memilih Simpan dan lanjutkan. {clientId} adalah nilai yang direkam dari halaman Gambaran Umum. Kemudian masukkan informasi berikut:

   1. Untuk nama Cakupan, masukkan Forecast.Read.
   2. Untuk Siapa yang dapat menyetujui, pastikan bahwa opsi Admin dan pengguna dipilih.
   3. Dalam kotak Nama tampilan persetujuan admin, masukkan Read forecast data.
   4. Dalam kotak Deskripsi persetujuan admin, masukkan Allows the application to read weather forecast data.
   5. Dalam kotak Nama tampilan persetujuan pengguna, masukkan Read forecast data.
   6. Dalam kotak Deskripsi persetujuan pengguna, masukkan Allows the application to read weather forecast data.
   7. Pastikan bahwa Status diatur ke Diaktifkan.

2. Pilih Tambahkan cakupan. Jika cakupan telah dimasukkan dengan benar, cakupan akan muncul di panel Mengekspos API .

   

Mendaftarkan aplikasi web

Tidak cukup untuk memiliki API web, Anda juga memerlukan aplikasi web untuk mendapatkan token akses untuk mengakses API web.

Ikuti langkah berikut untuk membuat pendaftaran aplikasi web:

1. Pilih Beranda untuk kembali ke halaman beranda. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.
2. Pilih Pendaftaran baru.
3. Masukkan Nama untuk aplikasi, seperti web-app-calls-web-api.
4. Untuk Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini. Untuk informasi tentang jenis akun yang berbeda, pilih opsi Bantu saya memilih .
5. Di bawah URI Pengalihan (opsional), pilih Web, lalu masukkan http://localhost dalam kotak teks URL.
6. Pilih Daftarkan.

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 tempat Anda ingin mendaftarkan aplikasi dari menu Direktori + langganan.
3. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.
4. Pilih Pendaftaran baru.
5. Masukkan Nama untuk aplikasi, seperti web-app-calls-web-api.
6. Untuk Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini. Untuk informasi tentang jenis akun yang berbeda, pilih opsi Bantu saya memilih .
7. Di bawah URI Pengalihan (opsional), pilih Web, lalu masukkan http://localhost dalam kotak teks URL.
8. Pilih Daftarkan.

Anda dapat melihat panel Gambaran Umum aplikasi saat pendaftaran selesai. Rekam ID Direktori (penyewa) dan ID Aplikasi (klien) yang akan digunakan dalam langkah-langkah selanjutnya.

Menambahkan rahasia klien

Rahasia klien adalah nilai string yang dapat digunakan aplikasi Anda untuk identitas itu sendiri, dan terkadang disebut sebagai kata sandi aplikasi. Aplikasi web menggunakan rahasia klien untuk membuktikan identitasnya saat meminta token.

Ikuti langkah-langkah ini untuk mengonfigurasi rahasia klien:

1. Dari panel Gambaran Umum, di bawah Kelola, pilih Sertifikat & rahasia>Rahasia>klien Rahasia klien baru.

2. Tambahkan deskripsi untuk rahasia klien Anda, misalnya Rahasia klien saya.

3. Pilih kedaluwarsa untuk rahasia atau tentukan masa pakai kustom.

   • Masa pakai rahasia klien dibatasi hingga dua tahun (24 bulan) atau kurang. Anda tidak dapat menentukan masa pakai kustom lebih dari 24 bulan.
   • Microsoft menyarankan agar Anda menetapkan nilai kedaluwarsa kurang dari 12 bulan.

4. Pilih Tambahkan.

5. Pastikan untuk merekam Nilai rahasia klien. Nilai rahasia ini tidak pernah ditampilkan lagi setelah Anda meninggalkan halaman ini.

Untuk informasi selengkapnya tentang cara menyimpan rahasia klien Anda dengan aman, lihat Praktik terbaik untuk manajemen rahasia di Key Vault.

Menambahkan izin untuk mengakses API web Anda

Dengan menentukan cakupan API web, aplikasi web dapat memperoleh token akses yang berisi cakupan yang disediakan oleh platform identitas Microsoft. Dalam kode, API web kemudian dapat menyediakan akses berbasis izin ke sumber dayanya berdasarkan cakupan yang ditemukan dalam token akses.

Ikuti langkah-langkah ini untuk mengonfigurasi izin klien ke API web:

1. Dari panel Gambaran Umum aplikasi Anda, di bagian Kelola, pilih Izin>API Tambahkan API izin>yang digunakan organisasi saya.
2. Pilih NewWebAPI1 atau API yang ingin Anda tambahkan izinnya.
3. Di bawah Pilih izin, centang kotak di samping Prakiraan.Baca. Anda mungkin perlu memperluas daftar Izin . Ini memilih izin yang harus dimiliki aplikasi klien atas nama pengguna yang masuk.
4. Pilih Tambahkan izin untuk menyelesaikan proses.

Setelah menambahkan izin ini ke API, Anda akan melihat izin yang dipilih di bawah Izin yang dikonfigurasi.

Anda mungkin juga melihat izin User.Read untuk Microsoft Graph API. Izin ini ditambahkan secara otomatis saat Anda mendaftarkan aplikasi.

Menguji API web

Untuk memastikan API Anda beroperasi dan siap menangani permintaan, ikuti langkah-langkah berikut:

1. Kloning repositori ms-identity-docs-code-dotnet.

   git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
   

2. Navigasi ke ms-identity-docs-code-dotnet/web-api dan buka appsettings.json, ganti {APPLICATION_CLIENT_ID} dan {DIRECTORY_TENANT_ID} dengan nilai berikut:

   • {APPLICATION_CLIENT_ID}adalah ID Aplikasi API web (klien) di panel Gambaran Umum aplikasi.
   • {DIRECTORY_TENANT_ID}adalah ID Direktori API web (penyewa) di panel Gambaran Umum aplikasi.

3. Jalankan perintah berikut untuk memulai aplikasi:

   dotnet run
   

4. Output yang mirip dengan berikut ini akan muncul. Rekam nomor port di https://localhost:{port} URL.

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: https://localhost:{port}
   ...
   

Menguji API web

Untuk memastikan API Anda beroperasi dan siap menangani permintaan, ikuti langkah-langkah berikut:

1. Navigasikan ke API web yang dibuat di Tutorial: Buat proyek ASP.NET Core dan konfigurasikan API, misalnya NewWebAPILocal, dan buka folder.

2. Buka jendela terminal baru dan navigasikan ke folder tempat proyek API web berada.

   .NET 6.0

   1. Jalankan perintah berikut untuk memulai aplikasi:

      dotnet run
      

   .NET 7.0

   1. Buka terminal baru dan jalankan perintah berikut untuk memulai aplikasi di https profil:

      dotnet run -launch-profile https`
      

3. Output yang mirip dengan berikut ini akan muncul. Rekam nomor port di https://localhost:{port} URL.

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: https://localhost:{port}
   ...
   

Mengonfigurasi permintaan resmi ke API web di Insomnia

Untuk mendapatkan token akses untuk permintaan API Anda, ikuti langkah-langkah berikut:

1. Luncurkan aplikasi Insomnia .

2. Pilih Permintaan HTTP Baru, atau Anda dapat menggunakan Ctrl + N untuk membuat Permintaan HTTP baru.

3. Di modal Permintaan Baru, pilih metode GET dari menu dropdown.

4. Untuk URL permintaan, masukkan URL titik akhir yang diekspos oleh API web, https://localhost:{port}/weatherforecast.

5. Dari menu dropdown Auth , pilih OAuth 2.0. Ini menampilkan formulir OAuth 2.0 .

6. Masukkan nilai berikut dalam formulir OAuth 2.0 :

   Pengaturan	Nilai
   JENIS GRANT	Pilih Kode Otorisasi
   URL OTORISASI	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize Ganti {tenantId} dengan ID Direktori (penyewa)
   URL TOKEN AKSES	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token Ganti {tenantId} dengan ID Direktori (penyewa)
   ID KLIEN	Nilai ID Aplikasi (klien) pendaftaran aplikasi web Anda
   RAHASIA KLIEN	Nilai rahasia klien pendaftaran aplikasi web Anda
   URL PENGALIHAN	Masukkan http://localhost, yang mengatur URL PENGALIHAN ke URI Pengalihan yang terdaftar dengan ID Microsoft Entra.
   Cakupan Opsi>Tingkat Lanjut	api://{application_client_id}/Forecast.Read Navigasi ke pendaftaran aplikasi web Anda, di bawah Kelola, pilih Izin API, lalu pilih Prakiraan.Baca Salin nilai di kotak teks, yang berisi nilai Cakupan

Mendapatkan token akses dan mengirim permintaan ke API web

1. Setelah nilai ini dimasukkan, pilih Ambil Token di akhir formulir. Ini meluncurkan jendela browser Insomnia tempat Anda mengautentikasi dengan kredensial pengguna Anda. Pastikan untuk mengizinkan pop up dari aplikasi Insomnia di browser.
2. Setelah mengautentikasi, pilih Kirim untuk mengirim permintaan ke titik akhir API web yang dilindungi.

Dengan token akses yang valid yang disertakan dalam permintaan, respons yang diharapkan adalah 200 OK dengan output yang mirip dengan:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Konten terkait

Untuk informasi selengkapnya tentang alur kode otorisasi OAuth 2.0 dan jenis aplikasi, lihat:

• Platform identitas Microsoft dan alur kode otorisasi OAuth 2.0
• Jenis aplikasi untuk platform identitas Microsoft