Bagikan melalui

Panduan Mulai Cepat: Memanggil API web ASP.NET yang dilindungi oleh platform identitas Microsoft

  • Artikel

Mulai cepat berikut menggunakan, menggunakan sampel kode yang menunjukkan cara melindungi API web ASP.NET dengan membatasi akses ke sumber dayanya ke akun yang diotorisasi saja. Sampel mendukung otorisasi akun dan akun Microsoft pribadi di organisasi Microsoft Entra mana pun.

Artikel ini juga menggunakan aplikasi Windows Presentation Foundation (WPF) untuk menunjukkan cara meminta token akses untuk mengakses API web.

Prasyarat

Klon atau unduh sampel

Sampel kode dapat diperoleh dengan dua cara:

  • Mengkloning dari shell atau baris perintah Anda:

    git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

  • Unduh sebagai file ZIP.

Tip

Untuk menghindari kesalahan yang disebabkan oleh keterbatasan panjang jalur di Windows, kami sarankan mengekstrak arsip atau mengkloning repositori ke direktori di dekat akar drive Anda.

Daftarkan API web (TodoListService)

Tip

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

Daftarkan API web di Pendaftaran aplikasi di portal Microsoft Azure.

  1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.

  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 dan pilih Pendaftaran baru.

  4. Masukkan Nama untuk aplikasi Anda, contohnya AppModelv2-NativeClient-DotNet-TodoListService. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  5. Untuk Tipe akun yang didukung, pilih Akun di direktori organisasi apa pun.

  6. Pilih Daftar untuk membuat aplikasi.

  7. Pada halaman Gambaran Umum aplikasi, cari nilai ID Aplikasi (klien), lalu catat untuk digunakan nanti. Anda akan memerlukannya untuk mengonfigurasi file konfigurasi Visual Studio untuk proyek ini (yaitu, ClientId dalam file TodoListService\appsettings.json ).

  8. Di bagian Kelola, pilih Ekspos API>Tambahkan cakupan. Terima URI ID Aplikasi yang diusulkan (api://{clientId}) dengan memilih Simpan dan lanjutkan, lalu masukkan informasi berikut:

    1. Untuk nama Cakupan, masukkan access_as_user.
    2. Untuk Siapa yang dapat menyetujui, pastikan bahwa opsi Admin dan pengguna dipilih.
    3. Dalam kotak Nama tampilan persetujuan admin, masukkan Access TodoListService as a user.
    4. Dalam kotak Deskripsi persetujuan admin, masukkan Accesses the TodoListService web API as a user.
    5. Dalam kotak Nama tampilan persetujuan pengguna, masukkan Access TodoListService as a user.
    6. Dalam kotak Deskripsi persetujuan pengguna, masukkan Accesses the TodoListService web API as a user.
    7. Untuk Status, tetap Aktifkan.

  9. Pilih Tambahkan cakupan.

Mengonfigurasi proyek layanan

Konfigurasikan proyek layanan agar sesuai dengan API web yang terdaftar.

  1. Buka solusi di Visual Studio, lalu buka file appsettings.json di bawah akar proyek TodoListService.

  2. Ganti nilai Enter_the_Application_Id_here dengan nilai ID Klien (ID Aplikasi) dari aplikasi yang Anda daftarkan di portal Pendaftaran aplikasi baik di ClientID properti dan Audience .

Menambahkan cakupan baru ke file app.config

Untuk menambahkan cakupan baru ke file app.config TodoListClient, lakukan langkah-langkah berikut:

  1. Di folder akar proyek TodoListClient, buka file app.config.

  2. Tempel ID Aplikasi dari aplikasi yang baru saja Anda daftarkan untuk proyek TodoListService di dalam parameter TodoListServiceScope, menggantikan string {Enter the Application ID of your TodoListService from the app registration portal}.

Catatan

Pastikan ID Aplikasi menggunakan format berikut: api://{TodoListService-Application-ID}/access_as_user (di mana {TodoListService-Application-ID} GUID mewakili ID Aplikasi untuk aplikasi TodoListService Anda).

Mendaftarkan aplikasi web (TodoListClient)

Daftarkan aplikasi TodoListClient di Pendaftaran aplikasi di portal Microsoft Azure, lalu konfigurasikan kode di proyek TodoListClient. Jika klien dan server dianggap sebagai aplikasi yang sama, Anda dapat menggunakan kembali aplikasi yang terdaftar di langkah 2. Gunakan aplikasi yang sama jika Anda ingin pengguna masuk dengan akun pribadi Microsoft.

Mendaftarkan aplikasi

Untuk mendaftarkan aplikasi TodoListClient, ikuti langkah-langkah berikut:

  1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.

  2. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi dan pilih Pendaftaran baru.

  3. Pilih Pendaftaran baru.

  4. Saat halaman Daftarkan aplikasi terbuka, masukkan informasi pendaftaran aplikasi Anda:

    1. Di bagian Nama, masukkan nama aplikasi bermakna yang akan ditampilkan kepada pengguna aplikasi (misalnya, NativeClient-DotNet-TodoListClient).
    2. Untuk Tipe akun yang didukung, pilih Akun di direktori organisasi apa pun.
    3. Pilih Daftar untuk membuat aplikasi.

    Catatan

    Dalam proyek TodoListClient fileapp.config, nilai default ida:Tenant diatur ke common. Nilai yang mungkin adalah:

    • common: Anda dapat masuk dengan menggunakan akun kantor atau sekolah atau akun pribadi Microsoft (karena Anda memilih Akun di direktori organisasi apa pun di langkah sebelumnya).
    • organizations: Anda dapat masuk dengan menggunakan akun kantor atau sekolah.
    • consumers: Anda hanya dapat masuk dengan menggunakan akun pribadi Microsoft.

  5. Pada halaman Gambaran Umum aplikasi, pilih Autentikasi, lalu selesaikan langkah-langkah ini untuk menambahkan platform:

    1. Di bawah Konfigurasi platform,, pilih tombol Tambahkan platform.
    2. Untuk Aplikasi seluler dan desktop, pilih Aplikasi seluler dan desktop.
    3. Untuk Pengalihan URI, pilih kotak centang https://login.microsoftonline.com/common/oauth2/nativeclient.
    4. Pilih Konfigurasikan.

  6. Pilih Izin API, lalu selesaikan langkah-langkah ini untuk menambahkan izin:

    1. Pilih tombol Tambahkan izin.
    2. Pilih tab API Saya.
    3. Dalam daftar API, pilih AppModelv2-NativeClient-DotNet-TodoListService API atau nama yang Anda masukkan untuk API web.
    4. Pilih kotak centang izin access_as_user jika belum dipilih. Gunakan kotak Pencarian jika perlu.
    5. Pilih tombol Tambahkan izin akses.

Konfigurasikan proyek Anda

Konfigurasikan proyek TodoListClient Anda dengan menambahkan ID Aplikasi ke file app.config Anda.

  1. Di portal Pendaftaran aplikasi, pada halaman Gambaran Umum, salin nilai ID Aplikasi (klien).

  2. Dari folder root proyek TodoListClient, buka file app.config, lalu tempelkan nilai ID Aplikasi dalam ida:ClientId parameter.

Jalankan proyek Anda

Mulai kedua proyek tersebut. Untuk pengguna Visual Studio;

  1. Klik kanan pada solusi Visual Studio dan pilih Properti

  2. Di Properti Umum pilih Proyek Startup dan kemudian Beberapa proyek startup.

  3. Untuk kedua proyek, pilih Mulai sebagai tindakan

  4. Pastikan layanan TodoListService dimulai terlebih dahulu dengan memindahkannya ke posisi pertama dalam daftar, menggunakan panah atas.

Masuk untuk menjalankan proyek TodoListClient Anda.

  1. Tekan F5 untuk memulai proyek. Halaman layanan terbuka, serta aplikasi desktop.

  2. Di TodoListClient, di kanan atas, pilih Masuk, kemudian masuk dengan kredensial yang sama yang Anda gunakan untuk mendaftarkan aplikasi Anda, atau masuk sebagai pengguna di direktori yang sama.

    Jika Anda masuk untuk pertama kalinya, Anda mungkin diminta untuk menyetujui API web TodoListService.

    Untuk membantu Anda mengakses API web TodoListService dan memanipulasi daftar Harus Dilakukan, login juga meminta token akses ke cakupan access_as_user.

Pra-otorisasi aplikasi klien Anda

Anda dapat mengizinkan pengguna dari direktori lain mengakses API web Anda dengan melakukan pra-otorisasi aplikasi klien untuk mengakses API web Anda. Anda melakukan ini dengan menambahkan ID Aplikasi dari aplikasi klien ke daftar aplikasi yang telah diotorisasi untuk API web Anda. Dengan menambahkan klien pra-otorisasi, Anda mengizinkan pengguna untuk mengakses API web Anda tanpa harus memberikan persetujuan.

  1. Di portal Pendaftaran aplikasi, buka properti aplikasi TodoListService Anda.
  2. Di bagian Mengekspos API, di bawah Aplikasi klien resmi, pilih Tambahkan aplikasi klien.
  3. Dalam kotak ID Klien, tempelkan ID Aplikasi dari aplikasi TodoListClient.
  4. Di bagian Cakupan resmi, pilih cakupan untuk api://<Application ID>/access_as_user API web.
  5. Pilih Tambahkan aplikasi.

Menjalankan proyek Anda

  1. Tekan F5 untuk menjalankan proyek Anda. Aplikasi TodoListClient Anda terbuka.
  2. Di kanan atas, pilih Masuk, lalu masuk dengan menggunakan akun Microsoft pribadi, seperti akun live.com atau hotmail.com, atau akun kantor atau sekolah.

Opsional: Membatasi akses masuk ke pengguna tertentu

Secara default, akun pribadi apa pun, seperti akun outlook.com atau live.com , atau akun kantor atau sekolah dari organisasi yang terintegrasi dengan ID Microsoft Entra dapat meminta token dan mengakses API web Anda.

Untuk menentukan siapa yang dapat masuk ke aplikasi Anda, dengan mengubah TenantId properti dalam file appsettings.json .

Bantuan dan dukungan

Jika Anda memerlukan bantuan, ingin melaporkan masalah, atau ingin mempelajari opsi dukungan, lihat Bantuan dan dukungan bagi pengembang.

Langkah berikutnya

Pelajari lebih lanjut dengan membangun api web ASP.NET Core yang dilindungi dalam seri tutorial berikut:

Tutorial API web yang dilindungi