> ## 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.

# Realm Yapısı

> İki realm, roller, identity provider, protocol mapper'lar ve token içeriği

API iki ayrı Keycloak realm'ından token kabul eder. Her realm kendi kullanıcı havuzu, client'ı,
rolleri ve mapper'larıyla tamamen bağımsızdır.

## diyanet-vatandas-dev-realm (Vatandaş)

Vatandaş portali (Website SPA) bu realm'a bağlanır.

| Öğe                    | Değer                            |
| ---------------------- | -------------------------------- |
| Realm                  | `diyanet-vatandas-dev-realm`     |
| Client                 | `diyanet-website` (public, PKCE) |
| Realm/Client rolü      | `Citizen`                        |
| Identity Provider      | `google` (Google ile devam et)   |
| Access token ömrü      | 7200 sn (2 saat)                 |
| Refresh token rotation | açık, 3600 sn                    |
| Login theme / locale   | `keycloak.v2` / `tr`             |

## diyanet-yonetim-dev-realm (Personel)

Yönetim paneli (Admin SPA) bu realm'a bağlanır.

| Öğe                    | Değer                                      |
| ---------------------- | ------------------------------------------ |
| Realm                  | `diyanet-yonetim-dev-realm`                |
| Client                 | `diyanet-admin` (public, PKCE)             |
| Roller                 | `SuperAdmin`, `Admin`, `Staff`, `ReadOnly` |
| Access token ömrü      | 300 sn (5 dakika)                          |
| Refresh token rotation | açık, 1800 sn                              |
| Login theme / locale   | `keycloak.v2` / `tr`                       |

Bu dört rol, uygulama tarafındaki `Role` enumeration'ıyla birebir eşleşir
(`SuperAdmin=1, Admin=2, Staff=3, ReadOnly=4`) ve DB'deki `role_permission` seed'i bu rollere
izin atar. Keycloak rolü token'a `realm_access.roles` / `resource_access.{client}.roles` olarak
girer; `KeycloakRoleClaimsTransformation` bunları `ClaimTypes.Role` ve `permissions` claim'ine
dönüştürür.

## Protocol Mapper'lar

Her client'ta iki custom mapper kuruludur (User Attribute → token claim):

| Name              | User Attribute    | Claim             | JSON Type | Multivalued | Access Token |
| ----------------- | ----------------- | ----------------- | --------- | :---------: | :----------: |
| `permissions`     | `permissions`     | `permissions`     | String    |    **ON**   |      ON      |
| `organization_id` | `organization_id` | `organization_id` | String    |     OFF     |      ON      |

`permissions` mapper'ı **multivalued** olmalıdır — bir kullanıcının birden fazla izni token'a
ayrı değerler olarak girer. `organization_id` tek değerlidir ve multi-tenant izolasyonunu besler
(`tenant_id` ile eşdeğer kabul edilir).

```json theme={null}
{
  "Name": "permissions",
  "UserAttribute": "permissions",
  "ClaimName": "permissions",
  "JsonType": "String",
  "Multivalued": true,
  "AddToAccessToken": true,
  "AddToIdToken": false,
  "AddToUserinfo": true
}
```

## Identity Provider — Google (yalnız vatandaş realm'ı)

Vatandaş realm'ında Google IdP tanımlıdır:

```json theme={null}
{
  "Alias": "google",
  "DisplayName": "Google ile devam et",
  "ProviderId": "google",
  "Enabled": true,
  "TrustEmail": true,
  "FirstBrokerLoginFlowAlias": "first broker login",
  "DefaultScopes": "openid profile email",
  "SyncMode": "IMPORT",
  "ClientId": "CHANGE_ME",
  "ClientSecret": "CHANGE_ME"
}
```

`ClientId`/`ClientSecret` Google Cloud Console'dan alınıp `.env` / provisioning config'ine
girilir.

## Token içeriği örneği

Personel realm'ından `Admin` rollü bir kullanıcının access token'ının ilgili kesiti
(`MapInboundClaims=false` ile claim isimleri korunur):

```json theme={null}
{
  "iss": "http://localhost:8080/realms/diyanet-yonetim-dev-realm",
  "aud": ["diyanet-admin", "account"],
  "sub": "a0000002-0000-0000-0000-000000000002",
  "preferred_username": "murat.unluoney",
  "realm_access": { "roles": ["Admin", "offline_access", "default-roles-..."] },
  "resource_access": {
    "diyanet-admin": { "roles": ["Admin"] }
  },
  "permissions": ["users:read", "users:write", "faqs:write"],
  "organization_id": "00000000-0000-0000-0000-000000000001"
}
```

API tarafında `KeycloakRoleClaimsTransformation` bu yapıyı normalize eder; ardından
`UserContextClaimsTransformation` DB'den `user_id`, eksik `permissions` ve `account_status`
claim'lerini ekler (bkz. [Authentication](/security/authentication)).

## İlgili

<CardGroup cols={2}>
  <Card title="Client Yapılandırması" href="/keycloak/client-configuration">
    Client ayarları ve manuel kurulum.
  </Card>

  <Card title="Provisioning" href="/keycloak/provisioning">
    Bu yapının otomatik kurulumu.
  </Card>

  <Card title="Authorization" href="/security/authorization">
    Rollerin izinlere haritalanması.
  </Card>

  <Card title="Multi-Tenancy" href="/security/multi-tenancy">
    organization\_id ile tenant izolasyonu.
  </Card>
</CardGroup>