> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/pluginler/auth-security.md).

# Authentication ve security plugin'leri

Kangal, route kimlik doğrulama eklentilerini ve yönetilen consumer credential'larını destekler. Kimlik doğrulama eklentileri çağıranı eklenti zincirinde doğrular. Yönetilen credential'lar ise ACL, rate-limit ve kapsamlı politikaların kullanacağı consumer kimliğini belirler.

Korunan her gateway veya route'a bir kimlik doğrulama politikası bağlayın. Erişim consumer grubu, rol, kullanıcı veya tenant'a da bağlıysa ACL ekleyin.

## Desteklenen kimlik doğrulama eklentileri

| Eklenti                        | Zorunlu yapılandırma                                                                              | Kullanım                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `api_key_auth`                 | `valid_keys`; isteğe bağlı `header_name`                                                          | Yapılandırılmış key'leri ve `X-API-Key` ile gönderilen yönetilen API key'leri doğrular. |
| `basic_auth`                   | `username` ve `password` içeren `allowed_users` kayıtları                                         | HTTP Basic credential'larını TLS üzerinden doğrular.                                    |
| `oauth2`                       | `introspection_url` veya `valid_tokens`; isteğe bağlı client credential'ları ve `required_scopes` | Bearer token'ları introspection veya açık token allowlist'iyle doğrular.                |
| `oidc`                         | `public_key`, issuer, audience, izin verilen algoritmalar; isteğe bağlı scope alanları            | İmzalı bearer token'ları yapılandırılmış güven ve claim gereksinimleriyle doğrular.     |
| `ldap_auth`                    | `server_url`, `user_dn_template` ve TLS ayarları                                                  | Basic credential'larını LDAP ile doğrular.                                              |
| `mtls_client_certificate_auth` | Güvenilen CA/fingerprint veya verified-header gereksinimi; isteğe bağlı kimlik kısıtları          | Güvenilen TLS terminator'ün ilettiği client sertifikasını doğrular.                     |
| `session_cookie_auth`          | `valid_session_ids` veya `valid_sessions`                                                         | Allowlist'teki session kimliğini doğrular.                                              |
| `vault_authentication`         | `secret_ref` ve injection modu                                                                    | Kangal'ın upstream service için kullanacağı credential'ı çözüp enjekte eder.            |

Eklenti destekliyorsa `hide_credentials`, gelen credential'ı proxy işleminden önce kaldırır. `upstream_headers`, normalize kimlik header'larını yönetir. Her korunan route için iki ayarı da gözden geçirin.

## Yönetilen API key ve grup ACL

Önce [Consumer'lar](/tr/consumerlar/consumers.md) bölümündeki gibi consumer ve API key oluşturun, ardından iki politikayı da bağlayın. Boş `valid_keys` dizisi, statik key eklemeden yönetilen API key'lere izin verir.

```json
{
  "name": "api_key_auth",
  "tenant_id": "tenant-a",
  "scope": "gateway",
  "gateway_id": "gateway-1",
  "trigger": "before_request",
  "priority": 200,
  "enabled": true,
  "config": {
    "valid_keys": [],
    "header_name": "X-API-Key"
  }
}
```

```json
{
  "name": "acl_control",
  "tenant_id": "tenant-a",
  "scope": "gateway",
  "gateway_id": "gateway-1",
  "trigger": "before_request",
  "priority": 100,
  "enabled": true,
  "config": {
    "allowed_groups": ["payments"]
  }
}
```

Kimlik doğrulama eklentisi eksik veya geçersiz API key için `401` döndürür. Kimlik başarıyla belirlendikten sonra ACL, consumer izin verilen bir grupta değilse `403` döndürür.

## Erişim politikaları

| Eklenti               | Ana yapılandırma                                                      | Kullanım                                                                                                        |
| --------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `acl_control`         | `allowed_users`, `allowed_roles`, `allowed_groups`, `allowed_tenants` | Yapılandırılan her kimlik boyutunu zorunlu kılar; grup eşleşmesinde yapılandırılmış gruplardan biri yeterlidir. |
| `ip_whitelist`        | `allowed_ips`                                                         | Tam client IP değerlerine izin verir.                                                                           |
| `ip_blacklist`        | `blocked_ips`                                                         | Tam client IP değerlerini reddeder.                                                                             |
| `bot_detection_basic` | User-Agent allow/deny pattern'leri ve response ayarları               | Sıralı regular-expression filtrelemesi uygular.                                                                 |
| `request_termination` | `header_equals`, `status_code`, `message`                             | Eşleşen istekleri upstream proxy işleminden önce durdurur.                                                      |
| `oas_validation`      | `spec`, doğrulama flag'leri ve boyut/status ayarları                  | İstekleri OpenAPI 3.x sözleşmesine göre doğrular.                                                               |

## Güvenlik gereksinimleri

* Credential taşıyan her istekte TLS kullanın. API key'leri URL'lere veya loglara yazmayın.
* Yüksek entropy'li API key üretin, onaylı bir secret manager'da saklayın ve tanımlı bir takvimle değiştirin.
* OAuth2 introspection için HTTPS endpoint kullanın, outbound erişimi sınırlandırın ve client credential'larını secret manager'da saklayın.
* OIDC için açık doğrulama key'i, izin verilen algoritmalar, beklenen issuer ve audience değerlerini yapılandırın. Provider key rotation sırasında yapılandırılmış key'i güncelleyin.
* LDAP bağlantılarında TLS kullanın ve directory endpoint'ini network policy ile sınırlandırın.
* Güvenilen TLS terminator, client tarafından gönderilen sertifika header'larını kaldırmalı; sertifika ve doğrulama header'larını kendisi eklemelidir.
* Yüksek entropy'li session kimlikleri kullanın; süresi dolan veya iptal edilen session'ları yapılandırılmış allowlist'ten çıkarın.
* Korunan upstream çağrılarında `vault_authentication.fail_open` değerini kapalı tutun.
* Consumer ve grup kapsamları kimliği belirlenmiş trafiği seçer; kimlik doğrulama gereksiniminin yerine geçmez.

## Yönetilen consumer credential'ları

Yönetilen `api_key` credential'ları önerilen consumer kimlik doğrulama yöntemidir ve `X-API-Key` üzerinden doğrudan `api_key_auth` ile entegre olur.

Yönetilen `basic` credential'ları kontrollü uyumluluk akışları için kullanılabilir. Yalnızca TLS üzerinden gönderin ve oluşan consumer veya grup kimliğini `acl_control` ile zorunlu kılın.

## Sorun giderme

| Belirti                              | Kontrol                                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Yönetilen API key reddediliyor       | `X-API-Key` kullanın; credential tenant, key ve expiry değerlerini doğrulayın; `api_key_auth` içinde `valid_keys: []` gönderin. |
| OAuth2 token reddediliyor            | Introspection URL'sini, client credential'larını, token activity değerini ve zorunlu scope'ları doğrulayın.                     |
| OIDC token reddediliyor              | Yapılandırılmış key, algoritma, issuer, audience, token expiry ve zorunlu scope'ları doğrulayın.                                |
| LDAP kimlik doğrulaması başarısız    | TLS bağlantısını, directory endpoint'ini, DN template'i ve bind credential'larını doğrulayın.                                   |
| mTLS kimlik doğrulaması başarısız    | Güvenilen terminator'ü, sertifika header'ını, doğrulama header'ını, geçerlilik süresini ve trust politikasını doğrulayın.       |
| Session kimlik doğrulaması başarısız | Yapılandırılmış cookie veya header adını, allowlist'teki session kimliğini ve rol/grup gereksinimlerini doğrulayın.             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/tr/pluginler/auth-security.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.