Bagikan melalui

Mengonfigurasi autentikasi dalam contoh aplikasi web yang memanggil API web dengan menggunakan Azure AD B2C

Penting

Berlaku mulai 1 Mei 2025, Azure AD B2C tidak akan lagi tersedia untuk dibeli untuk pelanggan baru. Pelajari lebih lanjut di FAQ kami.

Artikel ini menggunakan sampel ASP.NET aplikasi web yang memanggil API web untuk mengilustrasikan cara menambahkan autentikasi Azure Active Directory B2C (Azure AD B2C) ke aplikasi web Anda.

Penting

Sampel ASP.NET aplikasi web yang dirujuk dalam artikel ini digunakan untuk memanggil API web dengan token pembawa. Untuk aplikasi web yang tidak memanggil API web, lihat Mengonfigurasi autentikasi dalam contoh aplikasi web dengan menggunakan Azure AD B2C.

Gambaran Umum

OpenID Connect (OIDC) adalah protokol autentikasi yang dibangun di OAuth 2.0. Anda dapat menggunakan OIDC untuk memasukkan pengguna ke aplikasi dengan aman. Sampel aplikasi web ini menggunakan Microsoft Identity Web. Microsoft Identity Web adalah sekumpulan pustaka ASP.NET Core yang menyederhanakan penambahan dukungan autentikasi dan otorisasi ke aplikasi web yang dapat memanggil API web yang aman.

Alur masuk melibatkan langkah-langkah berikut:

  1. Pengguna membuka aplikasi web dan memilih Masuk.

  2. Aplikasi memulai permintaan autentikasi dan mengarahkan pengguna ke Azure AD B2C.

  3. Pengguna mendaftar atau masuk dan mengatur ulang kata sandi. Atau, mereka dapat masuk dengan akun sosial.

  4. Setelah pengguna masuk, Azure AD B2C mengembalikan kode otorisasi ke aplikasi.

  5. Aplikasi kemudian melakukan hal berikut:

    sebuah. Ini menukar kode otorisasi ke token ID, token akses, dan token refresh.
    b. Ini membaca klaim token ID, dan mempertahankan cookie otorisasi aplikasi.
    c. Ini menyimpan token refresh dalam cache dalam memori untuk digunakan nanti.

Ringkasan pendaftaran aplikasi

Untuk memungkinkan aplikasi masuk menggunakan Azure AD B2C dan memproses API web, Anda harus mendaftarkan dua aplikasi dalam direktori Azure AD B2C.

  • Pendaftaran aplikasi web memungkinkan aplikasi Anda untuk masuk menggunakan Azure AD B2C. Selama pendaftaran, Anda menentukan URI pengalihan. URI pengalihan adalah titik akhir di mana pengguna diarahkan oleh Azure AD B2C setelah autentikasi mereka dengan Azure AD B2C selesai. Proses pendaftaran aplikasi menghasilkan ID aplikasi, juga disebut ID klien, yang menjadi ID aplikasi Anda. Anda juga membuat rahasia klien, yang digunakan aplikasi Anda untuk memperoleh token dengan aman.

  • Pendaftaran API web memungkinkan aplikasi Anda memproses API web dengan aman. Pendaftaran mencakup cakupanAPI web. Cakupan menyediakan cara untuk mengelola izin ke sumber daya yang dilindungi seperti API web Anda. Anda memberikan izin aplikasi web ke cakupan API web. Ketika token akses diminta, aplikasi menentukan izin yang diinginkan dalam parameter cakupan permintaan.

Arsitektur dan pendaftaran aplikasi diilustrasikan dalam diagram berikut:

Diagram aplikasi web dengan pendaftaran dan token panggilan API web.

Memanggil API web

Setelah autentikasi selesai, pengguna berinteraksi dengan aplikasi, yang memanggil API web yang dilindungi. API web menggunakan autentikasi token pembawa. Token pembawa adalah token akses yang diperoleh aplikasi dari Azure AD B2C. Aplikasi mengirimkan token melalui header otorisasi dalam permintaan HTTPS.

Authorization: Bearer <access token>

Jika cakupan token akses tidak cocok dengan cakupan API web, pustaka autentikasi memperoleh token akses baru dengan cakupan yang benar.

Keluar dari sistem

Alur proses keluar meliputi langkah-langkah berikut:

  1. Pengguna keluar dari akun di aplikasi.
  2. Aplikasi menghapus objek sesinya, dan pustaka autentikasi menghapus cache tokennya.
  3. Aplikasi membawa pengguna ke endpoint sign-out Azure AD B2C untuk mengakhiri sesi Azure AD B2C.
  4. Pengguna dialihkan kembali ke aplikasi.

Prasyarat

Komputer yang berjalan:

Langkah 1: Mengonfigurasi alur pengguna

Saat pengguna mencoba masuk ke aplikasi Anda, aplikasi memulai permintaan autentikasi ke titik akhir otorisasi melalui alur pengguna. Alur pengguna mendefinisikan dan mengontrol pengalaman pengguna. Setelah pengguna menyelesaikan alur pengguna, Azure Active Directory B2C membuat token dan kemudian mengarahkan pengguna kembali ke aplikasi Anda.

Jika Anda belum melakukannya, buat alur pengguna atau kebijakan kustom. Ulangi langkah-langkah tersebut untuk membuat tiga alur pengguna terpisah sebagai berikut:

  • Gabungan alur pengguna daftar dan masuk, seperti susi. Alur pengguna ini juga mendukung pengalaman Lupa kata sandi Anda.
  • Alur Pengeditan Profil pengguna, seperti .
  • Alur pengguna untuk mengatur ulang kata sandi, seperti .

Azure AD B2C menambahkan B2C_1_ ke nama alur pengguna. Misalnya, susi menjadi B2C_1_susi.

Langkah 2: Mendaftarkan aplikasi web

Dalam langkah ini, Anda membuat aplikasi web dan pendaftaran aplikasi API web, dan menentukan cakupan API web Anda.

Langkah 2.1: Daftarkan aplikasi API web

Untuk membuat pendaftaran aplikasi API web (ID Aplikasi: 2), ikuti langkah-langkah berikut:

  1. Masuk ke portal Azure.

  2. Pastikan Anda menggunakan direktori yang berisi Azure AD B2C tenant Anda. Pilih ikon Direktori + langganan di bilah alat portal.

  3. Pada Setelan portal | Direktori + langganan, temukan direktori Azure AD B2C Anda di daftar Nama direktori, lalu pilih Beralih.

  4. Di portal Microsoft Azure, cari dan pilih AAD B2C.

  5. Pilih Pendaftaran aplikasi, lalu pilih Pendaftaran baru.

  6. Untuk Nama, masukkan nama untuk aplikasi (misalnya, my-api1). Biarkan nilai default untuk URI Pengalihan dan Jenis akun yang didukung.

  7. Pilih Daftarkan.

  8. Setelah pendaftaran aplikasi selesai, pilih Ringkasan.

  9. Catat nilai ID Aplikasi (klien) untuk digunakan nanti, saat Anda mengonfigurasi aplikasi web.

    Cuplikan layar menunjukkan cara mendapatkan ID aplikasi A P I web.

Langkah 2.2: Mengonfigurasi cakupan aplikasi API web

  1. Pilih aplikasi my-api1 yang Anda buat (ID Aplikasi: 2) untuk membuka halaman Ringkasannya.

  2. Di bawah Kelola, pilih Ekspos API.

  3. Di samping URI ID Aplikasi, pilih tautan Set. Ganti nilai default (GUID) dengan nama yang unik (misalnya, tasks-api ), kemudian pilih Simpan .

    Ketika aplikasi web Anda meminta token akses untuk API, ia harus menambahkan URI ini sebagai awalan bagi setiap cakupan yang Anda tentukan untuk API.

  4. Di bawah Cakupan yang ditentukan oleh API ini, pilih Tambahkan cakupan.

  5. Untuk membuat ruang lingkup yang menentukan akses baca ke API:

    1. Untuk Nama cakupan, masukkan tasks.read.
    2. Untuk Nama tampilan persetujuan admin, ketikkan Akses baca ke API tugas.
    3. Untuk Deskripsi perizinan admin, masukkan Izinkan akses baca ke API tugas.

  6. Pilih Tambahkan cakupan.

  7. Pilih Tambahkan cakupan, lalu tambahkan cakupan yang menentukan akses tulis ke API:

    1. Untuk Nama cakupan, masukkan tasks.write.
    2. Untuk Nama tampilan perizinan admin, masukkan Hak akses menulis ke API tugas.
    3. Untuk Deskripsi perizinan admin, masukkan Izinkan akses tulis ke API tugas.

  8. Pilih Tambahkan cakupan.

Langkah 2.3: Daftarkan aplikasi web

Untuk membuat pendaftaran aplikasi web, lakukan hal berikut:

  1. Pilih Pendaftaran aplikasi, lalu pilih Pendaftaran baru.

  2. Di bawah Nama, masukkan nama untuk aplikasi (misalnya, webapp1).

  3. Di bawah Jenis akun yang didukung, pilih Akun-akun di penyedia identitas atau direktori organisasi apa pun (untuk mengautentikasi pengguna melalui alur pengguna).

  4. Di bawah URI Pengalihan, pilih Web lalu, dalam kotak URL, masukkan https://localhost:5000/signin-oidc.

  5. Di bagian Izin, pilih kotak centang Berikan persetujuan admin untuk openid dan izin akses offline.

  6. Pilih Daftarkan.

  7. Setelah pendaftaran aplikasi selesai, pilih Ringkasan.

  8. Rekam ID Aplikasi (klien) untuk digunakan nanti, saat Anda mengonfigurasi aplikasi web.

    Cuplikan layar halaman Ringkasan aplikasi web untuk merekam ID aplikasi web Anda.

Langkah 2.4: Membuat rahasia klien aplikasi web

Buat rahasia klien untuk aplikasi web terdaftar. Aplikasi web menggunakan rahasia klien untuk membuktikan identitasnya saat meminta token.

  1. Di bagian Kelola, pilih Sertifikat & rahasia.
  2. Pilih Rahasia klien baru.
  3. Dalam kotak Deskripsi , masukkan deskripsi untuk rahasia klien (misalnya, clientsecret1).
  4. Di bawah Kedaluwarsa, pilih durasi yang rahasianya valid, lalu pilih Tambahkan.
  5. Catat Nilai rahasia. Anda akan menggunakan nilai ini untuk konfigurasi di langkah selanjutnya.

Langkah 2.5: Memberikan izin aplikasi web untuk API web

Untuk memberi izin kepada aplikasi Anda (ID Aplikasi: 1), ikuti langkah-langkah berikut:

  1. Pilih Pendaftaran aplikasi, lalu pilih aplikasi yang Anda buat (ID Aplikasi: 1).

  2. Di bagian Kelola, pilih Izin API.

  3. Di Izin yang dikonfigurasi, pilih Tambahkan izin.

  4. Pilih tab API Saya.

  5. Pilih API (ID Aplikasi: 2) yang aplikasi webnya akan diberi akses. Contohnya, masukkan my-api1.

  6. Di bagian Izin, luaskan tugas, lalu pilih cakupan yang Anda tentukan sebelumnya (misalnya, tasks.read dan tasks.write).

  7. Pilih Tambahkan izin.

  8. Pilih Beri persetujuan admin untuk <nama penyewa Anda>.

  9. Pilih Ya.

  10. Pilih Refresh, kemudian pastikan bahwa Diberikan untuk ... muncul di bawah Status untuk kedua ruang lingkup.

  11. Dari daftar Izin akses yang dikonfigurasi, pilih cakupan Anda, lalu salin nama lengkap cakupan.

    Cuplikan layar panel izin akses yang dikonfigurasi, yang memperlihatkan pemberian izin akses baca.

Langkah 3: Mendapatkan sampel aplikasi web

Unduh file zip, atau jalankan perintah Bash berikut untuk mengkloning aplikasi web sampel dari GitHub.

git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2

Ekstrak file sampel ke folder dengan total panjang jalur 260 karakter atau kurang.

Langkah 4: Mengonfigurasi API web sampel

Di folder sampel, di folder 4-WebApp-your-API/4-2-B2C/TodoListService , buka proyek TodoListService.csproj dengan Visual Studio atau Visual Studio Code.

Di bawah folder akar proyek, buka file appsettings.json. File ini berisi informasi tentang IdP Azure AD B2C Anda. Aplikasi API web menggunakan informasi ini untuk memvalidasi token akses yang diteruskan aplikasi web sebagai token pembawa. Perbarui properti pengaturan aplikasi berikut:

Bagian Kunci Nilai
AzureAdB2C Kasus Bagian pertama dari nama penyewa Azure AD B2C Anda. Contohnya, https://contoso.b2clogin.com.
AzureAdB2C Ruang Lingkup Nama penyewa lengkap penyewa Azure AD B2C Anda. Contohnya, contoso.onmicrosoft.com.
AzureAdB2C ClientId ID aplikasi API web dari langkah 2.1.
AzureAdB2C IDKebijakanDaftarMasukMasuk Alur pengguna, atau kebijakan kustom yang Anda buat di langkah 1.

File konfigurasi akhir Anda akan terlihat seperti file JSON berikut:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

Langkah 4.1: Atur kebijakan izin

API web memverifikasi bahwa pengguna diautentikasi dengan token pembawa, dan token pembawa memiliki cakupan yang diterima yang dikonfigurasi. Jika token pembawa tidak memiliki salah satu cakupan yang diterima ini, API web mengembalikan kode status HTTP 403 (Terlarang) dan menulis ke isi respons pesan yang memberi tahu cakupan mana yang diharapkan dalam token.

Untuk mengonfigurasi cakupan yang diterima, buka Controller/TodoListController.cs kelas, dan atur nama cakupan, tanpa URI lengkap.

[RequiredScope("tasks.read")]

Langkah 4.2: Jalankan contoh aplikasi API web

Untuk mengizinkan aplikasi web memanggil sampel API web, jalankan API web dengan melakukan hal berikut:

  1. Jika Anda diminta untuk melakukannya, pulihkan dependensi.
  2. Bangun dan jalankan proyek.
  3. Setelah proyek dibuat, Visual Studio atau Visual Studio Code memulai API web di browser dengan alamat berikut: https://localhost:44332.

Langkah 5: Mengonfigurasi contoh aplikasi web

Di folder sampel, di bawah 4-WebApp-your-API/4-2-B2C/Client folder, buka proyek TodoListClient.csproj dengan Visual Studio atau Visual Studio Code.

Di bawah folder akar proyek, buka appsettings.json file . File ini berisi informasi tentang IdP Azure AD B2C Anda. Aplikasi web menggunakan informasi ini untuk membangun hubungan kepercayaan dengan Azure AD B2C, memasukkan dan keluar pengguna, memperoleh token, dan memvalidasinya. Perbarui properti pengaturan aplikasi berikut:

Bagian Kunci Nilai
AzureAdB2C Kasus Bagian pertama dari nama penyewa Azure AD B2C Anda (misalnya, https://contoso.b2clogin.com).
AzureAdB2C Ruang Lingkup Nama lengkap penyewa Azure AD B2C Anda (misalnya, ).
AzureAdB2C ClientId ID aplikasi web dari langkah 2.3.
AzureAdB2C Rahasia Klien Rahasia aplikasi web dari langkah 2.4.
AzureAdB2C IDKebijakanDaftarMasukMasuk Alur pengguna atau kebijakan kustom yang Anda buat di langkah 1.
Daftar Todo Lingkupan Daftar TodoDaftar Cakupan API web yang Anda buat di langkah 2.5.
Daftar Todo TodoListBaseAddress URI dasar API web Anda (misalnya https://localhost:44332).

File konfigurasi akhir Anda akan terlihat seperti JSON berikut:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-app-application-id>",
    "ClientSecret": "<web-app-application-secret>",  
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  "TodoList": {
    "TodoListScope": "https://contoso.onmicrosoft.com/api/demo.read",
    "TodoListBaseAddress": "https://localhost:44332"
  }
}

Langkah 6: Jalankan contoh aplikasi web

  1. Bangun dan jalankan proyek.
  2. Telusuri menuju https://localhost:5000.
  3. Selesaikan proses pendaftaran atau masuk.

Setelah autentikasi berhasil, Anda akan melihat nama tampilan Anda di bilah navigasi. Untuk melihat klaim yang dikembalikan token Azure AD B2C ke aplikasi Anda, pilih TodoList.

Cuplikan layar klaim token aplikasi web.

Menyebarkan aplikasi Anda

Dalam aplikasi produksi, URI pengalihan pendaftaran aplikasi biasanya merupakan titik akhir yang dapat diakses publik tempat aplikasi Anda berjalan, seperti https://contoso.com/signin-oidc.

Anda dapat menambahkan dan mengubah URI pengalihan di aplikasi Anda yang telah terdaftar kapan saja. Pembatasan berikut berlaku untuk mengalihkan URI:

  • URL balasan harus dimulai dengan skema https.
  • URL balasan sensitif terhadap huruf besar/kecil. Ukuran huruf harus sesuai dengan ukuran huruf pada jalur URL pada aplikasi berjalan.

Cache token untuk aplikasi web

Sampel aplikasi web menggunakan serialisasi cache token dalam memori. Implementasi ini sangat bagus dalam sampel. Ini juga baik dalam aplikasi produksi, asalkan Anda tidak keberatan jika cache token hilang saat aplikasi web dimulai ulang.

Untuk lingkungan produksi, kami sarankan Anda menggunakan cache memori terdistribusi. Misalnya, cache Redis, NCache, atau cache SQL Server. Untuk detail tentang implementasi cache memori terdistribusi, lihat Serialisasi cache token.

Langkah selanjutnya