Perlindungan API

Saat Anda, sebagai pengembang, lindungi API Anda, Anda berfokus pada otorisasi. Untuk memanggil API sumber daya Anda, aplikasi perlu memperoleh otorisasi aplikasi. Sumber daya memberlakukan otorisasi. Dalam artikel ini, Anda mempelajari praktik terbaik untuk mencapai tujuan Zero Trust Anda. Ini menjelaskan cara melindungi API Anda melalui pendaftaran, izin dan definisi persetujuan, dan penerapan akses.

Mendaftarkan API yang dilindungi

Untuk melindungi API Anda dengan ID Microsoft Entra (ID Microsoft Entra), daftarkan API Anda. Kemudian Anda dapat mengelola API terdaftar Anda. Di MICROSOFT Entra ID, API adalah aplikasi dengan pengaturan pendaftaran aplikasi tertentu yang mendefinisikannya sebagai sumber daya atau API yang dapat diakses aplikasi lain. Di pusat admin Microsoft Entra, Microsoft Identity Developer, Pendaftaran aplikasi adalah API yang berada di tenan baik sebagai API lini bisnis atau layanan dari penyedia Software-as-a-Service (SaaS) yang memiliki API yang dilindungi oleh ID Microsoft Entra.

Selama pendaftaran, Anda menentukan bagaimana aplikasi panggilan mereferensikan API Anda dan izin yang didelegasikan dan aplikasinya. Pendaftaran aplikasi dapat mewakili solusi yang memiliki aplikasi klien dan API. Namun, dalam artikel ini, kami membahas skenario di mana sumber daya mandiri mengekspos API.

Biasanya, API tidak melakukan autentikasi atau secara langsung meminta otorisasi. API memvalidasi token yang disajikan aplikasi panggilan. API tidak memiliki rincian masuk interaktif, jadi Anda tidak perlu mendaftarkan pengaturan seperti URI pengalihan atau jenis aplikasi. API mendapatkan token mereka dari aplikasi yang memanggil API tersebut, bukan dengan berinteraksi dengan ID Microsoft Entra. Untuk API web, gunakan token akses OAuth2 untuk otorisasi. API Web memvalidasi token pembawa untuk mengotorisasi penelepon. Jangan terima token ID sebagai bukti izin.

Secara bawaan, Microsoft Entra ID menambahkan User.Read ke izin API dari pendaftaran aplikasi baru mana pun. Anda menghapus izin ini untuk sebagian besar API web. MICROSOFT Entra ID memerlukan izin API hanya saat API memanggil API lain. Jika API Anda tidak memanggil API lain, hapus User.Read izin saat Anda mendaftarkan API Anda.

Anda memerlukan pengidentifikasi unik untuk API Anda, yang dikenal sebagai URI ID Aplikasi, aplikasi klien yang perlu mengakses API Anda meminta izin untuk memanggil API Anda. URI ID Aplikasi harus unik di semua penyewa Microsoft Entra. Anda dapat menggunakan api://<clientId> (saran default di portal) di mana <clientId> adalah ID Aplikasi DARI API terdaftar Anda.

Untuk memberi pengembang yang memanggil API Anda dengan nama yang lebih mudah digunakan, Anda dapat menggunakan alamat API Anda sebagai URI ID Aplikasi Anda. Misalnya, Anda dapat menggunakan https://API.yourdomain.com di mana yourdomain.com adalah domain penerbit yang dikonfigurasi di penyewa Microsoft Entra Anda. Microsoft memvalidasi bahwa Anda memiliki kepemilikan domain sehingga Anda dapat menggunakannya sebagai pengidentifikasi unik untuk API Anda. Anda tidak perlu memiliki kode di alamat ini. API dapat berada di mana pun Anda menginginkannya, tetapi ini adalah praktik yang baik untuk menggunakan https alamat API sebagai URI ID Aplikasi.

Menentukan izin yang didelegasikan dengan hak istimewa paling sedikit

Jika aplikasi yang memiliki pengguna akan memanggil API Anda, tentukan setidaknya satu izin yang didelegasikan (lihat Menambahkan cakupan pada pendaftaran aplikasi Mengekspos API).

API yang menyediakan akses ke penyimpanan data organisasi dapat menarik perhatian pelaku jahat yang ingin mengakses data tersebut. Daripada hanya memiliki satu izin yang hanya didelegasikan, rancang izin Anda dengan mempertimbangkan prinsip Zero Trust akses hak istimewa minimal. Mungkin sulit untuk masuk ke model dengan hak istimewa paling sedikit nanti jika semua aplikasi klien dimulai dengan akses istimewa penuh.

Seringkali, pengembang jatuh ke dalam pola menggunakan satu izin seperti akses sebagai pengguna atau peniruan pengguna (yang merupakan frasa umum yang tidak akurat secara teknis). Izin tunggal seperti ini hanya memungkinkan akses istimewa penuh ke API Anda.

Deklarasikan cakupan hak istimewa paling sedikit sehingga aplikasi Anda tidak rentan terhadap kompromi atau digunakan untuk melakukan tugas yang tidak pernah Anda maksudkan. Tentukan beberapa cakupan Anda dalam Izin API. Misalnya, pisahkan cakupan antara membaca dan memperbarui data dan pertimbangkan untuk menawarkan izin baca saja. Akses tulis mencakup hak istimewa untuk operasi buat, perbarui, dan hapus. Klien tidak boleh memerlukan akses tulis untuk hanya membaca data.

Pertimbangkan izin akses standar dan penuh saat API Anda berfungsi dengan data sensitif. Batasi properti sensitif sehingga izin standar tidak mengizinkan akses (misalnya, Resource.Read). Kemudian terapkan izin akses penuh (misalnya, Resource.ReadFull) yang mengembalikan properti dan informasi sensitif.

Selalu evaluasi izin yang diminta untuk memastikan Anda mencari jumlah hak istimewa seminimal mungkin agar pekerjaan dapat diselesaikan. Hindari meminta izin hak istimewa yang lebih tinggi. Sebagai gantinya, buat izin individual untuk setiap skenario inti. Lihat referensi izin Microsoft Graph untuk contoh pendekatan ini yang baik. Temukan dan gunakan jumlah izin yang tepat untuk memenuhi kebutuhan Anda.

Sebagai bagian dari definisi cakupan Anda, putuskan apakah rentang operasi yang dapat dilakukan dengan cakupan tertentu memerlukan persetujuan admin.

Sebagai perancang API, Anda dapat memberikan panduan tentang cakupan mana yang dapat dengan aman hanya memerlukan persetujuan pengguna. Namun, admin penyewa dapat mengonfigurasi pengaturan penyewa sehingga semua izin memerlukan persetujuan dari admin. Jika Anda menentukan cakupan sebagai memerlukan persetujuan admin, izin selalu memerlukan persetujuan admin.

Saat Anda memutuskan persetujuan pengguna atau admin, Anda memiliki pertimbangan utama ini:

  • Apakah rentang operasi di belakang izin memengaruhi lebih dari satu pengguna. Jika izin memungkinkan pengguna untuk memilih aplikasi mana yang hanya dapat mengakses informasi mereka sendiri, maka persetujuan pengguna mungkin sesuai. Misalnya, pengguna dapat menyetujui untuk memilih aplikasi pilihan mereka untuk email. Namun, jika operasi di balik izin melibatkan lebih dari satu pengguna (seperti melihat profil pengguna lengkap pengguna lain), maka tentukan izin tersebut sebagai memerlukan persetujuan admin.

  • Apakah rentang operasi di belakang izin memiliki cakupan yang luas. Misalnya, cakupan yang luas adalah ketika izin memungkinkan aplikasi mengubah semua yang ada di penyewa atau melakukan sesuatu yang mungkin tidak dapat diubah. Cakupan luas menunjukkan bahwa Anda memerlukan persetujuan admin daripada persetujuan pengguna.

Jika Anda ragu, lebih baik bersikap hati-hati dan meminta persetujuan admin. Jelaskan dengan jelas dan ringkas konsekuensi dari persetujuan dalam rangkaian perizinan Anda. Asumsikan bahwa individu yang membaca string deskripsi Anda tidak memiliki keakraban dengan API atau produk Anda.

Hindari menambahkan API Anda ke izin yang ada dengan cara yang mengubah semantik izin. Menyalahgunakan izin yang ada melemahkan alasan di mana klien sebelumnya memberikan persetujuan.

Menentukan izin aplikasi

Saat membuat aplikasi nonpengguna, Anda tidak memiliki pengguna yang dapat dimintai nama pengguna dan kata sandi atau Autentikasi Multifaktor (MFA). Jika aplikasi tanpa pengguna (seperti beban kerja, layanan, dan daemon) memanggil API Anda, tentukan izin aplikasi untuk API Anda. Saat Anda menentukan izin aplikasi, gunakan peran aplikasi alih-alih menggunakan cakupan.

Seperti halnya izin yang didelegasikan, Anda memberikan izin aplikasi terperinci sehingga beban kerja yang memanggil API Anda dapat mengikuti akses hak istimewa paling sedikit dan selaras dengan prinsip Zero Trust. Hindari menerbitkan hanya satu peran aplikasi (izin aplikasi) dan satu cakupan (izin yang didelegasikan) atau mengekspos semua operasi ke setiap klien.

Workload mengautentikasi dengan kredensial klien dan meminta token dengan .default cakupan tertentu seperti yang ditunjukkan dalam contoh kode berikut.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Izin memerlukan persetujuan admin ketika tidak ada pengguna di depan aplikasi dan ketika izin aplikasi mengaktifkan berbagai operasi.

Menerapkan akses

Pastikan API Anda memastikan akses dengan memvalidasi dan menginterpretasikan token akses yang disediakan oleh aplikasi pemanggil sebagai token pembawa di https header otorisasi permintaan. Terapkan akses dengan memvalidasi token, mengelola refresh metadata, dan menerapkan cakupan dan peran seperti yang dijelaskan di bagian berikut.

Validasi token

Setelah API Anda menerima token, pastikan api memvalidasi token. Validasi memastikan bahwa token berasal dari penerbit yang tepat dan tidak mengalami perubahan atau modifikasi. Periksa tanda tangan karena Anda tidak mendapatkan token langsung dari ID Microsoft Entra seperti yang Anda lakukan dengan token ID. Validasi tanda tangan setelah API Anda menerima token dari sumber yang tidak tepercaya di jaringan.

Karena ada kerentanan yang diketahui terkait dengan verifikasi tanda tangan JSON Web Token (JWT), gunakan pustaka validasi token standar yang dikelola dengan baik dan terpercaya. Pustaka autentikasi (seperti Microsoft.Identity.Web) menggunakan langkah-langkah yang tepat dan mengurangi kerentanan yang diketahui.

Secara opsional, perluas validasi token. Gunakan klaim ID penyewa (tid) untuk membatasi penyewa tempat API Anda dapat memperoleh token. Gunakan klaim azp dan klaim appid untuk memfilter aplikasi yang dapat memanggil API Anda. Gunakan klaim ID objek (oid) untuk mempersempit akses lebih lanjut ke pengguna individu.

Mengelola penyegaran metadata

Selalu pastikan bahwa pustaka validasi token Anda secara efektif mengelola metadata yang diperlukan. Dalam hal ini, metadata adalah kunci publik, pasangan kunci privat, yang digunakan Microsoft untuk menandatangani token Microsoft Entra. Saat pustaka Anda memvalidasi token ini, pustaka tersebut mendapatkan daftar kunci penandatanganan publik kami yang diterbitkan dari alamat internet terkenal. Pastikan bahwa lingkungan hosting memiliki waktu yang tepat untuk mendapatkan kunci tersebut.

Misalnya, pustaka yang lebih lama kadang-kadang dikodekan secara keras untuk memperbarui kunci penandatanganan publik tersebut setiap 24 jam. Pertimbangkan kapan Microsoft Entra ID harus dengan cepat mengganti kunci tersebut, dan kunci yang Anda unduh tidak menyertakan kunci hasil penggantian yang baru. API Anda bisa offline selama sehari saat menunggu siklus refresh metadatanya. Referensikan panduan refresh metadata tertentu untuk memastikan bahwa Anda mendapatkan metadata dengan benar. Jika Anda menggunakan pustaka, pastikan pustaka tersebut mengolah metadata dalam waktu yang wajar.

Menerapkan ruang lingkup dan peran

Setelah memvalidasi token, API Anda melihat klaim dalam token untuk menentukan cara kerjanya.

Untuk token izin yang didelegasikan, mintaLAH API Anda memeriksa klaim cakupan (scp) untuk melihat apa yang telah disetujui aplikasi untuk dilakukan. Periksa klaim ID objek (oid) atau kunci subjek (sub) untuk mengetahui pengguna atas nama siapa aplikasi ini bekerja.

Kemudian minta pemeriksaan API Anda untuk memastikan bahwa pengguna juga memiliki akses ke operasi yang diminta. Jika API Anda menentukan peran untuk ditetapkan ke pengguna dan grup, pastikan API Anda memeriksa klaim peran apa pun dalam token dan berperilaku sesuai. Token izin aplikasi tidak memiliki klaim cakupan (scp). Sebagai gantinya, minta API Anda memeriksa klaim peran untuk menentukan izin aplikasi mana yang diterima beban kerja.

Setelah API Anda memvalidasi token dan cakupan dan memproses ID objek (oid), kunci subjek (sub), dan klaim peran, API Anda dapat mengembalikan hasilnya.

Langkah berikutnya

  • Last updated on