Keycloak Kurulumu 2026: Şirketiniz İçin Tek Şifreyle Giriş (SSO), Üretim Ayarları ve Yedekleme

Şirkette Nextcloud, Mattermost, Grafana, GitLab ya da Odoo gibi birden fazla uygulama kullanıyorsanız, her birinde ayrı kullanıcı ve parola yönetmek hem çalışanı hem BT ekibini yorar. İşten ayrılan birinin hesabını beş ayrı yerde kapatmayı unutmak da gerçek bir güvenlik açığıdır. Keycloak bu sorunu tek bir giriş noktasıyla çözer. Bu rehberde Keycloak'u şirketiniz için üretim ortamında, güvenli biçimde kurmanın adımlarını resmi belgelere dayanarak (Ekim 2026, Keycloak 26.8) anlatıyoruz. Tek şifreyle girişin neden gerekli olduğunu merak ediyorsanız önce şirket güvenliği rehberimize bakabilirsiniz.

Keycloak ne yapar?

• Tek şifreyle giriş (SSO): OpenID Connect ve SAML destekleyen uygulamalar girişi Keycloak'a bırakır; çalışan bir kez giriş yapar.
• Mevcut kullanıcı dizinine bağlanma: resmi belgelerin ifadesiyle Keycloak, mevcut LDAP ve Active Directory sunucularına bağlanabilir. Kullanıcıları ikinci kez oluşturmanız gerekmez.
• Kimlik aracılığı: Google, Microsoft Entra gibi harici OpenID Connect veya SAML sağlayıcılarıyla girişe aracılık eder.
• İki aşamalı doğrulama, parola politikaları ve oturum yönetimi tek yerden yönetilir.

Sunucu ve veritabanı

Keycloak OpenJDK ile doğrudan sunucuda ya da Docker, Podman, Kubernetes veya OpenShift üzerinde çalışır. Üretimde gömülü geliştirme veritabanı kullanılamaz; desteklenen veritabanları arasında PostgreSQL 14–18, MariaDB, MySQL 8, SQL Server ve Oracle vardır. Resmi boyutlandırma rehberine göre bir Keycloak örneği, realm önbelleği ve 10.000 oturum dahil yaklaşık 1250 MB bellek kullanır. İşlemci ihtiyacı giriş yoğunluğuna bağlıdır: saniyede her 15 parolalı giriş için 1 vCPU önerilir. Resmi belgeler tipik bir üretim ortamının iki veya daha fazla Keycloak örneğinden oluştuğunu belirtir. Örnekler birbirini aynı veritabanı üzerinden bulur ve dağıtık önbelleği (Infinispan) paylaşır.

Üretim modunda çalıştırma

Keycloak'un iki çalışma modu vardır. start-dev ilk deneme içindir: HTTP açıktır ve önbellek yalnızca yereldir. start ise üretim modudur ve "varsayılan olarak güvenli" ilkesiyle çalışır. Alan adı ve TLS ayarlanmadan başlamaz, hata verir. Açılışı hızlandırmak için yapılandırma önce kc.sh build ile derlenir, ardından kc.sh start --optimized ile başlatılır. Konteyner kullanıyorsanız bu derleme adımını imajı oluştururken yapan çok aşamalı (multi-stage) bir imaj hazırlamak resmi öneridir.

Temel üretim ayarları:

• Alan adı: --hostname ile Keycloak'un dışarıdan erişilen adresi verilir (ör. giris.sirketiniz.com.tr). Resmi belgeler, yönetim konsolunu ve API'yi ayrı bir alan adından sunmayı iyi uygulama olarak önerir.
• HTTPS: belgelere göre Keycloak'a giden ve Keycloak'tan çıkan tüm iletişim güvenli kanal gerektirir.
• Ters vekil (nginx, Traefik vb.): vekil TLS'i sonlandırıyorsa --proxy-headers xforwarded (ya da forwarded) ayarlanır ve vekilin bu başlıkları kendisi yazdığından emin olunur. TLS doğrudan Keycloak'a iletiliyorsa bu ayar kullanılmaz.
• Veritabanı: --db postgres --db-url-host … --db-username … --db-password … veya tam bir JDBC adresiyle --db-url.
• Sağlık kontrolü: --health-enabled=true ile açılır ve 9000 numaralı yönetim portundan sunulur (ör. /health/ready). Yük dengeleyici ve izleme bu adresi kullanmalıdır. 9000 portu internete açılmamalıdır.

İlk yönetici hesabı

İlk çalıştırmada, ana (master) realm henüz yokken --bootstrap-admin-username ve --bootstrap-admin-password ile (ya da ortam değişkenleriyle) geçici bir yönetici oluşturulur. Resmi belgelere göre bu hesap yalnız gerektiği süre kadar var olmalı ve sonra elle silinmelidir. Doğru sıra şöyledir: geçici hesapla giriş yapın, kalıcı ve iki aşamalı doğrulamalı bir yönetici oluşturun, geçici hesabı silin. Yönetici erişimini kaybederseniz tüm düğümler durdurularak bootstrap-admin komutuyla kurtarma yapılabilir.

Yedekleme ve sürüm yükseltme

Keycloak'un yapılandırması, kullanıcıları ve istemcileri veritabanında tutulur. Bu yüzden asıl yedek veritabanı yedeğidir. Buna sunucudaki yapılandırma dosyaları ve özel temalar da eklenmelidir. kc.sh export ile realm dışa aktarımı yapılabilir, ancak resmi belgeler bunun yedekleme ve geri yükleme için sınırlamaları olduğunu belirtir. Dışa aktarım olayları, kalıcı oturumları ve iptal edilmiş belirteçleri içermez, sunucu çalışırken de yapılamaz.

Sürüm yükseltmede resmi rehberin uyarısı açıktır: önce veritabanını yedekleyin, çünkü Keycloak veritabanı değişikliklerinin geri alınmasını desteklemez. Ara ve ana sürüm geçişlerinde Keycloak kapatılır; 26.6'dan beri yama sürümlerinde kesintisiz (rolling) güncelleme desteklenir. Veritabanı geçişi açılışta kendiliğinden çalışır. Çok büyük tablolarda (300.000 kaydın üzerinde) bazı dizinleri otomatik oluşturmaz, gereken SQL'i günlüğe yazar.

Uygulamaları bağlama

Keycloak kurulduktan sonra her uygulama için bir "istemci" (client) tanımlanır ve uygulamanın OIDC ya da SAML ayarlarına Keycloak'un adresi girilir. Nextcloud, Grafana, GitLab, Outline ve Open WebUI gibi uygulamalar bunu destekler. Ancak bazı yazılımlarda SSO ücretli sürüme ayrılmıştır: Formbricks'te SSO kurumsal lisanstadır, LiteLLM'de 5 kullanıcıdan sonrası ücretlidir, Mattermost ise ücretsiz Team Edition'ı SSO gerekmeyen ekipler için önerir. Uygulama seçmeden önce SSO'nun hangi sürümde olduğuna bakın. Lisans tuzakları için açık kaynak lisansları rehberimize göz atabilirsiniz.

Keycloak kimler için gereksiz?

• Tek bir uygulama kullananlar: yalnız bir yazılımınız varsa onun kendi kullanıcı yönetimi yeterlidir.
• Bakımı üstlenecek kimse yoksa: Keycloak tüm girişlerin geçtiği kapıdır. Güncellenmeyen ya da yedeği olmayan bir Keycloak, bütün uygulamaları birden etkiler.
• Daha sade bir çözüm yetiyorsa: küçük ekipler için authentik ya da Authelia daha kolay yönetilebilir.

e-veri.com ile Keycloak

Keycloak'u Türkiye'deki sunucularımızda yönetilen hosting olarak ya da sizin sunucunuzda kuruyoruz. Kapsam: PostgreSQL ile üretim kurulumu, alan adı, HTTPS ve ters vekil ayarları, LDAP/Active Directory bağlantısı, iki aşamalı doğrulama, uygulamalarınızın tek şifreyle girişe bağlanması, veritabanı yedeği, izleme ve sürüm yükseltmeleri. Ayrıntılar kurumsal hizmetler sayfamızda.

Sık sorulan sorular

Keycloak'un güncel sürümü hangisi?

1 Ekim 2026'da yayımlanan Keycloak 26.8.

start-dev ile üretimde çalıştırılabilir mi?

Hayır. start-dev yalnız deneme içindir: HTTP açıktır ve önbellek yereldir. Üretimde kc.sh start kullanılır; alan adı ve HTTPS ayarlanmadan başlamaz.

Keycloak için hangi veritabanı gerekir?

Üretimde harici bir veritabanı şarttır. PostgreSQL 14–18, MariaDB, MySQL 8, SQL Server ve Oracle desteklenir; gömülü geliştirme veritabanı yalnız deneme içindir.

Keycloak yedeği nasıl alınır?

Asıl yedek veritabanı yedeğidir; yapılandırma dosyaları ve özel temalar da yedeklenmelidir. kc.sh export ile realm dışa aktarılabilir, ancak bu yöntem olayları ve oturumları içermediği için tek başına yedek sayılmamalıdır.

Keycloak Active Directory ile çalışır mı?

Evet. Keycloak mevcut LDAP ve Active Directory sunucularına bağlanarak kullanıcıları oradan alabilir; ayrıca harici OIDC ve SAML kimlik sağlayıcılarıyla girişe aracılık eder.

Sürüm yükseltirken nelere dikkat edilmeli?

Önce veritabanı yedeklenmelidir, çünkü Keycloak veritabanı değişikliklerinin geri alınmasını desteklemez. Ara ve ana sürümlerde Keycloak kapatılarak yükseltilir; yama sürümlerinde 26.6'dan beri kesintisiz güncelleme desteklenir.