Keycloak, modern uygulamalar için merkezi kimlik doğrulama altyapısı sunan açık kaynaklı bir çözüm. OAuth2 ve OpenID Connect protokollerini temel alarak tek oturum açma deneyimi sağlıyor. Kurumsal ortamlarda sıkça tercih ediliyor çünkü kullanıcı yönetimi, rol tabanlı erişim kontrolü ve çoklu kimlik sağlayıcı entegrasyonu gibi özellikleri tek bir platformda birleştiriyor.
Temel Kavramlar
Keycloak mimarisinde birkaç kritik yapı taşı var. Realm, izole edilmiş güvenlik alanı olarak görev yapıyor; her realm kendi kullanıcı grubu, istemcileri ve yapılandırmasıyla bağımsız çalışıyor. Yeni bir kurulumda "master" realm varsayılan olarak geliyor ve yönetici hesapları bu realm altında tutuluyor.
Client, Keycloak'tan kimlik doğrulama talep eden uygulama veya servis. Her client için benzersiz bir istemci kimliği ve yönlendirme URI'si tanımlanıyor. İstemci tipi olarak "confidential" veya "public" seçilebiliyor; public tipi SPA uygulamaları için, confidential ise sunucu taraflı uygulamalar için uygun.
User, sisteme giriş yapan son kullanıcıları temsil ediyor. Kullanıcı öznitelikleri, gruplar ve roller aracılığıyla yönetiliyor. Role, belirli işlemlere erişim yetkisi tanımlayan soyut bir kavram; Group ise kullanıcıları organizasyonel yapıya göre gruplandıran bir mekanizma.
Kurulum Seçenekleri
Keycloak'u çalıştırmanın birden fazla yolu var. En yaygın kullanılan yöntem Docker container üzerinden kurulum. Tek komutla ayağa kaldırmak mümkün:
docker run -p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:26.6.3 start-devBu komut geliştirme ortamı için uygun. 26 sürümünden itibaren admin hesabı KC_BOOTSTRAP_ADMIN_USERNAME ve KC_BOOTSTRAP_ADMIN_PASSWORD değişkenleriyle açılışta oluşturuluyor; eski KEYCLOAK_ADMIN değişkenleri bu sürümde kaldırıldı. Bootstrap değişkenleri yalnızca ilk açılışta, veritabanında admin kullanıcısı yokken işliyor. Production kullanımda veritabanı bağlantısı ve TLS yapılandırması şart. PostgreSQL ile çalıştırmak için ek ortam değişkenleri gerekiyor; KC_DB=postgres ve veritabanı bağlantı parametreleri set edilmeli.
Kubernetes ortamında dağıtım için Helm chart kullanılabiliyor. Resmi Keycloak Operator, Kubernetes üzerinde realm ve kullanıcı yönetimini otomatikleştiriyor. Ancak operatör kurulumu biraz karmaşık; öncelikle Custom Resource Definition'ların tanımlanması gerekiyor.
İstemci Yapılandırması
Admin console üzerinden yeni bir istemci oluşturmak için önce realm seçilmeli, ardından "Clients" menüsünden "Create" butonuna tıklanmalı. İstemci kimliği girildikten sonra istemci tipi seçilmeli. OpenID Connect için "openid-connect" protokolü kullanılıyor.
İstemci ayarlarında dikkat edilmesi gereken birkaç nokta var. Valid Redirect URIs, güvenlik açısından kritik; yalnızca uygulamanın çalıştığı adresler girilmeli, aksi halde açık yönlendirme saldırılarına kapı açılır. Web Origins, CORS yapılandırması için gerekli; frontend uygulamasının kaynak adresi buraya eklenmeli.
Access token süresi varsayılan olarak 5 dakika. Bu değer "Tokens" sekmesinden ayarlanabiliyor. Session süresi de benzer şekilde yapılandırılıyor. Uzun süreli oturumlar için "Remember Me" özelliği etkinleştirilebilir; bu durumda oturum süresi uzatılıyor.
Spring Boot Entegrasyonu
Java tabanlı uygulamalarda Spring Security ile Keycloak entegrasyonu yaygın kullanılıyor. Maven dependencies olarak spring-boot-starter-oauth2-client ve spring-boot-starter-security eklenmeli. application.properties dosyasında istemci yapılandırması yapılıyor.
spring.security.oauth2.client.registration.keycloak.client-id=myapp
spring.security.oauth2.client.registration.keycloak.client-secret=secret
spring.security.oauth2.client.registration.keycloak.scope=openid,profile,email
spring.security.oauth2.client.provider.keycloak.issuer-uri=http://localhost:8080/realms/myrealm
spring.security.oauth2.client.provider.keycloak.user-name-attribute=preferred_usernameBu yapılandırma ile uygulama otomatik olarak Keycloak login sayfasına yönlendiriliyor. Başarılı kimlik doğrulama sonrası token'lar Spring Security tarafından yönetiliyor. Method seviyesinde yetkilendirme için @RolesAllowed anotasyonu kullanılabiliyor.
Kullanıcı Federasyonu
Active Directory veya LDAP ile entegrasyon, kurumsal ortamlarda sıkça ihtiyaç duyulan bir özellik. Keycloak'ta "User Federation" sekmesinden LDAP bağlantısı yapılandırılabiliyor. Bağlantı URL'si, temel DN, bind DN ve bind credentials girilmeli.
Kerberos entegrasyonu da mümkün; bu sayede Windows domain kullanıcıları oturum açabiliyor. Ancak Kerberos kurulumu karmaşık ve hata ayıklaması zor olabiliyor. Öncelikle temel LDAP senaryosunun çalıştığından emin olunmalı.
Güvenlik Önlemleri
Production ortamında mutlaka HTTPS kullanılmalı. Keycloak, varsayılan olarak HTTP üzerinden çalışıyor; reverse proxy arkasına alınarak TLS sonlandırması yapılmalı. Nginx veya HAProxy bu amaçla kullanılabiliyor.
Admin console erişimi IP bazlı kısıtlanmalı. Network seviyesinde firewall kuralları ile yalnızca güvenilir IP'lerden 8080 portuna erişime izin verilmeli. Ayrıca admin şifresi güçlü bir parola ile değiştirilmeli; varsayılan "admin/admin" kombinasyonu kesinlikle üretimde kullanılmamalı.
Token imzalama için RSA anahtar çifti kullanılıyor. Keycloak otomatik olarak anahtar üretiyor ancak uzun vadede anahtar yönetimi için harici keystore yapılandırması öneriliyor. Düzenli anahtar rotasyonu güvenlik açısından önemli.
Keycloak, kimlik doğrulama altyapısını tek noktadan yönetmeyi sağlıyor. Çok sayıda uygulamanın olduğu ortamlarda merkezi kullanıcı yönetimi büyük kolaylık sunuyor. Öğrenme eğrisi biraz dik olsa da dokümantasyon oldukça kapsamlı ve topluluk desteği güçlü.