API erişimini ve kimlik doğrulamayı ayarlayın

API güvenliği, çağıranın kim olduğunu ve hangi isteklere izin verildiğini belirler. Lunex’e kullanıcı olarak giriş yapmak, yayımlanmış API’yi çağırma yetkisiyle aynı işlem değildir. API için API access politikasını ayrıca hazırlayın.

Kimlik doğrulama ile yetkilendirme

Kimlik doğrulama, çağıranın sunduğu kullanıcı/parola, API key veya token’ın geçerli olup olmadığını denetler. Yetkilendirme, doğrulanmış kimliğin bu API’ye erişmesine izin verilip verilmediğini belirler. Geçerli bir JWT sahibi olmak, bütün API’leri çağırma hakkı anlamına gelmez; token’ın hedefi ve izinleri policy ile eşleşmelidir.

Örneğin bir uygulama doğru imzalı token sunabilir fakat token başka bir API için üretilmiş olabilir. Başka bir token doğru API’yi hedeflerken gerekli scope’u taşımayabilir. İlkinde audience kontrolü, ikincisinde izin kuralı önemlidir.

Lunex’teki Access policy, projenin yayımlanan API grubunun ayarıdır. Operation formunda ayrı bir kullanıcı/rol yetki matrisi oluşturmazsınız. İşlem veya iş kaydı düzeyinde daha ayrıntılı kurallar gerekiyorsa kapsamı ortam yöneticinizle belirleyin; native policy ve iş akışı sorumluluklarını açıkça ayırın. Örneğin “bu müşteri yalnızca kendi siparişini okuyabilir” kuralı, API key’in mevcut olmasından kendiliğinden çıkmaz.

Üç kimliği ayırın

İzleme Application ID bir erişim anahtarı değildir. Oluşturma ve arama kullanımı Application ID sayfasındadır. Kullanıcı girişi için kurumsal kimlik bağlantısını izleyin.

Hangi erişim yöntemini kullanmalısınız?

Bu seçim dışarıdan gelen çağrılar içindir. Route’un SAP’ye veya başka HTTP servisine bağlanırken kullanacağı credential, o bağlantının ayarıdır.

Erişim politikasını seçin

1. Projede API design → API access açın.
2. Dışarıdan çağrı alınacaksa API exposure → Enabled seçin.
3. Public transport alanında ortamınızda hazırlanmış HTTPS veya HTTP seçeneğini seçin.
4. Access policy değerini ihtiyacınıza göre belirleyin.

5. Basic/API key için Credential reference alanına Secret adını girin veya Select Secret ile seçin. Buraya parola ya da {{secret:…}} ifadesi yazmayın; alan kaynak adını bekler.
6. JWT için SecurityPolicy reference alanına ortam yöneticisinin sağladığı policy adını girin.
7. Save seçin. Geliştirme hedefinde uygulamak için Run/Reload, deployment’a almak için Commit and push → Build kullanın.

Görsel, JWT alanlarının nasıl doldurulduğunu gösterir. Unsaved işareti değişikliğin taslak olduğunu, Disabled seçimi dış erişimin kapalı tutulduğunu belirtir. orders-jwt bir policy adıdır; token veya client secret değildir. Gerçek kullanımda hazır policy’yi seçip exposure ve uygulama adımlarını ayrıca tamamlayın.

Politika projenin yayımlanan API grubuna uygulanır. Public seçimi kimlik doğrulamayı kaldırır. Hassas veri veya credential taşıyan çağrılarda ortam yöneticinizin hazırladığı HTTPS adresini kullanın; HTTP seçimi kendiliğinden HTTPS yönlendirmesi oluşturmaz.

Basic ve API key kaynaklarını hazırlayın

Ortam yöneticisi credential’ı çalışma ortamındaki System Secret olarak hazırlamalıdır. Basic için .htpasswd içeriği gerekir; düz metin kullanıcı/parola listesi yerine gateway’in kabul ettiği parola hash biçimini kullanın. .htpasswd anahtarını ortamın Kubernetes Secret hazırlama yöntemiyle oluşturun; System ekranının yeni key alanı noktayla başlayan adları kabul etmez. API key Secret’ında her istemci için ayrı bir anahtar değeri tutabilirsiniz.

Select Secret içinde Basic kaynağı Requires .htpasswd key durumundaysa doğru anahtar henüz yoktur. API key kaynağı boşsa en az bir credential eklenmelidir. Seçim ekranı uygun anahtarın varlığını gösterir; gerçek erişimi yayınlanan adres üzerinde doğrulayın.

Secret değerleri openapi.json, route URI’leri veya Git’e gönderilen properties dosyalarında bulunmamalıdır. Kaynak hazırlama ve akışta Secret kullanma yöntemi yapılandırma sayfasındadır.

Kaynak adı, anahtar adı ve gizli değer

Örneğin API key için orders-clients adlı Secret seçtiğinizi varsayın. Credential reference alanı orders-clients değerini tutar. Secret içindeki kayıt adları istemcileri ayırır; HTTP çağrısında x-api-key ile gönderilen değer ise ilgili kaydın gizli içeriğidir. Secret adı veya kayıt adı, gizli değerin yerine geçmez.

Birden çok istemci aynı anahtarı paylaşırsa bir istemciyi kaldırmak diğerlerini de etkileyebilir. Ayrı kayıtlarla hangi anahtarın hangi istemciye verildiğini ortam yönetiminde takip edin. Lunex bu kayıtları bir tüketici üyelik portalına dönüştürmez.

Anahtar değiştirme sırasında yeni değerle erişimi doğrulayın, istemciyi güncelleyin, sonra eski değeri ortam kaynağından kaldırıp artık kabul edilmediğini sınayın. Mevcut Secret’ın değeri ile projedeki Credential reference farklı değişikliklerdir: referans adı değişirse proje ayarını da Save ve ilgili çalışma/yayınlama adımıyla uygulayın.

Basic çağrısını denemek için aşağıdaki komut kullanıcı adını gönderir ve parolayı etkileşimli ister:

curl --include --user orders-client \
  https://lunex.example.com/orders-api/api/orders

Adres ve kullanıcıyı kendi ortamınızla değiştirin. Basic için gereken .htpasswd dosyası gateway’in desteklediği hash biçiminde hazırlanmalıdır; bir hash aracının varsayılanının otomatik olarak uygun olduğunu varsaymayın. Yönetici native Basic hazırlığını esas alabilir.

Kendi kimlik sağlayıcınızla JWT kullanın

Lunex token üretmez. Kurumunuzun kimlik sağlayıcısındaki API/uygulama kaydı, token edinme yöntemi ve token içeriği sizin erişim tasarımınıza bağlıdır.

JWT alanlarını anlayın

Client ID ile audience aynı olmak zorunda değildir. Client secret token edinme aşamasında kimlik sağlayıcısına ait bir credential’dır; API çağrısında Bearer token yerine gönderilmez. JWT içeriğini okuyabilmek, imzasını doğruladığınız anlamına gelmez.

Kurulum sorumluluklarını paylaşın

1. Kimlik sağlayıcınızda bu API için bir kaynak/audience ve gerekiyorsa scope’lar tanımlayın; örneğin audience orders-api, scope orders.read.
2. Çağıracak uygulama için istemci kaydı oluşturun. Client ID bu kayıttan alınır. Makineden makineye erişimde sağlayıcının uygun servis hesabı akışını kullanın; client secret’ı Secret yönetiminde saklayın.
3. Ortam yöneticinize token’ın tam issuer, beklenen audience, imza anahtarlarının JWKS adresi ve izin kurallarını verin.
4. Yönetici aynı runtime namespace’inde native bir SecurityPolicy hazırlar. Policy adı örneğin orders-jwt ise route seçicisi io.etzel.lunex/api-policy: orders-jwt etiketiyle eşleşmelidir.
5. Policy, Lunex kurulumunun API koruma kurallarıyla birlikte uygulanmalıdır. Ortam Git’inde sağlanan api-protection Kustomize bileşeni, yönetim yollarını engelleyen kuralları ekler. Yalnızca JWT tanımlı ham policy dosyasını uygulamak yeterli değildir.
6. Projede Access policy → JWT, SecurityPolicy reference → orders-jwt seçin ve değişikliği ilgili runtime’a uygulayın.
7. İstemcinin edindiği token ile yayımlanan API adresini çağırın. Token yokken, yanlış audience ile ve gerekli scope eksikken de deneme yapın.

Projede saklanan bağlantı şu şekildedir:

version: 1
enabled: true
protocols: [https]
authentication:
  type: jwt
  policyRef: orders-jwt

Issuer/JWKS ve yetki kuralları ortamın policy kaynağında kalır. Ortam policy’sindeki değişiklikler için iş route’larını yeniden derlemek gerekmez. Policy bulunamıyor veya bağlanamıyorsa erişim hazır kabul edilmemelidir; Publication → Detail ile ortam durumunu kontrol edin.

Örneğin ortam yöneticisinin native policy’sindeki aşağıdaki parça, orders adlı JWT sağlayıcısından doğrulanan token’da orders.read scope’unu arar:

authorization:
  defaultAction: Deny
  rules:
    - name: orders-read
      action: Allow
      principal:
        jwt:
          provider: orders
          scopes:
            - orders.read

Bu parça tek başına uygulanacak tam bir policy değildir. Aynı kaynağın JWT sağlayıcısı, hedef seçicisi ve kurulumun API koruma kurallarıyla birlikte hazırlanır. orders.read adını yazmanız kimlik sağlayıcısının bu izni otomatik vereceği anlamına gelmez. Native kapsamın ayrıntıları JWT izin kurallarında bulunur.

Makineden makineye kullanımda sağlayıcınızın servis istemcisi için tanımladığı yöntemle access token alın. Kullanıcı girişini bildiren ID token’ı veya client secret’ı bunun yerine göndermeyin. Token endpoint’i, istenebilecek scope’lar ve istemci doğrulama yöntemi kimlik sağlayıcısının kaydından öğrenilir; Lunex bu bilgileri otomatik oluşturmaz.

OpenAPI’de güvenliği belgeleyin

İstemcilere beklenen kimlik bilgisini anlatmak için Source içinde components.securitySchemes ve security kullanabilirsiniz. Örneğin JWT Bearer açıklaması:

{
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [{"BearerAuth": []}]
}

Bu, mevcut sözleşmeye eklenecek bir parçadır; diğer components tanımlarınızı koruyun. OAuth2/OpenID Connect bilgileri gibi formda ayrı alanı olmayan tanımlar da Source’ta tutulabilir.

OpenAPI güvenlik tanımı istemciye sözleşmeyi anlatır. Gerçek dış erişim API access politikası ve ortam güvenlik kaynağıyla uygulanır. İkisinin aynı gereksinimi anlattığını kontrol edin.

Örneğin sözleşmede Bearer tanımı bulunurken Access policy Public kalırsa yalnızca belgeye bakarak API’nin korunduğunu söyleyemezsiniz. Tersine, gateway API key isterken sözleşme bunu açıklamıyorsa tüketici eksik bilgiyle çağrı yapar. Global veya operation düzeyindeki security tanımını değiştirmek, Lunex’in proje erişim politikasını otomatik değiştirmez.

Erişimi gerçek adres üzerinden sınayın

Try it → Running project, geliştirme container’ına istek gönderir; public gateway’in Basic/API key/JWT kontrolünü sınamaz. API access içindeki adresi bir HTTP istemcisinde kullanın.

API key örneği, shell’de daha önce tanımlanmış API_KEY değişkenini kullanır:

curl --include \
  --header "x-api-key: $API_KEY" \
  https://lunex.example.com/orders-api/api/orders

JWT örneği:

curl --include \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  https://lunex.example.com/orders-api/api/orders

Adresleri kendi Copy operation address değerinizle değiştirin. Aynı isteği credential olmadan ve geçersiz credential ile de çalıştırın; korunan veri dönmemelidir. Geçerli token hâlâ reddediliyorsa issuer, audience, süre, scope, JWKS erişimi ve policy seçicisini ortam yöneticinizle kontrol edin.

İzinleri bir deneme tablosuyla doğrulayın

Yanıt kodu ve açıklamasını birlikte değerlendirin; ortam policy’si veya hazır olmayan bir kaynak farklı hata sonucu verebilir. Publication → Ready, kaynakların hazır olduğunu gösterir; bu denemelerin yapıldığını söylemez. API hata teşhisi erişim ile veri hatasını ayırmanıza yardımcı olur.