Skip to main content
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:
Alandiyanet-websitediyanet-admin
Client typeOpenID ConnectOpenID Connect
Client authenticationOFF (public)OFF (public)
Standard flow✅✅
Direct access grants☐☐
PKCE methodS256S256
Access token lifespan2 saat5 dakika
Refresh token rotationaçıkaçık
Redirect URIhttp://localhost:3000/* (+swagger)http://localhost:3001/* (+swagger)
Web originshttp://localhost:3000, :5005http://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
AlanDeğer
Client typeOpenID Connect
Client IDdiyanet-admin
Next → Capability config:
AlanDeğer
Client authenticationOFF (public)
Standard flow✅
Direct access grants☐
Service accounts roles☐
Next → Login settings:
AlanDeğer
Valid redirect URIshttp://localhost:3001/*
(2.)http://localhost:5005/swagger/oauth2-redirect.html
Web originshttp://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):
AlanDeğer
Name / User Attribute / Token Claim Namepermissions
Claim JSON TypeString
MultivaluedON
Add to access tokenON
İkinci mapper — organization_id:
AlanDeğer
Name / User Attribute / Token Claim Nameorganization_id
Claim JSON TypeString
MultivaluedOFF
Add to access tokenON
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:
KeyValue
permissionsusers:read
permissionsusers:write
organization_id00000000-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ı.