Kimlik sistemini bağlama

Müşteri ürünü kendi Keycloak’ıyla gelir (realm fleet). Kurumun kullanıcıları ayrı parola almadan kendi kimlik sistemleriyle girebilir: Microsoft Entra ID, AD FS ya da başka bir OIDC/SAML sağlayıcı, veya doğrudan Active Directory/LDAP. Bu kılavuz self-hosted kurulum içindir; SaaS’ta aynı adımları tenant için biz yaparız.

Yapılandırma Keycloak yönetici panelinde yapılır (https://<auth adresi>/admin, realm fleet). Realm dosyası yalnızca ilk açılışta içe aktarılır, bu yüzden panelden yapılan ayarlar sürüm güncellemelerinde korunur.

Uygulamanın beklediği

Hangi yöntem seçilirse seçilsin, giriş yapan kullanıcı şu iki koşulu sağlamalıdır:

Tenant’ın organization’ının üyesi olmalı. Her tenant Keycloak’ta bir organization’dır; organization’ın takma adı (alias) tenant’ın kısa adıdır (panel adresindeki <kısa ad>). Panel ve mobil uygulama girişi organization:<kısa ad> kapsamıyla ister; üye olmayan kullanıcı panelde “Erişiminiz yok” ekranını görür.

Bir tenant rolü taşımalı (realm rolü):

Rol	Kim
`tenant-admin`	Eğitim yöneticisi (web paneli): atama, kural, rapor, ayarlar, kullanıcı yönetimi
`viewer`	Web panelinde eğitimleri, atamaları ve raporları salt okunur görür
`learner`	Kursiyer: kendi eğitimleri, mobil uygulamada

Web panelini yalnızca tenant-admin ve viewer açar; yalnızca learner rolü olan ya da hiç rolü olmayan kullanıcı panelde “Erişiminiz yok” ekranını görür.

platform adını kullanmayın. Realm’de bu takma adla bir kimlik sağlayıcı SaaS destek girişine ayrılmıştır . Uygulama, platform sağlayıcısından gelen oturumu destek personeli sayar.

Hangi yöntem?

	OIDC / SAML (önerilen)	LDAP / Active Directory
Örnek	Entra ID, AD FS, Okta, Google Workspace	Kurum içi AD, OpenLDAP
Organization üyeliği	Kendiliğinden: sağlayıcı organization’a bağlanır, ilk girişte kullanıcı üye olur	Kendiliğinden değil: üyeler eklenmelidir (aşağıda)
Parola	Keycloak görmez; kurumun ekranında girilir (MFA dahil)	Keycloak’ın giriş ekranında girilir, LDAP’a sorulur
Ağ	Keycloak’tan sağlayıcıya HTTPS çıkışı	Keycloak’tan dizine LDAPS (636)

Kurumun bir OIDC/SAML sağlayıcısı varsa (AD kullanan çoğu kurumda Entra ID ya da AD FS vardır) onu kullanın.

1. OIDC sağlayıcı (örnek: Microsoft Entra ID)

Entra tarafında (App registrations → New registration):

Redirect URI (Web): https://<auth adresi>/realms/fleet/broker/<takma ad>/endpoint. Takma adı burada seçersiniz, ör. entra.
Certificates & secrets → yeni client secret.
Token configuration → Add groups claim (security groups). Rolleri gruptan eşlemek için gerekir; token’a grupların nesne kimlikleri yazılır.
Not alın: Directory (tenant) ID, Application (client) ID, secret.

Keycloak tarafında (Identity providers → OpenID Connect v1.0):

Alias: Entra’da redirect URI’ye yazdığınız takma ad (entra).
Discovery endpoint: https://login.microsoftonline.com/<tenant id>/v2.0/.well-known/openid-configuration.
Client authentication: Client secret sent as post; client ID ve secret Entra’dan.
Trust email: açık (Entra e-postayı doğrular). Sync mode: Force (kullanıcı bilgisi ve roller her girişte sağlayıcıdan yenilenir).
Kaydedin.

Diğer OIDC sağlayıcılarında (Okta, Google Workspace, AD FS’in OIDC’si) adımlar aynıdır; discovery adresi ve client bilgileri o sağlayıcıdan alınır.

2. SAML sağlayıcı (örnek: AD FS)

Keycloak tarafında (Identity providers → SAML v2.0):

Alias seçin (ör. adfs). Sağlayıcının metadata adresini (SAML entity descriptor) girin; adresler oradan dolar.
Principal type: e-posta ya da Subject NameID; Trust email açık, Sync mode Force.
Keycloak’ın hizmet sağlayıcı bilgileri:
- Entity ID: https://<auth adresi>/realms/fleet
- Metadata: https://<auth adresi>/realms/fleet/broker/<takma ad>/endpoint/descriptor
- ACS: https://<auth adresi>/realms/fleet/broker/<takma ad>/endpoint

AD FS tarafında: Keycloak’ın metadata adresiyle bir Relying Party Trust ekleyin. Gönderilecek claim’ler: e-posta, ad, soyad ve rol eşlemesi yapılacaksa grup üyeliği (Token-Groups ya da Group).

3. Sağlayıcıyı organization’a bağlama (OIDC ve SAML)

Organizations → tenant’ın organization’ı → Identity providers → Link identity provider:

Identity provider: 1. ya da 2. adımda eklediğiniz sağlayıcı.
Domain: kurumun e-posta alanı (organization’ın alanları arasında olmalı; yoksa önce Settings’ten ekleyin).
Redirect when email domain matches: açık. Giriş ekranında [email protected] yazan kullanıcı doğrudan kurumun giriş ekranına gider.
Hide on login page: isteğe bağlı. Açıksa giriş ekranında sağlayıcı düğmesi görünmez, yalnızca e-posta alanı yönlendirir.

Bu sağlayıcıyla ilk kez giren kullanıcı Keycloak’ta oluşturulur ve organization’a üye (managed member) olur.

4. Rolleri eşleme (OIDC ve SAML)

Identity providers → sağlayıcı → Mappers → Add mapper. Her mapper’da Sync mode override: Force. Böylece kurumda gruptan çıkarılan kullanıcının rolü bir sonraki girişte kalkar.

Varsayılan rol: Hardcoded Role → learner. Sağlayıcıdan gelen herkes kursiyer olur.
Yöneticiler: OIDC’de Advanced Claim to Role: claim groups, değer yönetici grubunun kimliği (Entra’da grubun Object ID’si), rol tenant-admin. SAML’de Advanced Attribute to Role ile aynı eşleme, grup özniteliğinin adıyla.
Salt okunur: aynı şekilde bir grup → viewer.

Panelin kullanıcı ekranından verilen rol, Force eşlemesi olan sağlayıcıdan gelen kullanıcıda bir sonraki girişte sağlayıcının verdiğine döner. Kurumun kullanıcılarını rol açısından grup üyeliğiyle yönetin.

5. LDAP / Active Directory

User federation → Add LDAP providers:

Vendor: Active Directory. Connection URL: ldaps://dc.kurum.local:636. Bind DN ve parolası: yalnızca okuma yetkili bir hizmet hesabı.
Users DN: kullanıcıların bulunduğu OU. Edit mode: READ_ONLY (parola ve bilgiler AD’de kalır).
Periodic changed users sync: açık (ör. 1 saat). AD’de devre dışı bırakılan hesap Keycloak’ta da kapanır.
Rol eşleme: Mappers → Add mapper → role-ldap-mapper ya da group-ldap-mapper ile AD grubu → tenant-admin, viewer; herkes için learner → hardcoded-ldap-role-mapper.

Organization üyeliği: Keycloak LDAP kullanıcılarını organization’a kendiliğinden eklemez. Kullanıcılar senkron edildikten sonra Organizations → organization → Members → Add member → Add realm user ile ekleyin. Yeni çalışanlar için bu adım tekrarlanır; çok sayıda kullanıcıda OIDC/SAML yöntemini tercih edin.

6. Kursiyerleri eğitime ekleme

Kursiyere atama yapılabilmesi için eğitimde bir öğrenen kaydı gerekir. Kurumun sistemiyle giren learner kullanıcısının kaydı, mobil uygulamayı ilk açtığında kendiliğinden açılır: ad, soyad ve e-posta sağlayıcının token’ından alınır (given_name, family_name, email; ad yoksa e-postanın @ öncesi). Kursiyer bundan sonra panelde Öğrenenler listesinde görünür ve atanabilir.

Sağlayıcı e-postayı göndermelidir (OIDC’de email kapsamı; SAML’de e-posta özniteliği ve eşlemesi). E-postasız kullanıcının kaydı açılmaz.
Tenant’ta aynı e-postayla başka bir kullanıcının öğrenen kaydı varsa (ör. daha önce davet edilmiş yerel hesap) yeni kayıt açılmaz; training-api bunu uyarı olarak loglar. Aşağıdaki hesap bağlama ayarıyla iki hesap birleşir.
Kendiliğinden kayıt FLEET_TRAINING_LEARNERS_PROVISION_ON_LOGIN=false ile kapatılır.

Kursiyeri ilk girişinden önce atamak gerekiyorsa (ör. işe başlayana zorunlu eğitim) kayıt önceden açılır:

Panelde Öğrenenler → Davet (tek tek), ya da
Kurumun İK sistemi dış API’yle senkronlar: PUT /api/ext/v1/training/learners/{personel no} ve { "email", "firstName", "lastName", "invite": true } (dış API).

Her iki yol da Keycloak’ta aynı e-postayla bir hesap açar. Kursiyer ilk kez kurumun sistemiyle girdiğinde Keycloak bu hesabı bulur ve varsayılan olarak bağlamak için yerel parolayı sorar. Bunu önlemek için sağlayıcının ilk giriş akışında hesap e-postayla kendiliğinden bağlanmalıdır:

Authentication → first broker login akışını kopyalayın (ör. first broker login - auto link).
Kopyada Handle Existing Account alt akışındaki Confirm link existing account ve Account verification options adımlarını silin, yerine Automatically set existing user ekleyin (Required).
Identity providers → sağlayıcı → First login flow override: bu kopya.

Bu ayar yalnızca e-postayı doğrulayan, kurumun kendi sağlayıcısında güvenlidir (Trust email açık). Sağlayıcıda e-postasını değiştirebilen biri aynı e-postalı başka bir hesaba bağlanabilir. Davette gösterilen geçici parola kullanılmaz; kursiyer kurumun hesabıyla girer.

Doğrulama

Tarayıcıda gizli pencerede tenant panelini açın, bir yönetici hesabının kurum e-postasını yazın: kurumun giriş ekranına gitmelidir (LDAP’ta Keycloak’ın giriş ekranı kalır).
Giriş sonrası panel açılmalıdır. Salt okunur grubundaki bir hesap ayarlar ve denetim kaydı menülerini görmez.
Keycloak → Users → kullanıcı: Identity provider links sağlayıcıyı, Role mapping rolleri, Organizations sekmesi tenant’ı göstermelidir.
Mobil uygulamada bir kursiyer hesabıyla giriş: sistem tarayıcısında aynı yönlendirme olur, kursiyerin eğitimleri görünür.

Sık görülen hatalar:

Belirti	Neden
Panelde “Erişiminiz yok” (yönetici hesabıyla)	Kullanıcı organization üyesi değil (LDAP: 5. adımdaki üyelik; OIDC/SAML: sağlayıcı organization’a bağlı değil) ya da grup → `tenant-admin` eşlemesi tutmuyor (Users → kullanıcı → Role mapping)
Mobil uygulamada eğitimler açılmıyor	`learner` rolü yok: Hardcoded Role eksik ya da üyelik yok
Kursiyer giriyor ama Öğrenenler listesinde yok	Mobil uygulamayı henüz açmadı; ya da token’da e-posta yok ya da e-posta başka bir öğrenende (training-api logu, 6. adım)
Sağlayıcıdan dönüşte `invalid redirect uri`	Sağlayıcıdaki redirect URI, Keycloak’taki takma adla aynı değil
Var olan yerel hesapla “hesap zaten var” ekranı	Aynı e-postalı yerel kullanıcı var; first broker login hesabı bağlamayı önerir. Kullanıcı yerel parolasıyla onaylar ya da yönetici yerel hesabı siler

Kullanıcı kurumdan ayrılınca

Kurumun sistemindeki hesap kapatılınca yeni giriş yapılamaz. Açık oturum ise Keycloak’ın oturum süresi dolana kadar sürer; hemen kesmek için Keycloak’ta Users → kullanıcı → Sessions → Sign out. Kursiyeri panelde Öğrenenler → Pasifleştir ile kapatın: yeni atama alamaz, hesabının tek rolü learner ise Keycloak hesabı da kapatılır. Eğitim kayıtları raporlarda kalır; kişisel verinin silinmesi KVKK ayarlarındaki saklama süresine göre yapılır.