Keycloak Nedir ve Kurumsal Kimlik Yönetimi Kurulumu

Bir kurumda uygulama sayısı arttıkça her birinin kendi kullanıcı veritabanını, parola politikasını ve oturum yönetimini taşıması sürdürülemez hale gelir. Çalışanlar her sistem için ayrı bir parola hatırlamak zorunda kalır, işten ayrılan birinin erişimini kapatmak için beş farklı panele girmek gerekir ve iki faktörlü doğrulama gibi güvenlik önlemleri her uygulamada baştan kurulur. Keycloak tam olarak bu dağınıklığı toparlamak için tasarlanmış, açık kaynaklı bir kimlik ve erişim yönetimi (IAM) platformudur. Kimlik doğrulamayı tek bir merkezde toplar; uygulamalar artık parola saklamaz, yalnızca "bu kullanıcı gerçekten kim ve neye yetkili" sorusunu Keycloak'a sorar.

Bu rehberde Keycloak'un temel yapı taşları olan realm, istemci ve rol kavramlarını, OIDC ile SAML protokol desteğini, Docker üzerinden üretim odaklı kurulumu, LDAP ile kullanıcı federasyonunu ve çok faktörlü kimlik doğrulamayı gerçek komutlarla ele alacağız. Sonunda Keycloak'u sık karşılaştırıldığı Authentik ile yan yana koyacak, hangi senaryoda hangisinin daha mantıklı olduğunu netleştireceğiz. Amacımız, kıdemli bir sistem yöneticisinin ekibe anlattığı türden pratik, uygulanabilir bir yol haritası çıkarmak.

Keycloak Nedir ve Hangi Sorunu Çözer#

Keycloak, uygulamalarınıza kimlik doğrulama (authentication) ve yetkilendirme (authorization) yeteneği kazandıran bir kimlik sunucusudur. Java tabanlıdır, Red Hat tarafından geliştirilir ve ticari sürümü Red Hat build of Keycloak adıyla desteklenir. Ücretsiz sürümü tam özellikli olduğu için birçok kurum production ortamında doğrudan açık kaynak sürümü çalıştırır.

En temel katkısı Single Sign-On (SSO), yani tek oturum açmadır. Kullanıcı bir kez Keycloak'a giriş yapar, ardından ona bağlı tüm uygulamalara parola girmeden erişir. Çıkış yaptığında (single logout) oturumu her yerde kapanır. Buna ek olarak Keycloak sosyal giriş (Google, Microsoft, GitHub), kimlik brokerliği, self-servis parola sıfırlama, e-posta doğrulama, marka temasıyla özelleştirilebilir giriş ekranları ve ince ayarlı yetki yönetimi sunar.

Pratik faydayı bir örnekle netleştirelim. Diyelim ki bir şirkette Nextcloud, Grafana, GitLab ve iç bir muhasebe uygulaması var. Keycloak olmadan her uygulama ayrı kullanıcı yönetir. Keycloak ile dördü de tek bir kimlik kaynağına bağlanır; yeni çalışan geldiğinde tek bir yerde hesap açılır, ayrıldığında tek bir yerde devre dışı bırakılır ve tüm sistemlere erişimi anında kapanır. İç uygulamalarınız için parola güvenliği artık uygulama geliştiricisinin değil, olgun bir kimlik sunucusunun sorumluluğundadır.

Realm, İstemci ve Rol Yapısı#

Keycloak'u anlamanın anahtarı üç kavramda saklıdır: realm, client ve role. Bu üçlüyü kavradığınızda panelin geri kalanı yerli yerine oturur.

Realm, izole bir kimlik alanıdır. Kendi kullanıcılarını, gruplarını, rollerini ve istemcilerini barındıran ayrı bir dünya gibi düşünün. Kurulumla birlikte gelen master realm yalnızca Keycloak'un kendi yönetimi içindir; kesinlikle burada üretim kullanıcısı tutmayın. Uygulamalarınız için her zaman ayrı bir realm oluşturun, örneğin sirket. Farklı müşterilere hizmet veriyorsanız her müşteriye bir realm ayırarak verilerini tamamen izole edebilirsiniz.

İstemci (client), Keycloak'a bağlanan her uygulamadır. Web uygulaması, mobil uygulama, tek sayfa uygulaması (SPA) veya arka plan servisi olabilir. İstemciler iki temel türe ayrılır. Confidential (gizli) istemciler bir client secret saklayabilen sunucu tarafı uygulamalardır. Public istemciler ise secret saklayamayan tarayıcı veya mobil uygulamalardır ve güvenlik için PKCE akışını kullanır.

Rol (role), kullanıcının ne yapabileceğini tanımlar. İki seviyede tanımlanır: realm rolleri tüm realm genelinde geçerlidir, client rolleri ise belirli bir uygulamaya özgüdür. Rolleri doğrudan kullanıcılara atamak yerine gruplar üzerinden yönetmek en iyi pratiktir; böylece "Muhasebe" grubuna eklediğiniz kişi otomatik olarak o gruba tanımlı tüm rolleri alır.

OIDC ve SAML Protokol Desteği#

Keycloak iki büyük kimlik protokolünü aynı anda konuşur: OpenID Connect (OIDC) ve SAML 2.0. Yeni bir uygulamayı bağlarken hangisini seçeceğinizi bilmek işinizi çok kolaylaştırır.

OpenID Connect, OAuth 2.0 üzerine inşa edilmiş modern protokoldür. JSON ve JWT tabanlıdır, hafiftir ve REST API'lerle, mobil uygulamalarla, tek sayfa uygulamalarıyla mükemmel uyum sağlar. Yeni bir entegrasyon yapıyorsanız varsayılan tercihiniz OIDC olmalıdır. Kullanıcı giriş yaptığında Keycloak bir kimlik token'ı (ID token) ve bir erişim token'ı (access token) döndürür; uygulama bu token içindeki claim'leri okuyarak kullanıcının kim olduğunu ve neye yetkili olduğunu anlar.

SAML 2.0, daha eski ama kurumsal dünyada hâlâ çok yaygın olan XML tabanlı bir protokoldür. Birçok geleneksel kurumsal yazılım (bazı ERP, İK ve doküman yönetim sistemleri) yalnızca SAML destekler. Keycloak bu uygulamalar için mükemmel bir SAML kimlik sağlayıcısı (IdP) olur.

Aşağıdaki tablo iki protokolü karar vermenizi kolaylaştıracak şekilde özetler.

Pratik kural şudur: uygulama OIDC destekliyorsa OIDC seçin. Yalnızca SAML destekliyorsa SAML kullanın. Keycloak ikisini de aynı realm içinde sorunsuz barındırır, yani bir realm hem OIDC hem SAML istemcilerine aynı anda hizmet verebilir.

Docker ile Keycloak Kurulumu#

Keycloak'u üretim ortamında çalıştırmanın en pratik yolu Docker'dır. Hızlı bir deneme için tek satırlık komut yeterlidir, ancak gerçek kullanım için mutlaka harici bir veritabanı ve kalıcı yapılandırma gerekir. Bu tür bir kurulum için en az 2 çekirdek ve 2-4 GB RAM sunan bir VDS sunucu rahatlıkla yeterli olur.

Önce hızlı denemeyi görelim. Aşağıdaki komut Keycloak'u geliştirme modunda ayağa kaldırır; bu mod yalnızca test içindir ve production'da kullanılmamalıdır.

docker run -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=degistir-beni \
  quay.io/keycloak/keycloak:26.0 \
  start-dev

Gerçek kurulum için PostgreSQL ve kalıcı bir yapı gerekir. Aşağıdaki docker-compose.yml üretime yakın bir kurulumu tanımlar.

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: guclu-db-parolasi
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    command: start --optimized
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: guclu-db-parolasi
      KC_HOSTNAME: kimlik.ornekfirma.com
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: degistir-beni
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    restart: unless-stopped

volumes:
  pg_data:

Keycloak'u genellikle bir ters vekil (reverse proxy) arkasında, TLS sonlandırmasıyla çalıştırırsınız. Nginx için tipik yapılandırma şöyledir.

server {
    listen 443 ssl http2;
    server_name kimlik.ornekfirma.com;

    ssl_certificate     /etc/letsencrypt/live/kimlik.ornekfirma.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kimlik.ornekfirma.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Kimlik sunucusu için geçerli bir sertifika şarttır; kullanıcı parolaları buradan geçtiği için TLS pazarlık konusu değildir. Sertifika için ücretsiz ve ücretli SSL seçeneklerinden yararlanabilir, saldırı yüzeyini azaltmak için bir WAF katmanı ekleyebilirsiniz. Alan adı yönlendirmesi için basit bir A kaydı yeterlidir.

kimlik   IN   A   203.0.113.25

İlk Realm ve İstemci Oluşturma#

Kurulum tamamlandıktan sonra https://kimlik.ornekfirma.com adresinden yönetim konsoluna admin bilgileriyle girin. İlk işiniz üretim için ayrı bir realm açmak olmalı. Sol üstteki realm seçicisinden "Create realm" deyip ada sirket verin ve oluşturun. Bundan sonraki tüm işlemleri master realm'de değil bu yeni realm'de yapacaksınız.

Şimdi ilk istemcinizi ekleyelim. Örnek olarak bir web uygulamasını OIDC ile bağlayalım. "Clients" menüsünden "Create client" deyin; protokol olarak OpenID Connect, client ID olarak web-uygulama girin. Bir sonraki adımda "Client authentication" seçeneğini açarsanız istemci confidential (gizli) olur ve bir client secret üretir. Son adımda geçerli yönlendirme URI'lerini tanımlamanız gerekir; buraya uygulamanızın geri dönüş adresini yazın.

Client ID                 = web-uygulama
Client authentication     = On
Valid redirect URIs       = https://uygulama.ornekfirma.com/*
Web origins               = https://uygulama.ornekfirma.com

İstemciyi kaydettikten sonra "Credentials" sekmesinden client secret'ı kopyalayın. Uygulamanızın OIDC yapılandırmasında bu değerlere ihtiyacınız olacak. Keycloak, her realm için standart bir keşif (discovery) adresi yayınlar; uygulamanız gerekli tüm uç noktaları buradan otomatik öğrenir.

issuer          = https://kimlik.ornekfirma.com/realms/sirket
discovery_url   = https://kimlik.ornekfirma.com/realms/sirket/.well-known/openid-configuration
client_id       = web-uygulama
client_secret   = KOPYALADIGINIZ-DEGER

Bir kullanıcı eklemek için "Users" menüsünden "Add user" deyin, kullanıcı adı ve e-postayı girin, sonra "Credentials" sekmesinden geçici bir parola tanımlayın. "Temporary" işaretli kalırsa kullanıcı ilk girişte parolasını değiştirmek zorunda kalır; bu, yeni hesap dağıtımı için güvenli bir varsayılandır. Ardından "Role mapping" veya grup üyeliği ile yetkilerini atayın. Bu noktadan sonra uygulamanızın giriş butonu kullanıcıyı Keycloak'a yönlendirir ve SSO devreye girer.

LDAP ile Kullanıcı Federasyonu#

Birçok kurumun kullanıcıları zaten bir dizin sunucusunda, tipik olarak Active Directory veya OpenLDAP'ta durur. Keycloak bu kullanıcıları kopyalamak yerine kullanıcı federasyonu ile mevcut dizine bağlanabilir. Böylece çalışanlar zaten kullandıkları kurumsal hesaplarıyla giriş yapar, parola yönetimi tek merkezde kalır.

Yapılandırma için sirket realm'inde "User federation" menüsüne gidin ve "Add LDAP providers" seçin. Bağlantı bilgilerini dizin sunucunuza göre doldurun.

Connection URL          = ldaps://dc01.ornekfirma.local:636
Bind type               = simple
Bind DN                 = CN=keycloak-svc,OU=Servis,DC=ornekfirma,DC=local
Users DN                = OU=Calisanlar,DC=ornekfirma,DC=local
Username LDAP attribute = sAMAccountName
UUID LDAP attribute     = objectGUID
Edit mode               = READ_ONLY
Import users            = On
Sync period             = 3600

Burada Edit mode seçimi kritiktir. READ_ONLY modunda Keycloak dizini yalnızca okur, hiçbir değişiklik yazmaz; bu, dizinin başka sistemler tarafından yönetildiği ortamlar için en güvenli seçenektir. WRITABLE modu Keycloak'un dizine yazmasına izin verir. Bağlantıyı test ettikten sonra "Synchronize all users" ile ilk eşitlemeyi başlatabilirsiniz. Dizindeki gruplarınızı Keycloak rollerine eşlemek için "Mappers" sekmesinden bir group mapper eklemek yerinde olur; böylece Active Directory'deki "Muhasebe" grubu otomatik olarak Keycloak yetkisine dönüşür.

LDAP servis hesabına yalnızca okuma yetkisi verin ve mümkünse ayrı, sınırlı bir hesap kullanın. Bu tür dizin ve sunucu bakımını kendiniz yönetmek istemiyorsanız sunucu yönetimi hizmetimiz bu yapılandırmaları sizin adınıza üstlenebilir.

Çok Faktörlü Kimlik Doğrulama (MFA)#

Keycloak'un en değerli özelliklerinden biri, çok faktörlü kimlik doğrulamayı uygulama tarafında hiç kod yazmadan sağlamasıdır. MFA'yı realm düzeyinde açtığınızda, o realm'e bağlı tüm uygulamalar otomatik olarak korunmuş olur. İki faktörlü doğrulamanın neden vazgeçilmez olduğunu ve nasıl çalıştığını daha ayrıntılı incelemek isterseniz iki faktörlü doğrulama rehberimizi okuyabilirsiniz.

En yaygın ikinci faktör OTP, yani zaman tabanlı tek kullanımlık paroladır. Google Authenticator, Aegis veya benzeri uygulamalarla çalışır. Zorunlu hale getirmek için "Authentication" menüsünden "Required actions" bölümüne gidip "Configure OTP" eylemini varsayılan olarak işaretleyin; böylece her yeni kullanıcı ilk girişte OTP kurmak zorunda kalır. Daha ince kontrol için "Flows" bölümünde giriş akışını kopyalayıp OTP adımını "Required" yapabilirsiniz.

OTP type          = totp
Algoritma         = SHA1
Basamak sayisi    = 6
Periyot           = 30 saniye
Required action   = Configure OTP (Default: On)

Keycloak ayrıca WebAuthn / Passkey destekler; bu sayede kullanıcılar donanım güvenlik anahtarı (YubiKey) veya cihazlarının biyometrik doğrulaması (parmak izi, yüz tanıma) ile giriş yapabilir. Passkey, kimlik avına karşı OTP'den çok daha dayanıklıdır ve giderek standart hale geliyor. Kullanıcı bazlı parola yönetimini de merkezîleştirmek istiyorsanız, Keycloak SSO'sunu bir Vaultwarden parola yöneticisi ile birleştirmek güçlü bir kombinasyon oluşturur.

Keycloak ve Authentik Karşılaştırması#

Keycloak'a alternatif ararken en çok karşınıza çıkacak isim Authentik'tir. İkisi de açık kaynak, self-hosted kimlik sağlayıcılarıdır ama felsefeleri farklıdır. Doğru seçimi yapmak için temel farkları bilmek gerekir.

Keycloak Java tabanlıdır, çok olgundur ve büyük kurumsal dağıtımlarda uzun yıllardır sınanmıştır. Standartlara sıkı sıkıya bağlıdır, geniş bir ekosistemi ve büyük bir topluluğu vardır. Karşılığında daha fazla bellek tüketir ve arayüzü bazı kullanıcılara ağır gelebilir. Authentik ise Python tabanlıdır, daha modern ve akıcı bir arayüz sunar, kaynak tüketimi daha düşüktür ve akış (flow) tabanlı esnek yapılandırmasıyla öne çıkar.

Pratik öneri şudur: standartlara tam uyum, geniş entegrasyon desteği ve kanıtlanmış kurumsal olgunluk önceliğinizse Keycloak seçin. Daha hafif kaynak kullanımı, modern arayüz ve hızlı kurulum arıyorsanız Authentik güçlü bir alternatiftir. İki proje de üretime uygundur; yanlış seçim diye bir şey yoktur, yalnızca ihtiyacınıza daha iyi oturan bir seçim vardır. Her iki uygulamayı da tek tıkla kurmak için App Center katalogumuza göz atabilirsiniz.

Güvenlik ve Yedekleme Notları#

Bir kimlik sunucusu tüm sistemlerinizin kapısıdır; ele geçirilirse her şey ele geçirilir. Bu yüzden birkaç kuralı asla ihmal etmeyin. Master realm admin hesabını yalnızca zorunlu hallerde kullanın, ona güçlü bir parola ve MFA tanımlayın. Yönetim konsolunu mümkünse yalnızca iç ağdan veya VPN üzerinden erişilebilir kılın. Keycloak'u ve altındaki veritabanını düzenli güncelleyin.

Veritabanı yedeği hayati önemdedir; realm yapılandırması, kullanıcılar ve istemci sırları hepsi PostgreSQL'de durur. Düzenli bir dump alın ve bu yedeği güvenli, dış bir konumda saklayın.

pg_dump -U keycloak -Fc keycloak > keycloak-$(date +%F).dump

Otomatik ve dış konuma alınan yedekler için yedekleme çözümlerimizden yararlanabilir, kurulumu başka bir sunucuya taşımanız gerektiğinde ücretsiz site taşıma hizmetimizden destek alabilirsiniz. Bu disiplinle bir donanım arızasında bile kimlik altyapınızı dakikalar içinde ayağa kaldırabilirsiniz.

Sıkça Sorulan Sorular#

Keycloak ücretsiz mi?#

Evet, Keycloak tamamen açık kaynaklıdır ve Apache 2.0 lisansı altında ücretsiz kullanılır. Tüm SSO, OIDC, SAML, LDAP federasyonu ve MFA özellikleri açık kaynak sürümde eksiksiz mevcuttur. Red Hat, ticari destek isteyen kurumlar için ayrıca destekli bir sürüm sunar, ancak yazılımın kendisi için lisans ücreti ödemeniz gerekmez. Küçük bir işletmeden büyük bir kuruma kadar herkes production ortamında ücretsiz sürümü çalıştırabilir.

Keycloak çalıştırmak için ne kadar kaynak gerekir?#

Küçük ve orta ölçekli kurulumlar için 2 çekirdek ve 2-4 GB RAM sunan bir sunucu genellikle yeterlidir. Java tabanlı olduğu için Keycloak bellek kullanımına duyarlıdır; kullanıcı sayısı ve eşzamanlı oturum arttıkça belleği yükseltmeniz gerekebilir. Veritabanını ayrı tutmanız ve production'da mutlaka harici PostgreSQL kullanmanız performans için önemlidir. Yük artan büyük dağıtımlarda birden fazla Keycloak örneğini küme halinde çalıştırarak yatay ölçekleme yapabilirsiniz.

OIDC ve SAML arasında hangisini seçmeliyim?#

Yeni bir uygulama entegre ediyorsanız ve uygulama OIDC destekliyorsa OIDC tercih edin; daha hafif, daha modern ve API dostu bir protokoldür. SAML'i yalnızca uygulamanız OIDC desteklemiyor ancak SAML destekliyorsa kullanın; bu durum genellikle eski kurumsal yazılımlarda görülür. Keycloak ikisini aynı realm içinde sorunsuz barındırdığı için tek bir kimlik altyapısıyla hem modern hem eski uygulamalara hizmet verebilirsiniz. Karar verirken uygulamanın belgelerine bakmak en kesin yoldur.

Mevcut Active Directory kullanıcılarımı Keycloak'a bağlayabilir miyim?#

Evet, bunu kullanıcı federasyonu ile yaparsınız. Keycloak'a LDAP sağlayıcısı olarak Active Directory'nizi tanımladığınızda çalışanlar zaten kullandıkları kurumsal hesaplarıyla giriş yapabilir ve kullanıcıları kopyalamanıza gerek kalmaz. Federasyonu okuma modunda (READ_ONLY) kurmanız, dizininizin başka sistemler tarafından yönetildiği durumlarda en güvenli yaklaşımdır. Grup eşleyicilerle Active Directory gruplarınızı doğrudan Keycloak rollerine bağlayabilir, böylece yetki yönetimini tek merkezden sürdürebilirsiniz.

Keycloak güncellemeleri sırasında oturumlar kesilir mi?#

Tek örnekli bir kurulumda güncelleme sırasında servis kısa süre kesileceği için aktif oturumlar geçici olarak etkilenir. Bu kesintiyi ortadan kaldırmak için Keycloak'u birden fazla örnekle küme halinde çalıştırıp örnekleri sırayla güncelleyebilirsiniz; bu yöntemde kullanıcılar kesinti hissetmez. Küçük kurulumlarda ise güncellemeyi düşük trafikli saatlere planlamak ve öncesinde veritabanı yedeği almak yeterli bir önlemdir. Her durumda büyük sürüm atlamalarında değişiklik notlarını okumanız, uyumluluk sorunlarından kaçınmak için önemlidir.

Kapanış#

Keycloak, dağınık kullanıcı yönetimini tek bir güvenli merkeze toplayan, kurumsal düzeyde olgunlaşmış bir kimlik ve erişim yönetimi platformudur. Realm, istemci ve rol yapısını kavradığınızda; OIDC ile SAML'i doğru yerlerde kullandığınızda; LDAP federasyonu ve MFA'yı devreye aldığınızda, işletmenizin tüm uygulamaları için sağlam, ölçeklenebilir ve merkezî bir güvenlik katmanı elde edersiniz. Doğru kurulmuş bir Keycloak, hem kullanıcı deneyimini basitleştirir hem de saldırı yüzeyini belirgin biçimde küçültür.

Kendi kimlik sunucunuzu kurmak için güçlü ve kararlı bir altyapıya ihtiyacınız var. Clou.TR'nin yüksek performanslı VDS sunucu ve sanal sunucu çözümleriyle Keycloak'u dakikalar içinde ayağa kaldırabilir, SSL ve WAF katmanlarıyla güvenliğini pekiştirebilir, uzman ekibimizin sunucu yönetimi desteğiyle kurulumu baştan sona bize bırakabilirsiniz. Kurumsal kimlik altyapınızı bugün sağlam temeller üzerine kurmak için ürün sayfalarımızı inceleyin.