Client Yapılandırması

Public PKCE client ayarları ve dev için adım adım manuel kurulum rehberi

Bu sayfa hem client ayarlarının ne anlama geldiğini hem de Keycloak’ı elle kurmak için adım adım rehberi içerir. Dev’de bu işi normalde otomatik provisioning yapar; manuel kurulum, provisioning kapalıyken veya harici bir Keycloak’ta lazım olur.

Client ayarları (her iki SPA)

Her iki SPA da public (PKCE) client’tır:

Alan	diyanet-website	diyanet-admin
Client type	OpenID Connect	OpenID Connect
Client authentication	OFF (public)	OFF (public)
Standard flow	✅	✅
Direct access grants	☐	☐
PKCE method	S256	S256
Access token lifespan	2 saat	5 dakika
Refresh token rotation	açık	açık
Redirect URI	http://localhost:3000/* (+swagger)	http://localhost:3001/* (+swagger)
Web origins	http://localhost:3000, :5005	http://localhost:3001, :5005

Client authentication kapalıdır (public client). Secret yoktur — tarayıcıda çalışan bir SPA secret saklayamaz. Güvenlik PKCE (code_challenge_method=S256) ile sağlanır.

Manuel kurulum (dev)

Aşağıdaki adımlar bir realm + client için verilmiştir; iki realm için tekrarlanır (diyanet-vatandas-dev-realm → diyanet-website, diyanet-yonetim-dev-realm → diyanet-admin).

1. Realm oluştur

   http://localhost:8080 → Administration Console → giriş (admin / .env → KEYCLOAK_ADMIN_PASSWORD). Sol üst master menüsü → Create Realm → Realm name: diyanet-yonetim-dev-realm → Create.

2. Client oluştur

   Clients → Create client

   Alan	Değer
   Client type	OpenID Connect
   Client ID	diyanet-admin

   Next → Capability config:

   Alan	Değer
   Client authentication	OFF (public)
   Standard flow	✅
   Direct access grants	☐
   Service accounts roles	☐

   Next → Login settings:

   Alan	Değer
   Valid redirect URIs	http://localhost:3001/*
   (2.)	http://localhost:5005/swagger/oauth2-redirect.html
   Web origins	http://localhost:3001, http://localhost:5005

   Save

3. PKCE'yi zorunlu kıl

   Clients → diyanet-admin → Advanced sekmesi → Advanced Settings → Proof Key for Code Exchange Code Challenge Method = S256 → Save.

4. Token ömrünü ayarla

   Realm settings → Tokens → Access Token Lifespan → personel realm’ı için 5 minutes, vatandaş realm’ı için 2 hours. (İstenirse client override edilebilir.)

5. Protocol mapper'ları ekle

   Clients → diyanet-admin → Client scopes → diyanet-admin-dedicated → Add mapper → By configuration → User Attribute.

   İlk mapper — permissions (multivalued):

   Alan	Değer
   Name / User Attribute / Token Claim Name	permissions
   Claim JSON Type	String
   Multivalued	ON
   Add to access token	ON

   İkinci mapper — organization_id:

   Alan	Değer
   Name / User Attribute / Token Claim Name	organization_id
   Claim JSON Type	String
   Multivalued	OFF
   Add to access token	ON

6. Realm rollerini oluştur

   Realm roles → Create role. Personel realm’ı için sırayla: SuperAdmin, Admin, Staff, ReadOnly. Vatandaş realm’ı için: Citizen.

7. Test kullanıcısı oluştur ve rol ata

   Users → Create new user (Username, Email, Email verified ON) → Credentials → Set password (Temporary: OFF) → Role mapping → Assign role. Listede “Filter by realm roles” seçip ilgili rolü (örn. Admin) ata.

8. Kullanıcı attribute'larını gir

   Users → (kullanıcıyı seç) → Attributes. permissions çok-değerli olduğundan birden çok satır eklenebilir:

   Key	Value
   permissions	users:read
   permissions	users:write
   organization_id	00000000-0000-0000-0000-000000000001

   Save.

9. Swagger'dan login test et

   API’yi başlat → http://localhost:5005/swagger → Authorize. KeycloakPersonel bölümünde scope’lar (openid profile email) seçili → Authorize → Keycloak login → test kullanıcısı ile gir. Artık istekler bu token ile gider. (Swagger PKCE kullanır, secret alanı boş bırakılır.)

curl ile token testi

Public + PKCE client’ta password grant kapalıdır (DirectAccessGrantsEnabled: false), bu yüzden token’ı tarayıcı akışıyla almak gerekir. Hızlı doğrulama için OIDC discovery’yi kontrol edebilirsiniz:

curl -s http://localhost:8080/realms/diyanet-yonetim-dev-realm/.well-known/openid-configuration \
  | jq '{issuer, token_endpoint, jwks_uri}'

Aldığınız access token’ı https://jwt.io ile açınca realm_access.roles, permissions[] ve organization_id claim’leri görünmelidir (bkz. Realm Yapısı).

Geçici olarak Direct access grants açıp password grant ile token almak teşhis için pratiktir, ama dev dışında kapalı tutun.

appsettings karşılığı

Manuel kurulan değerler appsettings.Development.json → Keycloak ile eşleşmelidir:

"Keycloak": {
  "Vatandas": {
    "BaseUrl": "http://localhost:8080",
    "PublicBaseUrl": "http://localhost:8080",
    "Realm": "diyanet-vatandas-dev-realm",
    "ClientId": "diyanet-website",
    "RequireHttpsMetadata": false,
    "ValidateAudience": true,
    "CookieName": "kc_vatandas_token"
  },
  "Personel": {
    "BaseUrl": "http://localhost:8080",
    "PublicBaseUrl": "http://localhost:8080",
    "Realm": "diyanet-yonetim-dev-realm",
    "ClientId": "diyanet-admin",
    "RequireHttpsMetadata": false,
    "ValidateAudience": true,
    "CookieName": "kc_personel_token"
  }
}

İlgili

Otomatik Provisioning

Bu adımları kod ile yapan yol.

Realm Yapısı

Roller, mapper’lar, token içeriği.

Ortamlar

Dev / stage / prod URL stratejisi.

Sorun Giderme

Redirect URI / PKCE hataları.