Kebijakan AccessControl

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Kebijakan AccessControl memungkinkan Anda mengizinkan atau menolak akses ke API Anda berdasarkan alamat IP tertentu.

Kebijakan ini adalah kebijakan Standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Catatan: Video berikut menunjukkan Editor Proxy klasik di UI Apigee. Apigee memperkenalkan versi baru Editor Proxy, yang memiliki desain berbeda dari versi klasik yang ditampilkan dalam video.

Video: Tonton video singkat untuk mempelajari lebih lanjut cara mengizinkan atau menolak akses ke API Anda berdasarkan alamat IP tertentu.

Meskipun Anda dapat melampirkan kebijakan ini di mana saja dalam alur proxy API, kemungkinan besar Anda ingin memeriksa alamat IP di awal alur ( Request / ProxyEndpoint / PreFlow), bahkan sebelum autentikasi atau pemeriksaan kuota.

Anda juga harus mempertimbangkan untuk menggunakan Google Cloud Armor dengan Apigee sebagai cara alternatif untuk mengamankan API Anda.

Sampel

Nilai mask dalam contoh IPv4 berikut mengidentifikasi mana dari empat oktet (8, 16, 24, 32 bit) yang dipertimbangkan oleh aturan pencocokan saat mengizinkan atau menolak akses. Nilai defaultnya adalah 32. Lihat atribut mask di referensi Elemen untuk mengetahui informasi selengkapnya.

Tolak 198.51.100.1

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Tolak semua permintaan dari alamat klien: 198.51.100.1

Izinkan permintaan dari alamat klien lain.

Menolak penggunaan variabel

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

Misalkan Anda menggunakan peta nilai kunci (KVM) untuk menyimpan nilai untuk penyamaran dan IP. Ini adalah pendekatan praktis untuk mengubah dan menyamarkan IP selama runtime tanpa harus mengupdate dan men-deploy ulang proxy API Anda. Anda dapat menggunakan kebijakan KeyValueMapOperations untuk mengambil variabel yang berisi nilai untuk kvm.mask.value dan kvm.ip.value (dengan asumsi itulah nama variabel dalam kebijakan KVM yang berisi nilai mask dan nilai IP dari KVM). Jika nilai yang Anda ambil adalah 24 untuk mask dan 198.51.100.1 untuk alamat IP, kebijakan AccessControl akan menolak semua permintaan dari: 198.51.100.*

Semua alamat klien lainnya akan diizinkan.

Tolak 198.51.100.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

Menolak semua permintaan dari alamat klien: 198.51.100.*

Izinkan permintaan dari alamat klien lain.

198.51.*.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
       <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Tolak semua permintaan dari alamat klien: 198.51.*.*

Izinkan permintaan dari alamat klien lain.

Tolak 198.51.100.*, izinkan 192.0.2.1

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="32">192.0.2.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Tolak semua permintaan dari alamat klien: 198.51.100.*, tetapi izinkan 192.0.2.1.

Izinkan permintaan dari alamat klien lain.

Izinkan 198.51.*.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Izinkan semua permintaan dari alamat: 198.51.*.*

Menolak permintaan dari alamat klien lain.

Mengizinkan beberapa IP

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
     </MatchRule>
  </IPRules>
</AccessControl>

Izinkan permintaan dari alamat klien: 198.51.100.* 192.0.2.* 203.0.113.*

Menolak semua alamat lainnya.

Menolak beberapa IP

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Menolak permintaan dari alamat klien: 198.51.100.* 192.0.2.* 203.0.113.*

Izinkan semua alamat lainnya.

Mengizinkan beberapa IP, menolak beberapa IP

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
      <SourceAddress mask="16">192.0.2.1</SourceAddress>
      <SourceAddress mask="16">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

Izinkan: 198.51.*.* 192.0.*.* 203.0.*.*

Menolak subset daftar yang diizinkan: 198.51.100.* 192.0.2.* 203.0.113.*

---

Catatan penggunaan

Selain melindungi API Anda dari IP berbahaya, kebijakan AccessControl juga memberi Anda kontrol atas akses IP yang sah. Misalnya, jika Anda hanya ingin komputer di bawah kontrol perusahaan Anda mengakses API yang diekspos di lingkungan pengujian, Anda dapat mengizinkan rentang alamat IP untuk jaringan internal Anda. Developer yang bekerja dari rumah dapat mengakses API ini menggunakan VPN.

Catatan: Jika Anda menggunakan tindakan keamanan dan kebijakan AccessControl untuk mengelola traffic berdasarkan alamat IP, tindakan keamanan akan selalu dieksekusi sebelum kebijakan AccessControl. Setelah itu, keduanya tidak akan saling memengaruhi; tindakan keamanan tidak memengaruhi kebijakan AccessControl dan sebaliknya.

Konfigurasi dan eksekusi kebijakan AccessControl melibatkan hal berikut:

• Tentukan serangkaian aturan pencocokan dengan salah satu dari dua tindakan (IZINKAN atau TOLAK) yang terkait dengan masing-masing aturan.
• Untuk setiap aturan kecocokan, tentukan alamat IP (elemen SourceAddress).
  • Lihat Cara kebijakan memilih alamat IP yang akan dievaluasi untuk menentukan alamat IP dalam pesan yang akan ditangani oleh aturan yang Anda konfigurasi.
  • Konfigurasi mask untuk setiap alamat IP. Anda mengizinkan atau menolak akses berdasarkan nilai mask pada alamat IP. Lihat Tentang penyamaran IP dengan notasi CIDR.
• Tentukan urutan pengujian aturan.
• Semua aturan pencocokan dijalankan dalam urutan yang diberikan. Jika aturan cocok, tindakan yang sesuai akan dijalankan dan aturan kecocokan berikutnya akan dilewati.
  • Jika aturan yang sama dikonfigurasi dengan tindakan IZINKAN dan TOLAK, aturan yang ditentukan terlebih dahulu dalam urutan akan dipicu dan aturan berikutnya (dengan tindakan lain) akan dilewati.

Cara kebijakan memilih alamat IP yang akan dievaluasi

Alamat IP dapat berasal dari berbagai sumber dalam permintaan. Misalnya, header X-Forwarded-For dapat berisi satu atau beberapa alamat IP. Bagian ini menjelaskan cara mengonfigurasi kebijakan AccessControl untuk mengevaluasi alamat IP yang tepat yang ingin Anda evaluasi.

Untuk Apigee hybrid, sebaiknya siapkan load balancer di depan cluster Kubernetes Anda. Load balancer dapat berupa L7 (HTTP-aware) atau L4 (TCP-aware). Load balancer L7 dapat menambahkan alamat IP sumber klien ke header X-Forwarded-For (XFF). Load balancer L4 harus dikonfigurasi untuk menggunakan protokol PROXY. Lihat panduan load balancer Anda tentang cara mengaktifkan dukungan protokol PROXY. Untuk mengaktifkan protokol PROXY di Ingress, lihat Alamat IP sumber klien asli dalam dokumentasi Istio.

Berikut adalah logika yang digunakan kebijakan AccessControl untuk memutuskan alamat IP mana yang akan dievaluasi:

Header X-Forwarded-For

Apigee otomatis mengisi header X-Forwarded-For dengan alamat IP yang diterima dari handshake TCP eksternal terakhir (seperti IP klien atau router). Jika ada beberapa alamat IP di header, alamat tersebut kemungkinan merupakan rangkaian server yang memproses permintaan. Namun, daftar alamat juga dapat berisi alamat IP yang dipalsukan. Jadi, bagaimana kebijakan mengetahui alamat mana yang harus dievaluasi?

Dimensi X-Forwarded-For dalam analisis Apigee

Apigee Analytics menulis nilai header X-Forwarded-For ke dimensi x_forwarded_for_ip. Untuk menentukan IP klien yang membuat permintaan ke Apigee, gunakan nilai dalam dimensi ax_resolved_client_ip, tetapi kecualikan ax_true_client_ip, yang tidak didukung dengan kebijakan AccessControl. Lihat Referensi metrik, dimensi, dan filter Analytics.

Tentang penyamaran IP dengan notasi CIDR

Notasi CIDR (Classless Inter-Domain Routing) adalah cara untuk menunjukkan rentang alamat IP melalui masking. Hal ini berlaku untuk IPv4 dan IPv6. Begini cara kerjanya. Kita akan menggunakan IPv4 dalam contoh untuk mempermudah.

Alamat IP adalah kelompok angka yang dipisahkan dengan titik. Dalam istilah biner, setiap grup adalah jumlah bit tertentu (8 untuk IPv4 dan 16 untuk IPv6). Alamat IPv4 198.51.100.1 terlihat seperti ini dalam biner:

11000110.00110011.01100100.00000001

Itu adalah 4 grup 8 bit, atau total 32 bit. Dengan CIDR, Anda dapat menunjukkan rentang dengan menambahkan /angka (1-32) ke alamat IP, seperti ini:

198.51.100.1/24

Dalam hal ini, 24 adalah angka yang akan Anda gunakan untuk nilai atribut mask dalam kebijakan ini.

Notasi ini berarti, "Biarkan 24 bit pertama apa adanya, bit yang tersisa dapat berupa nilai 0 hingga 255." Contoh:

Biarkan apa adanya	Kemungkinan nilai untuk grup terakhir
198.51.100.	0 - 255

Perhatikan bahwa mask terjadi di akhir grup tiga. Hal ini membuat semuanya menjadi rapi dan teratur, pada dasarnya membuat mask seperti ini: 198.51.100.*. Dalam sebagian besar kasus, menggunakan kelipatan 8 (IPv4) dan 16 (IPv6) akan memberi Anda tingkat masking yang diinginkan:

IPv4: 8, 16, 24, 32

IPv6: 16, 32, 48, 64, 80, 96, 112, 128

Namun, Anda dapat menggunakan angka lain untuk kontrol yang lebih terperinci, yang melibatkan sedikit penghitungan biner. Berikut adalah contoh yang menggunakan mask 30, seperti pada 198.51.100.1/30, dengan 1 terakhir adalah 00000001 dalam biner:

Biarkan apa adanya	Nilai yang memungkinkan
11000110.00110011.01100100.000000 (30 bit pertama)	00000000, 00000001, 00000010, atau 00000011
198.51.100.	0, 1, 2, atau 3

Dalam contoh ini, dengan konfigurasi yang ditetapkan ke <SourceAddress mask="30">198.51.100.1</SourceAddress>, IP berikut akan diizinkan (atau ditolak, bergantung pada aturan Anda):

• 198.51.100.0
• 198.51.100.1
• 198.51.100.2
• 198.51.100.3

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan AccessControl.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "ALLOW">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
        <MatchRule action = "DENY">
            <SourceAddress mask="24">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

Atribut <AccessControl>

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">

Elemen <ClientIPVariable>

Menentukan variabel alur yang berisi alamat IP yang diperiksa oleh kebijakan terhadap IPRules. Jika variabel alur tidak berisi alamat IP yang valid (ipv4 atau ipv6), kebijakan akan memunculkan error.

Catatan: Anda dapat menggunakan variabel alur client.resolved.ip untuk alamat IP klien. Lihat Penyelesaian IP klien untuk mengetahui informasi tentang cara alamat IP klien ditentukan untuk variabel tersebut.

Misalkan variabel alur ditetapkan ke 12.31.34.52. Pada contoh berikut, akses ditolak. Jika variabel disetel ke 10.11.12.13, akses akan diberikan.

<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>

Default	T/A
Kehadiran	Opsional
Jenis	Variabel alur

Elemen <IgnoreTrueClientIPHeader>

Catatan: Saat ini, jika Anda tidak menyertakan elemen ini atau menyetel elemen ini ke salah (false), Apigee tidak akan mengevaluasi header True-Client-IP dengan benar.

Elemen <IPRules>

Elemen induk yang berisi aturan yang mengizinkan atau menolak alamat IP. Atribut noRuleMatchAction memungkinkan Anda menentukan cara menangani alamat IP yang tidak tercakup oleh aturan pencocokan Anda.

<IPRules noRuleMatchAction = "ALLOW">

Default	T/A
Kehadiran	Opsional
Jenis	T/A

Atribut

Atribut	Deskripsi	Jenis	Default	Kehadiran
noRuleMatchAction	Tindakan yang harus dilakukan (izinkan atau tolak akses) jika aturan kecocokan yang ditentukan tidak diselesaikan (tidak cocok). Nilai yang valid: ALLOW atau DENY	String	IZINKAN	Wajib

Elemen <IPRules>/<MatchRule>

Tindakan yang harus diambil (izinkan atau tolak akses) jika alamat IP cocok dengan SourceAddress(es) yang Anda tentukan.

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
</IPRules>

Default	T/A
Kehadiran	Opsional
Jenis	T/A

Atribut

Atribut	Deskripsi	Jenis	Default	Kehadiran
tindakan	Tindakan yang harus dilakukan (izinkan atau tolak akses) jika aturan kecocokan yang ditentukan tidak diselesaikan (tidak cocok). Nilai yang valid: ALLOW atau DENY	String	IZINKAN	Wajib

Elemen <IPRules>/<MatchRule>/<SourceAddress>

Rentang alamat IP klien.

Nilai yang valid: Alamat IP yang valid (notasi desimal bertitik). Untuk perilaku karakter pengganti, gunakan atribut mask.

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="{variable}">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">{variable}</SourceAddress>
    </MatchRule>
</IPRules>

Seperti yang ditunjukkan dalam contoh sebelumnya, elemen SourceAddress juga mendukung Template pesan untuk atribut mask atau alamat IP, yang berarti Anda dapat menetapkan nilai menggunakan variabel yang saat ini tersedia dalam alur proxy API.

Misalnya, Anda dapat menyimpan alamat IP di peta nilai kunci (KVM) dan menggunakan kebijakan KeyValueMapOperations untuk mengambil alamat IP dan menetapkannya ke variabel (seperti kvm.ip.value). Kemudian, Anda dapat menggunakan variabel tersebut untuk alamat IP:

<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>

Menetapkan masker dan/atau alamat IP dengan variabel memberi Anda fleksibilitas untuk mengubah nilai saat runtime tanpa harus mengubah dan men-deploy ulang proxy API.

Default	T/A
Kehadiran	Opsional
Jenis	String (hanya satu alamat IP)

Atribut

Atribut	Deskripsi	Jenis	Default	Kehadiran
masker	Atribut mask adalah cara untuk menunjukkan rentang alamat IP yang akan diizinkan atau ditolak. Maskara setara dengan penggunaan notasi CIDR (Classless Inter-Domain Routing). Contoh: <SourceAddress mask="24">198.51.100.1</SourceAddress> setara dengan notasi CIDR berikut: 198.51.100.1/24 Nilai valid: IPv4: 1-32 IPv6: 1-128 Nilai nol (0) hanya valid untuk IP 0.0.0.0, sehingga tidak praktis. Menetapkan mask dengan variabel Atribut mask juga mendukung Template pesan, yang berarti Anda dapat menyetel nilai dengan variabel yang saat ini tersedia di alur proxy API. Misalnya, Anda dapat menyimpan nilai mask di KVM dan menggunakan kebijakan KeyValueMapOperations untuk mengambil mask dan menetapkannya ke variabel. Untuk menyetel mask IP dengan variabel, gunakan format berikut, dengan asumsi variabel diberi nama kvm.mask.value: mask="{kvm.mask.value}"	Bilangan bulat	T/A	Wajib

Elemen <ValidateBasedOn>

Jika header HTTP X-Forwarded-For berisi beberapa alamat IP, gunakan elemen ValidateBasedOn ini untuk mengontrol alamat IP mana yang dievaluasi.

Catatan: Saat ini, Anda harus menyetel elemen <IgnoreTrueClientIPHeader> ke benar (true) agar beberapa alamat IP dapat dievaluasi.

Gunakan pendekatan ini untuk mengevaluasi alamat IP hanya jika Anda yakin dengan validitas alamat IP yang ingin Anda evaluasi. Misalnya, jika Anda memilih untuk mengevaluasi semua alamat IP di header X-Forwarded-For, Anda harus dapat memercayai validitas alamat tersebut, dan/atau menyiapkan aturan TOLAK atau IZINKAN yang komprehensif agar hanya IP tepercaya yang dapat memanggil proxy API Anda.

Catatan: Anda dapat menggunakan variabel alur client.resolved.ip untuk alamat IP klien di <clientIPVariable>, bukan menggunakan <ValidateBasedOn>. Lihat elemen <ClientIPVariable>.

Alamat IP paling kiri di header adalah milik klien, dan yang paling kanan adalah server yang meneruskan permintaan ke layanan saat ini. Alamat IP paling kanan, atau terakhir, adalah alamat yang diterima Apigee dari handshake TCP eksternal terakhir.

Nilai yang Anda masukkan dalam elemen ini memungkinkan Anda menentukan apakah akan memeriksa semua alamat IP di header (default), hanya alamat IP pertama, atau hanya alamat IP terakhir.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "DENY">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

Default	X_FORWARDED_FOR_ALL_IP
Kehadiran	Opsional
Nilai valid	X_FORWARDED_FOR_ALL_IP (default) X_FORWARDED_FOR_FIRST_IP X_FORWARDED_FOR_LAST_IP

Skema

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
accesscontrol.IPDeniedAccess	403	The client IP address, or an IP address passed in the API request, matches an IP address specified in the <SourceAddress> element within the <MatchRule> element of the Access Control Policy, and the action attribute of the <MatchRule> element is set to DENY.
accesscontrol.InvalidIPAddressInVariable	500	The flow variable in <ClientIPVariable> contains an invalid IP address.

Fault variables

These variables are set when a runtime error occurs. For more information, see Variables specific to policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "IPDeniedAccess"
acl.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	acl.AC-AllowAccess.failed = true

Example fault response

Note: For fault handling, the best practice is to trap the errorcode part of the fault response. Do not rely on the text in the faultstring because it could change.

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"steps.accesscontrol.IPDeniedAccess"
      }
   }
}

Example fault rule

<FaultRule name="IPDeniedAccess">
    <Step>
        <Name>AM-IPDeniedAccess</Name>
        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>
    </Step>
    <Condition>(acl.failed = true) </Condition>
</FaultRule>