Cara mengamankan API menggunakan autentikasi sertifikat klien di API Management

BERLAKU UNTUK: Semua tingkatAN API Management

API Management menyediakan kemampuan untuk mengamankan akses ke API (yaitu, klien ke API Management) menggunakan sertifikat klien dan autentikasi TLS bersama. Anda dapat memvalidasi sertifikat yang disajikan oleh klien penghubung dan memeriksa properti sertifikat terhadap nilai yang diinginkan menggunakan ekspresi kebijakan.

Untuk informasi tentang mengamankan akses ke layanan backend API menggunakan sertifikat klien (yaitu API Management ke backend), lihat Cara mengamankan layanan back-end menggunakan autentikasi sertifikat klien.

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

Opsi sertifikat

Untuk validasi sertifikat, API Management dapat memeriksa sertifikat yang dikelola dalam instans API Management Anda. Jika Anda memilih untuk menggunakan API Management untuk mengelola sertifikat klien, Anda memiliki opsi berikut:

• Mereferensikan sertifikat yang dikelola di Azure Key Vault
• Menambahkan file sertifikat langsung di API Management

Menggunakan sertifikat brankas kunci disarankan karena membantu meningkatkan keamanan API Management:

• Sertifikat yang disimpan dalam brankas kunci dapat digunakan kembali di seluruh layanan
• Kebijakan akses terperinci dapat diterapkan pada sertifikat yang disimpan dalam brankas kunci
• Sertifikat yang diperbarui dalam brankas kunci secara otomatis diputar di API Management. Setelah pembaruan di brankas kunci, sertifikat dalam API Management diperbarui dalam waktu 4 jam. Anda juga dapat melakukan refresh pada sertifikat secara manual menggunakan portal Microsoft Azure atau melalui API REST manajemen.

Prasyarat

• Jika Anda belum membuat instans layanan API Management, lihat Membuat instans layanan API Management.

• Anda memerlukan akses ke sertifikat dan kata sandi untuk manajemen dalam brankas kunci Azure atau mengunggah ke layanan API Management. Sertifikat harus dalam format CER atau PFX. Sertifikat yang ditandatangani sendiri diperbolehkan.

  Jika Anda menggunakan sertifikat yang ditandatangani sendiri, instal juga sertifikat CA akar dan menengah tepercaya di instans API Management Anda.

  Catatan

  Sertifikat CA untuk validasi sertifikat tidak didukung di tingkat Konsumsi.

Prasyarat untuk integrasi brankas kunci

1. Jika Anda belum memiliki brankas kunci, buatlah. Untuk langkah-langkah dalam membuat brankas kunci, lihat Mulai Cepat: Membuat brankas kunci menggunakan portal Microsoft Azure.

   Untuk membuat atau mengimpor sertifikat ke brankas kunci, lihat Mulai Cepat: Mengatur dan mengambil sertifikat dari Azure Key Vault menggunakan portal Azure.

2. Aktifkan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna di instans API Management.

Mengonfigurasi akses ke brankas kunci

1. Di portal, arahkan ke brankas kunci Anda.

2. Di menu sebelah kiri, pilih Konfigurasi akses, dan perhatikan Model izin yang dikonfigurasi.

3. Bergantung pada model izin, konfigurasikan kebijakan akses brankas kunci atau akses Azure RBAC untuk identitas terkelola API Management.

   Untuk menambahkan kebijakan akses brankas kunci:
   

   1. Di menu sebelah kiri, pilih Kebijakan akses.
   2. Pada halaman Kebijakan akses, pilih + Buat.
   3. Pada tab Izin , di bawah Izin rahasia, pilih Dapatkan dan Daftar, lalu pilih Berikutnya.
   4. Pada tab Utama , Pilih prinsipal, cari nama sumber daya identitas terkelola Anda, lalu pilih Berikutnya. Jika Anda menggunakan identitas yang ditetapkan sistem, prinsipal adalah nama instans API Management Anda.
   5. Pilih Berikutnya lagi. Di tab Tinjau + buat, pilih Buat.

   Untuk mengonfigurasi akses Azure RBAC:
   

   1. Di menu sebelah kiri, pilih Kontrol akses (IAM).
   2. Pada halaman Kontrol akses (IAM), pilih Tambahkan penetapan peran.
   3. Pada tab Peran , pilih Pengguna Rahasia Key Vault.
   4. Pada tab Anggota, pilih Identitas> terkelola+ Pilih anggota.
   5. Pada halaman Pilih identitas terkelola, pilih identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna yang terkait dengan instans API Management Anda, lalu pilih Pilih.
   6. Pilih Tinjau + tetapkan.

Persyaratan untuk firewall Key Vault

Jika firewall Key Vault diaktifkan pada brankas kunci Anda, berikut ini adalah persyaratan tambahan:

• Anda harus menggunakan identitas terkelola yang ditetapkan sistem oleh instans API Management untuk mengakses brankas kunci.

• Di firewall Key Vault, aktifkan opsi Izinkan Layanan Microsoft Tepercaya untuk melewati firewall ini.

• Pastikan bahwa alamat IP klien lokal Anda diizinkan untuk mengakses brankas kunci untuk sementara saat Anda memilih sertifikat atau rahasia untuk ditambahkan ke Azure API Management. Untuk informasi lebih lanjut, lihat Mengonfigurasi pengaturan jaringan Azure Key Vault.

  Setelah menyelesaikan konfigurasi, Anda dapat memblokir alamat klien Anda di firewall brankas kunci.

Persyaratan jaringan virtual

Jika instance Manajemen API diterapkan di jaringan virtual, konfigurasikan juga pengaturan jaringan berikut:

• Aktifkan titik akhir layanan ke Azure Key Vault pada subnet API Management.
• Mengonfigurasi aturan grup keamanan jaringan (NSG) untuk memungkinkan lalu lintas keluar ke tag layanan AzureKeyVault dan AzureActiveDirectory.

Untuk detailnya, lihat Konfigurasi jaringan saat menyiapkan Azure API Management di VNet.

Menambahkan sertifikat brankas kunci

Lihat Prasyarat untuk integrasi brankas kunci.

Penting

Saat menambahkan sertifikat brankas kunci ke instans API Management, Anda harus memiliki izin untuk mencantumkan rahasia dari brankas kunci.

Perhatian

Saat menggunakan sertifikat brankas kunci di API Management, berhati-hatilah untuk tidak menghapus sertifikat, brankas kunci, atau identitas terkelola yang digunakan untuk mengakses brankas kunci.

Untuk menambahkan sertifikat brankas kunci ke API Management:

1. Di Portal Microsoft Azure, navigasikan ke instans API Management Anda.

2. Di bawah Keamanan, pilih Sertifikat.

3. Pilih Sertifikat>+ Tambahkan.

4. Di Id, masukkan nama pilihan Anda.

5. Di Sertifikat, pilih Brankas kunci.

6. Masukkan pengidentifikasi sertifikat brankas kunci, atau pilih Pilih untuk memilih sertifikat dari brankas kunci.

   Penting

   Jika Anda memasukkan pengidentifikasi sertifikat brankas kunci sendiri, pastikan bahwa brankas tersebut tidak memiliki informasi versi. Jika tidak, sertifikat tidak akan diputar secara otomatis di API Management setelah pembaruan di brankas kunci.

7. Di Identitas klien, pilih identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna yang sudah ada. Pelajari cara menambahkan atau memodifikasi identitas terkelola di layanan API Management Anda.

   Catatan

   Identitas membutuhkan izin untuk mendapatkan dan mencantumkan sertifikat dari brankas kunci. Jika Anda belum mengonfigurasi akses ke brankas kunci, API Management akan meminta Anda sehingga dapat mengonfigurasi identitas secara otomatis dengan izin yang diperlukan.

8. Pilih Tambahkan.

   

9. Pilih Simpan.

Mengunggah sertifikat

Untuk mengunggah sertifikat klien ke API Management:

1. Di Portal Microsoft Azure, navigasikan ke instans API Management Anda.

2. Di bawah Keamanan, pilih Sertifikat.

3. Pilih Sertifikat>+ Tambahkan.

4. Di Id, masukkan nama pilihan Anda.

5. Di Sertifikat, pilih Kustom.

6. Telusuri untuk memilih file .pfx sertifikat, dan masukkan kata sandinya.

7. Pilih Tambahkan.

   

8. Pilih Simpan.

Catatan

Jika Anda hanya ingin menggunakan sertifikat untuk mengautentikasi klien dengan API Management, Anda dapat mengunggah file CER.

Mengaktifkan instans API Management untuk menerima dan memverifikasi sertifikat klien

Tingkat Pengembang, Dasar, Standar, atau Premium

Untuk menerima dan memverifikasi sertifikat klien melalui HTTP/2 di tingkat Pengembang, Dasar, Dasar v2, Standar, Standar v2, atau Premium, Anda harus mengaktifkan pengaturan Negosiasi sertifikat klien pada bilah Domain kustom seperti yang ditunjukkan di bawah ini.

Tingkat konsumsi

Untuk menerima dan memverifikasi sertifikat klien di tingkat Konsumsi, Anda harus mengaktifkan pengaturan Minta sertifikat klien pada bilah Domain kustom seperti yang ditunjukkan di bawah ini.

Kebijakan untuk memvalidasi sertifikat klien

Gunakan kebijakan validasi-sertifikat-klien untuk memvalidasi satu atau beberapa atribut sertifikat klien yang digunakan untuk mengakses API yang dihosting di instans API Management Anda.

Konfigurasikan kebijakan untuk memvalidasi satu atau beberapa atribut termasuk penerbit sertifikat, subjek, thumbprint, apakah sertifikat divalidasi terhadap daftar pencabutan online, dan lainnya.

Validasi sertifikat dengan variabel konteks

Anda juga dapat membuat ekspresi kebijakan dengan context variabel untuk memeriksa sertifikat klien. Contoh di bagian berikut ini memperlihatkan ekspresi menggunakan properti context.Request.Certificate dan properti context lainnya.

Catatan

Autentikasi sertifikat timbayar mungkin tidak berfungsi dengan benar ketika titik akhir gateway API Management diekspos melalui Application Gateway. Ini karena Application Gateway berfungsi sebagai load balancer Lapisan 7, membangun koneksi SSL yang berbeda dengan layanan API Management backend. Akibatnya, sertifikat yang dilampirkan oleh klien dalam permintaan HTTP awal tidak akan diteruskan ke APIM. Namun, sebagai solusinya, Anda dapat mengirimkan sertifikat menggunakan opsi variabel server. Untuk instruksi terperinci, lihat Variabel Server Autentikasi Timah.

Penting

• Mulai Mei 2021, properti context.Request.Certificate hanya meminta sertifikat saat hostnameConfiguration instans API Management menetapkan properti negotiateClientCertificate ke True. Secara default, negotiateClientCertificate ditetapkan ke False.
• Jika negosiasi ulang TLS dinonaktifkan di klien Anda, Anda mungkin melihat kesalahan TLS saat meminta sertifikat menggunakan properti context.Request.Certificate. Jika ini terjadi, aktifkan pengaturan negosiasi ulang TLS di klien.
• Negosiasi ulang sertifikasi tidak didukung di tingkat API Management v2.

Memeriksa pengeluar sertifikat dan subjek

Kebijakan di bawah ini dapat dikonfigurasi untuk memeriksa pengeluar sertifikat dan subjek sertifikat klien:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Catatan

Untuk menonaktifkan pemeriksaan daftar pencabutan sertifikat, gunakan context.Request.Certificate.VerifyNoRevocation() alih-alih context.Request.Certificate.Verify(). Jika sertifikat klien ditandatangani sendiri, sertifikat CA root (atau perantara) harus diunggah ke API Management agar context.Request.Certificate.Verify() dan context.Request.Certificate.VerifyNoRevocation() berfungsi.

Memeriksa thumbprint

Kebijakan di bawah ini dapat dikonfigurasi untuk memeriksa thumbprint dari sertifikat klien:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Catatan

Untuk menonaktifkan pemeriksaan daftar pencabutan sertifikat, gunakan context.Request.Certificate.VerifyNoRevocation() alih-alih context.Request.Certificate.Verify(). Jika sertifikat klien ditandatangani sendiri, sertifikat CA root (atau perantara) harus diunggah ke API Management agar context.Request.Certificate.Verify() dan context.Request.Certificate.VerifyNoRevocation() berfungsi.

Memeriksa thumbprint terhadap sertifikat yang diunggah ke API Management

Contoh berikut menunjukkan cara memeriksa thumbprint sertifikat klien terhadap sertifikat yang diunggah ke API Management:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Catatan

Untuk menonaktifkan pemeriksaan daftar pencabutan sertifikat, gunakan context.Request.Certificate.VerifyNoRevocation() alih-alih context.Request.Certificate.Verify(). Jika sertifikat klien ditandatangani sendiri, sertifikat CA root (atau perantara) harus diunggah ke API Management agar context.Request.Certificate.Verify() dan context.Request.Certificate.VerifyNoRevocation() berfungsi.

Tip

Masalah kebuntuan sertifikat klien yang dijelaskan dalam artikel ini dapat muncul dalam beberapa cara, misalnya permintaan dibekukan, permintaan menghasilkan kode status 403 Forbidden setelah waktu habis, context.Request.Certificate adalah null. Masalah ini biasanya memengaruhi permintaan POST dan PUT dengan panjang konten sekitar 60 KB atau lebih besar. Untuk mencegah masalah ini terjadi, aktifkan pengaturan "Negosiasikan sertifikat klien" untuk nama host yang diinginkan pada bilah "Domain kustom" seperti yang ditunjukkan pada gambar pertama dokumen ini. Fitur ini tidak tersedia di tingkat Konsumsi.

Langkah berikutnya

• Cara mengamankan layanan backend menggunakan autentikasi sertifikat klien
• Cara menambahkan sertifikat CA kustom di Azure API Management
• Pelajari tentang kebijakan dalam API Management