Menggunakan nilai bernama dalam kebijakan Azure API Management

BERLAKU UNTUK: Semua tingkat API Management

Kebijakan API Management adalah kemampuan sistem yang kuat yang memungkinkan penerbit untuk mengubah perilaku API melalui konfigurasi. Kebijakan adalah kumpulan pernyataan yang dijalankan secara berurutan atas permintaan atau respons API. Pernyataan kebijakan dapat dibuat menggunakan nilai teks literal, ekspresi kebijakan, dan nilai bernama.

Nilai yang diberi nama adalah kumpulan pasangan nama/nilai global di setiap instans API Management. Nilai bernama dapat digunakan untuk mengelola nilai string konstan dan rahasia di seluruh konfigurasi dan kebijakan API.

Jenis nilai

Tipe	Deskripsi
Sederhana	String literal atau ekspresi kebijakan
Rahasia	String literal atau ekspresi kebijakan yang dienkripsi oleh API Management
Key Vault	Pengidentifikasi rahasia yang disimpan dalam Azure key vault.

Nilai atau rahasia biasa dapat berisi ekspresi kebijakan. Misalnya, ekspresi @(DateTime.Now.ToString()) mengembalikan string yang berisi tanggal dan waktu saat ini.

Untuk detail tentang atribut nilai bernama, lihat referensi REST API Manajemen API.

Rahasia penyimpanan kunci

Nilai rahasia dapat disimpan baik sebagai string terenkripsi dalam API Management (rahasia kustom) atau dengan merujuk rahasia di Azure Key Vault.

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

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

Catatan

Rahasia yang disimpan di Azure Key Vault harus antara 1 dan 4096 karakter, karena API Management tidak dapat mengambil nilai yang melebihi batas ini.

Prasyarat

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

Prasyarat untuk integrasi brankas utama

Catatan

Saat ini, fitur ini tidak tersedia di ruang kerja.

• 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 rahasia ke brankas kunci, lihat Mulai Cepat: Mengatur dan mengambil rahasia dari Azure Key Vault menggunakan portal Azure.

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

Mengonfigurasi akses ke brankas kunci

1. Di portal, buka brankas kunci Anda.
2. Di menu sebelah kiri, pilih Konfigurasi akses. Perhatikan Model izin yang dikonfigurasi.
3. Bergantung pada model izin, konfigurasikan kebijakan akses Key Vault atau akses Azure RBAC untuk identitas terkelola API Management.

Untuk menambahkan kebijakan akses Key Vault:

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 Utama, 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 di brankas kunci, Anda harus memenuhi persyaratan berikut:

• Anda harus menggunakan identitas terkelola yang diberikan oleh sistem pada instans API Management untuk mengakses penyimpanan 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 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 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 API Management di jaringan virtual.

Menambahkan atau mengedit nilai bernama

Menambahkan rahasia brankas kunci ke API Management

Lihat Prasyarat untuk integrasi Key Vault.

Penting

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

Perhatian

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

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

2. Di bagian API, pilih Nilai bernama>+Tambahkan.

3. Masukkan pengidentifikasi Nama, dan masukkan Nama tampilan yang digunakan untuk mereferensikan properti dalam kebijakan.

4. Dalam Jenis nilai, pilih Brankas kunci.

5. Masukkan pengidentifikasi rahasia brankas kunci (tanpa versi), atau pilih Pilih untuk memilih rahasia dari brankas kunci.

   Penting

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

6. 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 rahasia dari Key Vault. Jika Anda belum mengonfigurasi akses ke brankas kunci, API Management akan meminta Anda sehingga dapat mengonfigurasi identitas secara otomatis dengan izin yang diperlukan.

7. Tambahkan satu atau beberapa tag opsional untuk membantu menata nilai bernama Anda, kemudian Simpan.

8. Pilih Buat.

   

Menambahkan nilai biasa atau rahasia ke API Management

Portal

1. Di Portal Microsoft Azure, navigasikan ke instans API Management Anda.
2. Di bagian API, pilih Nilai bernama>+Tambahkan.
3. Masukkan pengidentifikasi Nama, dan masukkan Nama tampilan yang digunakan untuk mereferensikan properti dalam kebijakan.
4. Dalam Jenis nilai, pilih Biasa atau Rahasia.
5. Di Nilai, masukkan string atau ekspresi kebijakan.
6. Tambahkan satu atau beberapa tag opsional untuk membantu menata nilai bernama Anda, kemudian Simpan.
7. Pilih Buat.

Setelah nilai bernama dibuat, Anda dapat mengeditnya dengan memilih nama. Jika Anda mengubah nama tampilan, kebijakan apa pun yang mereferensikan nilai bernama akan diperbarui secara otomatis untuk menggunakan nama tampilan baru.

Azure CLI

Untuk mulai menggunakan Azure CLI:

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Mengautentikasi ke Azure menggunakan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan dan mengelola ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan az upgrade.

Untuk menambahkan nilai bernama, gunakan perintah az apim nv create:

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Setelah membuat nilai bernama, Anda dapat memperbaruinya dengan menggunakan perintah az apim nv update. Untuk melihat semua nilai yang diberi nama Anda, gunakan perintah az apim nv list:

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Untuk melihat detail nilai bernama yang Anda buat untuk contoh ini, jalankan perintah az apim nv show:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Contoh ini adalah nilai rahasia. Perintah sebelumnya tidak mengembalikan nilai . Untuk melihat nilainya, jalankan perintah az apim nv show-secret:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Untuk menghapus nilai bernama, gunakan perintah az apim nv delete:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Gunakan nilai yang dinamai

Contoh di bagian ini menggunakan nilai yang diberi nama yang ditampilkan dalam tabel berikut ini.

Nama	Nilai	Rahasia
ContosoHeader	TrackingId	Salah
ContosoHeaderValue	••••••••••••••••••••••	Benar
ExpressionProperty	@(DateTime.Now.ToString())	Salah
ContosoHeaderValue2	This is a header value.	Salah

Untuk menggunakan nilai bernama dalam kebijakan, letakkan nama tampilannya di dalam sepasang kurung kurawal ganda seperti {{ContosoHeader}}, seperti yang diperlihatkan dalam contoh berikut:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

Dalam contoh ini, ContosoHeader digunakan sebagai nama header dalam kebijakan set-header, dan ContosoHeaderValue digunakan sebagai nilai header tersebut. Ketika kebijakan ini dievaluasi selama permintaan atau respons terhadap gateway API Management, {{ContosoHeader}} dan {{ContosoHeaderValue}} diganti dengan nilai masing-masing.

Nilai bernama dapat digunakan sebagai atribut lengkap atau nilai elemen seperti yang diperlihatkan dalam contoh sebelumnya, tetapi juga dapat disisipkan ke dalam atau dikombinasikan dengan bagian dari ekspresi teks literal seperti yang diperlihatkan dalam contoh berikut:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Nilai yang dinamai juga dapat mencakup ekspresi kebijakan. Dalam contoh berikut, ekspresi ExpressionProperty digunakan.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Ketika kebijakan ini dievaluasi, {{ExpressionProperty}} diganti dengan nilainya, @(DateTime.Now.ToString()). Karena nilainya adalah ekspresi kebijakan, ekspresi dievaluasi dan kebijakan dilanjutkan dengan eksekusinya.

Anda dapat menguji ini di portal Microsoft Azure atau portal pengembang dengan memanggil operasi yang memiliki kebijakan dengan nilai bernama dalam lingkup. Dalam contoh berikut, operasi dipanggil dengan dua kebijakan contoh sebelumnya set-header dengan nilai-nilai yang diberi nama. Perhatikan bahwa respons berisi dua header kustom yang dikonfigurasi menggunakan kebijakan dengan nilai yang dinamai.

Jika Anda melihat pelacakan API keluar untuk panggilan yang mencakup dua kebijakan contoh sebelumnya dengan nilai yang dinamai, Anda dapat melihat dua kebijakan set-header dengan nilai yang dinamai tersebut disisipkan, begitu juga evaluasi ekspresi kebijakan untuk nilai yang dinamai yang memuat ekspresi kebijakan.

Interpolasi string juga dapat digunakan dengan nilai yang diberi nama.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Nilai untuk CustomHeader akan menjadi The URL encoded value is This+is+a+header+value..

Perhatian

Jika kebijakan mereferensikan rahasia di Azure Key Vault, nilai dari brankas kunci akan terlihat oleh pengguna yang memiliki akses ke langganan yang diaktifkan untuk penelusuran permintaan API.

Meskipun nilai bernama dapat berisi ekspresi kebijakan, nilai tersebut tidak boleh berisi nilai bernama lainnya. Jika teks yang berisi referensi nilai bernama digunakan untuk angka, seperti Text: {{MyProperty}}, referensi tersebut tidak akan dipecahkan dan digantikan.

Hapus nilai yang diberi nama

Untuk menghapus nilai bernama, pilih nama lalu pilih Hapus dari menu konteks (...).

Penting

Jika nilai bernama direferensikan oleh kebijakan API Management mana pun, Anda tidak dapat menghapusnya hingga Anda menghapus nilai bernama dari semua kebijakan yang menggunakannya.

Konten terkait

• Pelajari selengkapnya tentang bekerja dengan kebijakan
  • Kebijakan di API Management
  • Referensi kebijakan
  • Pernyataan kebijakan