Bagikan melalui

Tutorial: Membangun daemon multipenyewa yang menggunakan platform identitas Microsoft

  • Artikel

Dalam tutorial ini, Anda mengunduh dan menjalankan aplikasi web daemon ASP.NET yang menunjukkan penggunaan hibah info masuk klien OAuth 2.0 untuk mendapatkan token akses untuk memanggil Microsoft Graph API.

Dalam tutorial ini:

  • Integrasikan aplikasi daemon dengan platform identitas Microsoft
  • Berikan izin aplikasi langsung ke aplikasi oleh admin
  • Dapatkan token akses untuk memanggil Microsoft Graph API
  • Panggil Microsoft Graph API.

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

Prasyarat

  • Visual Studio 2017 atau 2019.
  • Penyewa Microsoft Entra. Untuk informasi selengkapnya, lihat Cara mendapatkan penyewa Microsoft Entra.
  • Satu atau beberapa akun pengguna di penyewa Anda. Contoh ini tidak akan berfungsi dengan akun Microsoft. Jika Anda masuk dengan akun Microsoft dan belum pernah membuat akun pengguna di direktori Anda, lakukan sekarang.

Skenario

Aplikasi ini dibangun sebagai aplikasi MVC ASP.NET baru. Aplikasi ini menggunakan middleware OWIN OpenID Connect untuk memasukkan pengguna.

Komponen "daemon" dalam sampel ini adalah pengontrol API, SyncController.cs. Ketika pengontrol dipanggil, pengontrol menarik daftar pengguna di penyewa Microsoft Entra pelanggan dari Microsoft Graph. SyncController.cs dipicu oleh panggilan AJAX di aplikasi web. Aplikasi ini menggunakan Pustaka Autentikasi Microsoft (MSAL) untuk .NET guna memperoleh token akses untuk Microsoft Graph.

Karena aplikasi ini adalah aplikasi multipenyewa untuk pelanggan bisnis Microsoft, aplikasi ini harus menyediakan cara bagi pelanggan untuk "mendaftar" atau "menghubungkan" aplikasi ke data perusahaan mereka. Selama alur koneksi, Administrator Global terlebih dahulu memberikan izin aplikasi langsung ke aplikasi sehingga dapat mengakses data perusahaan dengan cara yang tidak interaktif, tanpa adanya pengguna yang masuk. Sebagian besar logika dalam sampel ini menunjukkan cara mencapai alur koneksi ini menggunakan titik akhir persetujuan admin platform identitas.

Diagram memperlihatkan Aplikasi UserSync dengan tiga item lokal yang tersambung ke Azure, dengan Mulai titik Auth memperoleh token secara interaktif untuk menyambungkan ke MICROSOFT Entra ID, AccountController mendapatkan persetujuan admin untuk menyambungkan ke ID Microsoft Entra, dan pengguna baca SyncController untuk menyambungkan ke Microsoft Graph.

Untuk informasi selengkapnya tentang konsep yang digunakan dalam sampel ini, baca dokumentasi protokol info masuk klien untuk platform identitas.

Mengkloning atau mengunduh repositori ini

Dari shell atau baris perintah, masukkan perintah ini:

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

Atau unduh sampel dalam file zip.

Mendaftarkan aplikasi Anda

Sampel ini memiliki satu proyek. Untuk mendaftarkan aplikasi dengan penyewa Microsoft Entra, Anda dapat:

Jika Anda ingin menggunakan otomatisasi:

  1. Pada Windows, jalankan PowerShell dan buka akar direktori yang dikloning.

  2. Jalankan perintah ini:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Jalankan skrip untuk membuat aplikasi Microsoft Entra Anda dan konfigurasikan kode aplikasi sampel yang sesuai:

    .\AppCreationScripts\Configure.ps1

    Cara lain menjalankan skrip dijelaskan dalam Skrip pembuatan aplikasi.

  4. Buka solusi Visual Studio dan pilih Mulai untuk menjalankan kode.

Jika Anda tidak ingin menggunakan otomatisasi, gunakan langkah-langkah di bagian berikut.

Pilih penyewa

Tip

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

  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 Anda, contohnya dotnet-web-daemon-v2. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  6. Di bagian Jenis akun yang didukung, pilih Akun di direktori organisasi apa pun.

  7. Di bagian URI Pengalihan (opsional), pilih Web dalam kotak kombo dan masukkan https://localhost:44316/ dan https://localhost:44316/Account/GrantPermissions sebagai URI Pengalihan.

    Jika ada lebih dari dua URI pengalihan, Anda harus menambahkannya dari tab Autentikasi nanti, setelah aplikasi berhasil dibuat.

  8. Pilih Daftar untuk membuat aplikasi.

  9. Pada halaman Ringkasan aplikasi, temukan nilai ID Aplikasi (klien) dan rekam untuk digunakan nanti. Anda akan membutuhkannya untuk mengonfigurasi file konfigurasi Visual Studio untuk proyek ini.

  10. Di bagian Kelola, pilih Autentikasi.

  11. Atur URL keluar saluran depan ke https://localhost:44316/Account/EndSession.

  12. Di bagian Hibah implisit dan alur hibrid, pilih Token akses dan token ID. Sampel ini mengharuskan alur hibah implisit diaktifkan untuk memasukkan pengguna dan memanggil API.

  13. Pilih Simpan.

  14. Di bagian Kelola, pilih Sertifikat & rahasia.

  15. Di bagian Rahasia klien, pilih Rahasia klien baru.

  16. Masukkan deskripsi kunci (misalnya, rahasia aplikasi).

  17. Pilih durasi kunci baik Dalam 1 tahun, Dalam 2 tahun, atau Tidak Pernah Kedaluwarsa.

  18. Pilih Tambahkan. Catat nilai kunci di lokasi yang aman. Anda akan memerlukan kunci ini nanti untuk mengonfigurasi proyek di Visual Studio.

  19. Di bagian Kelola, pilih Izin API>Tambahkan izin.

  20. Di bagian Microsoft API yang umum digunakan, pilih Microsoft Graph.

  21. Di bagian Izin aplikasi, pastikan bahwa izin yang tepat dipilih: User.Read.All.

  22. Pilih Tambahkan izin.

Mengonfigurasi sampel untuk menggunakan penyewa Anda

Dalam langkah-langkah berikut, ClientID sama dengan "ID aplikasi" atau AppId.

Buka solusi di Visual Studio untuk mengonfigurasi proyek.

Mengonfigurasi proyek klien

Jika Anda menggunakan skrip penyiapan, perubahan berikut akan diterapkan untuk Anda.

  1. Buka file UserSync\Web.Config.
  2. Temukan kunci aplikasi ida:ClientId. Ganti nilai yang ada dengan ID aplikasi aplikasi dotnet-web-daemon-v2 yang sebelumnya direkam.
  3. Temukan kunci aplikasi ida:ClientSecret. Ganti nilai yang ada dengan kunci yang Anda simpan selama pembuatan aplikasi dotnet-web-daemon-v2 .

Jalankan sampel

Bersihkan solusi, bangun kembali solusi, jalankan aplikasi UserSync, lalu masuk sebagai administrator di penyewa Microsoft Entra Anda. Jika Anda tidak memiliki penyewa Microsoft Entra untuk pengujian, Anda dapat mengikuti instruksi ini untuk mendapatkannya.

Saat Anda masuk, aplikasi ini terlebih dahulu meminta izin kepada Anda untuk masuk dan membaca profil pengguna Anda. Persetujuan ini memungkinkan aplikasi memastikan bahwa Anda adalah pengguna bisnis.

Persetujuan pengguna

Aplikasi kemudian mencoba menyinkronkan daftar pengguna dari penyewa Microsoft Entra Anda, melalui Microsoft Graph. Jika tidak dapat melakukannya, aplikasi meminta Anda (administrator penyewa) untuk menghubungkan penyewa ke aplikasi.

Kemudian, aplikasi meminta izin untuk membaca daftar pengguna di penyewa Anda.

Persetujuan admin

Setelah memberikan izin, Anda akan keluar dari aplikasi. Upaya keluar ini memastikan bahwa token akses yang ada untuk Microsoft Graph dihapus dari cache token. Saat Anda masuk lagi, token baru yang diperoleh akan memiliki izin yang diperlukan untuk melakukan panggilan ke Microsoft Graph.

Saat Anda memberikan izin, aplikasi kemudian dapat meminta kueri untuk pengguna kapan saja. Anda dapat memverifikasinya dengan memilih tombol Sinkronkan Pengguna dan me-refresh daftar pengguna. Coba tambahkan atau hapus pengguna dan sinkronkan ulang daftar. (Tetapi perhatikan bahwa aplikasi hanya menyinkronkan halaman pertama pengguna.)

Tentang kode

Kode yang relevan untuk sampel ini ada dalam file berikut:

  • App_Start\Startup.Auth.cs, Controllers\AccountController.cs: Proses masuk awal. Secara khusus, tindakan pada pengontrol memiliki atribut Otorisasi, yang memaksa pengguna untuk masuk. Aplikasi ini menggunakan alur kode otorisasi untuk memasukkan pengguna.
  • Controllers\SyncController.cs: Menyinkronkan daftar pengguna ke penyimpanan dalam memori lokal.
  • Controllers\UserController.cs: Menampilkan daftar pengguna dari penyimpanan dalam memori lokal.
  • Controllers\AccountController.cs: Memperoleh izin dari admin penyewa dengan menggunakan titik akhir persetujuan admin.

Membuat ulang sampel aplikasi

  1. Di Visual Studio, buat proyek Visual C# Aplikasi Web ASP.NET (.NET Framework) baru.
  2. Pada layar berikutnya, pilih templat proyek MVC. Tambahkan juga referensi folder dan inti untuk Web API, karena Anda akan menambahkan pengontrol API web nanti. Biarkan mode autentikasi yang dipilih proyek sebagai default: Tidak Ada Autentikasi.
  3. Pilih proyek di jendela Penjelajah Solusi dan pilih tombol F4.
  4. Di properti proyek, atur SSL Diaktifkan ke True. Perhatikan informasi dalam URL SSL. Anda akan membutuhkannya saat mengonfigurasi pendaftaran aplikasi ini di portal Microsoft Azure.
  5. Tambahkan paket NuGet middleware OWIN ASP.NET berikut:
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. Di folder App_Start:
    1. Buat kelas bernama Startup.Auth.cs.
    2. Hapus .App_Start dari nama namespace.
    3. Ganti kode untuk kelas Startup dengan kode dari file yang sama dari aplikasi contoh. Pastikan untuk mengambil seluruh definisi kelas. Definisi berubah dari Startup kelas publik ke Startup kelas parsial publik.
  7. Di Startup.Auth.cs, atasi referensi yang hilang dengan menambahkan menggunakan pernyataan seperti yang disarankan oleh Visual Studio IntelliSense.
  8. Klik kanan proyek, pilih Tambahkan, lalu pilih Kelas.
  9. Di kotak pencarian, masukkan OWIN. Kelas Startup OWIN akan muncul sebagai pilihan. Pilih, dan beri nama kelas Startup.cs.
  10. Di Startup.cs, ganti kode untuk kelas Startup dengan kode dari file yang sama dari aplikasi contoh. Sekali lagi, perhatikan bahwa definisi berubah dari Startup kelas publik ke Startup kelas parsial publik.
  11. Di folder Model, tambahkan kelas baru yang disebut MsGraphUser.cs. Ganti implementasi dengan konten file dengan nama yang sama dari sampel.
  12. Tambahkan instans Pengontrol MVC 5 - Kosong baru yang disebut AccountController. Ganti implementasi dengan konten file dengan nama yang sama dari sampel.
  13. Tambahkan Pengontrol MVC 5 - Kosong baru yang disebut UserController. Ganti implementasi dengan konten file dengan nama yang sama dari sampel.
  14. Tambahkan Pengontrol Web API 2 - Kosong baru yang disebut SyncController. Ganti implementasi dengan konten file dengan nama yang sama dari sampel.
  15. Untuk antarmuka pengguna, di folder Tampilan\Akun, tambahkan tiga instans Tampilan Kosong (tanpa model) bernama GrantPermissions, Index, dan UserMismatch. Tambah dan satu instans bernama Index di folder Tampilan\Pengguna. Ganti implementasi dengan konten file dengan nama yang sama dari sampel.
  16. Perbarui Shared_Layout.cshtml dan Home\Index.cshtml untuk menautkan berbagai tampilan dengan benar.

Menyebarkan sampel ke Azure

Proyek ini memiliki aplikasi web dan proyek API web. Untuk menyebarkannya ke situs web Azure, ikuti langkah-langkah berikut untuk masing-masing situs web:

  1. Membuat situs web Azure.
  2. Publikasikan API aplikasi web dan web ke situs web.
  3. Perbarui klien untuk memanggil situs web sebagai ganti Ekspres IIS.

Buat dan terbitkan dotnet-web-daemon-v2 ke situs web Azure

  1. Masuk ke portal Azure.
  2. Di sudut kiri atas, pilih Buat sumber daya.
  3. Pilih Web>Aplikasi Web, lalu beri nama situs web Anda. Misalnya, beri nama dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Pilih informasi untuk Langganan, Grup sumber daya, dan Paket layanan aplikasi dan lokasi. OS adalah Windows, dan Publikasi adalah Kode.
  5. Pilih Buat dan tunggu hingga layanan aplikasi dibuat.
  6. Saat Anda mendapatkan pemberitahuan Penyebaran berhasil, pilih Buka sumber daya untuk masuk ke layanan aplikasi yang baru dibuat.
  7. Setelah situs web dibuat, temukan di Dasbor dan pilih untuk membuka layar Ringkasan layanan aplikasi.
  8. Dari tab Ringkasan layanan aplikasi, unduh profil penerbitan dengan memilih tautan Dapatkan profil penerbitan dan menyimpannya. Anda dapat menggunakan mekanisme penyebaran lainnya, seperti menyebarkan dari kontrol sumber.
  9. Beralih ke Visual Studio lalu:
    1. Buka proyek dotnet-web-daemon-v2.
    2. Klik kanan proyek di Penjelajah Solusi, lalu pilih Terbitkan.
    3. Pilih Impor Profil di bilah bawah, dan impor profil penerbitan yang Anda unduh sebelumnya.
  10. Pilih Konfigurasikan.
  11. Pada tab Koneksi, perbarui URL tujuan agar menggunakan "https". Misalnya, gunakan https://dotnet-web-daemon-v2-contoso.azurewebsites.net. Pilih Selanjutnya.
  12. Pada tab Pengaturan, pastikan Aktifkan Autentikasi Organisasi dikosongkan.
  13. Pilih Simpan. Pilih Terbitkan di layar utama.

Visual Studio akan menerbitkan proyek dan secara otomatis membuka browser ke URL proyek. Jika Anda melihat halaman web default proyek, artinya publikasi berhasil.

Memperbarui pendaftaran aplikasi penyewa Microsoft Entra untuk dotnet-web-daemon-v2

  1. Kembali ke pusat admin Microsoft Entra, lalu pilih aplikasi dotnet-web-daemon-v2 di Pendaftaran aplikasi.
  2. Pada halaman Autentikasi untuk aplikasi Anda, perbarui bidang URL keluar saluran depan dengan alamat layanan Anda. Misalnya, gunakan https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  3. Dari menu Branding, perbarui URL Beranda ke alamat layanan Anda. Misalnya, gunakan https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Simpan konfigurasi.
  5. Tambahkan URL yang sama dalam daftar nilai menu Autentikasi>URI Pengalihan. Jika Anda memiliki beberapa URL pengalihan, pastikan ada entri baru yang menggunakan URI layanan aplikasi untuk setiap URL pengalihan.

Membersihkan sumber daya

Jika tidak diperlukan lagi, hapus objek aplikasi yang dibuat pada langkah Mendaftarkan aplikasi. Untuk menghapus aplikasi, ikuti petunjuk di Menghapus aplikasi yang ditulis oleh Anda atau organisasi Anda.

Dapatkan bantuan

Gunakan Microsoft Q&A untuk mendapatkan dukungan dari komunitas. Ajukan pertanyaan Anda di Microsoft Q&A terlebih dahulu, dan telusuri masalah yang sudah ada untuk melihat apakah seseorang telah mengajukan pertanyaan Anda sebelumnya. Pastikan pertanyaan atau komentar Anda ditandai dengan azure-ad-adal-deprecation, , azure-ad-msaldan dotnet-standard."

Jika Anda menemukan bug dalam sampel, harap laporan masalah pada Masalah GitHub.

Jika Anda menemukan bug di MSAL.NET, harap laporkan masalah pada Masalah MSAL.NET GitHub.

Untuk memberikan rekomendasi, buka halaman Voice Pengguna.

Langkah berikutnya

Pelajari selengkapnya tentang cara membangun aplikasi daemon yang menggunakan platform identitas Microsoft untuk mengakses API web yang dilindungi:

Skenario: Aplikasi daemon yang memanggil API web