Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Apa
Dengan kebijakan Kontrol Akses, Anda dapat mengizinkan atau menolak akses ke API dengan alamat IP tertentu.
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.
Contoh
Nilai mask dalam sampel IPv4 berikut mengidentifikasi oktet mana (8, 16, 24, 32
bit) yang dipertimbangkan aturan pencocokan saat mengizinkan atau menolak akses. Nilai defaultnya adalah 32. Lihat atribut
mask
dalam referensi Elemen untuk 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 lainnya.
Menolak menggunakan variabel
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "ALLOW"> <MatchRule action = "DENY"> <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress> </MatchRule> </IPRules> </AccessControl>
Misalnya Anda menggunakan peta nilai kunci (KVM) untuk menyimpan nilai penyamaran dan IP.
Ini adalah pendekatan praktis untuk mengubah IP dan masking 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 bahwa 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>
Tolak semua permintaan dari alamat klien: 198.51.100.*
Izinkan permintaan dari alamat klien lainnya.
198.51.*.*
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "ALLOW"> <MatchRule action = "DENY"> <SourceAddress mask="16">198.51.100.1</SourceAddress> </MatchRule> </IPRules> </AccessControl>
Menolak semua permintaan dari alamat klien: 198.51.*.*
Izinkan permintaan dari alamat klien lainnya.
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 lainnya.
Mengizinkan 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 lainnya.
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.*
Tolak semua alamat lain.
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>
Tolak permintaan dari alamat klien: 198.51.100.* 192.0.2.* 203.0.113.*
Izinkan semua alamat lain.
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 dari daftar yang diizinkan: 198.51.100.* 192.0.2.* 203.0.113.*
Catatan penggunaan
Selain melindungi API Anda dari IP berbahaya, kebijakan Kontrol Akses juga memberi Anda kontrol atas akses IP yang sah. Misalnya, jika hanya ingin komputer di bawah kendali perusahaan Anda mengakses API yang diekspos di lingkungan pengujian, Anda dapat mengizinkan rentang alamat IP untuk jaringan internal. Developer yang bekerja dari rumah dapat mengakses API ini menggunakan VPN.
Konfigurasi dan eksekusi kebijakan Kontrol Akses mencakup hal-hal berikut:
- Tentukan kumpulan aturan pencocokan dengan salah satu dari dua tindakan (ALLOW atau DENY) yang terkait dengan masing-masing tindakan.
- Untuk setiap aturan pencocokan, tentukan alamat IP (elemen SourceAddress).
- Lihat Cara kebijakan memilih alamat IP yang akan dievaluasi untuk menentukan alamat IP pada pesan yang aturannya akan ditangani.
- Konfigurasikan 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 aturan yang diuji.
- Semua aturan pencocokan dijalankan dalam urutan yang ditentukan. Jika aturan cocok, tindakan terkait akan dijalankan dan aturan pencocokan berikut akan dilewati.
- Jika aturan yang sama dikonfigurasi dengan tindakan ALLOW dan DENY, aturan yang ditentukan terlebih dahulu dalam urutan tersebut akan dipicu dan aturan berikutnya (dengan tindakan lainnya) akan dilewati.
Cara kebijakan memilih alamat IP yang akan dievaluasi
Alamat IP dapat berasal dari berbagai sumber dalam permintaan. Misalnya, header pesan True-Client-IP
mungkin berisi alamat IP, dan header X-Forwarded-For
mungkin berisi satu atau beberapa alamat IP. Bagian ini menjelaskan cara mengonfigurasi kebijakan AccessControl untuk mengevaluasi alamat IP yang tepat yang ingin Anda evaluasi.
Berikut adalah logika yang digunakan kebijakan AccessControl untuk menentukan alamat IP yang akan dievaluasi:
1. Header True-Client-IP
Kebijakan ini terlebih dahulu akan memeriksa alamat IP di header True-Client-IP
. Jika
header berisi alamat IP yang valid, kebijakan akan mengevaluasi alamat tersebut.
2. Header X-Forwarded-For
Jika tidak ada header True-Client-IP
, atau jika Anda telah menetapkan elemen
<IgnoreTrueClientIPHeader> ke
true, kebijakan akan mengevaluasi alamat IP di header X-Forwarded-For
.
Edge 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 rantai server yang memproses permintaan. Namun, daftar alamat juga dapat berisi alamat IP spoofing. Jadi, bagaimana kebijakan tersebut mengetahui alamat mana
yang harus dievaluasi?
Konfigurasi organisasi dan konfigurasi kebijakan Anda menentukan alamat
X-Forwarded-For
yang dievaluasi oleh kebijakan.
Pertama, periksa apakah properti feature.enableMultipleXForwardCheckForACL
ditetapkan di organisasi Anda. Anda dapat menggunakan API
Dapatkan organisasi untuk memeriksanya. Kemudian:
- Jika Anda tidak melihat
feature.enableMultipleXForwardCheckForACL
dalam daftar properti organisasi Anda, berarti properti tersebut ditetapkan ke false (default). Dengan properti ini disetel ke salah (false), kebijakan tersebut akan mengevaluasi alamat terakhir di header (terlihat di alat Trace), yang merupakan alamat IP yang diterima Edge dari handshake TCP eksternal terakhir. - Jika
feature.enableMultipleXForwardCheckForACL
di organisasi Anda disetel ke benar (true), konfigurasikan elemen <ValidateBasedOn> untuk menentukan alamat IP yang dievaluasi oleh kebijakan.
Mengubah properti feature.enableMultipleXForwardCheckForACL
Administrator Organisasi Edge dapat menggunakan
Perbarui properti organisasi untuk menetapkan
properti feature.enableMultipleXForwardCheckForACL
.
Contoh API berikut menetapkan properti di Edge untuk Private Cloud. Jika ada properti lain yang ditetapkan di organisasi Anda, pastikan untuk menyertakan properti tersebut. Jika tidak, data tersebut akan dihapus.
curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \ "<Organization type="trial" name="MyOrganization"> <DisplayName>MyOrganization</DisplayName> <Properties> <Property name="feature.enableMultipleXForwardCheckForACL">true</Property> <!-- Include other existing properties as well. --> </Properties> </Organization>"
Di Edge untuk Private Cloud, setelah mengubah nilai properti
feature.enableMultipleXForwardCheckForACL
,
Anda harus memulai ulang pemroses pesan, seperti yang dijelaskan dalam
Memulai/menghentikan/memulai ulang setiap komponen.
Dimensi X-Forwarded-For di analisis Apigee
Edge Analytics menuliskan nilai header X-Forwarded-For
ke
dimensi x_forwarded_for_ip
. Untuk menentukan IP klien yang membuat permintaan ke Edge, gunakan nilai dalam dimensi ax_true_client_ip
atau ax_resolved_client_ip
. Lihat referensi metrik, dimensi, dan filter Analytics untuk informasi selengkapnya.
Tentang penyamaran IP dengan notasi CIDR
Notasi CIDR (Classless Inter-Domain Routing) adalah cara untuk menunjukkan rentang alamat IP melalui masking. Ini berlaku untuk IPv4 dan IPv6. Begini cara kerjanya. Kita akan menggunakan IPv4 dalam contoh kita agar lebih mudah.
Alamat IP adalah kumpulan angka yang dipisahkan oleh 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 berarti 4 kelompok yang masing-masing 8 bit, atau total 32 bit. Dengan CIDR, Anda dapat menunjukkan rentang dengan menambahkan /number (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, "Pertahankan 24 bit pertama persis seperti aslinya, bit yang tersisa dapat berupa nilai apa pun 0 hingga 255". Contoh:
Pertahankan setelan ini persis seperti apa adanya | Nilai yang mungkin untuk grup terakhir |
---|---|
198.51.100. | 0—255 |
Perhatikan bahwa mask terjadi di akhir grup tiga. Fungsi ini akan membuat semuanya tampak bagus dan rapi, intinya membuat mask seperti ini: 198.51.100.*. Pada umumnya, menggunakan kelipatan 8 (IPv4) dan 16 (IPv6) akan memberi Anda level penyamaran yang Anda inginkan:
IPv4: 8, 16, 24, 32
IPv6: 16, 32, 48, 64, 80, 96, 112, 128
Namun, Anda dapat menggunakan angka lain untuk kontrol yang lebih mendetail, yang memerlukan sedikit penghitungan biner. Berikut ini contoh penggunaan mask 30, seperti pada 198.51.100.1/30, dengan 1 terakhir adalah 00000001 dalam biner:
Pertahankan setelan ini persis seperti apa adanya | Nilai yang mungkin |
---|---|
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 Kontrol Akses.
<?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">
Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Wajib |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini sudah tidak digunakan lagi. |
false | Tidak digunakan lagi |
Elemen <DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Ketersediaan | Opsional |
Jenis | String |
Elemen <IgnoreTrueClientIPHeader>
Jika Anda menetapkannya ke benar (true), kebijakan akan mengabaikan header True-Client-IP
dan mengevaluasi alamat IP di header X-Forwarded-For
, mengikuti
perilaku evaluasi X-Forwarded-For yang telah Anda konfigurasi.
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1"> <DisplayName>Access Control-1</DisplayName> <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader> ... </AccessControl>
Default | false |
---|---|
Ketersediaan | Opsional |
Jenis | Boolean |
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 dalam aturan pencocokan Anda.
<IPRules noRuleMatchAction = "ALLOW">
Default | T/A |
---|---|
Ketersediaan | Opsional |
Jenis | T/A |
Atribut
Atribut | Deskripsi | Jenis | Default | Ketersediaan |
---|---|---|---|---|
noRuleMatchAction |
Tindakan yang akan diambil (mengizinkan atau menolak 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 dilakukan (mengizinkan atau menolak akses) jika alamat IP cocok dengan SourceAddress 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 |
---|---|
Ketersediaan | Opsional |
Jenis | T/A |
Atribut
Atribut | Deskripsi | Jenis | Default | Ketersediaan |
---|---|---|---|---|
action |
Tindakan yang akan diambil (mengizinkan atau menolak 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 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 di
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
). Anda kemudian dapat menggunakan variabel tersebut untuk alamat IP:
<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>
Menyetel mask 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 |
---|---|
Ketersediaan | Opsional |
Jenis | String (hanya satu alamat IP) |
Atribut
Atribut | Deskripsi | Jenis | Default | Ketersediaan |
---|---|---|---|---|
masker |
Atribut
setara dengan notasi CIDR berikut: 198.51.100.1/24 Nilai valid: IPv4: 1-32 IPv6: 1-128 Nilai nol (0) hanya berlaku untuk IP 0.0.0.0, sehingga tidak praktis. Menetapkan mask dengan variabel Atribut
|
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 yang dievaluasi.
Gunakan pendekatan ini untuk mengevaluasi alamat IP hanya jika Anda yakin tentang validitas alamat IP yang ingin Anda evaluasi. Misalnya, jika memilih untuk mengevaluasi semua
alamat IP di header X-Forwarded-For
, Anda harus dapat memercayai
validitas alamat tersebut, dan/atau menyiapkan aturan DENY atau ALLOW yang komprehensif untuk mengizinkan hanya IP tepercaya
yang memanggil proxy API Anda.
Alamat IP paling kiri dalam 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 Edge yang diterima dari handshake TCP eksternal terakhir.
Nilai yang dimasukkan 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 |
---|---|
Ketersediaan | Opsional |
Nilai valid |
|
Skema
Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Penyebab | Perbaiki |
---|---|---|---|
accesscontrol.IPDeniedAccess |
403 | Alamat IP klien, atau alamat IP yang diteruskan
dalam permintaan API, cocok dengan alamat IP yang ditentukan dalam elemen <SourceAddress> dalam
elemen <MatchRule> Kebijakan Kontrol Akses, dan atribut action dari elemen
<MatchRule> ditetapkan ke DENY . |
build |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Variabel khusus untuk error kebijakan.
Variabel | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "IPDeniedAccess" |
acl.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | acl.AC-AllowAccess.failed = true |
Contoh respons kesalahan
{ "fault":{ "faultstring":"Access Denied for client ip : 52.211.243.3" "detail":{ "errorcode":"accesscontrol.IPDeniedAccess" } } }
Contoh aturan kesalahan
<FaultRule name="IPDeniedAccess"> <Step> <Name>AM-IPDeniedAccess</Name> <Condition>(fault.name Matches "IPDeniedAccess") </Condition> </Step> <Condition>(acl.failed = true) </Condition> </FaultRule>