Menggunakan nilai bernama dalam kebijakan Azure API Management

BERLAKU UNTUK: Semua tingkatAN 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 bernama adalah kumpulan pasangan nama/nilai global di setiap instans API Management. Tidak ada batas yang diberlakukan pada jumlah item dalam koleksi. Nilai bernama dapat digunakan untuk mengelola nilai string konstan dan rahasia di seluruh konfigurasi dan kebijakan API.

Jenis nilai

Tipe	Deskripsi
Biasa	String literal atau ekspresi kebijakan
Rahasia	String literal atau ekspresi kebijakan yang dienkripsi oleh API Management
Brankas kunci	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 API Management.

Rahasia key vault

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.

Prasyarat

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

Prasyarat untuk integrasi brankas kunci

• 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, 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 atau mengedit nilai bernama

Menambahkan rahasia brankas kunci ke API Management

Lihat Prasyarat untuk integrasi brankas kunci.

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 pengidentifikasi rahasia brankas kunci sendiri, pastikan bahwa brankas 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 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.

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 Cepat untuk Bash di 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 Masuk dengan Azure CLI.

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

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

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 bernama Anda, jalankan 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

Menggunakan nilai bernama

Contoh di bagian ini menggunakan nilai bernama yang diperlihatkan 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 bernama juga dapat berisi 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 set-header contoh sebelumnya dengan nilai bernama. Perhatikan bahwa respons berisi dua header kustom yang dikonfigurasi menggunakan kebijakan dengan nilai bernama.

Jika Anda melihat jejak API keluar untuk panggilan yang menyertakan dua kebijakan sampel sebelumnya dengan nilai bernama, Anda dapat melihat dua kebijakan set-header dengan nilai bernama yang disisipkan serta evaluasi ekspresi kebijakan untuk nilai bernama yang berisi ekspresi kebijakan.

Interpolasi string juga dapat digunakan dengan nilai bernama.

<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 nilai, seperti Text: {{MyProperty}}, referensi tersebut tidak akan diselesaikan dan diganti.

Menghapus nilai bernama

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.

Langkah berikutnya

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