Bagikan melalui

Memanggil API dalam contoh aplikasi daemon .NET

  • Artikel

Panduan ini menggunakan contoh aplikasi daemon .NET untuk menunjukkan kepada Anda bagaimana aplikasi daemon memperoleh token untuk memanggil API web yang dilindungi. Microsoft Entra melindungi API web.

Aplikasi daemon memperoleh token atas nama dirinya sendiri (bukan atas nama pengguna). Pengguna tidak dapat berinteraksi dengan aplikasi daemon karena memerlukan identitasnya sendiri. Jenis aplikasi ini meminta token akses dengan menggunakan identitas aplikasinya dan menyajikan ID aplikasi, kredensial (kata sandi atau sertifikat), dan URI ID aplikasi ke ID Eksternal Microsoft Entra.

Prasyarat

Mendaftarkan aplikasi daemon dan API web

Dalam langkah ini, Anda membuat daemon 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 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.

Mendaftarkan aplikasi daemon

Untuk mengaktifkan aplikasi Anda untuk memasukkan pengguna dengan Microsoft Entra, MICROSOFT Entra External ID harus mengetahui aplikasi yang Anda buat. Pendaftaran aplikasi membangun hubungan kepercayaan antara aplikasi dan Microsoft Entra. Saat Anda mendaftarkan aplikasi, ID Eksternal menghasilkan pengidentifikasi unik yang dikenal sebagai ID Aplikasi (klien), nilai yang digunakan untuk mengidentifikasi aplikasi Anda saat membuat permintaan autentikasi.

Langkah-langkah berikut menunjukkan cara mendaftarkan aplikasi Anda di pusat admin Microsoft Entra:

  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;

    1. Masukkan Nama aplikasi yang bermakna yang ditampilkan kepada pengguna aplikasi, misalnya ciam-client-app.
    2. Di bawah Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini.

  6. Pilih Daftarkan.

  7. Panel Gambaran Umum aplikasi ditampilkan setelah pendaftaran berhasil. Rekam ID Aplikasi (klien) yang akan digunakan dalam kode sumber aplikasi Anda.

Membuat rahasia klien

Buat rahasia klien untuk aplikasi terdaftar. Aplikasi ini menggunakan rahasia klien untuk membuktikan identitasnya ketika meminta token.

  1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-client-app) untuk membuka halaman Gambaran Umumnya.
  2. Di bagian Kelola, pilih Sertifikat & rahasia.
  3. Pilih Rahasia klien baru.
  4. Dalam kotak Deskripsi , masukkan deskripsi untuk rahasia klien (misalnya, rahasia klien aplikasi ciam).
  5. Di bawah Kedaluwarsa, pilih durasi yang rahasianya valid (sesuai aturan keamanan organisasi Anda), lalu pilih Tambahkan.
  6. Catat Nilai rahasia. Anda akan menggunakan nilai ini untuk konfigurasi pada langkah selanjutnya. Nilai rahasia tidak akan ditampilkan lagi, dan tidak dapat diambil dengan cara apa pun, setelah Anda menavigasi jauh dari Sertifikat dan rahasia. Pastikan Anda merekamnya.

Memberikan izin API ke aplikasi daemon

  1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat, seperti ciam-client-app.

  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 aplikasi . Kami memilih opsi ini sebagai aplikasi masuk sebagai dirinya sendiri, bukan pengguna.

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

  8. Pilih tombol Tambahkan izin akses.

  9. Pada titik ini, Anda telah menetapkan izin dengan benar. Namun, karena aplikasi daemon tidak mengizinkan pengguna untuk berinteraksi dengannya, pengguna 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 izin.

Mengkloning atau mengunduh sampel aplikasi daemon 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-dotnet-tutorial.git

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

Mengonfigurasi contoh aplikasi daemon dan API

Untuk menggunakan pendaftaran aplikasi Anda di sampel aplikasi web klien:

  1. Di editor kode Anda, buka file ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json .

  2. Temukan tempat penampung:

    • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) dari aplikasi daemon 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 daemon 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 file ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI/appsettings.json .

  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 daemon dan API

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

    cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListAPI
dotnet run

  2. Jalankan klien daemon dengan menggunakan perintah berikut:

    cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient
dotnet run

Jika aplikasi daemon dan API web Anda berhasil dijalankan, Anda akan melihat sesuatu yang mirip dengan array JSON berikut di jendela konsol Anda:

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server

Cara kerjanya

Aplikasi daemon menggunakan pemberian kredensial klien OAuth2.0 untuk memperoleh token akses untuk dirinya sendiri dan bukan untuk pengguna. Token akses yang diminta aplikasi berisi izin yang diwakili sebagai peran. Alur kredensial klien menggunakan sekumpulan izin ini sebagai pengganti cakupan pengguna untuk token aplikasi. Anda mengekspos izin aplikasi ini di API web sebelumnya, lalu memberikannya ke aplikasi daemon. Aplikasi daemon dalam artikel ini menggunakan Microsoft Authentication Library untuk .NET untuk menyederhanakan proses memperoleh token.

Di sisi API, API web harus memverifikasi bahwa token akses memiliki izin yang diperlukan (izin aplikasi). API web menolak token akses yang tidak memiliki izin yang diperlukan.

Konten terkait