Memanggil API web ASP.NET Core dengan cURL

Artikel ini memperlihatkan kepada Anda cara memanggil API web ASP.NET Core yang dilindungi menggunakan URL Klien (cURL). cURL adalah alat baris perintah yang digunakan pengembang untuk mentransfer data ke dan dari server. 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 cURL.

Artikel ini memperlihatkan kepada Anda cara memanggil API web ASP.NET Core yang dilindungi menggunakan URL Klien (cURL). cURL adalah alat baris perintah yang digunakan pengembang untuk mentransfer data ke dan dari server. 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 cURL.

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 cURL di komputer stasiun kerja Anda.
• Persyaratan minimum .NET 6.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 cURL di komputer stasiun kerja Anda.

Mendaftarkan aplikasi dengan platform identitas Microsoft

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. Panel Gambaran Umum aplikasi ditampilkan saat pendaftaran selesai. Rekam ID Direktori (penyewa) dan ID Aplikasi (klien) yang akan digunakan dalam kode sumber aplikasi Anda.

   

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 dicantumkan di panel Mengekspos API .

   

Mendaftarkan aplikasi web

Namun, memiliki API web tidak cukup, karena aplikasi web juga diperlukan untuk mendapatkan token akses untuk mengakses API web yang telah Anda buat.

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.

Setelah pendaftaran selesai, pendaftaran aplikasi ditampilkan di panel Gambaran Umum . 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.

Menambahkan izin aplikasi untuk mengizinkan akses ke API web

Dengan menentukan cakupan API web dalam pendaftaran aplikasi 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 aplikasi web ke API web:

1. Dari panel Gambaran Umum aplikasi web Anda (web-app-that-calls-web-api), di bagian Kelola, pilih Izin>API Tambahkan izin>API 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

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 folder dan buka ./appsettings.json file, ganti {APPLICATION_CLIENT_ID} dan {DIRECTORY_TENANT_ID} dengan:

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

3. Jalankan perintah berikut untuk memulai aplikasi:

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

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

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. Jalankan perintah berikut untuk memulai aplikasi di https profil:

   dotnet run --launch-profile https
   

1. 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}
   ...
   

Meminta kode otorisasi

Alur kode otorisasi dimulai dengan klien mengarahkan pengguna ke titik akhir /authorize. Dalam permintaan ini, klien meminta Forecast.Read izin dari pengguna.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

1. Salin URL, ganti parameter berikut dan tempelkan ke browser Anda:

   • {tenant_id}adalah ID Direktori (penyewa) aplikasi web.
   • {web-app-calls-web-api_application_client_id}adalah ID Aplikasi (klien) di panel Gambaran Umum aplikasi web (web-app-calls-web-api).
   • {web_API_application_client_id}adalah ID Aplikasi (klien) di panel Gambaran Umum API web (NewWebAPI1).

2. Masuk sebagai pengguna di penyewa Microsoft Entra tempat aplikasi terdaftar. Menyetujui permintaan akses apa pun, jika perlu.

3. Browser Anda akan dialihkan ke http://localhost/. Lihat bilah navigasi browser Anda dan salin untuk {authorization_code} digunakan dalam langkah-langkah berikut. URL mengambil bentuk cuplikan berikut:

   http://localhost/?code={authorization_code}
   

Menggunakan kode otorisasi dan cURL untuk mendapatkan token akses

cURL sekarang dapat digunakan untuk meminta token akses dari platform identitas Microsoft.

1. Salin perintah cURL di cuplikan berikut. Ganti nilai dalam tanda kurung dengan parameter berikut ke terminal Anda. Pastikan untuk menghapus tanda kurung:

   curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
   -d 'client_id={web-app-calls-web-api_application_client_id}' \
   -d 'api://{web_API_application_client_id}/Forecast.Read' \
   -d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
   -d 'redirect_uri=http://localhost' \
   -d 'grant_type=authorization_code' \
   -d 'client_secret={client_secret}'
   

   • {tenant_id}adalah ID Direktori (penyewa) aplikasi web.
   • client_id={web-app-calls-web-api_application_client_id}, dan adalah ID Aplikasi (klien) di panel Gambaran Umum aplikasi web (web-app-calls-web-api).session_state={web-app-calls-web-api_application_client_id}
   • api://{web_API_application_client_id}/Forecast.Readadalah ID Aplikasi (klien) di panel Gambaran Umum API web (NewWebAPI1).
   • code={authorization_code} adalah kode otorisasi yang diterima dalam Meminta kode otorisasi. Ini memungkinkan alat cURL untuk meminta token akses.
   • client_secret={client_secret}adalah nilai rahasia klien yang direkam di Tambahkan rahasia klien.

2. Jalankan perintah cURL dan jika dimasukkan dengan benar, Anda akan menerima respons JSON yang mirip dengan output berikut:

   {
      "token_type": "Bearer",
      "scope": "api://{web_API_application_client_id}/Forecast.Read",
      "expires_in": 3600,
      "ext_expires_in": 3600,
      "access_token": "{access_token}"
   }
   

Memanggil API web dengan token akses

Dengan menjalankan perintah cURL sebelumnya, platform identitas Microsoft telah menyediakan token akses. Token yang diperoleh sekarang dapat digunakan sebagai pembawa dalam permintaan HTTP untuk memanggil API web.

1. Untuk memanggil API web, salin perintah cURL berikut, ganti nilai berikut di tanda kurung dan tempelkan ke terminal Anda:

   curl -X GET https://localhost:{port}/weatherforecast -ki \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer {access_token}"
   

   • {access_token} nilai token akses yang direkam dari output JSON di bagian sebelumnya.
   • {port} nomor port dari API web yang direkam saat menjalankan API di terminal. Pastikan nomor portnya https .

2. Dengan token akses yang valid yang disertakan dalam permintaan, respons yang diharapkan adalah HTTP/2 200 dengan output yang mirip dengan output berikut:

   HTTP/2 200
   content-type: application/json; charset=utf-8
   date: Day, DD Month YYYY HH:MM:SS
   server: Kestrel
   [{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]
   

Langkah berikutnya

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