> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diyanet.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak Genel Bakış

> Keycloak'ın rolü, çift-realm mantığı, client'lar, token ömürleri ve provisioning stratejisi

Keycloak bu sistemde kimlik sağlayıcısıdır (IdP): kullanıcı havuzu, parola, MFA, SSO ve dış
IdP federasyonu (Google) ondadır. Token üretir; uygulama bu token'ı doğrular ve yetkilendirmeyi
kendi yapar.

## Neden Keycloak

* **OIDC + SSO** standartlarına tam uyum, JWKS ile RS256 imza doğrulama.
* **Identity Federation** — Google gibi dış IdP'leri delege eder.
* **MFA, parola politikası, brute-force koruma** hazır gelir.
* **Self-hosted** — kullanıcı verisi dışarı çıkmaz (on-prem müşteri ortamı için kritik).
* **Çoklu realm** — vatandaş ve personeli aynı sunucuda izole tutar.

## Çift realm mantığı

API iki ayrı realm'dan token kabul eder; her birinin ayrı kullanıcı havuzu, client'ı ve rolleri
vardır.

| Taraf                  | Realm (dev)                  | Client            | Token ömrü            | Rol(ler)                                   |
| ---------------------- | ---------------------------- | ----------------- | --------------------- | ------------------------------------------ |
| Vatandaş (Website SPA) | `diyanet-vatandas-dev-realm` | `diyanet-website` | **2 saat** (7200 sn)  | `Citizen`                                  |
| Personel (Admin SPA)   | `diyanet-yonetim-dev-realm`  | `diyanet-admin`   | **5 dakika** (300 sn) | `SuperAdmin`, `Admin`, `Staff`, `ReadOnly` |

<Note>
  Personel token'ı bilinçli olarak çok kısadır (5 dk). Yönetim paneli yüksek-yetkili olduğundan
  çalınan bir token'ın penceresi minimumda tutulur; refresh token rotation (30 dk lifespan) ile
  sürekli oturum sağlanır. Vatandaş tarafı kullanılabilirlik için daha uzun tutulur (2 saat).
</Note>

## Client'lar

Her iki client da **public** (PKCE) client'tır — SPA'lar tarayıcıda çalıştığı için secret
saklayamaz:

```text theme={null}
diyanet-website : PublicClient=true, StandardFlow=true, PkceRequired=true (S256), 2 saat token
diyanet-admin   : PublicClient=true, StandardFlow=true, PkceRequired=true (S256), 5 dk token
```

`DirectAccessGrantsEnabled` ve `ServiceAccountsEnabled` kapalıdır; yalnızca Authorization Code

* PKCE akışı açıktır.

## Provisioning: dev vs stage/prod

```mermaid theme={null}
flowchart LR
    subgraph Dev["Dev"]
        D1["Keycloak container<br/>localhost:8080"]
        D2["API açılışta otomatik<br/>provisioning (RunOnce)"]
        D2 --> D1
    end
    subgraph Prod["Stage / Prod"]
        P1["Harici Keycloak<br/>auth.diyanet.gov.tr"]
        P2["Provisioning genelde KAPALI<br/>realm manuel veya tek-sefer"]
        P2 -.-> P1
    end
```

* **Dev**: Keycloak bir container'dır (`localhost:8080`); API açılışta `KeycloakProvisioning`
  ile realm/client/rol/kullanıcı/mapper'ı otomatik kurar (`RunOnce: true`).
* **Stage/Prod**: Keycloak genelde müşterinin mevcut harici instance'ıdır. Provisioning
  `Enabled: false` yapılıp realm manuel kurulabilir veya tek seferlik provisioning ile.

## Token edinim akışı (Auth Code + PKCE)

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant U as Kullanıcı
    participant SPA as SPA
    participant KC as Keycloak Realm
    participant API as .NET API
    U->>SPA: /login
    SPA->>SPA: code_verifier + code_challenge (S256)
    SPA->>KC: GET /auth?response_type=code&code_challenge=...
    KC->>U: Login formu (kc_locale=tr)
    U->>KC: Parola (+ MFA)
    KC-->>SPA: redirect_uri?code=<code>
    SPA->>KC: POST /token (code + code_verifier)
    KC-->>SPA: access_token + refresh_token + id_token
    SPA->>API: Cookie/Bearer ile çağrı
    API-->>SPA: 200 / 401 / 403
```

## Bu bölümde

<CardGroup cols={2}>
  <Card title="Realm Yapısı" href="/keycloak/realm-structure">
    İki realm, roller, protocol mapper'lar, token içeriği.
  </Card>

  <Card title="Client Yapılandırması" href="/keycloak/client-configuration">
    Public client ayarları ve manuel kurulum rehberi.
  </Card>

  <Card title="Otomatik Provisioning" href="/keycloak/provisioning">
    KeycloakProvisioning config'i ve hosted service.
  </Card>

  <Card title="Ortamlar" href="/keycloak/environments">
    Dev / stage / prod farkları, BaseUrl vs PublicBaseUrl.
  </Card>

  <Card title="Sorun Giderme" href="/keycloak/troubleshooting">
    Sık hatalar ve çözümleri.
  </Card>

  <Card title="Authentication" href="/security/authentication">
    API tarafında token doğrulama.
  </Card>
</CardGroup>