Tutorial: Membangun daemon multi-penyewa yang menggunakan platform identitas Microsoft

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 memulai.

Prasyarat

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 dipanggil, pengontrol menarik daftar pengguna di penyewa Azure Active Directory (Microsoft Azure Active Directory) 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 multi-penyewa untuk pelanggan bisnis Microsoft, aplikasi harus menyediakan cara bagi pelanggan untuk "mendaftar" atau "menyambungkan" 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 shows UserSync App with three local items connecting to Azure, with Start dot Auth acquiring a token interactively to connect to Azure A D, AccountController getting admin consent to connect to Azure A D, and SyncController reading user to connect to 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 Azure Active Directory, 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 Azure Active Directory Anda dan konfigurasikan kode aplikasi contoh 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 Azure Active Directory

  1. Masuk ke portal Azure.
  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih penyewa aplikasinya ingin Anda daftarkan.

Daftarkan aplikasi klien (dotnet-web-daemon-v2)

  1. Cari dan pilih Azure Active Directory.

  2. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.

  3. Masukkan Nama untuk aplikasi Anda, misalnya dotnet-web-daemon-v2. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

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

  5. 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.

  6. Pilih Daftar untuk membuat aplikasi.

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

  8. Di bagian Kelola, pilih Autentikasi.

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

  10. 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.

  11. Pilih Simpan.

  12. Di bagian Kelola, pilih Sertifikat & rahasia.

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

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

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

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

  17. Di bawah Kelola, pilih Izin API>Tambahkan izin.

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

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

  20. Pilih Tambahkan izin.

Mengonfigurasi sampel untuk menggunakan penyewa Azure Active Directory 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 dari aplikasi dotnet-web-daemon-v2 yang disalin dari portal Microsoft Azure.
  3. Temukan kunci aplikasi ida:ClientSecret. Ganti nilai yang ada dengan kunci yang Anda simpan selama pembuatan aplikasi dotnet-web-daemon-v2 di portal Microsoft Azure.

Jalankan sampel

Hapus solusi, bangun kembali solusi, jalankan aplikasi UserSync, lalu masuk sebagai administrator di penyewa Azure Active Directory Anda. Jika Anda tidak memiliki penyewa Azure Active Directory untuk pengujian, Anda dapat mengikuti petunjuk 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.

User consent

Aplikasi ini kemudian mencoba menyinkronkan daftar pengguna dari penyewa Azure Active Directory 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.

Admin consent

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#ASP.NET Web Application (.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 ASP.NET OWIN middleware NuGet:
    • 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 Azure Active Directory untuk dotnet-web-daemon-v2

  1. Kembali ke portal Microsoft Azure.
  2. Di panel kiri, pilih layanan Azure Active Directory, lalu pilih Pendaftaran aplikasi.
  3. Pilih aplikasi dotnet-web-daemon-v2.
  4. 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.
  5. Dari menu Branding, perbarui URL Beranda ke alamat layanan Anda. Misalnya, gunakan https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  6. Simpan konfigurasi.
  7. 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

Saat tidak lagi diperlukan, hapus objek aplikasi yang Anda buat di langkah Daftarkan aplikasi Anda. 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 jelajahi masalah yang ada untuk melihat apakah seseorang telah mengajukan pertanyaan Anda sebelumnya. Pastikan pertanyaan atau komentar Anda diberi tag dengan "azure-ad-adal-deprecation", "azure-ad-msal", dan "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: