Mulai Cepat: Melindungi API web dengan platform identitas Microsoft

Artikel
06/02/2022
10 menit untuk membaca

Di mulai cepat ini, unduh dan jalankan sampel kode yang menunjukkan cara melindungi API web ASP.NET dengan membatasi akses ke sumber dayanya hanya untuk akun yang diotorisasi. Sampel ini mendukung otorisasi akun dan akun Microsoft pribadi di organisasi Azure Active Directory (Azure AD) mana pun.

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

Prasyarat

Akun Azure dengan langganan aktif. Buat akun gratis.
Visual Studio 2017 atau 2019. Unduh Visual Studio secara gratis.

Klon atau unduh sampel

Anda dapat memperoleh sampel dengan salah satu dari 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)

Daftarkan API web di Pendaftaran aplikasi di portal Microsoft Azure.

Masuk ke portal Microsoft Azure.
Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Directori + langganan di menu atas untuk memilih penyewa tempat Anda ingin mendaftarkan aplikasi.
Cari dan pilih Azure Active Directory.
Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.
Masukkan Nama untuk aplikasi Anda, misalnya AppModelv2-NativeClient-DotNet-TodoListService. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya di lain waktu.
Untuk Tipe akun yang didukung, pilih Akun di direktori organisasi apa pun.
Pilih Daftar untuk membuat aplikasi.
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 project ini (artinya, ClientId dalam file TodoListService\Web.config).
Di bawah Kelola, pilih Mengekspos 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.
Pilih Tambahkan cakupan.

Mengonfigurasi proyek layanan

Konfigurasikan proyek layanan agar sesuai dengan API web yang terdaftar.

Buka solusi di Visual Studio, lalu buka fileWeb.config di bawah akar proyek TodoListService.
Ganti nilai parameter ida:ClientId dengan nilai ID Klien (ID Aplikasi) dari aplikasi yang baru saja Anda daftarkan di portal Pendaftaran aplikasi.

Menambahkan cakupan baru ke file app.config

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

Di folder akar proyek TodoListClient, buka file app.config.
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:

Buka platform identitas Microsoft untuk portal pendaftaran aplikasi pengembang.
Pilih Pendaftaran baru.
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.
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.
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.

Mengonfigurasi proyek Anda

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

Di portal Pendaftaran aplikasi, pada halaman Gambaran Umum, salin nilai ID Aplikasi (klien) .
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. Jika Anda menggunakan Visual Studio:

Klik kanan pada solusi Visual Studio dan pilih Properti
Di Properti Umum pilih Proyek Startup dan kemudian Beberapa proyek startup.
Untuk kedua proyek, pilih Mulai sebagai tindakan
Pastikan layanan TodoListService dimulai terlebih dahulu dengan memindahkannya ke posisi pertama dalam daftar, menggunakan panah atas.

Masuk untuk menjalankan proyek TodoListClient Anda.

Tekan F5 untuk memulai proyek. Halaman layanan terbuka, serta aplikasi desktop.
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.

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

Menjalankan proyek Anda

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

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

Untuk menentukan siapa yang bisa masuk ke aplikasi Anda, gunakan salah satu opsi berikut:

Opsi 1: Membatasi akses ke satu organisasi (penyewa tunggal)

Anda dapat membatasi akses masuk ke aplikasi Anda ke akun pengguna yang berada dalam satu penyewa Azure Active Directory, termasuk akun tamu penyewa tersebut. Skenario ini umum untuk aplikasi lini bisnis.

Buka file App_Start\Startup.Auth, lalu ubah nilai titik akhir metadata yang diteruskan ke dalam OpenIdConnectSecurityTokenProvider ke https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration. Anda juga dapat menggunakan nama penyewa, seperti contoso.onmicrosoft.com.
Dalam file yang sama, atur ValidIssuer properti TokenValidationParameters ke https://sts.windows.net/{Tenant ID}/, dan atur ValidateIssuer argumen ke true.

Opsi 2: Menggunakan metode kustom untuk memvalidasi penerbit

Anda dapat menerapkan metode kustom untuk memvalidasi penerbit dengan menggunakan IssuerValidator parameter. Untuk informasi selengkapnya tentang parameter ini, lihat kelas TokenValidationParameters.

Bantuan dan dukungan

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

Langkah berikutnya

Pelajari selengkapnya tentang skenario API web yang dilindungi yang didukung platform identitas Microsoft.

Skenario API web yang dilindungi

Dalam mulai cepat ini, Anda mengunduh sampel kode API web ASP.NET Core dan meninjau caranya membatasi akses sumber daya ke akun yang diotorisasi saja. Sampel ini mendukung otorisasi akun dan akun Microsoft pribadi di organisasi Azure Active Directory (Azure AD) mana pun.

Prasyarat

Akun Azure dengan langganan aktif. Buat akun gratis.
Penyewa Azure Active Directory
.NET Core SDK 3.1+
Visual Studio 2019 atau Visual Studio Code

Langkah 1: Daftarkan aplikasi

Pertama, daftarkan API web di penyewa Azure AD Anda dan tambahkan cakupan dengan mengikuti langkah-langkah berikut:

Masuk ke portal Microsoft Azure.
Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih penyewa aplikasinya ingin Anda daftarkan.
Cari dan pilih Microsoft Azure Active Directory.
Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.
Untuk Nama, masukkan nama aplikasi. Misalnya, masukkan AspNetCoreWebApi-Quickstart. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
Pilih Daftarkan.
Di bagian Kelola, pilih Ekspos API>Tambahkan cakupan. Untuk URI ID Aplikasi, terima default dengan memilih Simpan dan lanjutkan, lalu masukkan detail berikut:
- Nama cakupan: access_as_user
- Siapa yang dapat menyetujui? : Admin dan pengguna
- Nama tampilan persetujuan admin: Access AspNetCoreWebApi-Quickstart
- Deskripsi persetujuan admin: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
- Nama tampilan persetujuan admin: Access AspNetCoreWebApi-Quickstart
- Deskripsi persetujuan admin: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
- Status: Diaktifkan
Pilih Tambahkan cakupan untuk menyelesaikan penambahan cakupan.

Langkah 2: Unduh ASP.NET Core

Unduh solusi ASP.NET Core dari GitHub.

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.

Langkah 3: Konfigurasikan proyek ASP.NET Core

Dalam langkah ini, konfigurasikan kode sampel agar dapat digunakan dengan pendaftaran aplikasi yang Anda buat sebelumnya.

Ekstrak arsip .zip ke folder lokal di dekat akar drive. Misalnya, ekstrak ke dalam C:\Azure-Samples.

Sebaiknya ekstrak arsip ke direktori dekat akar drive untuk menghindari kesalahan yang disebabkan oleh keterbatasan panjang jalur di Windows.
Buka solusi di folder webapi di editor kode Anda.
Buka file appsettings.json dan ubah kode berikut:
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Ganti Enter_the_Application_Id_here dengan ID aplikasi (klien) dari aplikasi yang Anda daftarkan di portal Microsoft Azure. Anda dapat menemukan nilai ID aplikasi (klien) di halaman Gambaran Umum aplikasi.
- Ganti Enter_the_Tenant_Info_Here dengan salah satu hal berikut ini:
  - Jika aplikasi Anda hanya mendukung Akun di direktori organisasi, ganti nilai ini dengan ID direktori (penyewa) (GUID) atau nama penyewa (misalnya, contoso.onmicrosoft.com). Anda dapat menemukan nilai ID direktori (penyewa) di halaman Gambaran Umum aplikasi.
  - Jika aplikasi Anda mendukung Akun di direktori organisasi apa pun, ganti nilai ini dengan organizations.
  - Jika aplikasi Anda mendukung Semua pengguna akun Microsoft, biarkan nilai ini sebagai common.

Untuk mulai cepat ini, jangan ubah nilai lain dalam file appsettings.json.

Cara kerja sampel

API web menerima token dari aplikasi klien, dan kode di API web memvalidasi token. Skenario ini dijelaskan secara lebih terperinci dalam Skenario: API web terlindungi.

Kelas permulaan

Middleware Microsoft.AspNetCore.Authentication menggunakan kelas Startup yang dijalankan saat proses hosting dimulai. Dalam metode ConfigureServices, ekstensi AddMicrosoftIdentityWebApi yang disediakan oleh Microsoft.Identity.Web disebut.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

Metode AddAuthentication() ini mengonfigurasi layanan untuk menambahkan autentikasi berbasis JwtBearer.

Baris yang berisi .AddMicrosoftIdentityWebApi menambahkan otorisasi platform identitas Microsoft ke API web Anda. Kemudian dikonfigurasi untuk memvalidasi token akses yang dikeluarkan oleh platform identitas Microsoft berdasarkan informasi AzureAD di bagian file konfigurasi appsettings.json:

Kunci appsettings.json	Deskripsi
`ClientId`	ID aplikasi (klien) untuk aplikasi yang terdaftar di portal Microsoft Azure.
`Instance`	Titik akhir layanan token keamanan (STS) bagi pengguna untuk mengautentikasi. Nilai ini biasanya `https://login.microsoftonline.com/`, menunjukkan awan publik Azure.
`TenantId`	Nama penyewa atau ID penyewanya (GUID), atau `common` untuk memasukkan pengguna dengan akun kantor atau sekolah atau akun pribadi Microsoft.

Metode Configure() ini berisi dua metode penting, app.UseAuthentication() dan app.UseAuthorization(), yang memungkinkan fungsionalitas bernama:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Melindungi pengontrol, metode pengontrol, atau halaman Razor

Anda dapat melindungi pengontrol atau metode pengontrol menggunakan atribut [Authorize]. Atribut ini membatasi akses ke pengontrol atau metode dengan hanya mengizinkan pengguna terautentikasi. Tantangan autentikasi kemudian dapat mulai mengakses pengontrol jika pengguna tidak diautentikasi.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Validasi cakupan dalam pengontrol

Kode dalam API memverifikasi bahwa cakupan yang diperlukan ada di token menggunakan HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Bantuan dan dukungan

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

Langkah berikutnya

Repositori GitHub yang berisi sampel kode API Web ASP.NET Core ini mencakup instruksi dan lebih banyak sampel kode yang menunjukkan kepada Anda cara:

Menambahkan autentikasi ke API web ASP.NET Core baru.
Hubungi API web dari aplikasi desktop.
Panggil API hilir seperti Microsoft Graph dan API Microsoft lainnya.

Tutorial API web ASP.NET Core di GitHub

Mulai Cepat: Melindungi API web dengan platform identitas Microsoft

Prasyarat

Klon atau unduh sampel

Daftarkan API web (TodoListService)

Mengonfigurasi proyek layanan

Menambahkan cakupan baru ke file app.config

Mendaftarkan aplikasi web (TodoListClient)

Mendaftarkan aplikasi

Mengonfigurasi proyek Anda

Jalankan proyek Anda

Pra-otorisasi aplikasi klien Anda

Menjalankan proyek Anda

Opsional: Membatasi akses masuk ke pengguna tertentu

Opsi 1: Membatasi akses ke satu organisasi (penyewa tunggal)

Opsi 2: Menggunakan metode kustom untuk memvalidasi penerbit

Bantuan dan dukungan

Langkah berikutnya

Prasyarat

Langkah 1: Daftarkan aplikasi

Langkah 2: Unduh ASP.NET Core

Langkah 3: Konfigurasikan proyek ASP.NET Core

Cara kerja sampel

Kelas permulaan

Melindungi pengontrol, metode pengontrol, atau halaman Razor

Validasi cakupan dalam pengontrol

Bantuan dan dukungan

Langkah berikutnya