BobIDP özel kaynağını ve bobctl configure-idp komutunu kullanarak IBM Bob self-hosted için LDAP veya Active Directory federasyonunu yapılandırın.

LDAP veya Active Directory ortamınızı Keycloak'a kullanıcı federasyonu sağlayıcısı olarak bağlamak için bobctl configure-idp komutunu kullanın. Bu kurulumu yükleme sırasında veya dağıtımdan sonra herhangi bir noktada tamamlayabilirsiniz.

Başlamadan önce

LDAP federasyonunu yapılandırmadan önce aşağıdaki gereksinimlerin karşılandığından emin olun:

OpenShift Container Platform (OCP) kümesinin uygun port üzerinden LDAP sunucusuna ağ bağlantısı vardır:

ldap:// için 389
ldaps:// için 636

Dizine okuma erişimi olan bir servis hesabı (bind DN) mevcuttur veya LDAP sunucusu anonim bağlamalara (anonymous binds) izin verecek şekilde yapılandırılmıştır.

Özel veya dahili olarak imzalanmış bir sertifika yetkilisi (CA) ile ldaps:// kullanıyorsanız, LDAP sunucusunun CA sertifikasını PEM formatında edinin.

bobctl komut satırı yardımcı programı kuruludur ve oc hedef kümeye karşı yapılandırılmış ve kimlik doğrulaması yapılmıştır.

Yapılandırma dosyası referansı

Bir LDAP sağlayıcısını kaydetmeden önce sağlanan şablondan bir IDP yapılandırma dosyası oluşturun.

cp config-idp-template.yaml my-idp.yaml

Yapılandırma dosyasının iki bölümü vardır: tüm dağıtım için geçerli olan üst düzey alanlar ve her girişin bir LDAP federasyon sağlayıcısını tanımladığı isteğe bağlı bir ldaps listesi.

Üst düzey alanlar

Alan	Gerekli	Açıklama
`domains`	Evet	Bob'un girişte kabul ettiği e-posta etki alanlarının listesi. Bir etki alanının kaldırılması onu kaldırır; bu etki alanına sahip kullanıcılar giriş yapamaz.
`adminEmails`	Hayır	Bob yönetici erişimi verilecek kullanıcı e-postalarının listesi. Operatör, Keycloak `bob-admins` grubunu ve Bob yönetici veritabanını atomik olarak günceller.
`ldaps`	Hayır	LDAP federasyon sağlayıcısı yapılandırmalarının listesi. Yalnızca doğrudan Keycloak kullanıcıları kullanan dağıtımlar için tamamen atlayın.

Gerekli alanlar (LDAP sağlayıcı girişi başına)

Alan	Açıklama
`name`	LDAP sağlayıcısı için benzersiz, açıklayıcı bir tanımlayıcı. Yapılandırılan her sağlayıcının farklı bir adı olmalıdır.
`vendor`	Entegre edilecek LDAP dizininin türünü belirtir. Desteklenen değerler: `other` (OpenLDAP ve LDAPv3 uyumlu), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	Protokol (`ldap://` veya `ldaps://`), host adı ve port numarası dahil olmak üzere LDAP sunucusunun tam URL'si.
`usersDn`	Kullanıcı hesaplarının depolandığı ve kullanıcı girişlerinin arandığı ve içe aktarıldığı dizin konumu.
`usernameLDAPAttribute`	Kullanıcıların kimlik doğrulaması yaparken kullanıcı adı olarak sağladıkları dizin özniteliği (attribute).
`rdnLDAPAttribute`	Dizin yapısı içindeki girişleri tanımlamak için kullanılan dizin özniteliği. Çoğu yapılandırmada bu, `usernameLDAPAttribute` ile aynıdır.
`uuidLDAPAttribute`	Her kullanıcı hesabını kalıcı olarak tanımlamak için kullanılan benzersiz, kararlı, değişmeyen bir dizin özniteliği.
`userObjectClasses`	Hangi dizin girişlerinin kullanıcı hesabı olarak tanınacağını ve işleneceğini tanımlayan virgülle ayrılmış LDAP nesne sınıfları (object classes) listesi.

Önemli:

domains alanı, on-premises dağıtımlarda alan adı tabanlı yönlendirmeyi yapılandırmanın tek yoludur. Bob yönetim kullanıcı arayüzü üzerinden alan adlarını yapılandırmayın; çünkü bu doğru yöntem değildir ve kimlik doğrulama hatalarına neden olabilir.

İsteğe bağlı alanlar (LDAP sağlayıcı girişi başına)

| Alan | Açıklama | |-------|-------------| | Yönetici ayrıcalıkları verilecek kullanıcıların e-posta adresleri. Bob bu kullanıcılara otomatik olarak yönetici erişimi atar. | | bindDn | Dizinle kimlik doğrulaması yapmak ve bağlanmak için kullanılan servis hesabının DN'i. Dizin anonim bağlama erişimine izin veriyorsa atlanabilir. | | bindPasswordSecret | Bağlama hesabı parolasını içeren önceden oluşturulmuş bir Secret'ın adı. bobctl configure-idp çalıştırılmadan önce instance namespace'inde oluşturulmalıdır. | | useTruststoreSpi | LDAP CA sertifikasının sunucu doğrulaması için ne zaman kullanılacağını belirtir. Değerler: always (özel veya dahili olarak düzenlenen CA sertifikaları için varsayılan), ldapsOnly (genel olarak güvenilen CA sertifikaları için), never (güvenli olmayan ldap:// üzerinden bağlanırken). | | ldapsCACertSecret | PEM formatında LDAP sunucusunun CA sertifikasını içeren önceden oluşturulmuş bir Secret'ın adı. bobctl configure-idp çalıştırılmadan önce instance namespace'inde oluşturulmalıdır. | | searchScope | Dizin aramalarının derinliğini belirler. 2 tüm alt kapsayıcıları ve alt ağaçları arar (varsayılan); 1 aramaları yalnızca doğrudan alt girişlerle sınırlar. | | customUserSearchFilter | Örneğin servis hesaplarını hariç tutmak veya aramaları belirli kullanıcı türleriyle kısıtlamak için tüm kullanıcı arama işlemlerine uygulanan ek bir filtre. | | userSync.enabled | true olarak ayarlandığında, sağlayıcı başlangıçta yapılandırıldığında tüm kullanıcılar içe aktarılır ve sonraki dizin değişiklikleri her beş dakikada bir senkronize edilir. Çoğu dağıtım için önerilir. | | userAttributeMappings | Dizin özniteliklerinin email, firstName ve lastName gibi Bob kullanıcı profili alanlarıyla nasıl eşlendiğini tanımlar. | | priority | Birden fazla sağlayıcı yapılandırıldığında sağlayıcıların değerlendirilme sırasını belirler. Daha düşük değerlere sahip sağlayıcılar önce kontrol edilir. Varsayılan 0dır. | | groupMapper | LDAP gruplarını Keycloak ile senkronize eder. Bkz. LDAP grup senkronizasyonunu yapılandırma. |

Kullanıcı senkronizasyon davranışı

userSync.enabled değeri true olarak ayarlandığında, Bob, LDAP sağlayıcısı kaydedildiğinde tüm kullanıcıların tek seferlik içe aktarımını gerçekleştirir. İlk içe aktarma tamamlandıktan sonra, devam eden kullanıcı yaşam döngüsü senkronizasyonu SCIM aracılığıyla otomatik olarak gerçekleştirilir.

İpucu:

Büyük LDAP dizinleri için userSync.enabled ayarını false olarak bırakmayı ve kullanıcıların ilk kez oturum açtıklarında sağlanmasına izin vermeyi değerlendirin. Bu yaklaşım, LDAP sağlayıcısını kaydetmek için gereken süreyi azaltabilir.

LDAP grup senkronizasyonunu yapılandırma

LDAP gruplarını Keycloak ile senkronize etmek için isteğe bağlı groupMapper yapılandırmasını kullanın. Grup senkronizasyonuyla LDAP dizininizdeki kullanıcılar ve grup üyelikleri Keycloak aracılığıyla içe aktarılır ve yönetilir.

groupsDn parametresi zorunludur. Diğer tüm parametreler isteğe bağlıdır ve LDAP dizin şemanıza ve grup yapınıza uyacak şekilde özelleştirilebilir.

Kısıtlama:

bob-admins ve bob-users grupları platform tarafından yönetilen gruplardır. LDAP grup senkronizasyonuna dahil edilmezler.

Parametre	Varsayılan değer	Açıklama
`groupsDn`	Gerekli	LDAP grup girişlerini içeren temel ayırt edici ad (base DN).
`name`	`groups`	Keycloak'taki grup eşleyicisinin (group mapper) görünen adı.
`groupNameLdapAttribute`	`cn`	Keycloak'un grup adı olarak kullandığı LDAP özniteliği.
`groupObjectClasses`	`groupOfNames`	Grup girişlerini tanımlayan LDAP nesne sınıfı veya sınıfları.
`membershipLdapAttribute`	`member`	Grup girişinde üye bilgilerini içeren öznitelik.
`membershipAttributeType`	`DN`	Üye değerlerinin formatı. Desteklenen değerler: `DN` (distinguished names) ve `UID` (user IDs).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Grup üyeliklerini belirlemek için kullanılan yöntem.
`memberOfLdapAttribute`	`memberOf`	`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` kullanıldığında grup üyeliği bilgilerini içeren kullanıcı özniteliği.
`customGroupSearchFilter`	Yok	Grupları ararken kullanılan ek LDAP filtresi. Filtre parantez içine alınmalıdır, örneğin `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Senkronizasyon modu. Desteklenen değerler: `LDAP_ONLY` ve `READ_ONLY`.
`groupsPath`	`/`	Senkronize edilen grupların oluşturulduğu Keycloak grup hiyerarşisindeki konum.

Grup üyeliği alma stratejileri

userRolesRetrieveStrategy parametresi, Keycloak'un bir kullanıcının grup üyeliklerini nasıl belirleyeceğini denetler.

Strateji	Açıklama
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Kullanıcılara referanslar içeren grup girişlerini arayarak grup üyeliklerini alır.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Kullanıcının `memberOf` özniteliğinden grup üyeliklerini alır.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	LDAP dizini tarafından desteklendiğinde iç içe geçmiş gruplar dahil olmak üzere grup üyeliklerini özyinelemeli (recursive) olarak alır.

İpucu:

LDAP dizininiz grup üyeliği bilgilerini memberOf özniteliği aracılığıyla kullanıcı girişlerinde saklamadığı veya özyinelemeli aramalar gerektiren iç içe geçmiş grup yapıları kullanmadığı sürece LOAD_GROUPS_BY_MEMBER_ATTRIBUTE kullanın.

Örnek yapılandırma

# Bob'un girişte kabul etmesi gereken e-posta etki alanları
domains:
  - corp.example.com

# Bob yönetici erişimi verilecek kullanıcılar
adminEmails:
  - alice@corp.example.com

# LDAP federasyon sağlayıcıları
ldaps:
  - name: corp-ldap

    vendor: other
    connectionUrl: ldaps://ldap.corp.example.com:636
    usersDn: ou=People,dc=corp,dc=example,dc=com
    usernameLDAPAttribute: uid
    rdnLDAPAttribute: uid
    uuidLDAPAttribute: entryUUID
    userObjectClasses: inetOrgPerson,organizationalPerson,person

    bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com
    bindPasswordSecret: corp-ldap-bind

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    userSync:
      enabled: true

    userAttributeMappings:
      - ldapAttribute: mail
        userModelAttribute: email
      - ldapAttribute: givenName
        userModelAttribute: firstName
      - ldapAttribute: sn
        userModelAttribute: lastName

    # İsteğe bağlı: LDAP gruplarını Keycloak ile senkronize et
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

./bobctl configure-idp --config my-idp.yaml

Uygulamadan önce bir IDP yapılandırmasını doğrulama

Kümeye bir IDP yapılandırması uygulamadan önce, yapılandırmayı doğrulamak ve oluşturulacak kaynakları önizlemek için --dry-run seçeneğini kullanın. Bir deneme çalıştırması (dry run) yapmak, kümede herhangi bir değişiklik yapılmadan önce yaygın yapılandırma sorunlarının belirlenmesine yardımcı olabilir.

./bobctl configure-idp --config my-idp.yaml --dry-run

Dry run aşağıdaki kontrolleri gerçekleştirir:

Yapılandırma dosyasında gerekli tüm yapılandırma parametrelerinin mevcut olduğunu doğrular.

Oluşturulacak veya güncellenecek BobIDP özel kaynağının bir önizlemesini görüntüler.

Kümedeki herhangi bir kaynağı oluşturmadan, değiştirmeden veya silmeden çıkar.

Not:

Dry-run işlemi, LDAP sunucusuna ağ bağlantısını doğrulamaz, sağlanan kimlik bilgilerini dizine karşı doğrulamaz veya kümedeki başvurulan Secret'ların varlığını onaylamaz. Bu doğrulamalar yalnızca yapılandırma uygulandıktan sonra gerçekleştirilir ve LDAPReachable ve LDAPAuthenticated durum koşullarına yansıtılır.

Yapılandırmayı uygulama

IDP yapılandırma dosyanızı oluşturup doğruladıktan sonra, yapılandırmayı kümeye uygulamak için configure-idp komutunu çalıştırın.

./bobctl configure-idp --config my-idp.yaml

Flag	Gerekli	Açıklama
`--config <file>`	Evet	IDP yapılandırma dosyasının yolunu belirtir.
`--dry-run`	Hayır	Kümeye herhangi bir değişiklik uygulamadan yapılandırmayı doğrular ve oluşturulacak veya güncellenecek kaynakların bir önizlemesini görüntüler.

Komut çalıştığında, bobctl operatörün yapılandırmayı mutabakata varmasını (reconcile) bekler ve BobIDP özel kaynağı tarafından bildirilen durum koşullarını kontrol ederek IDP'yi doğrular.

Kontrol	Neyi doğrular
`Ready`	Yapılandırmanın başarıyla uygulandığını.
`LDAPRegistered`	LDAP sağlayıcısının Keycloak'a kaydedildiğini.
`LDAPReachable`	LDAP sunucusuna kümeden erişilebildiğini.
`LDAPAuthenticated`	Yapılandırılan bağlama kimlik bilgilerinin geçerli olduğunu.
`LDAPUserSyncSucceeded`	İlk kullanıcı içe aktarımının başarıyla tamamlandığını. Bu koşul yalnızca `userSync.enabled` değeri `true` olarak ayarlandığında değerlendirilir.

Varsayılan doğrulama zaman aşımı 600 saniyedir (10 dakika). Büyük dizinlerin bulunduğu ortamlarda, ilk kullanıcı senkronizasyonunun tamamlanması birkaç dakika sürebilir. Zaman aşımı süresini artırmak için BOB_IDP_WAIT_TIMEOUT ortam değişkenini ayarlayın:

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

Birden fazla LDAP sağlayıcısı yapılandırma

Birden fazla LDAP veya Active Directory kaynağından kullanıcıları entegre etmek için her dizini IDP yapılandırma dosyasının ldaps listesinde ayrı bir girdi olarak ekleyin ve configure-idp komutunu yeniden çalıştırın.

./bobctl configure-idp --config my-idp.yaml

IDP kaynak durumunu inceleme

IDP yapılandırmasının durumunu görüntülemek için:

oc get bobidp -n <instance-namespace>

Ayrıntılı yapılandırma ve durum bilgilerini görüntülemek için:

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Entegrasyonu doğrulama

bobctl configure-idp başarıyla tamamlandıktan sonra LDAP entegrasyonunun düzgün çalıştığını doğrulayın.

BobIDP özel kaynağının durumunu kontrol edin:

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Aşağıdaki durum koşullarının True olarak ayarlandığını doğrulayın:

Koşul	Amaç
`Ready`	Yapılandırmanın başarıyla uygulandığını onaylar.
`LDAPRegistered`	LDAP sağlayıcısının Keycloak'a kaydedildiğini onaylar.
`LDAPReachable`	Kümenin LDAP sunucusuyla iletişim kurabildiğini onaylar.
`LDAPAuthenticated`	Yapılandırılan bağlama kimlik bilgilerinin geçerli olduğunu onaylar.
`LDAPUserSyncSucceeded`	Tüm kullanıcıların başarıyla içe aktarıldığını onaylar. Yalnızca `userSync.enabled: true` olduğunda mevcuttur.

Herhangi bir koşul False ise tanı ayrıntıları için ilgili message alanını inceleyin.

Kullanıcı kimlik doğrulamasının çalıştığını doğrulamak için federe LDAP dizinindeki kimlik bilgilerini kullanarak oturum açın.

Bob URL'sini açın:

https://bob.<namespace>.<ingress-domain>

Başarılı bir oturum açma; bağlantının, kimlik doğrulamanın, etki alanı yönlendirmesinin, SCIM sağlamanın ve rol eşlemenin düzgün çalıştığını onaylar.

Kullanıcı ilk kez oturum açtıktan sonra, kullanıcı kaydının Bob'da mevcut olduğunu onaylayın.

Bob yönetim kullanıcı arayüzünü açın:

https://bob.<namespace>.<ingress-domain>/admin

Bir Bob yöneticisi olarak oturum açın ve test kullanıcısının kullanıcılar listesinde göründüğünü doğrulayın.

Eğer groupMapper bir LDAP grubunu Bob yöneticileriyle eşleyecek şekilde yapılandırılmışsa:

Eşlenen yönetici grubuna ait bir kullanıcı hesabıyla oturum açın.
Kullanıcının Bob yönetim kullanıcı arayüzüne erişebildiğini onaylayın.
Yönetici düzeyindeki işlevlerin kullanılabilir olduğunu doğrulayın.

userSync.enabled: true ise, kullanıcılar LDAP sağlayıcısı kaydedildikten sonra otomatik olarak içe aktarılır. Test kullanıcısı ilk oturum açmaya gerek kalmadan Bob'da görünmelidir.

Kullanıcı birkaç dakika sonra görünmezse sağlama hataları için bob-admin loglarını inceleyin:

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

Bildirilen SCIM ile ilgili hataları inceleyin ve senkronizasyon sürecini yeniden denemeden önce bunları çözün.

LDAP entegrasyonu

Bu sayfada