Keycloak’da First Broker Login Flow’u İnceleyelim #10

Merhaba,

Keycloak’da First Broker Login Flow Nedir?

First Broker Login Flow, Keycloak’a Google, Github, Azure AD, SAML IdP yahut başka bir Keycloak gibi harici bir kimlik sağlayıcı (Identity Provider / IdP) üzerinden ilk kez giriş yapan bir kullanıcının nasıl işleneceğini belirleyen bir akıştır. Burada zaten dikkat ederseniz kritik kelime First (ilk)‘tür. Yani buradan şunu anlayabiliriz ki; kullanıcının, harici bir IdP ile ilk defa giriş yaptığı ve Keycloak’da bu IdP ile eşleşmiş bir kullanıcının henüz olmadığı durumlarda kullanılan bir akıştan bahsediyoruz…

Tabi First Broker Login Flow’u tam sindirebilmek için öncelikle büyük resmi anlamak gerektiğini düşünüyorum. Malumunuz, temelde Keycloak’da iki farklı login senaryosu mevcuttur. Bunlardan biri kullanıcının Keycloak üzerinden username ve password bilgilerini kullanarak Browser Flow ile giriş yaptığı normal login akışıyken, diğeri ise Google, Azure AD vs. gibi harici sağlayıcılardan giriş yaptığı mevzu bahis Broker Login Flow’dur.

Eğer ki, kullanıcı harici sağlayıcı üzerinden daha önce eşleştirilmişse buna Post Broker Login Flow, yok eğer kullanıcı ilk defa harici kaynaktan geliyorsa buna da First Broker Login Flow denmektedir.

Gerçek Hayat Örneği

Diyelim ki, login ekranında Google, GitHub ve Azure AD seçenekleri olan myapp.com domaininde bir uygulamamız olsun ve kullanıcı Google üzerinden login olmaya çalışsın… Süreç şöyle cereyan edecektir:

Her şeyden önce Keycloak -bu kullanıcı bende var mı?- sorusunu soracaktır… ve aldığı cevaba göre aşağıdaki iki durum söz konusu olacaktır.

First Broker Login Flow’un Amacı Nedir?

Keycloak’da first broker login flow, bir kullanıcı harici bir kimlik sağlayıcıdan ilk kez giriş yaptığında devreye giren özel bir kimlik doğrulama sürecidir ve asıl amacı bu harici kimliği Keycloak içindeki yerel kullanıcı hesaplarıyla güvenli ve tutarlı bir şekilde ilişkilendirmektir.

Misal olarak kullanıcı, Google veya GitHub hesabıyla giriş yaptığında, Keycloak önce bu kullanıcının sistemde zaten kayıtlı olup olmadığını kontrol eder, eğer aynı e-posta adresiyle manuel oluşturulmuş bir hesap varsa kullanıcıdan bu hesapları birleştirmesi istenir. Böylece aynı kişinin farklı giriş yöntemleriyle birden fazla hesap oluşturmasının önüne geçilmiş olur. Yok eğer kullanıcı tamamen yeni ise o taktirde profil bilgileri gözden geçirilerek doğrudan yeni bir kullanıcı kaydı oluşturulur.

Bu akış aynı zamanda kuruluşların güvenlik politikalarına uygun olarak ek doğrulama adımları eklemesine de olanak tanımaktadır. Örnek vermemiz gerekirse eğer; ilk harici girişte iki faktörlü kimlik doğrulama veya e-posta doğrulaması zorunlu kılınabilir.

First broker login flow, bu ve bunlara benzer davranışları sergilememizi sağlayarak özellikle birden fazla bağımsız kimlik ve erişim yönetimi gerektiren federasyonel senaryolarda kullanıcı deneyimini düzgün bir şekilde yönetmek, veri bütünlüğünü korumak ve hesap ele geçirme gibi güvenlik risklerini minimize etmek için kritik öneme sahip bir mekanizmadır.

First Broker Login Flow’un İç Yapısı

First broker login flow’un iç yapısındaki akış mantığı aşağıdaki gibidir:

Dikkat ederseniz, her adımın kendine has bir mimari görevi mevcuttur. Her ne kadar yukarıdaki şema gerekli açıklamaları veriyor olsa da bizler aşağıda tüm adımları kısaca izah edelim:

• Review Profile : External identity bilgisini normalize etmektedir.
• Create User If Unique : Yeni internal user oluşturmaktadır.
• Handle Existing Account : External identity’yi existing user’a bağlamaktadır.
• Verify existing account : Account takeover saldırısını önlemektedir.
• Re-authentication : Gerçek kullanıcı doğrulaması yapmaktadır.
• Conditional 2FA : Ek güvenlik katmanı eklemektedir.

First Broker Login Flow’u Kullanırken Nelere Dikkat Edilmelidir?

First broker login flow, external identity → internal user mapping süreci söz konusu olduğundan Keycloak’ta en çok yanlış yapılandırılan ve en çok güvenlik açığı oluşturabilen flow’lardan birisidir. Ki yanlış yapılandırıldığı taktirde, kullanıcı hesaplarının ele geçirilmesi söz konusu olabilir! Bu açıdan olayı değerlendirdiğimizde bu akışa dair dikkat edilmesi gereken kritik noktaları ele almakta fayda görmekteyim:

1. Account Takeover nedir?
   Account takeover (ATO), bir saldırganın bir kullanıcı hesabına yetkisi olmadığı halde erişim elde etmesi ve o kullanıcı gibi hareket edebilmesidir. Yani saldırgan, gerçek kullanıcının hesabını ele geçirir ve sistem açısından artık ‘o kişi’ olarak kabul edilir.

   Örneğin; Keycloak’da ali@gmail.com email’ine sahip bir kullanıcının zaten var olduğunu düşünelim. Eğer saldırgan aynı email adresiyle bir Google hesabı oluşturur ve Keycloak, hiçbir ek doğrulama yapmadan bu Google hesabını mevcut Keycloak hesabına otomatik olarak link ederse, saldırgan gerçek kullanıcının şifresini bilmeden o hesaba erişebilmiş olacaktır. İşte bu durum account takeover olarak adlandırılmaktadır.

   Genel olarak account takeover şu yöntemlerle gerçekleştirilir:

   • Çalınmış şifreleri kullanılması (data breach sonrası)
   • Phishing (sahte login sayfasıyla şifrenin çalınması)
   • Zayıf ve tekrar kullanılan şifreler
   • Email adresinin ele geçirilmesi yahut erişimin sağlanması
   • Yanlış yapılandırılmış authentication ve identity linking

   Account Takeover riskine dikkat edilmelidir!
   Keycloak’ta first broker login flow sırasında ‘bağlantı’ sağlamak (ya da link etmek), Google gibi external bir Identity Provider’dan gelen kullanıcı ile Keycloak’da zaten var olan bir kullanıcı hesabının aynı kişiye ait olup olmadığının doğrulanıp, aynı kişi olduğu kanıtlandığı taktirde bu iki kimliği birbirine bağlama işlemidir. Yani kullanıcı daha önce Keycloak’ta email ve şifre ile oluşturulmuş bir hesaba sahipse ve sonradan Google ile login olmaya çalışıyorsa, Keycloak bu Google hesabını otomatik olarak o mevcut hesaba bağlamamaktadır! Bunun yerine kullanıcıdan email doğrulaması yapmasını veya mevcut hesabının şifresini girmesini isteyerek gerçekten hesap sahibi olduğunu kanıtlamasını istemektedir. Bu süreç neticesinde Google kimliği ile Keycloak’taki kullanıcı hesabı arasında kalıcı bir ilişki (federated identity mapping) oluşturulmuş olacaktır ve böylece, kullanıcı bundan böyle hem Google ile hem de normal Keycloak login bilgileriyle aynı hesaba güvenli şekilde erişebilme imkanı elde etmiş olacaktır.

   Peki bunun account takeover ile alakası nedir? diye sorarsanız;
   Eğer ki Keycloak, external identity provider’dan gelen bir kullanıcıyı sırf mail adresi aynı diye hiçbir ek doğrulama yapmadan mevcut bir Keycloak hesabına otomatik olarak bağlarsa, kötü niyetli bir kişi kurbanın email adresini kullanarak kendi harici hesabını (örneğin Google) oluşturup o email ile login olabilir ve Keycloak da bunu gerçek kullanıcı sanarak kurbanın mevcut hesabına bağlayabilir. Bu durumda saldırgan, kurbanın Keycloak hesabına şifre bilmeden erişmiş ve hesabı ele geçirmiş olur. First broker login flow içindeki ‘Confirm Link Existing Account’, ‘Verify Existing Account by Email’ ve ‘Re-authenticaiton’ gibi adımların temel gayesi de tam olarak bu durumu engellemektir. Keycloak, external kimlik ile mevcut hesabı linklemeden önce kullanıcıdan email doğrulaması veya mevcut hesap şifresini isteyerek external identity’yi bağlamaya çalışan kişinin gerçekten o hesabın sahibi olup olmadığını kanıtlamasını isteyerek bir güvenlik önlemi oluşturur.

2. Email verified claim’ine körü körüne güvenmemelidir!
   Bazı identity provider’lar kullanıcı bilgilerini gönderirken email adresinin doğrulanmış olduğunu ifade eden email_verified = true claim’ini de gönderirler. Evet, o email adresi doğrulanmış olabilir ancak bizler körü körüne bu bilgiye güvenmemeliyiz. Çünkü bu değer yanlış, eksik veya kötü niyetli olacak şekilde aktif olarak işaretlenmiş olabilir ve esasında email adresinin gerçek sahibi olmayan kişi, doğrulanmış gibi kabul edilerek kullanıcı hesabına erişebilir ve böylece account takeover riski söz konusu olabilir. Bu nedenle en güvenli yaklaşım, external provider’ın gönderdiği email_verified bilgisine tamamen güvenmek yerine, Keycloak’un kendi ‘Verify Email’ mekanizmasının kullanılmasıdır.
3. “Automatically link existing accounts” ayarına dikkat edilmelidir!
   Keycloak’ta identity provider yapılandırmasında bulunan ‘Automatically link existing accounts’ veya benzer şekilde çalışan ‘Trust Email’ ayarları aktif edilirse, external identity provider’dan gelen kullanıcının email adresi, Keycloak’ta zaten var olan bir kullanıcıyla eşleştiği anda Keycloak bu iki hesabı hiçbir ek doğrulama yapmadan otomatik olarak birbirine bağlama davranışı sergileyerek istemeden ciddi bir güvenlik riski durumu yaratılabilir. Çünkü, saldırgan kurbanın email adresini kullanarak kendi external hesabını oluşturup sisteme giriş yaparsa, Keycloak bunu gerçek kullanıcı sanarak mevcut hesaba otomatik olarak bağlayabilir ve böylece saldırgan o hesabı ele geçirebilir. Yani yukarıdaki satırlarda bass bass vurguladığımız account takeover durumu bu ayarlar neticesinde yine cereyan edebilir. Bu riski önlemek için otomatik bağlama yerine first broker login flow içinde yer alan ‘Confirm Link Existing Account’ gibi adımlar aktif tutulmalı ve böylece external hesabı mevcut hesaba bağlamadan önce kullanıcıdan şifresini girmesi veya emailini doğrulaması istenmelidir.
4. “Create User If Unique” execution’ı kritiktir! Dikkat edilmeli!
   Keycloak’taki ‘Create User If Unique’ execution’ı, external identity provider’dan gelen kullanıcı bilgilerine bakarak Keycloak’ta aynı email veya username’e sahip bir kullanıcı olup olmadığını kontrol etmekte ve eğer böyle bir kullanıcı yoksa otomatik olarak yeni bir kullanıcı oluşturmaktadır.

   Ancak burada dikkat edilmesi gereken önemli bir husus vardır, o da, identity provider’dan gelen username bilgisinin her daim güvenilir veya benzersiz olmayabileceğidir. Çünkü kimi provider’lar username göndermezken, kimileri ise çakışabilecek değerler gönderebilir… Ee bu da yanlış kullanıcı oluşturulmasına veya çakışmalara neden olabilir. Bu riski önlemek için identity provider mapper yapılandırmasında username alanının email veya email prefix gibi sistemde benzersiz olacak bir değerden türetilmesi önerilmektedir. Böylece her external kullanıcı Keycloak içinde doğru ve benzersiz bir kullanıcı olarak oluşturulur ve kimlik eşleştirme süreci güvenli ve tutarlı bir şekilde gerçekleştirilmiş olur.

5. Username’in boş gelmesi durumuna dikkat edilmelidir!
   Bazı identity provider’lar (özellikle Google) kullanıcıya ait email bilgisini gönderirken ayrı bir username alanı göndermeyebilir ve bu durumda Keycloak yeni kullanıcı oluştururken kullanacağı username değerini otomatik olarak belirleyemez! Eğer böyle bir senaryoda first broker login flow içerisindeki ‘Review Profile’ execution’ı aktif değilse, Keycloak eksik bilgi nedeniyle hatalı kullanıcı oluşturabilir veya beklenmedik bir username atayarak ileride kimlik eşleştirme ve kullanıcı yönetimi açısından kimi sorunlara temel atabilir. Bu nedenle ‘Review Profile’ adımı aktif tutulduğunda Keycloak, external provider’dan gelen bilgileri kullanıcıya gösterir ve eksik olan username alanının kullanıcı tarafından doldurulmasını sağlar. Böylece oluşturlan kullanıcı kaydı doğru, tutarlı ve sistemle uyumlu bir hale gelmiş olacaktır.
6. Duplicate user creation riskine dikkat edilmelidir!
   Keycloak’ta identity provider entegrasyonu sırasında mapper yapılandırması yanlış yapılırsa, aynı email adresine sahip external kullanıcıyı her login olduğunda mevcut kullanıcıyla eşleştirmek yerine yeni bir kullanıcı olarak oluşturabilir ve bu durum sistemde aynı email adresine sahip birden fazla kullanıcı kaydının oluşmasına, yani duplicate user problemine yol açabilir. Bu hem güvenlik hem de kimlik yönetimi açısından ciddi sorunlar doğurabilir çünkü aynı kişiye ait birden fazla hesap demek, doğru kimlik eşleştirmesi yapılamayacak demektir. Bu riski önlemek için realm ayarlarından ‘Email unique’ seçeneği aktif hale getirilerek, Keycloak’da aynı email adresiyle birden fazla kullanıcının oluşturulması engellenebilir ve kimlik bütünlüğü korunabilir.
7. Domain restriction kullanılması önerilmektedir!
   Enterprise sistemlerde genellikle sadece belirli bir kuruma ait kullanıcıların giriş yapmasına izin verilmesi gerekmekte ve bu nedenle external identity provider’dan gelen kullanıcıların email adreslerinin belirli bir domain’e ait olup olmadığı kontrol edilmesi gerekmektedir.

   Bu kontrol yapılmadığı taktirde herhangi bir kişi kendi kişisel email adresiyle external provider üzerinden login olabilir ve sistemde yetkisiz erişim elde edebilir. Haliyle bu durum ciddi bir güvenlik açığı oluşturacaktır. Bu riski önlemek için first broker login flow içine eklenecek bir kontrol mekanizması veya custom authenticator ile kullanıcının email adresinin izin verilen domain ile bitip bitmediği doğrulanmalı ve sadece belirlenen domain’e ait kullanıcıların sisteme giriş yapmasına izin verilerek sistemin yalnızca yetkili organizasyon kullanıcılarına açık olması sağlanmalıdır.

8. Identity Provider spoofing riskine dikkat edilmelidir!
   Bir sistemde birden fazla identity provider tanımlıysa eğer aynı emailin farklı provider’lar üzerinden gelebilme ihtimali söz konusudur. Ancak bu email adresi aynı olsa dahi bu kimliklerin gerçekte aynı kişiye ait olduğunun ise ilk etapta bir garantisi olmayacaktır. Keycloak, bu iki kimliği sadece email adresleri aynı diye otomatik olarak aynı kullanıcı hesabına bağlarsa, yine burada account takeover zaafiyeti söz konusu olabilir. Bu nedenle, first broker login flow içindeki ‘Configrm Link Existing Account’ adımı oldukça kritik öneme sahiptir. Çünkü Keycloak, external identity’yi mevcut hesaba bağlamadan önce kullanıcıdan ek doğrulama yapmasını isteyecek ve böylece farklı identity provider’lardan gelen kimliklerin gerçekten aynı kullanıcıya ait olup olmadığı güvenli şekilde doğrulamış olacaktır.
9. Mapper’ların doğru yapılandırılması kritik arz etmektedir!
   Keycloak’ta identity provider entegrasyonu sırasında mapper’lar, external provider’dan gelen kullanıcı bilgilerinin Keycloak içindeki kullanıcı alanlarına nasıl aktarılacağını belirlemektedir. Bu yapılandırmanın doğru yapılması kritik öneme sahiptir çünkü email, username, firstName, lastName ve emailVerified gibi alanlar doğru şekilde eşleştirilmezse Keycloak kullanıcının kimliğini doğru şekilde tanımlayamaz, bu da her login’de yeni kullanıcı oluşturulmasına, mevcut kullanıcıyla eşleştirme yapılamamasına veya güvenlik doğrulamalarının hatalı çalışmasına neden olabilir.

   Özellikle email alanı en kritik alandır, çünkü Keycloak çoğu durumda kullanıcı eşleştirmesini email üzerinden yapar ve email yanlış map edilirse aynı kullanıcı için birden fazla hesap oluşabilir veya yanlış kullanıcıya erişim sağlanabilir, bu nedenle identity provider mapper’larının dikkatli ve doğru şekilde yapılandırılması, hem kimlik bütünlüğünü hem de güvenliği sağlamak açısından elzemdir!

10. Test ve prod ortamlarının flow’larının farklı olmasına özen gösterilmelidir!
    Test ortamlarında genellikle geliştirme ve entegrasyon süreçlerini hızlandırmak amacıyla external identity provider’dan gelen kullanıcıların otomatik olarak sisteme dahil edilmesine izin verilir. Bu nedenle first broker login flow içinde ‘Create User If Unique’ gibi adımlar aktif tutularak yeni kullanıcıların herhangi bir ek onaya gerek kalmadan otomatik olarak oluşturulması test süreçlerinde mümkündür.

    Ancak production ortamında aynı yaklaşım ciddi güvenlik riskleri doğurabileceğinden, her external kullanıcının otomatik olarak sisteme erişim kazanması yerine, yalnızca belirli bir domain’e ait kullanıcıların kabul edilmesi veya yeni kullanıcıların admin onayından geçtikten sonra aktif edilmesi gibi daha kısıtlayıcı ve kontrollü mekanizmaların uygulanması daha uygundur. Böylece sistem yalnızca yetkili ve doğrulanmış kullanıcıların erişimine açık tutulur ve yetkisiz kişilerin sisteme dahil olması da engellenmiş olur.

13 Kritik Soru / 13 Kritik Cevap

Şimdi çoğu kritik incelemelerde yaptığımız gibi bu içeriğimizde de first broker login flow’a dair akla gelen gelmeyen tüm soruları kendimizce sorup cevaplandıralım ve böylece konuya dair olabilecek tüm kırıntıları toparlayalım…

Keycloak’da First Broker Login Flow Yapılandırmasını İnceleyelim

Şimdi Keycloak’da first broker login flow yapılandırmasını incelemeye geçebiliriz. Tabi bunun için öncelikle yapılması gereken esasında en az bir tane olacak şekilde external identity provider ayarlamaktır. Mesela bizler bu içeriğimizde yalnızca Google üzerinden örneklendirmede bulunuyor olsak da sizler GitHub, Azure AD vs.’ide sürece dahil edebilir ve çalışmanızı daha da zenginleştirebilirsiniz.

1. External Identity Provider’ın Yapılandırılması (Google)

İlk olarak external identity provider’ımız olan Google’ı Google Cloud Console üzerinden yapılandırmaya başlayalım.

• 1 Adım (Yeni Proje Oluşturma)
  Yapacağımız çalışmayla ilgili yeni bir proje oluşturalım. Tabi isteğiniz doğrultusunda mevcut olan projelerden birini de tercih edebilirsiniz.
• 2 Adım (OAuth Consent Screen’i Ayarlama)
  Google’ın kullanıcıya göstereceği onay ekranını yapılandıralım. Bunun için Google Console’da yandaki görselde olduğu gibi OAuth Consent Screen‘i arayıp bulalım ve açılan sayfada istenilen alanları uygun şekilde doldurup ve audience kısmını da external olacak şekilde ayarlayıp yapılandırmayı sağlayalım.

  Tabi burada yapılan işlemlerin login akışının teknik kısmıyla ilgili olmadığını, yalnızca client oluşturmamızı sağlayacak olan bir zemin hazırladığını söylemekte fayda görmekteyim…

• 3 Adım (OAuth Client Oluşturma)
  Şimdi ise Keycloak’da yaptığımız gibi Google’da da uygulamamıza karşılık gelecek bir client oluşturmamız gerekmektedir. Ki Client ID ve Client Secret değerlerini elde edebilelim.

  Bunun için oluşturduğumuz (ya da mevcut olan) projenin ana sayfasından ‘Create OAuth client’ butonuna tıklayalım ve açılan sayfayı aşağıdaki görselde olduğu gibi dolduralım:Client’ı oluşturduktan sonra sistem bizlere Client ID ve Client Secret değerlerini verecektir. Bu değerleri Clients menüsünden ilgili client detaylarına gelerek görebilirsiniz…

2. Internal Identity Provider’ın Yapılandırılması (Keycloak)

Evet… Şimdi de oluşturduğumuz bu Google client’ı, Client ID ile Client Secret değerleri üzerinden Keycloak’la ilişkilendirecek konfigürasyonu gerçekleştirelim ve böylece Google login yapılandırmasını tamamlayalım. Tabi bunun için Keycloak Dashboard’da Identity providers sayfası üzerinden Google provider’ına gelinmesi gerekmektedir.Buradaki yapılandırma ayarlarına göz atarsak eğer;

• Redirect URI : Google login işleminden sonra kullanıcıyı geri göndereceği adrestir. Bu adresin, bir önceki external identity provider yapılandırması sürecindeki 3. adımda Authorized redirect URIs kısmında kullanıldığını hatırlatırım…
• Alias : Bu provider’ın sistem içindeki teknik adıdır. Google login butonuna verilen adreste URL’de /broker/google/login şeklinde görülmektedir.
• Display Name : Login ekranında kullanıcıya gözükecek isimdir. Boş kaldığı taktirde alias kullanılacaktır.
• Display Order : Birden fazla provider’ın olduğu senaryolarda login ekranında hangi sırada gözükeceğini belirler. Sıralama sayıların büyüklüğüyle ters orantılıdır.
• Prompt : Google tarafında login ekranının hangi davranışla yönlendirme yapılacağını söyler. Misal olarak;
  • Eğer boş bırakırsan : Kullanıcı zaten Google’a login ise direkt devam edecektir, yok eğer login değilse login ekranını gösterecektir. Ayrıca daha önce izin verilmişse tekrar sormayacaktır. Bu en normal ve önerilen ayardır!
  • login : Google’da kullanıcı login olmuş olsa bile tekrar şifre soracaktır. Bir nevi force login‘dir.
  • consent : Kullanıcı daha önce izin vermiş olsa bile izin ekranını tekrar gösterir. Yani her girişte onay ister!
  • none : Bu ayar ise en kritik olanıdır diyebiliriz. Kullanıcıdan hiçbir etkileşim istemeden sessizce login gerçekleştirir.
• Hosted Domain : Sadece belirli bir Google Workspace domain’ine izin vermek için kullanılır. Örneğin yalnızca firma.com uzantılı Google hesapları login olsun isteniyorsa bu alana firma.com yazılmalıdır.
• Use userIp param : Google’a kullanıcının IP bilgisini gönderir. Genelde kapalı kalır, çoğu senaryoda gerekmemektedir.
• Request refresh token : Google’dan refresh token talep eder.

Şimdi de provider yapılandırmasını daha da ciddi noktaya taşıyalım ve scroll barı sayfanın biraz aşağısına indirerek Advanced settings kısmını inceyelim.

Advanced Settings

• Scopes : Google’dan hangi bilgilerin istendiğini ifade eder. Varsayılan olarak genelde openid email profile bilgileri istenmektedir.

  Peki buraya neler yazabiliriz?
  🔹Google Calendar erişimi

  openid email profile https://www.googleapis.com/auth/calendar.readonly
  

  🔹Google Drive erişimi

  openid email profile https://www.googleapis.com/auth/drive.readonly
  

  🔹Gmail erişimi

  openid email profile https://www.googleapis.com/auth/gmail.readonly
  
• Store Tokens : Google’dan gelen access ve refresh token’ların Keycloak içinde saklanmasını sağlar.

  Eğer açılırsa Google API’lerine Keycloak üzerinden erişim sağlanabilir, yok eğer kapalıysa da sadece login için kullanılır.

• Accepts prompt=none forward from client : Eğer bu ayar açılırsa, client (ya da frontend) prompt=none ayarını Google’a yönlendirecektir. İleri seviye SSO senaryoları için kullanılmaktadır.
• Disable User Info : Google’dan ek olarak userinfo endpoint çağrısı yapılmasını engeller. Default olarak kapalı olsa da açıldığı taktirde bazı claim’ler gelmeyebilir.
• Trust Email ⚠️ ÖNEMLİ : Google’dan gelen email’in doğrulanmış kabul edilip edilmeyeceğini yapılandırır. Yani Google’ın email_verified claim’ine güvenecektir. Kapalı olduğu taktirde ise Keycloak ayrıca email doğrulaması isteyebilir.

  Google için genelde açılabilir ancak kurumsal güvenlik gerektiren noktalarda kapalı kullanılması önerilmektedir.

• Account Linking Only : Bu provider’dan yeni bir kullanıcının oluşturulup oluşturulmayacağını yapılandırdığımız ayardır. Yani aktifleştirilirse yalnızca mevcut hesaplara link gerçekleştirilir ve yeni user creation süreci engellenmiş olur. Özellikle production süreçlerinde güvenlik için sık kullanılmaktadır.
• Hide on Login Page : Login ekranında Google ile giriş butonu görünmez ama URL ile yine de çağrılabilir.
• Show in Account Console : Kullanıcı profil sayfasında bu provider görünsün mü?
• Verify Essential Claim : OIDC ‘essential claim’ kontrolü yapar.
• First Login Flow Override : Bu provider’dan ilk kez login olan kullanıcı için hangi flow’un çalışacğaını belirler.
• Post Login Flow : Login başarıyla tamamlandıktan sonra ekstradan bir flow daha çalıştırabilmemizi sağlar.
• Sync Mode ⚠️ ÇOK ÖNEMLİ : Google’dan gelen kullanıcı bilgilerinin nasıl senkronize edileceğini yapılandırır.
  • Import : İlk login’de sonradan değişmeyecek şekilde import edilir.
  • Force : Her login’de Google’daki değişiklikler güncellenir.
  • Legacy : Keycloak’un eski versiyonlarındaki karma davranışı korur. Yani ne tam olarak import ne de force davranışı sergiler.
• Case-sensitive username : Username büyük/küçük harf duyarlılığını yapılandırır.

Direkt Asp.NET Core Projesinden External Identity Provider İle Login Yapma

Şimdi de Asp.NET Core uygulamalarında kullanıcıyı Keycloak’a yönlendirmeksizin, Keycloak’daki Google login yapılandırmasını kullanarak direkt bir buton aracılığıyla Google üzerinden giriş nasıl yapılabileceğini inceleyelim…

Tabi öncelikle bunun için Keycloak’da standard flow akışına sahip client authentication olarak yapılandırılmış aşağıdaki ayarlarda application-client isimli bir client oluşturalım.Ardından bu client’la ilişkilendirilmiş Asp.NET Core uygulamasını aşağıdaki gibi yapılandıralım:

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
    .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options =>
    {
        options.LoginPath = "/login";
        options.LogoutPath = "/logout";
    })
    .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, options =>
    {
        options.Authority = "http://127.0.0.1:8080/realms/master";
        options.ClientId = "application-client";
        options.ClientSecret = "xtiFpVpuOxNS3CoN2v78h7ay7ns06t9z";
        options.ResponseType = "code";

        options.SaveTokens = true;
        options.GetClaimsFromUserInfoEndpoint = true;
        options.RequireHttpsMetadata = false;

        options.Scope.Clear();
        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("email");

        options.CallbackPath = "/signin-oidc";

        options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Disable;

        options.TokenValidationParameters = new()
        {
            NameClaimType = JwtRegisteredClaimNames.PreferredUsername,
        };

        options.Events = new OpenIdConnectEvents
        {
            OnRedirectToIdentityProvider = context =>
            {
                if (context.Properties.Items.TryGetValue("kc_idp_hint", out var provider))
                {
                    context.ProtocolMessage.SetParameter("kc_idp_hint", provider);
                }

                return Task.CompletedTask;
            }
        };
    });

Burada can alıcı iki nokta mevcuttur.

Birincisi, 29. satırdaki options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Disable komutudur. Burada dikkat ederseniz Pushed Authorization Requests (PAR) yapılandırmasını disable olarak ayarlamaktayız. Bunun nedeni, Keycloak’un 26.x sürümüyle birlikte PAR’ın varsayılan olarak zorunlu hale gelmiş olmasıdır. Ki bu zorunluluk neticesinde bir login yönlendirme parametresi olan kc_idp_hint Keycloak tarafından işlenememektedir. O yüzden PAR mekanizması bu noktada devre dışı bırakılmaktadır.

kc_idp_hint, Keycloak’a kullanıcın hangi Identity Provider ile giriş yapacağını söyleyen bir yönlendirme parametresidir.

İkinci can alıcı nokta ise 36 ile 47. satır aralığında, oluşturulan Keycloak’a yönlendirme URL’ine kc_idp_hint parametresinin eklenmesidir. Kullanıcının Keycloak login sayfasını görmeksizin hangi Identity Provider (IdP) ile giriş yapacağını belirlememizi sağlayan kc_idp_hint parametresi, işte tam da bu noktada authorization flow URL’ine müdahale ederek kullanıcının yönlendirileceği URL’in Google login URL’i olacağını ifade etmektedir. Burada dikkat ederseniz Keycloak’a yönlendirme isteği oluşturulmadan hemen önce OpenIdConnectEvents ile araya girilmekte ve yönlendirmenin başlatıldığı noktadan gönderilen property’ler kontrol edilerek, içerisinde kc_idp_hint var mı yok mu değerlendirilmektedir. Eğer bu değer varsa oluşturulacak yönlendirme URL’ine eklenmekte ve Google login süreci tam olarak konfigüre edilmektedir.

Asp.NET Core uygulamasının yapılandırmasını bu şekilde yaptıktan sonra geriye yalnızca aşağıdaki gibi Google ile login yapmamızı sağlayacak olan noktayı, yani bir action’ı oluşturmak kalmaktadır:

.
.
.
        [HttpPost()]
        public IActionResult LoginWithGoogle(LoginViewModel model)
        {
            return Challenge(new AuthenticationProperties { RedirectUri = "/", Items = { ["kc_idp_hint"] = "google" } }, OpenIdConnectDefaults.AuthenticationScheme);
        }
.
.
.

Burada da dikkat ederseniz LoginWithGoogle action metodunun içerisinde Challenge yapılırken AuthenticationProperties‘e RedirectUri‘nin yanında bir de Items eklemekte ve mevzu bahis olan kc_idp_hint parametresi burada Dictionary olarak tanımlanıp identity provider’ın “google” olacağı ifade edilmektedir.

Evet… Asp.NET Core ile Keycloak yapılandırmalı Google ile login çalışması bundan ibarettir. Daha fazla teknik detay için içeriğimizin sonundaki GitHub reposuna göz atabilirsiniz.

Direkt SPA’da External Identity Provider İle Login Yapma

Benzer mantıkla bir SPA’de de Keycloak’da yapılandırılmış ve direkt Google login’e yönlendiren bir butona ihtiyacımız olabilir. Bunun için yapılması gerekenler oldukça basittir. Şimdi gelin bunu bir Angular uygulaması üzerinden kısaca deneyimlemeye çalışalım…

Öncelikle Keycloak’da standard flow akışına sahip aşağıdaki görseldeki gibi yapılandırılmış angular-client isimli bir client oluşturalım:
Ardından ilgili Angular projesine keycloak-js kütüphanesini yükleyelim.

Ve devamında aşağıdaki yapılandırmaya sahip bir konfigürasyon dosyası oluşturalım:

keycloak.configurations.ts;

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
    url: 'http://127.0.0.1:8080',
    realm: 'master',
    clientId: 'angular-client'
});

export default keycloak;

Ve uygulama ayarlarının yapıldığı app.config.ts dosyasında da aşağıdaki yapılandırmada bulunalım:

.
.
.
import keycloak from './configurations/keycloak.configurations';

export const appConfig: ApplicationConfig = {
  providers: [
    provideBrowserGlobalErrorListeners(),
    provideRouter(routes),
    provideAppInitializer(() => {
      keycloak.init({
        onLoad: 'check-sso',
        pkceMethod: 'S256',
        checkLoginIframe: false
      })
    })
  ]
};

Evet, artık uygulamamız belirtilen Keycloak sunucusunda yapılandırılmış olan Google ile login sürecine oldukça hazır. Bunu test edebilmek için aşağıdaki gibi basit bir component tasarlamamız yeterli olacaktır:

import keycloak from './configurations/keycloak.configurations';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  template: `
  <button (click)="loginWithGoogle()">Google ile giriş</button>
  `
})
export class App {
  async loginWithGoogle() {
    await keycloak.login({
      idpHint: 'google',
      redirectUri: window.location.origin
    });
  }
}

İşte bu kadar 🙂

Bizler içerik boyunca teknik açıdan Google ile login sürecini tecrübe etmiş bulunmaktayız. Tabi ki de sizler farklı external identity provider’ları deneyebilir ve varsa küçük nüanslar bizleri de aydınlatabilirsiniz.

Nihai olarak;

First Broker Login Flow, modern kimlik federasyonunun bel kemiğini oluşturan ve external identity provider’lar ile kurumsal kullanıcı yönetimi arasındaki kritik köprüyü güvenli bir şekilde inşa etmemizi sağlayan vazgeçilmez bir mekanizmadır. Doğru yapılandırıldığı taktirde hem kullanıcı deneyimini kusursuzlaştıran hem de hesap ele geçirme gibi ciddi güvenlik risklerini bertaraf eden bu akış, Keycloak’un identity brokering yeteneklerini tam anlamıyla ete kemiğe büründürmektedir. Unutulmamalıdır ki, her external provider’dan giriş esasında bir güven meselesidir. Bu meselenin yapılandırması ne kadar sağlam ve bilinçli bir şekilde sağlanırsa, dijital kimlik altyapısı o kadar dirençli ve güvenilir olacaktır.

İlgilenenlerin faydalanması dileğiyle…
Sonraki yazılarımda görüşmek üzere…
İyi çalışmalar…