Docker Run ile Güvenli Keycloak Kurulumu: SSL Sertifikalarıyla Adım Adım Rehber

Kimlik ve erişim yönetimi modern uygulamaların vazgeçilmez bir parçasıdır ve bu alanda Keycloak güçlü bir açık kaynak çözüm sunar. Ancak, Keycloak’u Docker üzerinde çalıştırırken güvenliği sağlamak, özellikle hassas verilerin iletimi söz konusu olduğunda kritik öneme sahiptir. Peki, Docker run komutunu kullanarak SSL sertifikalarıyla güvenli bir Keycloak kurulumunu adım adım nasıl gerçekleştirebiliriz? Bu rehberde, üretim ortamına hazır, güvenli bir Keycloak örneğini Docker konteynerlerinde nasıl hayata geçireceğinizi, SSL/TLS şifrelemesinin tüm detaylarıyla birlikte ele alacağız.

Dijital dünyada kimlik ve erişim yönetimi, uygulamaların ve verilerin korunması açısından merkezi bir rol oynamaktadır. Keycloak, bu alanda lider açık kaynak çözümlerden biri olarak öne çıkar; kullanıcı kimlik doğrulama, yetkilendirme, tek oturum açma (SSO) ve sosyal kimlik sağlayıcı entegrasyonu gibi geniş bir yelpazede hizmetler sunar. Web uygulamaları, mobil uygulamalar ve API’ler için güvenli bir kimlik katmanı oluşturmak isteyen geliştiriciler ve kurumlar için Keycloak, esnekliği ve geniş özellik setleriyle cazip bir seçenektir. Ancak, Keycloak’un sunduğu bu güçlü özellikler, doğru güvenlik önlemleri alınmadığında potansiyel riskleri de beraberinde getirebilir. Özellikle kullanıcı kimlik bilgileri, oturum token’ları ve yetkilendirme kodları gibi hassas verilerin ağ üzerinden iletimi sırasında bu riskler en üst düzeye çıkar.

İşte bu noktada SSL/TLS (Secure Sockets Layer / Transport Layer Security) devreye girer. SSL/TLS, internet üzerindeki veri trafiğini şifreleyerek gizliliği, veri bütünlüğünü ve sunucu kimlik doğrulamasını sağlamak için kullanılan standart bir şifreleme protokolüdür. Bir kullanıcı web tarayıcısı üzerinden Keycloak’a eriştiğinde veya bir uygulama Keycloak ile iletişim kurduğunda, bu bağlantının SSL/TLS ile korunması hayati öneme sahiptir. SSL/TLS sertifikaları, sunucunun kimliğini doğrular ve istemcinin gerçekten doğru Keycloak sunucusuyla iletişim kurduğundan emin olmasını sağlar. Ayrıca, HTTPS (HTTP Secure) protokolünü kullanarak, istemci ile sunucu arasında aktarılan tüm verilerin şifrelenmesini garanti eder. Bu şifreleme, araya giren kötü niyetli kişilerin (man-in-the-middle saldırıları) veri paketlerini dinlemesini veya değiştirmesini engeller.

Güvenli bir Keycloak kurulumu için SSL/TLS’nin neden bu kadar kritik olduğunu birkaç temel başlıkta özetleyebiliriz:

• Veri Gizliliği: Kullanıcı adı, şifre, e-posta gibi hassas bilgiler, şifreleme sayesinde yetkisiz erişime karşı korunur. Bu, özellikle kamuya açık Wi-Fi ağları gibi güvensiz ortamlarda veri sızıntılarını önler.
• Veri Bütünlüğü: SSL/TLS, aktarılan verilerin üçüncü partiler tarafından değiştirilmediğini garanti eder. Bu, oturum token’larının veya yetkilendirme kodlarının yolda manipüle edilmesini engeller.
• Sunucu Kimlik Doğrulama: SSL sertifikaları, istemcinin bağlantı kurduğu sunucunun gerçekten iddia ettiği sunucu olduğunu doğrular. Bu, kimlik avı (phishing) saldırılarına ve sahte sunuculara karşı koruma sağlar.
• Uyumluluk ve Güven: Modern tarayıcılar ve uygulamalar, HTTPS üzerinden güvenli bağlantıları zorunlu tutar. Güvenli olmayan (HTTP) bağlantılar genellikle uyarılarla karşılaşır ve kullanıcılar tarafından güvensiz olarak algılanır. Ayrıca, birçok regülasyon ve uyumluluk standardı (GDPR, PCI DSS vb.) hassas verilerin şifrelenmesini zorunlu kılar.
• API Güvenliği: Keycloak, OAuth 2.0 ve OpenID Connect (OIDC) gibi protokoller aracılığıyla uygulamalarınızla iletişim kurar. Bu protokollerin güvenliği, temelinde SSL/TLS şifrelemesine dayanır. Eğer Keycloak ile uygulamalarınız arasındaki iletişim güvenli değilse, yetkilendirme kodları ve erişim token’ları kolayca ele geçirilebilir.

Dolayısıyla, Keycloak’u Docker üzerinde çalıştırırken, Docker konteynerinin doğru SSL/TLS sertifikalarıyla yapılandırılması sadece bir “güzel olur” değil, bir “olmazsa olmaz” gerekliliktir. Bu makale boyunca, bu kritik güvenlik katmanını Docker run komutlarıyla nasıl kolayca entegre edeceğimizi adım adım ele alacağız. Bu sayede, hem geliştirme hem de üretim ortamlarınızda güvenli ve kararlı bir kimlik yönetim sistemi kurabileceksiniz.

Docker Run ile Keycloak: Temel Kurulum ve SSL Öncesi Hazırlıklar Nasıl Yapılır?

Keycloak’u Docker üzerinde çalıştırmak, hızlı kurulum, kolay taşınabilirlik ve kaynak izolasyonu gibi birçok avantaj sunar. SSL sertifikalarını entegre etmeden önce, Keycloak’un temel bir Docker kurulumunu anlamak ve gerekli ön hazırlıkları yapmak önemlidir. Bu bölüm, Keycloak’u Docker ile nasıl başlatacağınızı ve SSL entegrasyonu için hangi dosya ve dizin yapılandırmalarına ihtiyacınız olduğunu detaylandıracaktır.

Keycloak Docker İmajını Çekme ve İlk Çalıştırma

Keycloak’un resmi Docker imajı Docker Hub’da mevcuttur ve docker pull komutu ile kolayca indirilebilir. Tercih edilen sürümü belirterek, belirli bir kararlı sürümü kullanmak iyi bir uygulamadır:

docker pull jboss/keycloak:18.0.0

Yukarıdaki komut, Keycloak'un 18.0.0 sürümünü yerel sisteminize çekecektir. Sürüm numarası, ihtiyaçlarınıza göre değişiklik gösterebilir. İndirme işlemi tamamlandıktan sonra, Keycloak'u bir Docker konteynerinde başlatabiliriz. Basit bir çalıştırma komutu genellikle şöyledir:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password jboss/keycloak:18.0.0 start-dev

Bu komutun detaylarına inelim:

• -p 8080:8080: Konteynerin 8080 portunu ana makinenin 8080 portuna eşler. Keycloak varsayılan olarak 8080 portunda HTTP üzerinden çalışır.
• -e KEYCLOAK_ADMIN=admin: Keycloak yönetim konsoluna erişmek için kullanılacak yönetici kullanıcı adını (admin) ayarlar.
• -e KEYCLOAK_ADMIN_PASSWORD=password: Yönetici kullanıcının şifresini (password) ayarlar. Bu şifreyi üretim ortamında mutlaka daha karmaşık ve güvenli bir şifre ile değiştirmelisiniz.
• jboss/keycloak:18.0.0: Kullanılacak Docker imajının adını ve sürümünü belirtir.
• start-dev: Keycloak'u geliştirme modunda başlatır. Bu mod, bazı güvenlik kontrollerini atlayarak hızlı başlangıç sağlar ancak üretim ortamı için uygun değildir. Üretimde start komutu kullanılmalı ve veritabanı ile SSL gibi konfigürasyonlar doğru şekilde yapılmalıdır.

Bu komutu çalıştırdıktan sonra, tarayıcınızdan http://localhost:8080 adresine giderek Keycloak yönetim paneline erişebilmeniz gerekir. Ancak dikkat, bu bağlantı şu an için güvenli değildir ve SSL/TLS şifrelemesi kullanmamaktadır. Bir sonraki adımlarımız, bu bağlantıyı güvenli hale getirmek üzerine yoğunlaşacaktır.

SSL Entegrasyonu İçin Ön Hazırlıklar: Sertifikalar ve Keystore

Keycloak'u SSL ile çalıştırmanın temelinde, uygun sertifikalara sahip olmak ve bunları Keycloak'un anlayabileceği bir formatta sunmak yatar. Genellikle Keycloak (ve arkasındaki WildFly/Undertow web sunucusu), sertifikaları bir Java Keystore (JKS) veya PKCS#12 (.p12) dosyasında bekler. Bu dosyalar, hem özel anahtarı (private key) hem de SSL sertifikasını (public certificate) içerir.

SSL sertifikalarını edinme ve hazırlama süreci iki ana yolu takip edebilir:

1. Geliştirme Ortamı İçin Kendinden İmzalı (Self-Signed) Sertifikalar: Hızlı testler veya dahili geliştirme ortamları için kendinden imzalı sertifikalar oluşturabilirsiniz. Bu sertifikalar, güvenilir bir Sertifika Yetkilisi (CA) tarafından doğrulanmadığı için tarayıcılar tarafından "güvenli değil" uyarısı verir, ancak şifreleme işlevselliğini test etmek için yeterlidir.
2. Üretim Ortamı İçin Güvenilir Sertifika Yetkilisi (CA) Tarafından İmzalanmış Sertifikalar: Üretim ortamlarında mutlaka Let's Encrypt, DigiCert, GlobalSign gibi güvenilir bir CA tarafından imzalanmış sertifikalar kullanılmalıdır. Bu sertifikalar, tarayıcılar tarafından otomatik olarak güvenilir kabul edilir ve herhangi bir uyarı göstermez.

Bu makalede, öncelikle kendinden imzalı sertifikaların nasıl oluşturulacağını ve ardından bunların Keycloak'a nasıl entegre edileceğini ele alacağız. Üretim ortamı için CA sertifikaları da benzer bir mantıkla Keystore'a aktarılabilir.

Bir adet anahtar deposu (keystore) ve bir adet güven deposu (truststore) dosyasına ihtiyacımız olacak. Keystore, Keycloak sunucusunun kendi kimliğini doğrulamak için kullanacağı özel anahtar ve sertifika çiftini içerirken, truststore ise Keycloak'un harici servislere (örneğin bir LDAP sunucusu veya başka bir OIDC sağlayıcısı) bağlanırken onların kimliğini doğrulamak için güveneceği sertifikaları barındırır.

Sertifikaları hazırladıktan sonra, bunları Docker konteynerine nasıl monte edeceğimiz ve Keycloak'u bu sertifikaları kullanmaya nasıl ikna edeceğimiz bir sonraki adım olacaktır. Bu, Docker'ın volume (birim) mekanizmasını kullanarak ana makinedeki dosyaları konteyner içine kopyalamak ve Keycloak'un başlangıç ayarlarını (örneğin Java System Properties) uygun şekilde yapılandırmakla mümkün olacaktır. Bu ön hazırlıklar, güvenli bir Keycloak ortamının temelini oluşturur ve sorunsuz bir SSL entegrasyonu için kritik öneme sahiptir.

Kendinden İmzalı SSL Sertifikası Oluşturma ve Keycloak İçin Keystore Hazırlığı Nasıl Yapılır?

Geliştirme ve test ortamları için hızlıca bir SSL sertifikası edinmek gerektiğinde, kendinden imzalı (self-signed) sertifikalar pratik bir çözüm sunar. Bu sertifikalar, resmi bir Sertifika Yetkilisi (CA) tarafından imzalanmadığı için tarayıcılar tarafından "güvenli değil" uyarısı verse de, SSL/TLS şifrelemesinin işlevselliğini test etmek için tamamen yeterlidir. Bu bölümde, OpenSSL aracını kullanarak kendinden imzalı bir sertifika çiftini nasıl oluşturacağınızı ve Keycloak'un anlayacağı bir Java Keystore (JKS veya PKCS#12) dosyasına nasıl dönüştüreceğinizi adım adım açıklayacağız.

Adım 1: OpenSSL ile Özel Anahtar ve Sertifika Oluşturma

İlk olarak, bir özel anahtar (.key) ve bir sertifika (.crt) dosyası oluşturacağız. Bu işlem için OpenSSL kullanacağız. Komut satırınızı açın ve aşağıdaki komutu çalıştırın:

openssl req -x509 -newkey rsa:2048 -keyout keycloak.key -out keycloak.crt -days 365 -nodes -subj "/CN=localhost"

Bu komutun parametrelerini inceleyelim:

• openssl req: Yeni bir sertifika imzalama isteği (CSR) veya kendinden imzalı bir sertifika oluşturmak için kullanılır.
• -x509: Bir CSR yerine kendinden imzalı bir sertifika oluşturulacağını belirtir.
• -newkey rsa:2048: Yeni bir RSA anahtarı oluşturur (2048 bit uzunluğunda). Bu anahtar, keycloak.key dosyasına kaydedilecektir.
• -keyout keycloak.key: Oluşturulan özel anahtarın dosya adını belirtir.
• -out keycloak.crt: Oluşturulan sertifikanın dosya adını belirtir.
• -days 365: Sertifikanın geçerlilik süresini gün cinsinden ayarlar (bu örnekte 1 yıl).
• -nodes: Özel anahtarın şifrelenmeyeceğini belirtir. Bu, otomatik başlangıç senaryoları için uygundur, ancak üretim ortamında anahtarın şifrelenmesi daha güvenlidir.
• -subj "/CN=localhost": Sertifikanın konu (Subject) alanını doğrudan ayarlar. CN (Common Name) olarak localhost kullanmak, yerel testler için önemlidir. Eğer Keycloak'u bir alan adı (örneğin keycloak.example.com) üzerinden erişilebilir hale getirecekseniz, CN değerini bu alan adına ayarlamalısınız.

Bu komut başarılı bir şekilde çalıştırıldıktan sonra, bulunduğunuz dizinde keycloak.key (özel anahtarınız) ve keycloak.crt (kamu sertifikanız) adında iki dosya oluşacaktır.

Adım 2: Özel Anahtar ve Sertifikayı PKCS#12 Formatına Dönüştürme

Keycloak'un (ve Java uygulamalarının genel olarak) sertifikaları yönetmek için tercih ettiği format genellikle Java Keystore (JKS) veya PKCS#12'dir. PKCS#12, hem özel anahtarı hem de sertifikayı tek bir dosyada saklayabilen daha modern bir formattır. OpenSSL ile oluşturduğumuz .key ve .crt dosyalarını bir .p12 dosyasına dönüştürelim:

openssl pkcs12 -export -in keycloak.crt -inkey keycloak.key -name keycloak -out keycloak.p12 -passout pass:mypassword

Bu komutun parametreleri şunlardır:

• openssl pkcs12 -export: PKCS#12 formatında bir dosya dışa aktarmak için kullanılır.
• -in keycloak.crt: Sertifika dosyasını belirtir.
• -inkey keycloak.key: Özel anahtar dosyasını belirtir.
• -name keycloak: Keystore içindeki anahtar çiftine bir takma ad verir. Bu takma ad genellikle anahtar deposu erişimi için kullanılır.
• -out keycloak.p12: Oluşturulacak PKCS#12 dosyasının adını belirtir.
• -passout pass:mypassword: PKCS#12 dosyasının şifresini (mypassword) ayarlar. Bu şifre, Keycloak'u başlatırken kullanılacaktır ve üretim ortamında çok güçlü bir şifre olmalıdır.

Bu adımdan sonra, keycloak.p12 adlı bir dosyanız olacak. Bu dosya, Keycloak'un SSL bağlantıları kurmak için ihtiyaç duyduğu tüm sertifika bilgilerini içerir.

Adım 3: Keycloak İçin Sertifika Dizin Yapısı

Keycloak'un bu sertifika dosyasını bulabilmesi için, Docker konteyneri içinde belirli bir yere kopyalanması gerekir. Genellikle Keycloak konteynerinde /opt/keycloak/conf/ dizini sertifika ve yapılandırma dosyaları için uygun bir konumdur. Bu nedenle, keycloak.p12 dosyasını bu dizine monte edeceğiz. Ana makinede, bu dosyayı kolayca yönetebileceğiniz bir dizinde tutmak en iyisidir, örneğin:

mkdir -p ./certs
mv keycloak.p12 ./certs/

Böylece, ./certs/keycloak.p12 yoluyla sertifika dosyanıza erişebilir ve bunu Docker konteynerine bağlamak için kullanabilirsiniz.

Bu hazırlıklar, Keycloak'u SSL ile çalıştırmak için gerekli olan temel sertifika dosyasını sağlamış olur. Bir sonraki adımımız, bu sertifika dosyasını kullanarak Docker run komutu ile Keycloak'u güvenli bir şekilde başlatmaktır. Bu, Keycloak'un HTTPS üzerinden erişilebilir olmasını sağlayacak ve kullanıcılarınızın ve uygulamalarınızın güvenli bir bağlantı üzerinden kimlik doğrulama ve yetkilendirme işlemlerini gerçekleştirmesine olanak tanıyacaktır. Unutmayın, bu kendinden imzalı sertifika sadece geliştirme ve test amaçlıdır; üretimde her zaman güvenilir bir CA tarafından imzalanmış sertifikalar kullanmalısınız.

Docker Run ile SSL Sertifikalı Keycloak Nasıl Kurulur? Adım Adım Rehber

Önceki bölümde kendinden imzalı SSL sertifikamızı (PKCS#12 formatında) hazırladık ve Keycloak için gerekli ön yapılandırmayı tamamladık. Şimdi, bu sertifikayı Docker konteynerine entegre ederek Keycloak'u HTTPS üzerinden çalışır hale getireceğiz. Bu adım, hem sertifikayı Keycloak'un içine yerleştirmeyi hem de Keycloak'un SSL'i doğru bir şekilde kullanması için gerekli Java seçeneklerini ayarlamayı içerir.

Adım 1: Keycloak Konteynerini SSL Sertifikası ile Başlatma

Keycloak'u SSL sertifikasıyla başlatmak için docker run komutuna bazı ek parametreler eklememiz gerekecek. Öncelikle, ana makinedeki sertifika dosyamızı (keycloak.p12) Docker konteynerinin içine bağlamalıyız. Ardından, Keycloak'un hangi keystore dosyasını kullanacağını ve bu dosyanın şifresini bildirmeliyiz. Bu bilgiler genellikle Java System Properties aracılığıyla JAVA_OPTS veya KC_HTTPS_KEYSTORE_* gibi ortam değişkenleriyle sağlanır.

Aşağıdaki komut, önceki bölümde hazırladığımız sertifika dosyasını kullanarak Keycloak'u SSL ile başlatır:

docker run -p 8443:8443 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=password \
  -v ./certs/keycloak.p12:/opt/keycloak/conf/keycloak.p12 \
  -e KC_HTTPS_KEYSTORE_FILE=/opt/keycloak/conf/keycloak.p12 \
  -e KC_HTTPS_KEYSTORE_PASSWORD=mypassword \
  -e KC_HOSTNAME=localhost \
  jboss/keycloak:18.0.0 \
  start --optimized

Bu komuttaki yeni ve önemli parametreleri detaylandıralım:

• -p 8443:8443: Keycloak'un varsayılan HTTPS portu olan 8443'ü ana makinenin 8443 portuna eşler. Artık Keycloak'a HTTPS üzerinden bu porttan erişeceğiz.
• -v ./certs/keycloak.p12:/opt/keycloak/conf/keycloak.p12: Ana makinenizdeki ./certs/keycloak.p12 dosyasını Docker konteyneri içindeki /opt/keycloak/conf/keycloak.p12 yoluna bağlar. Bu, Keycloak'un sertifika dosyasına erişmesini sağlar.
• -e KC_HTTPS_KEYSTORE_FILE=/opt/keycloak/conf/keycloak.p12: Keycloak'a HTTPS için kullanılacak keystore dosyasının yolunu bildirir. Bu, Keycloak'un Undertow web sunucusunun SSL konfigürasyonunu otomatik olarak yapmasını sağlar.
• -e KC_HTTPS_KEYSTORE_PASSWORD=mypassword: Keystore dosyasının şifresini Keycloak'a iletir. Keystore dosyasını oluştururken kullandığınız şifre ile aynı olmalıdır (örneğimizde "mypassword").
• -e KC_HOSTNAME=localhost: Keycloak'un istemciler için bildireceği ana bilgisayar adını ayarlar. Kendinden imzalı sertifikamız CN=localhost ile oluşturulduğu için bu önemlidir. Üretim ortamında gerçek alan adınızı belirtmelisiniz.
• start --optimized: Keycloak'u üretim modunda optimize edilmiş bir şekilde başlatır. Geliştirme modu yerine üretim modu kullanmak, daha iyi performans ve güvenlik sağlar.

Adım 2: Keycloak Yönetim Konsoluna Güvenli Erişim

Yukarıdaki komutu çalıştırdıktan sonra Keycloak konteyneri başlatılacak ve HTTPS bağlantılarını dinlemeye başlayacaktır. Tarayıcınızı açın ve aşağıdaki adrese gidin:

https://localhost:8443

Kendinden imzalı bir sertifika kullandığımız için tarayıcınız büyük ihtimalle "Bağlantınız güvenli değil" veya benzeri bir uyarı gösterecektir. Bu beklenen bir durumdur. Güvenli olmayan siteye devam etme seçeneğini tıklayarak Keycloak yönetim konsoluna erişebilirsiniz. Konsola, KEYCLOAK_ADMIN ve KEYCLOAK_ADMIN_PASSWORD ile belirttiğiniz kimlik bilgileriyle giriş yapabilirsiniz.

Bu aşamada Keycloak'unuz artık HTTPS üzerinden çalışıyor ve tüm trafik şifrelenmiş durumda. Ancak, tarayıcınızın uyarısı, bu sertifikanın bir CA tarafından doğrulanmadığını gösterir. Üretim ortamında bu tür bir uyarı kabul edilemez.

Adım 3: Üretim Ortamı İçin Güvenilir CA Sertifikalarıyla Entegrasyon

Üretim ortamında, yukarıdaki kendinden imzalı sertifika yerine Let's Encrypt veya ticari bir CA'dan alınmış sertifikalar kullanmalısınız. Süreç temel olarak aynıdır, ancak birkaç fark vardır:

1. Sertifika Edinme: Bir CA'dan SSL sertifikası edinin. Bu genellikle bir CSR (Sertifika İmzalama İsteği) oluşturmayı ve bunu CA'ya göndermeyi içerir. CA, size sertifikanızı (genellikle .crt veya .pem formatında) ve muhtemelen bir zincir sertifikası (CA Bundle) sağlayacaktır.
2. PKCS#12 veya JKS Oluşturma: Elde ettiğiniz özel anahtarı, sunucu sertifikasını ve CA zincirini (varsa) kullanarak bir PKCS#12 veya JKS dosyası oluşturmanız gerekir. Bu işlem OpenSSL veya Java'nın keytool aracıyla yapılabilir. Örneğin, bir .crt ve .key dosyanız varsa, bunları önceki örnekteki gibi PKCS#12'ye dönüştürebilirsiniz. Eğer bir CA bundle'ınız varsa, bunu da PKCS#12'ye eklemeniz gerekebilir.
3. Keycloak'a Entegrasyon: Hazırladığınız güvenilir .p12 veya .jks dosyasını önceki docker run komutundaki gibi Keycloak konteynerine bağlayın ve KC_HTTPS_KEYSTORE_FILE ile KC_HTTPS_KEYSTORE_PASSWORD değişkenlerini doğru şekilde ayarlayın. KC_HOSTNAME değerini de sertifikanın verildiği tam alan adına (FQDN) ayarlamayı unutmayın.

# Örnek CA sertifikası ile PKCS#12 oluşturma (varsa CA bundle dahil)
# Bu kısım, CA'dan aldığınız sertifika dosyalarına göre değişiklik gösterebilir.
openssl pkcs12 -export -in your_domain.crt -inkey your_domain.key \
  -certfile ca_bundle.crt -name keycloak -out keycloak_prod.p12 \
  -passout pass:YourProductionPassword

Ardından, docker run komutunu güncelleyerek bu yeni dosyayı kullanın:

docker run -p 8443:8443 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=your_secure_password \
  -v ./certs/keycloak_prod.p12:/opt/keycloak/conf/keycloak.p12 \
  -e KC_HTTPS_KEYSTORE_FILE=/opt/keycloak/conf/keycloak.p12 \
  -e KC_HTTPS_KEYSTORE_PASSWORD=YourProductionPassword \
  -e KC_HOSTNAME=keycloak.yourdomain.com \
  jboss/keycloak:18.0.0 \
  start --optimized

Bu adımlarla, Keycloak'u hem geliştirme hem de üretim ortamları için SSL sertifikalarıyla güvenli bir şekilde Docker üzerinde çalıştırabilirsiniz. Unutmayın, üretim ortamlarında güvenlik en yüksek önceliktir ve şifreler ile sertifika yönetim süreçleri titizlikle takip edilmelidir.

Vaka Analizi: Küçük Bir Şirketin Güvenli Keycloak Geçişi

Bir e-ticaret platformu olan "Anadolu El Sanatları" adlı küçük bir şirket, mikro hizmet mimarisine geçiş yaparken kimlik ve erişim yönetimi (IAM) konusunda ciddi zorluklar yaşıyordu. Önceden, her hizmetin kendi kullanıcı veritabanı vardı ve bu durum, kullanıcı deneyimini olumsuz etkileyen, güvenlik açıklarına yol açabilen ve yönetim yükünü artıran bir karmaşa yaratıyordu. Şirket, kullanıcıların tek bir hesapla tüm hizmetlere erişebileceği (SSO) ve geliştiricilerin kimlik doğrulama süreçleriyle uğraşmak zorunda kalmayacağı merkezi bir IAM çözümü arayışındaydı. Açık kaynak olması, esnekliği ve OAuth 2.0 / OpenID Connect desteği nedeniyle Keycloak'u seçtiler.

Sorun: Güvensiz Keycloak Kurulumu ve Operasyonel Zorluklar

İlk başta, "Anadolu El Sanatları" ekibi Keycloak'u Docker üzerinde hızlıca kurdu, ancak SSL sertifikası entegrasyonunu ertelediler ve Keycloak'u HTTP üzerinden çalıştırdılar. Geliştirme ortamında bu durum sorun yaratmasa da, üretim ortamına yaklaştıkça aşağıdaki sorunlarla karşılaştılar:

1. Tarayıcı Güvenlik Uyarıları: Uygulama kullanıcıları Keycloak'un oturum açma sayfasına yönlendirildiğinde tarayıcılarında "Bu site güvenli değil" uyarıları görmeye başladı. Bu durum, şirket imajına zarar veriyor ve kullanıcı güvenini sarsıyordu.
2. Mobil Uygulama Entegrasyonu Sorunları: Mobil uygulamalar (iOS/Android), güvenli olmayan HTTP bağlantılarıyla Keycloak ile iletişim kurmayı reddediyordu veya özel istisnalar gerektiriyordu. Bu da geliştirme sürecini karmaşıklaştırıyordu.
3. API Güvenliği Endişeleri: Mikro hizmetler Keycloak ile token alışverişi yaparken, HTTP üzerinden gönderilen yetkilendirme kodları ve erişim token'ları ağda düz metin olarak iletiliyordu. Bu, "Man-in-the-Middle" (Ortadaki Adam) saldırılarına açık bir kapı bırakıyordu ve hassas kullanıcı verilerinin ele geçirilme riskini artırıyordu.
4. Veri Tabanı Bağlantısı Güvenliği: Keycloak'un arkasındaki PostgreSQL veritabanına olan bağlantılar da başlangıçta şifresizdi, bu da veritabanı seviyesinde ek güvenlik riskleri yaratıyordu.

Çözüm: Docker Run ile Güvenli SSL Entegrasyonu ve Nginx Ters Proxy

Ekip, bu güvenlik ve operasyonel sorunları çözmek için makalede anlatılan adımları izleyerek Keycloak kurulumlarını güvenli hale getirme kararı aldı. Bu süreçte attıkları adımlar şunlar oldu:

1. Geliştirme Ortamı İçin Kendinden İmzalı Sertifikalar: Geliştirme ortamında hızlı testler için OpenSSL kullanarak kendinden imzalı sertifikalar oluşturdular ve bunları Keycloak'un bir PKCS#12 keystore'una dönüştürdüler. Böylece geliştiriciler, üretimdeki davranışa yakın bir ortamda çalışabildi ve mobil uygulamaları SSL ile test etmeye başladı.
2. Üretim Ortamı İçin Let's Encrypt ve Nginx Ters Proxy: Üretim ortamında, maliyet etkinliği ve otomatik yenileme özellikleri nedeniyle Let's Encrypt sertifikalarını kullanmaya karar verdiler. Keycloak'u doğrudan dış dünyaya açmak yerine, trafik yükünü dengelemek ve sertifika yönetimini kolaylaştırmak için bir Nginx ters proxy kullanmaya karar verdiler. Nginx, 443 portundan gelen HTTPS trafiğini sonlandırıyor, Let's Encrypt sertifikalarını yönetiyor ve ardından trafiği dahili ağda HTTP üzerinden Keycloak konteynerine iletiyordu. Bu yaklaşım, Keycloak'un güvenlik yükünü azalttı ve sertifika yenileme süreçlerini otomatik hale getirdi.
3. Docker Komutlarının Güncellenmesi:
   • Keycloak'u HTTP'de (8080) çalışacak şekilde Docker'da başlattılar, ancak sadece dahili ağdan erişilebilir kıldılar.
   • Nginx konteynerini ise 443 portunda çalıştırdılar ve ana makineye bağladılar. Nginx'in yapılandırmasına Let's Encrypt sertifikaları ve Keycloak'a yönlendirme kuralları eklendi.

   Aşağıdaki gibi bir Nginx yapılandırması kullandılar (basitleştirilmiş):

   
   server {
       listen 443 ssl;
       server_name keycloak.anadoluelsanatlari.com;
   
       ssl_certificate /etc/letsencrypt/live/keycloak.anadoluelsanatlari.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/keycloak.anadoluelsanatlari.com/privkey.pem;
   
       location / {
           proxy_pass http://keycloak-container:8080; # Dahili ağdaki Keycloak servis adı
           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;
           proxy_redirect off;
       }
   }
   

   Keycloak konteynerini başlatırken KC_HOSTNAME değerini Nginx'in kullandığı alan adına ayarladılar:

   
   docker run -d --name keycloak-container \
     -e KEYCLOAK_ADMIN=anadolu_admin \
     -e KEYCLOAK_ADMIN_PASSWORD=cok_guclu_sifre \
     -e KC_HOSTNAME=keycloak.anadoluelsanatlari.com \
     -e KC_DB=postgres \
     -e KC_DB_URL_HOST=postgres-container \
     -e KC_DB_USERNAME=keycloak_db_user \
     -e KC_DB_PASSWORD=db_cok_guclu_sifre \
     jboss/keycloak:18.0.0 \
     start --optimized
   

   Nginx konteynerini başlatırken ise Let's Encrypt sertifikalarının olduğu dizini bağladılar:

   
   docker run -d --name nginx-proxy \
     -p 443:443 \
     -v ./nginx.conf:/etc/nginx/conf.d/default.conf \
     -v /etc/letsencrypt:/etc/letsencrypt \ # Certbot ile alınan sertifikaların olduğu dizin
     --network your_docker_network \
     nginx
   

4. Veritabanı Şifrelemesi: PostgreSQL bağlantılarını da SSL ile şifrelemek için Keycloak'un veritabanı bağlantı URL'sine sslmode=require parametresini eklediler ve PostgreSQL sunucusunu da SSL ile yapılandırdılar.

Sonuçlar ve Faydaları

Bu güvenli geçişin ardından, "Anadolu El Sanatları" şirketi önemli faydalar elde etti:

• Geliştirilmiş Güvenlik: Tüm hassas veriler (kullanıcı kimlik bilgileri, token'lar) ağ üzerinden şifreli olarak iletilerek güvenlik açıkları kapatıldı.
• Artan Kullanıcı Güveni: Tarayıcıdaki güvenlik uyarıları ortadan kalktı, bu da kullanıcıların siteye olan güvenini artırdı ve profesyonel bir imaj sağladı.
• Sorunsuz Mobil Entegrasyon: Mobil uygulamalar, Keycloak ile sorunsuz bir şekilde HTTPS üzerinden iletişim kurabildi, geliştirme süreçleri basitleşti.
• Kolaylaştırılmış Sertifika Yönetimi: Nginx ve Certbot entegrasyonu sayesinde Let's Encrypt sertifikalarının otomatik yenilenmesi sağlandı, manuel müdahaleye gerek kalmadı.
• Merkezi Kimlik Yönetimi: Keycloak'un sunduğu SSO ve diğer özellikler tam potansiyeliyle kullanılabildi, kullanıcılar tüm hizmetlere tek bir hesapla erişebildi ve şirket içindeki yönetim yükü azaldı.

Bu vaka analizi, küçük bir şirketin bile doğru adımlarla ve uygun araçlarla (Docker, Keycloak, Nginx, Let's Encrypt) üretim ortamında sağlam ve güvenli bir kimlik yönetim altyapısı kurabileceğini göstermektedir. Güvenlik, hiçbir zaman göz ardı edilmemesi gereken bir önceliktir ve SSL/TLS entegrasyonu, bu güvenlik katmanının temelini oluşturur.

İleri Düzey Keycloak Yapılandırmaları ve En İyi Uygulamalar Nelerdir?

Keycloak'u SSL sertifikalarıyla güvenli bir şekilde Docker üzerinde çalıştırmak önemli bir adımdır, ancak üretim ortamında kararlı, performanslı ve bakımı kolay bir sistem için daha ileri düzey yapılandırmalar ve en iyi uygulamalar göz önünde bulundurulmalıdır. Bu bölüm, Keycloak kurulumunuzu daha da sağlamlaştırmak için çeşitli ipuçları ve teknikler sunacaktır.

Kalıcı Veri Depolama (Persistent Storage)

Varsayılan Keycloak Docker imajı, tüm verileri (realm'ler, kullanıcılar, oturumlar) konteynerin kendi dosya sisteminde tutar. Bu, konteyner silindiğinde tüm verilerin kaybolacağı anlamına gelir. Üretim ortamında bu kabul edilemez bir durumdur. Bu nedenle, Keycloak'u harici bir veritabanına bağlamak ve konteyner verilerini kalıcı hale getirmek esastır.

Veritabanı Entegrasyonu: Keycloak, PostgreSQL, MySQL/MariaDB, Oracle ve MS SQL Server gibi birçok veritabanını destekler. Docker üzerinde Keycloak'u harici bir veritabanına bağlamak için, veritabanı sunucusunu ayrı bir konteynerde veya yönetilen bir hizmet olarak çalıştırmalı ve Keycloak konteynerini bu veritabanına bağlamalısınız. Aşağıdaki ortam değişkenleri bu bağlantı için kullanılır:

docker run -d --name keycloak-prod \
  -p 8443:8443 \
  -v ./certs/keycloak_prod.p12:/opt/keycloak/conf/keycloak.p12 \
  -e KC_HTTPS_KEYSTORE_FILE=/opt/keycloak/conf/keycloak.p12 \
  -e KC_HTTPS_KEYSTORE_PASSWORD=YourProductionPassword \
  -e KC_HOSTNAME=keycloak.yourdomain.com \
  -e KC_DB=postgres \
  -e KC_DB_URL_HOST=postgres-container \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_USERNAME=keycloak_db_user \
  -e KC_DB_PASSWORD=db_cok_guclu_sifre \
  jboss/keycloak:18.0.0 \
  start --optimized

Burada postgres-container, Docker ağındaki PostgreSQL konteynerinizin adıdır. Bu sayede Keycloak verileri veritabanında saklanır ve konteyner silinse bile verileriniz güvende kalır.

Ters Proxy (Reverse Proxy) Kullanımı: Nginx veya Apache

Üretim ortamlarında Keycloak'u doğrudan internete açmak yerine, önüne bir ters proxy (Nginx, Apache HTTP Server veya bir Load Balancer) yerleştirmek en iyi uygulamadır. Ters proxy'nin faydaları şunlardır:

• SSL Sonlandırma: Sertifika yönetimi ve SSL sonlandırma, ters proxy üzerinde yapılır. Bu, Keycloak'un kaynaklarını serbest bırakır ve Keycloak'un dahili ağda HTTP üzerinden çalışmasına olanak tanır. Sertifika yenileme gibi işlemler proxy üzerinde yapılır ve Keycloak'un kendisi bu değişikliklerden etkilenmez.
• Yük Dengeleme: Birden fazla Keycloak örneği çalıştığında, ters proxy gelen trafiği bu örneklere dağıtabilir, böylece ölçeklenebilirlik ve yüksek erişilebilirlik sağlanır.
• Ek Güvenlik Katmanı: Ters proxy, DDoS koruması, Web Uygulama Güvenlik Duvarı (WAF) entegrasyonu ve erişim kontrolü gibi ek güvenlik katmanları sağlayabilir.
• Statik İçerik Sunumu: Gerekirse, ters proxy statik dosyaları (CSS, JS) Keycloak'tan bağımsız olarak sunabilir, performansı artırır.

Bir ters proxy kullanırken Keycloak'un KC_HOSTNAME, KC_HTTP_ENABLED=true (eğer HTTP kullanılıyorsa) ve KC_PROXY=edge veya KC_PROXY=reencrypt gibi ayarlarının doğru yapıldığından emin olunmalıdır. KC_PROXY=edge, ters proxy'nin SSL sonlandırmasını yaptığını ve Keycloak'a HTTP ile erişildiğini belirtir. KC_PROXY=reencrypt ise ters proxy ile Keycloak arasında da SSL bağlantısı olduğunu varsayar.

Keycloak Performans Ayarları

Keycloak'un performansını optimize etmek için Java Virtual Machine (JVM) ve Keycloak'un kendi yapılandırma ayarları üzerinde çalışabilirsiniz:

• JVM Bellek Ayarları: JAVA_OPTS_APPEND ortam değişkeni ile JVM heap boyutunu (-Xmx, -Xms) ayarlayabilirsiniz. Örneğin:

  
  -e JAVA_OPTS_APPEND="-Xmx2048m -Xms512m"
  

• Önbellekleme (Caching): Keycloak, performans için geniş çaplı önbellekleme kullanır. Önbellek ayarlarını (örneğin Infinispan) özelleştirebilirsiniz. Yüksek yüklü ortamlarda dağıtık önbellek (distributed cache) kullanmak gerekebilir.
• Veritabanı Bağlantı Havuzu: Veritabanı bağlantı havuzunun boyutunu ayarlayarak veritabanı performansını optimize edebilirsiniz. Bu ayarlar, Keycloak'un veritabanı bağlantılarını daha etkin kullanmasını sağlar.

Kapsayıcı Yönetim Platformları (Kubernetes, Docker Swarm)

Tek bir docker run komutu ile başlayan kurulum, üretim ortamında genellikle Kubernetes veya Docker Swarm gibi kapsayıcı düzenleme platformlarına taşınır. Bu platformlar, yüksek erişilebilirlik, otomatik ölçeklendirme, hizmet keşfi ve otomatik sertifika yönetimi (örneğin Cert-Manager ile) gibi gelişmiş özellikler sunar. Bu geçiş, karmaşıklığı artırsa da, büyük ölçekli ve kritik uygulamalar için vazgeçilmezdir.

Güvenlik İpuçları

• Yönetici Kimlik Bilgileri: Keycloak yönetim konsolu için kullanılan KEYCLOAK_ADMIN_PASSWORD her zaman çok güçlü ve karmaşık bir şifre olmalıdır. Mümkünse, bu bilgileri ortam değişkenleri yerine Docker Secrets veya Kubernetes Secrets gibi güvenli mekanizmalarla yönetin.
• Sertifika Yenileme: Özellikle Let's Encrypt gibi kısa ömürlü sertifikalar kullanıyorsanız, otomatik yenileme süreçlerinin (örneğin Certbot veya Nginx proxy üzerinde) düzgün çalıştığından emin olun. Sertifikanın süresi dolduğunda tüm uygulamanız erişilemez hale gelebilir.
• Sürekli Güvenlik Denetimi: Keycloak güncellemelerini takip edin ve güvenlik yamalarını düzenli olarak uygulayın. Keycloak topluluğu ve geliştiricileri, olası güvenlik açıklarını hızla giderirler.
• Denetim ve İzleme: Keycloak'un ve altında yatan JVM'nin performansını ve güvenlik loglarını izlemek için araçlar kullanın. Anomalileri tespit etmek ve olası saldırılara karşı erken uyarı sağlamak için bu loglar çok değerlidir.

Bu ileri düzey yapılandırmalar ve en iyi uygulamalar, Keycloak kurulumunuzu geliştirme ortamından üretim ortamına sorunsuz bir şekilde taşırken karşılaşabileceğiniz güvenlik, performans ve yönetim zorluklarını aşmanıza yardımcı olacaktır. Güvenli bir kimlik yönetimi altyapısı kurmak, sadece ilk kurulumu yapmakla bitmez; sürekli bakım, izleme ve iyileştirme gerektiren dinamik bir süreçtir.

Sıkça Sorulan Sorular (SSS)

Bu bölümde, Docker ile SSL sertifikalı Keycloak kurulumu hakkında sıkça karşılaşılan soruları ve cevaplarını bulacaksınız. Bu bilgiler, karşılaştığınız sorunları gidermenize veya kurulumunuzu daha iyi anlamanıza yardımcı olacaktır.

Keycloak'u HTTP üzerinden çalıştırıp, önüne bir ters proxy ile SSL sonlandırması yapmak daha mı güvenlidir?

Evet, genellikle üretim ortamlarında bu yaklaşım daha çok tercih edilir ve daha güvenli kabul edilir. Ters proxy (Nginx, Apache veya bir yük dengeleyici) SSL sertifikalarını yönetir ve gelen HTTPS trafiğini sonlandırır. Ardından, trafiği dahili ağ içinde HTTP (veya dahili ağda da SSL ile "re-encrypt") üzerinden Keycloak konteynerine iletir. Bunun faydaları şunlardır:

• Merkezi Sertifika Yönetimi: Sertifikaların yenilenmesi ve yönetimi tek bir noktada (proxy üzerinde) kolaylaşır.
• Keycloak Kaynaklarının Serbest Bırakılması: SSL şifreleme/şifre çözme yükü proxy üzerine biner, Keycloak'un CPU kaynakları kimlik yönetimi görevlerine ayrılır.
• Ek Güvenlik Katmanları: Ters proxy, güvenlik duvarı, DDoS koruması, hız sınırlama gibi ek güvenlik özellikleri sağlayabilir.
• Ölçeklenebilirlik: Yük dengeleyicilerle birden fazla Keycloak örneğine trafik dağıtılabilir.

Bu senaryoda Keycloak'u başlatırken KC_HOSTNAME'i alan adınıza ve KC_PROXY=edge (eğer proxy ile Keycloak arasında HTTP ise) veya KC_PROXY=reencrypt (eğer proxy ile Keycloak arasında da HTTPS ise) olarak ayarlamanız önemlidir.

Keycloak'un SSL sertifikasını ne sıklıkla yenilemeliyim?

Sertifikanın geçerlilik süresine bağlıdır. Let's Encrypt sertifikaları genellikle 90 gün geçerlidir ve bu nedenle her 60-75 günde bir yenilenmesi önerilir. Ticari CA'lardan alınan sertifikalar ise genellikle 1 ila 3 yıl geçerlilik süresine sahiptir. Sertifika yenileme işlemlerini otomatikleştirmek, özellikle Let's Encrypt için Certbot gibi araçlarla, en iyi uygulamadır. Unutulmamalıdır ki, süresi dolmuş bir sertifika, Keycloak'unuzun tamamen erişilemez hale gelmesine neden olabilir.

Kendinden imzalı sertifikalar dışında hangi SSL sertifikası türlerini kullanmalıyım?

Üretim ortamları için her zaman güvenilir bir Sertifika Yetkilisi (CA) tarafından imzalanmış sertifikalar kullanmalısınız. En yaygın ve önerilen seçenekler şunlardır:

• Let's Encrypt: Ücretsiz, otomatikleştirilebilir ve dünya genelinde güvenilen sertifikalar sunar. Web siteleri ve API'ler için harika bir seçenektir.
• Ticari CA'lar (DigiCert, GlobalSign, Sectigo vb.): Kuruluş doğrulama, daha yüksek garanti seviyeleri ve müşteri desteği sunan ücretli sertifikalardır. Özellikle büyük ölçekli işletmeler veya belirli uyumluluk gereksinimleri olan durumlar için tercih edilebilir.

Keycloak'un Keystore dosyasının şifresini unutursam ne yapmalıyım?

Keystore dosyasının şifresi unutulursa, dosyaya erişilemez hale gelir ve Keycloak SSL bağlantılarını kuramaz. Bu durumda, Keystore dosyasını yeniden oluşturmanız ve yeni bir şifre belirlemeniz gerekebilir. Eğer sertifikanız bir CA tarafından imzalanmışsa, sertifika sağlayıcınızdan yedeklerini isteyebilir veya özel anahtarınız ve sertifikanız varsa Keystore'u yeniden oluşturabilirsiniz. Kendinden imzalı sertifika ise, yukarıdaki adımları takip ederek yenisini oluşturabilirsiniz. Şifrelerin güvenli bir şekilde saklanması (örneğin bir şifre yöneticisi veya sır yönetimi çözümü ile) bu tür durumları önlemek için kritik öneme sahiptir.

Mobil uyumlu HTML örnekleri nasıl dahil edilebilir?

Makale içeriği genellikle metinsel ve kod tabanlı olduğundan, doğrudan "interaktif mobil HTML" öğelerini dahil etmek pek yaygın değildir. Ancak, makalenin genel görünümünü ve okunabilirliğini artırmak için CSS Media Query örnekleri, HTML içeriğinin mobil cihazlarda nasıl daha iyi görüntülenebileceğini gösteren bir "stil ipucu" olarak eklenebilir. Örneğin:

Yukarıdaki CSS kodu, web sayfasının temel stilini tanımlar ve bir medya sorgusu (@media (max-width: 768px)) kullanarak, ekran genişliği 768 pikselden az olduğunda (yani mobil cihazlarda) yazı tipi boyutunu küçültür ve kod bloklarının içeriğini otomatik olarak sarar. Bu, mobil cihazlarda kod örneklerinin okunabilirliğini artırır.

Bu makalede, Docker run komutunu kullanarak SSL sertifikalı bir Keycloak kurulumunu adım adım nasıl gerçekleştireceğinizi, temelden ileri düzeye kadar tüm detaylarıyla öğrendiniz. Güvenli bir kimlik ve erişim yönetimi altyapısı, modern uygulamalar için vazgeçilmezdir ve bu rehber, bu yolda size sağlam bir başlangıç noktası sunmayı amaçlamıştır.