Bagikan melalui

Lindungi API di dalam API Management menggunakan otorisasi OAuth 2.0 dengan Microsoft Entra ID

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Dalam artikel ini, Anda akan mempelajari langkah-langkah tingkat tinggi untuk mengonfigurasi instans Azure API Management Anda untuk melindungi API, dengan menggunakan protokol OAuth 2.0 dengan ID Microsoft Entra.

Untuk gambaran umum konseptual otorisasi API, lihat Autentikasi dan otorisasi ke API di API Management.

Prasyarat

Untuk mengikuti langkah-langkah dalam artikel ini, Anda harus memiliki:

  • Instans API Management
  • API yang diterbitkan menggunakan instans API Management
  • Penyewa Microsoft Entra

Gambaran Umum

Ikuti langkah-langkah ini untuk melindungi API di API Management, menggunakan otorisasi OAuth 2.0 dengan ID Microsoft Entra.

  1. Daftarkan aplikasi (disebut backend-app dalam artikel ini) di ID Microsoft Entra untuk melindungi akses ke API.

    Untuk mengakses API, pengguna atau aplikasi akan memperoleh dan menyajikan token OAuth yang valid yang memberikan akses ke aplikasi ini dengan setiap permintaan API.

  2. Konfigurasikan kebijakan validate-jwt di API Management untuk memvalidasi token OAuth yang disajikan di setiap permintaan API masuk. Permintaan yang valid dapat diteruskan ke API.

Detail tentang alur otorisasi OAuth dan cara menghasilkan token OAuth yang diperlukan berada di luar cakupan artikel ini. Biasanya, aplikasi klien terpisah digunakan untuk memperoleh token dari ID Microsoft Entra yang mengotorisasi akses ke API. Untuk tautan ke informasi selengkapnya, lihat Langkah berikutnya.

Mendaftarkan aplikasi di ID Microsoft Entra untuk mewakili API

Dengan menggunakan portal Azure, lindungi API dengan ID Microsoft Entra dengan terlebih dahulu mendaftarkan aplikasi yang mewakili API.

Untuk detail tentang pendaftaran aplikasi, lihat Mulai Cepat: Mengonfigurasi aplikasi untuk mengekspos API web.

  1. Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.

  2. Pilih Pendaftaran baru.

  3. Saat Halaman daftarkan aplikasi muncul, masukkan informasi pendaftaran aplikasi Anda:

    • Di bagian Nama, masukkan nama aplikasi bermakna yang akan ditampilkan kepada pengguna aplikasi, seperti backend-app.
    • Di bagian Tipe akun yang didukung, pilih opsi yang sesuai dengan skenario Anda.

  4. Biarkan bagian URI Pengalihan kosong.

  5. Pilih Daftar untuk membuat aplikasi.

  6. Di halaman Gambaran Umum aplikasi, temukan nilai ID Aplikasi (klien) dan catat untuk digunakan nanti.

  7. Di bawah bagian Kelola menu samping, pilih Ekspos API dan atur URI ID Aplikasi dengan nilai default. Jika Anda mengembangkan aplikasi klien terpisah untuk mendapatkan token OAuth 2.0 untuk akses ke backend-app, catat nilai ini untuk nanti.

  8. Pilih tombol Tambahkan cakupan untuk menampilkan halaman Tambahkan cakupan:

    1. Masukkan nama Lingkupbaru, nama tampilan persetujuan Admin, dan deskripsi persetujuan Admin.
    2. Pastikan status lingkup diaktifkan dipilih.

  9. Pilih tombol Tambahkan cakupan untuk membuat cakupan.

  10. Ulangi dua langkah sebelumnya untuk menambahkan semua ruang lingkup yang didukung oleh API Anda.

  11. Saat cakupan dibuat, buat catatan dari cakupan itu untuk digunakan dalam langkah berikutnya.

Konfigurasi kebijakan validasi JWT untuk melakukan pra-otorisasi permintaan

Contoh kebijakan berikut, saat ditambahkan ke <inbound> bagian kebijakan, memeriksa nilai klaim audiens dalam token akses yang diperoleh dari ID Microsoft Entra yang disajikan di header Otorisasi. Ini mengembalikan pesan kesalahan jika token tidak valid. Konfigurasikan kebijakan ini pada cakupan kebijakan yang sesuai untuk skenario Anda.

  • openid-config Di URL, aad-tenant adalah ID penyewa di MICROSOFT Entra ID. Temukan nilai ini di portal Azure, misalnya, pada halaman Gambaran Umum sumber daya Microsoft Entra Anda. Contoh yang ditampilkan mengasumsikan aplikasi Microsoft Entra penyewa tunggal dan titik akhir konfigurasi v2.
  • Nilainya claim adalah ID klien dari backend-app yang Anda daftarkan di ID Microsoft Entra.
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Catatan

URL openid-config sebelumnya sesuai dengan titik akhir v2. Untuk titik akhir v1 openid-config , gunakan https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Untuk informasi mengenai cara mengonfigurasi kebijakan, lihat Mengatur atau mengedit kebijakan. Lihat referensi validasi-jwt untuk lebih banyak kustomisasi pada validasi JWT. Untuk memvalidasi JWT yang disediakan oleh layanan Microsoft Entra, API Management juga menyediakan kebijakan.validate-azure-ad-token

Alur kerja otorisasi

  1. Pengguna atau aplikasi memperoleh token dari ID Microsoft Entra dengan izin yang memberikan akses ke backend-app.

  2. Token ditambahkan di header Otorisasi atas permintaan API ke API Management.

  3. API Management memvalidasi token dengan menggunakan kebijakan validate-jwt.

    • Jika permintaan tidak memiliki token yang valid, API Management akan memblokirnya.

    • Jika permintaan disertai dengan token yang valid, gateway dapat meneruskan permintaan ke API.

Langkah berikutnya