Palo Alto XML API Yapılandırması: SignLogger Entegrasyonu iç

Bu rehber, Palo Alto Networks güvenlik duvarı ile SignLogger arasında XML API üzerinden çalışan bir bağlantının güvenlik duvarı tarafında nasıl hazırlanacağını adım adım anlatır. Amaç, SignLogger'ın misafir ağında kimlik doğrulayan kullanıcıları güvenlik duvarına IP-kullanıcı eşleşmesi (User-ID mapping) olarak bildirebilmesi, gerektiğinde oturum kapatma bilgisini iletebilmesi ve güvenlik duvarından bilgi çekebilmesidir. Palo Alto'nun resmi dokümantasyonu, harici sistemlerin PAN-OS üzerindeki tümleşik User-ID aracına oturum açma ve kapatma olaylarını XML API ile gönderebileceğini açıkça belirtir; bu rehber de tam olarak bu yolu izler.

Rehberde geçen tüm IP adresleri, arayüz adları, kullanıcı adları ve profil isimleri bir laboratuvar ortamından alınmış örneklerdir. Kendi kurulumunuzda bunları kendi ağ planınıza göre değiştirmeniz gerekir. Örnek ortamda güvenlik duvarı PA-445 modeli ve PAN-OS 11.1.13 sürümüdür; ancak anlatılan menüler ve mantık PAN-OS 10.x ve 11.x sürümlerinin tamamında büyük ölçüde aynıdır.

Bu doküman, daha önce hazırladığımız Captive Portal (Authentication Portal) ve RADIUS yapılandırma rehberinin devamı niteliğindedir. Captive Portal tarafı çalışır durumdayken API bağlantısı, portalda kimliğini doğrulayan kullanıcının güvenlik duvarında da isimle görünmesini, politikaların kullanıcı bazlı yazılabilmesini ve loglarda kullanıcı adının yer almasını sağlar. API tarafındaki testleri SignLogger arayüzünden yapacağınız için, burada yalnızca Palo Alto tarafında yapılması gereken ayarlara odaklanıyoruz.

Palo Alto XML API Nedir ve SignLogger Entegrasyonunda Ne İşe Yarar?

PAN-OS XML API, güvenlik duvarının web arayüzünden yaptığınız hemen her işlemi HTTPS üzerinden programatik olarak yapmanıza izin veren bir arayüzdür. İstekler güvenlik duvarının /api/ yoluna gönderilir, cevaplar XML olarak döner. Yapılandırma okuma ve yazma, operasyonel komut çalıştırma, commit tetikleme, log ve rapor çekme, dosya import ve export etme ve User-ID eşleşmesi gönderme gibi kategoriler bu arayüz üzerinden kullanılabilir.

SignLogger entegrasyonunda bu arayüzün en önemli kullanım alanı User-ID kategorisidir. Misafir bir kullanıcı SignLogger'ın kimlik doğrulama sayfasından giriş yaptığında, SignLogger bu kullanıcının IP adresi ile kullanıcı adını eşleştiren bir mesajı güvenlik duvarına gönderir. Güvenlik duvarı bu eşleşmeyi kendi User-ID tablosuna yazar. Böylece trafik loglarında ve raporlarda IP adresinin yanında kullanıcı adı da görünür, güvenlik politikalarında kullanıcı veya grup bazlı kural yazmak mümkün olur. Kullanıcı oturumunu kapattığında veya süresi dolduğunda aynı arayüzle eşleşme kaldırılabilir.

Bu bağlantının kurulabilmesi için Palo Alto tarafında üç temel şartın sağlanması gerekir. Birincisi, API kullanımı için yetkilendirilmiş bir yönetici hesabı ve bu hesaba atanmış bir yönetici rol profili olmalıdır. İkincisi, bu hesabın kullanıcı adı ve şifresiyle bir API anahtarı (API key) üretilmiş olmalıdır. Üçüncüsü, SignLogger sunucusunun güvenlik duvarının yönetim arayüzüne ağ seviyesinde erişebilmesi ve o arayüzde HTTPS servisinin açık olması gerekir. Rehberin geri kalanı bu üç şartı sağlayacak ayarları sırayla anlatıyor.

Örnek Laboratuvar Ortamı ve Adresleme Planı

Bu rehberdeki ekran görüntüleri aşağıdaki laboratuvar ortamından alınmıştır. Kendi ortamınıza uyarlarken tüm değerleri kendi ağınıza göre değiştirin.

Güvenlik duvarı modeli ve sürümü: PA-445, PAN-OS 11.1.13
API isteklerinin gönderildiği güvenlik duvarı adresi: 10.254.253.244 (ethernet1/2 veri arayüzü üzerinde, trust bölgesi)
MGT (out-of-band yönetim) arayüzü: 192.168.1.1
SignLogger sunucusu: 10.100.100.253 (portal ve API istemcisi)
Misafir ağı: 172.16.1.0/24, geçit 172.16.1.1 (ethernet1/2.71, Guest bölgesi)
Kurumsal ağ: 172.16.0.0/24, geçit 172.16.0.1 (ethernet1/2.70, trust bölgesi)
API için oluşturulan yönetici hesabı: apiadmin
API için oluşturulan yönetici rol profili: apirole

Buradaki en kritik ayrıntı, API isteklerinin hangi arayüze gönderileceğidir. Palo Alto güvenlik duvarlarında varsayılan yönetim yolu ayrı bir MGT arayüzüdür ve bu arayüz genellikle veri düzlemindeki ağlardan erişilemez. Bu laboratuvarda SignLogger'ın eriştiği 10.254.253.244 adresi MGT değil, ethernet1/2 veri arayüzü üzerindedir. Bir veri arayüzünden yönetim ve API erişimi verilebilmesi için o arayüze bir Interface Management Profile atanması ve profilde HTTPS servisinin işaretlenmesi şarttır. Bu ayrıntı atlandığında API istekleri hiç cevap almadan zaman aşımına düşer ve sorun çoğu zaman kimlik doğrulama problemi sanılır.

Ön Koşullar

Başlamadan önce aşağıdaki maddelerin hazır olması işi çok kolaylaştırır.

Güvenlik duvarının web arayüzüne superuser yetkisine sahip bir hesapla erişim. Yönetici hesabı ve rol profili oluşturmak, yönetim arayüzü ayarlarını değiştirmek ve commit yapmak için bu yetki gerekir.
SignLogger sunucusunun IP adresi. Bu adresi hem izin listelerinde hem de güvenlik politikalarında kullanacaksınız.
SignLogger'ın güvenlik duvarına hangi IP adresi üzerinden ulaşacağının netleştirilmesi. MGT arayüzü mi, bir veri arayüzü mü?
Captive Portal (Authentication Portal) yapılandırmasının çalışır durumda olması. Zorunlu değildir ama entegrasyonun anlamlı sonuç vermesi için önerilir.
Yapılandırmaya başlamadan önce Device > Setup > Operations menüsünden çalışan yapılandırmanın yedeğinin alınması. Geri dönmek gerekirse en hızlı yol budur.

Adım 1: API Erişimi İçin Özel Yönetici Rol Profili (Admin Role Profile) Oluşturma

Palo Alto'nun resmi dokümantasyonunda API erişimi için açık bir en iyi uygulama tavsiyesi vardır: XML API erişimi için ayrı bir yönetici hesabı kullanın. Bunun nedeni yalnızca düzen değildir. Ayrı hesap sayesinde API trafiği denetim kayıtlarında insan yöneticilerin işlemlerinden ayrı görünür, hesabın yetkileri yalnızca ihtiyacı olan kategorilerle sınırlanabilir ve bir güvenlik olayında yalnızca o hesabın anahtarı iptal edilerek entegrasyon durdurulabilir. Aynı şekilde bir insan yöneticinin şifresi değiştiğinde entegrasyon bozulmaz.

Ayrı hesabın yetkilerini belirlemek için önce bir yönetici rol profili oluşturmak gerekir. Güvenlik duvarının web arayüzünde Device > Admin Roles yoluna gidin ve sayfanın altındaki Add düğmesine basın. Örnek ortamda bu profile apirole adı verilmiştir. Profil oluşturulurken Role alanında kapsam seçilir: Device seçeneği profili tüm cihaz için geçerli kılar, Virtual System seçeneği ise yetkiyi belirli bir sanal sisteme sınırlar. Tek vsys kullanan tipik kurulumlarda Device kapsamı yeterlidir.

Görsel 1: Device > Admin Roles sayfası ve API için oluşturulan apirole profili.

XML API Sekmesindeki İzinler

Rol profili penceresinde dört sekme bulunur: Web UI, XML API, Command Line ve REST API. Entegrasyonun kalbi XML API sekmesidir. Bu sekmede Web UI sekmesinden farklı olarak yalnızca Enable ve Disable seçenekleri vardır; Read Only diye bir orta seçenek yoktur. Yani bir kategoriyi ya tamamen açarsınız ya tamamen kapatırsınız.

Sekmedeki kategoriler ve SignLogger entegrasyonundaki anlamları şöyledir.

User-ID Agent: Entegrasyonun zorunlu kategorisidir. SignLogger'ın IP-kullanıcı eşleşmesi gönderebilmesi için bu kategori Enable olmalıdır. Kapalı kalması durumunda API anahtarı doğru olsa bile güvenlik duvarı yetki hatası döner.
Operational Requests: show ve clear ile başlayan operasyonel komutları çalıştırma yetkisidir. SignLogger'ın mevcut eşleşme tablosunu okuması, sistem bilgisini sorgulaması veya bir eşleşmeyi temizlemesi için gerekir. Doğrulama ve sorun giderme açısından açılması kuvvetle önerilir.
Configuration: Çalışan veya aday yapılandırmayı okuma ve yazma yetkisidir. SignLogger'ın güvenlik duvarı üzerinde nesne, adres grubu ya da politika güncellemesi yapması planlanıyorsa gerekir. Yalnızca User-ID gönderimi yapılacaksa kapalı bırakılabilir.
Commit: Yapılandırma değişikliklerini çalışan yapılandırmaya uygulama yetkisidir. Configuration yetkisi verildiyse anlamlıdır; aksi halde gerek yoktur. User-ID eşleşmeleri çalışma zamanı verisi olduğu için commit gerektirmez.
Log ve Report: Trafik, tehdit ve kimlik doğrulama loglarını sorgulama ve rapor üretme yetkileridir. SignLogger üzerinden raporlama veya 5651 kapsamında kayıt eşleştirmesi yapılacaksa açılması gerekir.
Import ve Export: Sertifika, yanıt sayfası ve benzeri dosyaları güvenlik duvarına yükleme ve indirme yetkileridir. SignLogger'ın ürettiği comfort page dosyasının API ile yüklenmesi gibi senaryolarda gerekir.
IoT Agent: IoT Security aboneliğiyle ilgilidir ve bu entegrasyonda kullanılmaz.

Örnek laboratuvarda tüm test senaryolarının önü açık olsun diye apirole profilinde XML API sekmesindeki tüm kategoriler Enable bırakılmıştır. Canlı ortamda ise en az yetki ilkesini uygulayarak yalnızca gerçekten kullanılan kategorileri açık tutmanızı öneririm. Örneğin sadece User-ID gönderimi yapılacaksa User-ID Agent ve Operational Requests kategorileri çoğu zaman yeterlidir.

Görsel 2: Admin Role Profile penceresi, XML API sekmesi ve kategori bazında Enable/Disable seçenekleri.

Web UI, Command Line ve REST API Sekmeleri

Command Line sekmesi, hesabın SSH veya konsol üzerinden CLI erişiminde hangi seviyede yetkili olacağını belirler. Seçenekler None, superuser, superreader, vsysadmin ve vsysreader şeklindedir. Bir API hesabının komut satırına girmesine ihtiyaç yoktur; bu nedenle en güvenli tercih None seçeneğidir. Örnek ortamda da None seçilmiştir. Böylece API anahtarı veya şifre ele geçse bile bu hesapla CLI üzerinden işlem yapılamaz.

Web UI sekmesi, hesabın web arayüzünde hangi menüleri görebileceğini belirler. XML API kullanımı için bu sekmedeki izinlerin açık olması gerekmez. Bununla birlikte, sorun giderme sırasında aynı hesapla arayüze girip loglara bakmak isterseniz Monitor ve bazı Device bölümlerini Read Only olarak açık bırakabilirsiniz. Örnek laboratuvarda kolaylık olsun diye tüm Web UI izinleri Enable durumdadır; canlı ortamda bunu kısmanız önerilir.

REST API sekmesi, PAN-OS'un JSON tabanlı REST arayüzünü kapsar. XML API'den ayrı bir izin kümesidir. SignLogger yalnızca XML API kullanıyorsa bu sekme kapalı kalabilir; ileride REST üzerinden nesne veya politika yönetimi planlanıyorsa ilgili kaynaklar buradan açılır.

Görsel 3: Admin Role Profile penceresi, Command Line sekmesi ve None seçimi.

Görsel 4: Admin Role Profile penceresi, REST API sekmesi ve kaynak bazında izinler.

Adım 2: API İçin Ayrı Bir Yönetici Hesabı (Administrator) Oluşturma

Rol profili hazır olduğuna göre sıra bu profili kullanacak hesabı oluşturmaya geldi. Device > Administrators yoluna gidin ve Add düğmesine basın. Açılan pencerede aşağıdaki alanları doldurun.

Name: Hesabın kullanıcı adı. Örnek ortamda apiadmin kullanılmıştır. Bu adı API anahtarı üretirken ve SignLogger tarafında tanımlarken kullanacaksınız. Sonradan değiştirmek kolay olmadığı için baştan anlamlı bir ad seçin.
Authentication Profile: Hesabın LDAP, RADIUS, TACACS+ veya SAML gibi harici bir kaynakla doğrulanmasını istiyorsanız buradan bir profil seçilir. API hesaplarının harici kimlik doğrulamaya bağlı olması önerilmez, çünkü harici sunucu erişilemez olduğunda entegrasyon durur. Örnek ortamda None seçilmiş ve yerel bir şifre tanımlanmıştır.
Password ve Confirm Password: Güçlü ve yalnızca bu hesaba özel bir şifre girin. Şifreyi yalnızca API anahtarı üretirken kullanacaksınız; SignLogger'a şifre yazılmaz, anahtar yazılır.
Administrator Type: Role Based seçeneğini işaretleyin. Dynamic seçeneği superuser gibi hazır rolleri verir ve API hesabı için fazla geniştir.
Profile: Adım 1'de oluşturduğunuz rol profilini seçin. Örnek ortamda apirole seçilmiştir.
Password Profile: Kurumsal politikanız gereği şifrelerin belirli aralıklarla değişmesi gerekiyorsa buradan bir profil atanabilir. Ancak dikkat: bu hesabın şifresi her değiştiğinde mevcut API anahtarları geçersiz olur ve yeni anahtar üretip SignLogger'a girmeniz gerekir. Bu nedenle API hesaplarına şifre süresi profili atamadan önce süreç planlaması yapmanızı öneririm.

Pencereyi OK ile kapattıktan sonra değişiklik henüz aday yapılandırmadadır. Sağ üstteki Commit düğmesine basıp değişikliği çalışan yapılandırmaya uygulayana kadar hesap gerçekten aktif olmaz ve bu hesapla API anahtarı üretilemez. Commit'i atlamak, bu adımda en sık yapılan hatadır.

Görsel 5: Device > Administrators sayfası ve API için oluşturulan apiadmin hesabı.

Görsel 6: Administrator penceresi. Administrator Type Role Based, Profile ise apirole seçilmiştir.

Adım 3: Yönetim ve API Erişiminin Ağ Katmanında Açılması

Hesap ve rol hazır olsa bile, SignLogger sunucusu güvenlik duvarına ağ seviyesinde ulaşamıyorsa hiçbir API isteği cevap alamaz. PAN-OS'ta yönetim düzlemi erişimi iki farklı yerden kontrol edilir ve hangi adrese istek gönderdiğinize göre bunlardan biri devreye girer.

Seçenek A: MGT Arayüzü Üzerinden Erişim

Device > Setup > Interfaces yoluna gidin ve listedeki Management satırına tıklayın. Açılan Management Interface Settings penceresinde üç grup ayar bulunur.

IP adresleme: IP Type olarak Static veya DHCP Client seçilir. Örnek ortamda MGT arayüzü 192.168.1.1 statik adresiyle yapılandırılmıştır.
Services: Bu arayüz üzerinden hangi yönetim servislerinin dinleneceğini belirler. XML API için HTTPS kutusunun işaretli olması zorunludur, çünkü API istekleri HTTPS üzerinden gelir. HTTP seçeneğini açmamak en iyisidir; API anahtarı şifrelenmemiş bağlantıda açık metin olarak taşınır. Ping seçeneği erişim testleri için pratiktir. Telnet kesinlikle kapalı kalmalıdır.
Permitted IP Addresses: Bu liste boş bırakıldığında tüm kaynaklardan yönetim erişimi kabul edilir. Listeye tek bir kayıt eklendiği anda liste bir beyaz liste haline gelir ve yalnızca oradaki adresler erişebilir. Bu nedenle SignLogger sunucusunun adresini eklerken kendi yönetim istasyonunuzun adresini veya ağınızı da eklemeyi unutmayın; aksi halde commit sonrası kendinizi arayüzden kilitleyebilirsiniz. Örnek laboratuvarda bu liste boştur; canlı ortamda mutlaka doldurulması önerilir.

Görsel 7: Device > Setup > Interfaces sayfası ve Management satırı.

Görsel 8: Management Interface Settings penceresi. HTTPS servisi açık, Permitted IP Addresses listesi boş.

Seçenek B: Veri Arayüzü Üzerinden Erişim ve Interface Management Profile

Çoğu gerçek kurulumda SignLogger sunucusu MGT ağında değildir. Bu durumda API isteklerini bir veri arayüzünün IP adresine göndermek gerekir. Örnek laboratuvarda SignLogger'ın hedefi 10.254.253.244 adresidir ve bu adres ethernet1/2 arayüzüne aittir. Bir veri arayüzünün yönetim isteklerini kabul etmesi için o arayüze bir Interface Management Profile atanması zorunludur. Profil atanmamış bir veri arayüzü, doğru API anahtarıyla gelen istekleri bile sessizce düşürür.

Önce Network > Interfaces sayfasından hangi arayüzün hangi IP adresini ve hangi yönetim profilini taşıdığını görün. Bu sayfada Management Profile kolonu, arayüze atanmış profili gösterir. Örnek ortamda ethernet1/2 arayüzü 10.254.253.244/24 adresine sahip, trust bölgesinde ve Allow-Ping adında bir yönetim profili atanmış durumdadır. Aynı fiziksel arayüz üzerinde iki alt arayüz de vardır: ethernet1/2.70 kurumsal ağ için 172.16.0.1/24, ethernet1/2.71 ise misafir ağı için 172.16.1.1/24 adresini taşır.

Görsel 9: Network > Interfaces sayfası. ethernet1/2 arayüzü, IP adresi, bölgesi ve yönetim profili.

Yönetim profillerinin kendisi Network > Network Profiles > Interface Mgmt yolundan yönetilir. Bu sayfada her profil için hangi servislerin açık olduğu kolonlar halinde görünür. Örnek ortamda iki profil vardır: Allow-Ping profilinde Ping, SSH ve HTTPS açıktır; Guest-Interface profilinde ise misafir ağı için Response Pages ve User-ID seçenekleri açıktır. Bu ikinci profil Captive Portal yanıt sayfalarının misafir ağında sunulabilmesi için gereklidir ve API ile ilgisi yoktur.

Görsel 10: Network > Network Profiles > Interface Mgmt sayfası ve profillerin servis kolonları.

Profil adına tıkladığınızda Interface Management Profile penceresi açılır. Bu pencerede iki grup seçenek bulunur. Administrative Management Services grubunda HTTP, HTTPS, Telnet ve SSH kutuları vardır; XML API için HTTPS zorunludur. Network Services grubunda Ping, HTTP OCSP, SNMP, Response Pages, User-ID ve User-ID Syslog dinleyicileri yer alır. Buradaki User-ID kutusu XML API ile karıştırılmamalıdır: o kutu, başka bir Palo Alto cihazının veya Windows User-ID aracının bu arayüze bağlanabilmesi içindir. SignLogger eşleşmeleri HTTPS üzerinden XML API ile gönderdiği için o kutuyu açmanıza gerek yoktur.

Pencerenin sağındaki Permitted IP Addresses listesi, MGT arayüzündeki mantıkla aynı çalışır. Boş bırakılırsa bu arayüzden gelen tüm yönetim istekleri kabul edilir. En güvenli yaklaşım, SignLogger sunucusunun IP adresini ve yönetim istasyonlarınızı buraya ekleyip listeyi daraltmaktır. Böylece misafir ağındaki bir cihaz güvenlik duvarının yönetim arayüzünü hiç göremez.

Önemli bir uyarı: API erişimi için kullanmayacağınız arayüzlere yönetim profili atamayın. Özellikle internete bakan arayüzde HTTPS yönetimini açmak, güvenlik duvarının yönetim arayüzünü tüm dünyaya açar. Örnek ortamda internete bakan ethernet1/1 arayüzünde hiçbir yönetim profili atanmamıştır ve bu doğru olan davranıştır.

Görsel 11: Interface Management Profile penceresi. HTTPS açık, Permitted IP Addresses listesi boş.

Adım 4: API Anahtarı Ayarları ve Anahtar Ömrü (API Key Lifetime)

PAN-OS'ta API anahtarlarıyla ilgili merkezi ayarlar Device > Setup > Management sayfasının Authentication Settings bölümündedir. Bölümün sağ üst köşesindeki dişli çark simgesine basıldığında Authentication Settings penceresi açılır. Burada entegrasyon açısından üç alan önemlidir.

API Key Lifetime (min): Üretilen API anahtarlarının kaç dakika geçerli olacağını belirler. Varsayılan değer 0'dır ve bu, anahtarın süresiz geçerli olması anlamına gelir. Palo Alto'nun güvenlik tavsiyesi bu alana bir süre yazmaktır. Ancak süre dolunca anahtar geçersiz olur ve entegrasyon durur; bu nedenle SignLogger tarafında anahtarı otomatik yenileyen bir mekanizma yoksa 0 değerini korumak ve güvenliği Permitted IP listeleriyle sağlamak daha kolay yönetilir bir yaklaşımdır. Örnek ortamda bu değer 0'dır.
Expire All API Keys: Bu bağlantı, üretilmiş tüm API anahtarlarını tek hamlede geçersiz kılar. Bir anahtarın sızdığından şüphelendiğinizde başvurulacak acil müdahale düğmesidir. Kullanıldıktan sonra tüm entegrasyonlar için yeni anahtar üretmek gerekir.
API Key Certificate: Anahtarların imzalanmasında kullanılacak sertifikayı belirler. Kullanılacak sertifikanın RSA olması, anahtar uzunluğunun en az 3072 bit olması ve kendinden imzalı bir kök sertifika olması gerekir. Bu ayarı etkinleştirmek veya değiştirmek mevcut tüm anahtarları geçersiz kılar. Başlangıç kurulumunda boş bırakmak, entegrasyon çalıştıktan sonra planlı bir bakım penceresinde devreye almak en pratik yoldur. Örnek ortamda bu alan boştur.

Aynı pencerede Idle Timeout, Failed Attempts ve Lockout Time gibi alanlar da vardır. Bunlar web arayüzü oturumlarını ilgilendirir ve API anahtarıyla yapılan isteklere doğrudan etki etmez; yine de kurumsal güvenlik politikanıza uygun değerlerle doldurulması iyi bir alışkanlıktır.

Görsel 12: Device > Setup > Management sayfası ve Authentication Settings bölümü.

Görsel 13: Authentication Settings penceresi ve API Key Lifetime alanı.

API Anahtarının Üretilmesi

API anahtarı, güvenlik duvarının keygen uç noktasına kullanıcı adı ve şifreyle yapılan bir istek sonucunda üretilir. Bu işlem şifre gerektirdiği için sistem yöneticisi tarafından bizzat yapılmalıdır; üretilen anahtar da bir parola kadar gizli tutulmalıdır. Palo Alto'nun resmi dokümantasyonunda önerilen yöntem POST isteği kullanmaktır:

curl -k -X POST "https://10.254.253.244/api/?type=keygen" -H "Content-Type: application/x-www-form-urlencoded" -d "user=apiadmin&password=SIFRENIZ"

Başarılı istek sonucunda güvenlik duvarı status alanı success olan bir XML cevabı döner ve cevabın içindeki key etiketi API anahtarını içerir. Bu anahtar bundan sonra tüm isteklerde kimlik yerine kullanılır. Anahtarı iletmenin üç yolu vardır: X-PAN-KEY başlığıyla göndermek, isteğin gövdesinde key parametresi olarak göndermek veya URL sorgu dizesine key parametresi olarak eklemek. Güvenlik açısından en iyi seçenek X-PAN-KEY başlığıdır, çünkü URL'ye yazılan anahtar sunucu ve vekil sunucu kayıtlarına düşer. SignLogger tarafında alan mevcutsa başlık yöntemini tercih edin.

Anahtarın hangi durumlarda geçersiz olacağını bilmek, aylar sonra yaşanacak bir kesintiyi hızla çözmenizi sağlar. Palo Alto'nun dokümantasyonuna göre bir API anahtarı şu durumlarda geçersiz olur: hesabın şifresi değiştirildiğinde, hesap silindiğinde, tanımlanan anahtar ömrü dolduğunda, API anahtarı sertifikası yeniden yapılandırıldığında veya süresi dolduğunda ve tüm anahtarlar elle süresi doldurulmuş sayıldığında. Entegrasyon bir gün sebepsiz durduysa önce bu listeyi kontrol edin.

Adım 5: User-ID Tarafının Hazırlanması

SignLogger'ın gönderdiği eşleşmelerin işe yaraması için güvenlik duvarının User-ID tarafının da hazır olması gerekir. Bu adım atlandığında API istekleri success cevabı dönse bile loglarda kullanıcı adları görünmez ve kullanıcı bazlı politikalar çalışmaz. Bu, entegrasyonda en sık rastlanan "her şey doğru ama çalışmıyor" senaryosudur.

Bölgelerde User Identification'ın Etkinleştirilmesi

PAN-OS, bir IP-kullanıcı eşleşmesini yalnızca kaynak bölgesinde User Identification etkinse politika ve log değerlendirmesinde kullanır. Network > Zones yoluna gidin ve misafirlerin bulunduğu bölgeyi açın. Enable User Identification kutusunu işaretleyin. Örnek ortamda bu ayar Guest bölgesinde etkindir; trust ve untrust bölgelerinde kapalıdır.

Aynı pencerede User Identification ACL bölümündeki Include List ve Exclude List alanları vardır. Bu listeler, bölge içindeki hangi alt ağların kullanıcı eşleştirmesine dahil edileceğini veya dahil edilmeyeceğini belirler. Sunucu ağları ve yazıcılar gibi kullanıcı kimliği olmayan cihazların bulunduğu alt ağları dışlama listesine eklemek, gereksiz eşleşmelerin önüne geçer. Önemli bir davranış detayı: Include List'e bir kayıt eklerseniz listede olmayan tüm alt ağlar otomatik olarak dışarıda kalır.

Görsel 14: Network > Zones sayfası. Misafir bölgesinde User Identification etkin.

User Mapping Zaman Aşımı ve Sunucu İzleme

Device > User Identification > User Mapping sekmesi, PAN-OS'un tümleşik User-ID aracının ayarlarını içerir. Bu sayfada API entegrasyonu için en önemli iki alan Enable User Identification Timeout kutusu ve User Identification Timeout (min) değerindedir. Bu süre, API ile yazılan bir eşleşmenin ne kadar süre sonra kendiliğinden silineceğini belirler. Örnek ortamda kutu işaretli ve süre 45 dakikadır.

Bu süreyi belirlerken SignLogger'daki misafir oturum süresiyle uyumlu bir değer seçmek gerekir. Güvenlik duvarındaki süre portaldaki oturum süresinden kısa olursa kullanıcı henüz oturumdayken eşleşme düşer ve loglarda kullanıcı adı kaybolur. Tersi durumda, yani güvenlik duvarındaki süre çok uzun olursa, aynı IP adresini alan yeni bir misafir eski kullanıcının kimliğiyle eşleşmiş görünür. Misafir ağlarında DHCP kira süresi genellikle kısa olduğu için bu ikinci risk daha ciddidir. En sağlıklı yöntem, SignLogger'ın oturum kapatma bilgisini API ile aktif olarak göndermesi ve zaman aşımının yalnızca emniyet ağı olarak kalmasıdır.

Aynı sayfadaki Server Monitoring listesi, Active Directory gibi kaynakları izleyerek eşleşme toplamak içindir. SignLogger entegrasyonunda eşleşmeler API ile geldiği için bu listenin boş olması sorun değildir; örnek ortamda da boştur. Kurumsal ağ için Active Directory izlemesi de kullanıyorsanız iki kaynak birlikte çalışabilir.

Görsel 15: Device > User Identification > User Mapping sekmesi ve User Identification Timeout değeri.

Adım 6: XML API İstek Yapısı ve User-ID Mesajları

Bu bölüm doğrudan bir arayüz ayarı değildir, ancak SignLogger tarafındaki tanımları yaparken ve sorun giderirken güvenlik duvarının ne beklediğini bilmek büyük kolaylık sağlar. Güvenlik duvarının üzerinde yerleşik bir API tarayıcısı vardır. Tarayıcınızda güvenlik duvarının adresine /api/ ekleyerek açtığınızda kategorilerin listelendiği bir sayfa görürsünüz: Commit, Configuration Commands, Export, Import, Logs, Operational Commands, Reports, User ID ve IoT. Her kategoriye girdiğinizde o kategori için kullanılacak URL kalıbı ekranda gösterilir. Bu sayfa yalnızca oturum açmış bir yöneticiye görünür ve entegrasyonu sınamak için en hızlı araçtır.

User ID kategorisi seçildiğinde kullanılacak yol şu biçimdedir:

/api/?type=user-id&cmd=<uid-message>...</uid-message>

Bu kalıp içindeki uid-message gövdesi, hangi kullanıcının hangi IP adresiyle eşleştiğini anlatır. Bir kullanıcı giriş yaptığında login bloğu, çıktığında logout bloğu kullanılır. Tipik bir giriş mesajının yapısı şöyledir:

<uid-message>

<type>update</type>

<login>

</login>

</payload>

</uid-message>

Buradaki alanların anlamı şöyledir. name alanı kullanıcı adını, ip alanı kullanıcının cihazının IP adresini taşır. timeout alanı isteğe bağlıdır ve bu tek eşleşme için dakika cinsinden bir ömür belirler; verilmediğinde güvenlik duvarının genel User Identification Timeout değeri geçerli olur. Kullanıcı oturumunu kapattığında aynı yapı login yerine logout bloğuyla gönderilir ve eşleşme tablodan silinir.

Kullanıcı adı biçimi konusunda dikkatli olun. Etki alanı kullanılan ortamlarda PAN-OS genellikle alan adıyla birlikte yazılan biçimi bekler. Misafir ağı gibi etki alanı olmayan senaryolarda ise sade kullanıcı adı yeterlidir; bu durumda User Mapping sayfasındaki Allow matching usernames without domains seçeneği işinizi kolaylaştırabilir. Önemli olan, SignLogger'ın gönderdiği adın güvenlik politikalarında kullandığınız adla birebir aynı olmasıdır.

Görsel 16: Güvenlik duvarının yerleşik XML API tarayıcısı ve kategori listesi.

Görsel 17: XML API tarayıcısının User ID bölümü ve kullanılacak URL kalıbı.

Adım 7: Güvenlik Politikası ve Ağ Yolu Kontrolü

Yönetim profili doğru olsa bile trafiğin güvenlik duvarına ulaşamadığı durumlar olur. SignLogger sunucusu, API isteklerini gönderdiği arayüzün bulunduğu bölgeden farklı bir bölgede yer alıyorsa trafiğin güvenlik politikasından da geçmesi gerekebilir. Böyle bir durumda kaynağı SignLogger sunucusu, hedefi güvenlik duvarının ilgili arayüz IP adresi ve servisi HTTPS olan bir izin kuralı yazılır. Kuralı yazarken hedef adresi çok geniş bırakmamaya özen gösterin.

Ağ yolunu doğrulamanın en hızlı yolu sırayla üç kontroldür. Önce SignLogger sunucusundan güvenlik duvarının hedef adresine ping atın; yönetim profilinde Ping açıksa cevap gelmelidir. Ardından aynı sunucudan 443 numaralı porta bir TCP bağlantısı denemesi yapın. Son olarak tarayıcıdan güvenlik duvarının arayüzünü açmayı deneyin. Bu üç kontrol geçilmişse sorun ağ katmanında değil, kimlik doğrulama veya yetki katmanındadır.

Bir başka sık rastlanan durum, güvenlik duvarının sertifikasının kendinden imzalı olmasıdır. SignLogger tarafındaki HTTP istemcisi sertifika doğrulaması yapıyorsa istek bağlantı kurmadan hata verir. Laboratuvar ortamında sertifika doğrulamasını devre dışı bırakmak pratiktir; canlı ortamda ise güvenlik duvarının yönetim arayüzüne kurumsal sertifika otoritenizden imzalı bir sertifika yüklemek ve doğrulamayı açık tutmak doğru olan yaklaşımdır.

Doğrulama ve Test

Testleri kademeli yapmak, sorunun hangi katmanda olduğunu hızla gösterir. Önerdiğim sıra şöyledir.

Anahtarın geçerliliğini sınayın. Basit bir sistem bilgisi sorgusu (type=op ve show system info komutu) doğru cevap veriyorsa hem ağ yolu hem kimlik doğrulama çalışıyor demektir.
Tek bir eşleşme gönderin. Örnek uid-message yapısını kullanarak bir test kullanıcısı ve test IP adresi yazın. Cevapta status değerinin success olması gerekir.
Eşleşmenin tabloya yazıldığını kontrol edin. Güvenlik duvarının komut satırında show user ip-user-mapping all komutu ile veya API üzerinden aynı komutu çalıştırarak listeye bakın. Eşleşmenin kaynağı XML API olarak görünmelidir.
Gerçek bir misafirle deneyin. Misafir ağındaki bir cihazla SignLogger portalından giriş yapın ve ardından güvenlik duvarının trafik loglarında o IP adresinin yanında kullanıcı adının göründüğünü doğrulayın.
Oturum kapatmayı test edin. Kullanıcı çıkış yaptıktan sonra eşleşmenin tablodan kalktığını görün. Kalkmıyorsa SignLogger logout mesajı göndermiyor demektir ve zaman aşımı süresini beklemek gerekir.
Kullanıcı bazlı bir kural yazın. Politikanın gerçekten kullanıcı kimliğine göre eşleştiğini görmek, entegrasyonun işe yaradığının son kanıtıdır.

Sorun Giderme: Sık Karşılaşılan Hatalar

Aşağıdaki tablo, entegrasyon sırasında en sık görülen belirtileri ve olası nedenlerini derliyor.

İstek hiç cevap almıyor, zaman aşımına düşüyor: Ağ yolu veya yönetim profili sorunu. Hedef adresin hangi arayüzde olduğunu, o arayüze bir Interface Management Profile atanıp atanmadığını ve profilde HTTPS'in açık olup olmadığını kontrol edin. Permitted IP Addresses listesi dolu ise SignLogger adresinin listede olup olmadığına bakın.
Invalid credentials benzeri kimlik hatası: Anahtar geçersiz olmuş olabilir. Hesabın şifresi değişti mi, hesap silindi mi, anahtar ömrü doldu mu, API anahtarı sertifikası değişti mi? Bu sorulardan biri evetse yeni anahtar üretmek gerekir.
Yetki hatası alınıyor ama anahtar geçerli: Rol profilinin XML API sekmesinde ilgili kategori kapalı olabilir. Özellikle User-ID Agent kategorisinin Enable olduğunu doğrulayın. Rol profilinde değişiklik yaptıktan sonra commit yapmayı unutmayın.
Cevap success dönüyor ama loglarda kullanıcı adı görünmüyor: Büyük olasılıkla kaynak bölgede User Identification etkin değildir. Network > Zones altında ilgili bölgeyi kontrol edin. Include List kullanıyorsanız misafir alt ağının listede olduğunu doğrulayın.
Eşleşme kısa sürede kayboluyor: User Identification Timeout değeri portal oturum süresinden kısa olabilir veya gönderilen mesajdaki timeout değeri çok küçüktür.
Kullanıcı çıkış yaptı ama eşleşme duruyor: SignLogger logout mesajı göndermiyor olabilir. Geçici çözüm zaman aşımını kısaltmaktır; kalıcı çözüm oturum kapatma bildirimini API'ye eklemektir.
Yanlış kullanıcı görünüyor: Aynı IP adresi başka bir misafire verilmiş olabilir. DHCP kira süresi ile eşleşme ömrünü birbirine yakın değerlere çekin ve logout bildirimini devreye alın.
SSL veya sertifika hatası: Güvenlik duvarının arayüz sertifikası kendinden imzalıdır ve istemci sertifika doğrulaması yapıyordur. Kurumsal CA'dan imzalı sertifika yükleyin.
Arayüzde değişiklik yapıldı ama etkisi yok: Aday yapılandırma commit edilmemiştir. Sağ üstteki Commit düğmesini kullanın.

Güvenlik Önerileri

API anahtarı güvenlik duvarının kapısını açan bir anahtardır ve bu nedenle bir yönetici şifresi kadar değerlidir. Entegrasyonu kalıcı olarak güvenli tutmak için şu önlemleri almanızı öneririm. Yalnızca API için ayrı bir hesap kullanın ve bu hesabı insan yöneticilerle paylaşılmış hale getirmeyin. Rol profilinde en az yetki ilkesini uygulayarak kullanmadığınız XML API kategorilerini kapatın. Command Line yetkisini None bırakın. Yönetim arayüzünde ve veri arayüzündeki yönetim profilinde Permitted IP Addresses listesini doldurun ve yalnızca SignLogger ile yönetim istasyonlarınıza izin verin. HTTP ve Telnet servislerini asla açmayın. Anahtarı URL sorgu dizesi yerine X-PAN-KEY başlığıyla gönderin. Anahtarın sızdığından şüphelenirseniz Expire All API Keys bağlantısını kullanıp yeni anahtar üretin. Son olarak, kim ne zaman API ile ne yaptı sorusunu cevaplayabilmek için Monitor > Logs > Configuration ve System loglarını düzenli olarak gözden geçirin.

Hızlı Kontrol Listesi

Yapılandırmayı tamamladıktan sonra aşağıdaki maddeleri tek tek işaretleyin.

Device > Admin Roles altında API için bir rol profili oluşturuldu.
Rol profilinin XML API sekmesinde User-ID Agent kategorisi Enable durumda.
Rol profilinin Command Line sekmesinde None seçili.
Device > Administrators altında Role Based tipinde ayrı bir API hesabı oluşturuldu ve rol profili atandı.
API isteklerinin gideceği adres netleştirildi ve bu adres MGT değilse ilgili arayüze Interface Management Profile atandı.
İlgili yönetim profilinde HTTPS servisi açık, HTTP ve Telnet kapalı.
Permitted IP Addresses listesi kurumsal politikaya göre dolduruldu ve kendi yönetim adresiniz de listeye eklendi.
Device > Setup > Management altındaki API Key Lifetime değeri bilinçli olarak seçildi.
Misafirlerin bulunduğu bölgede Enable User Identification işaretli.
User Identification Timeout değeri portal oturum süresiyle uyumlu.
Tüm değişiklikler Commit ile çalışan yapılandırmaya uygulandı.
API anahtarı sistem yöneticisi tarafından üretildi ve SignLogger'a güvenli bir şekilde tanımlandı.
Test kullanıcısıyla eşleşme gönderildi ve güvenlik duvarında görüldü.
Gerçek bir misafir girişinde trafik loglarında kullanıcı adı görüldü.
Çıkış sonrasında eşleşmenin kalktığı doğrulandı.

Sıkça Sorulan Sorular

API entegrasyonu için Captive Portal şart mı?

Hayır. XML API ile eşleşme göndermek Captive Portal'dan bağımsızdır. Ancak misafir kullanıcıların kimliğinin nereden geldiği sorusunu cevaplayan taraf portal olduğu için, ikisi birlikte kullanıldığında anlamlı bir bütün oluşur.

XML API ile REST API arasındaki fark nedir?

XML API daha eski ve daha kapsamlıdır; User-ID eşleşmesi gönderme, log çekme, commit tetikleme gibi işlerin tamamı buradan yapılır. REST API ise nesne ve politika yönetimine odaklı, JSON tabanlı bir arayüzdür. User-ID gönderimi için XML API kullanılır. İkisinin izinleri rol profilinde ayrı sekmelerde yönetilir.

API anahtarı süresiz olsun mu?

Palo Alto güvenlik gerekçesiyle bir ömür tanımlanmasını önerir. Uygulamada ise anahtarı otomatik yenileyen bir mekanizma yoksa süre dolumu sessiz bir kesintiye yol açar. Kararı verirken şunu sorun: anahtar süresi dolduğunda SignLogger yeni anahtarı kendisi üretebiliyor mu? Cevap hayırsa ömrü sınırsız bırakıp erişimi IP listeleriyle daraltmak daha güvenli bir bütün oluşturur.

SignLogger'a hesabın şifresini yazmam gerekir mi?

Hayır. Şifre yalnızca anahtar üretirken bir kez kullanılır. SignLogger'a yazılan değer API anahtarıdır. Bu ayrım önemlidir: şifre değişse bile anahtarı yenileyene kadar entegrasyon durur, ama şifreyi üçüncü bir sistemde saklamamış olursunuz.

MGT arayüzü yerine veri arayüzü kullanmak güvenlik riski mi?

Kontrolsüz bırakılırsa evet. En temiz çözüm yönetimi ayrı bir MGT ağında tutmaktır. Veri arayüzü kullanmak zorundaysanız yönetim profilinde yalnızca HTTPS'i açın, Permitted IP Addresses listesini SignLogger ve yönetim istasyonlarıyla sınırlayın ve bu profili kesinlikle internete bakan arayüze atamayın.

Eşleşmeler commit gerektirir mi?

Hayır. User-ID eşleşmeleri çalışma zamanı verisidir ve anında geçerli olur. Commit yalnızca rol profili, hesap ve arayüz ayarları gibi yapılandırma değişiklikleri için gereklidir.

Sonuç

Palo Alto ile SignLogger arasındaki XML API bağlantısı, güvenlik duvarı tarafında çok sayıda ayar gerektirmez; ancak gereken ayarların hepsinin doğru olması gerekir. Özetle yapılacaklar şunlar: API için ayrı bir yönetici rol profili oluşturup XML API sekmesinde User-ID Agent yetkisini açmak, bu profili kullanan ayrı bir yönetici hesabı tanımlamak, isteklerin gideceği arayüzde HTTPS yönetimini açmak, misafir bölgesinde User Identification'ı etkinleştirmek, zaman aşımı sürelerini portalla uyumlu hale getirmek ve tüm değişiklikleri commit etmek. API anahtarının üretilmesi şifre gerektirdiği için sistem yöneticisine ait bir adımdır.

Bu yapı kurulduğunda misafir ağındaki trafik artık anonim IP adresleri olarak değil, isimli kullanıcılar olarak görünür. Bu, hem güvenlik politikalarını kullanıcı bazına taşımanızı hem de yasal kayıt yükümlülüklerinizi anlamlı verilerle karşılamanızı sağlar. Yapılandırmaya başlamadan önce yedek almayı, canlıya almadan önce testleri kademeli yapmayı ve erişim listelerini daraltmayı ihmal etmeyin.

Kaynaklar

Bu rehberdeki teknik bilgiler Palo Alto Networks'ün resmi dokümantasyonuna dayanıyor. İlgili bölümler şunlar:

PAN-OS ve NGFW API dokümantasyonu: API Authentication and Security bölümü, anahtarın hangi yöntemlerle iletilebileceğini ve güvenlik tavsiyelerini açıklar.
PAN-OS API Authentication ve Enable API Access bölümü: XML API erişimi için ayrı bir yönetici hesabı kullanılması tavsiyesinin kaynağıdır.
Get Your API Key ve Generate an API Key Certificate bölümleri: keygen isteğinin biçimi, sertifika gereksinimleri ve anahtarın hangi durumlarda geçersiz olduğu bilgisi buradan alınmıştır.
Configure an Admin Role Profile ve Configure a Firewall Administrator Account bölümleri: rol profili ve hesap alanlarının anlamları için başvurulmuştur.
Send User Mappings to User-ID Using the XML API bölümü: harici sistemlerin oturum açma ve kapatma olaylarını tümleşik User-ID aracına gönderme yöntemini tanımlar.
Enable User-ID ve Map IP Addresses to Users bölümleri: bölge bazında User Identification, Include ve Exclude listeleri ile eşleşme zaman aşımı davranışı için başvurulmuştur.

Not: Bu rehberdeki tüm IP adresleri, arayüz adları, hesap ve profil isimleri bir laboratuvar ortamına aittir ve örnek amacıyla verilmiştir. Kendi kurulumunuzda bu değerleri kendi ağ planınıza ve güvenlik politikanıza göre uyarlamanız gerekir.