Konfigurasikan federasi LDAP atau Active Directory untuk IBM Bob on-premises menggunakan custom resource BobLDAP dan perintah bobctl add-ldap.

Bob on-premises mengintegrasikan lingkungan LDAP atau Active Directory-mu dengan Keycloak melalui utilitas bobctl, yang mengonfigurasi direktori sebagai federation provider pengguna Keycloak. Meskipun integrasi ini biasanya disiapkan selama instalasi, integrasi ini juga dapat dikonfigurasi, diperbarui, atau dipelihara setelah deployment sebagai bagian dari aktivitas manajemen pengguna yang berkelanjutan.

Sebelum kamu mulai

Sebelum mengonfigurasi federasi LDAP, pastikan persyaratan berikut terpenuhi:

Cluster OpenShift Container Platform (OCP) memiliki konektivitas jaringan ke server LDAP pada port yang sesuai:

389 untuk ldap://
636 untuk ldaps://

Service account (bind DN) dengan akses baca ke direktori tersedia, atau server LDAP dikonfigurasi untuk mengizinkan anonymous bind.

Jika menggunakan ldaps:// dengan certificate authority (CA) privat atau yang ditandatangani secara internal, dapatkan sertifikat CA server LDAP dalam format PEM.

Utilitas command-line bobctl terinstal, dan oc dikonfigurasi dan terautentikasi terhadap cluster target.

Referensi file konfigurasi

Buat file konfigurasi LDAP dari template yang tersedia sebelum mendaftarkan provider LDAP.

cp config-ldap-template.yaml my-ldap.yaml

File konfigurasi berisi parameter wajib dan opsional yang mendefinisikan cara Bob terhubung ke, mengautentikasi dengan, dan menyinkronkan pengguna dari direktori LDAP-mu.

Field wajib

Field	Deskripsi
`name`	Pengenal unik dan deskriptif untuk provider LDAP. Setiap provider yang dikonfigurasi harus memiliki nama yang berbeda.
`vendor`	Menentukan tipe direktori LDAP yang akan diintegrasikan. Nilai yang didukung: `other` (OpenLDAP dan yang kompatibel dengan LDAPv3), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	URL lengkap server LDAP, termasuk protokol (`ldap://` atau `ldaps://`), hostname, dan nomor port.
`usersDn`	Lokasi direktori tempat akun pengguna disimpan dan dari sana entri pengguna dicari dan diimpor.
`usernameLDAPAttribute`	Atribut direktori yang digunakan pengguna sebagai username mereka saat mengautentikasi.
`rdnLDAPAttribute`	Atribut direktori yang digunakan untuk mengidentifikasi entri dalam struktur direktori. Dalam sebagian besar konfigurasi, ini sama dengan `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Atribut direktori yang unik, stabil, dan tidak berubah yang digunakan untuk mengidentifikasi setiap akun pengguna secara permanen.
`userObjectClasses`	Daftar dipisah koma dari kelas objek LDAP yang mendefinisikan entri direktori mana yang dikenali dan diproses sebagai akun pengguna.
`domains`	Satu atau lebih domain email yang terkait dengan direktori. Selama autentikasi, pengguna yang alamat email-nya cocok dengan salah satu domain yang dikonfigurasi secara otomatis diarahkan ke provider LDAP ini untuk validasi kredensial.

Penting:

Parameter domains adalah satu-satunya metode yang didukung untuk mengonfigurasi routing berbasis domain dalam deployment on-premises. Jangan konfigurasikan domain melalui antarmuka pengguna administrasi Bob karena hal itu tidak didukung dan dapat menyebabkan error autentikasi.

Field opsional

Field	Deskripsi
`adminEmails`	Alamat email pengguna untuk diberikan hak istimewa administrator. Bob secara otomatis menetapkan akses admin kepada pengguna ini.
`bindDn`	DN service account yang digunakan untuk mengautentikasi dan terhubung ke direktori. Dapat dihilangkan jika direktori mengizinkan akses anonymous bind.
`bindPasswordSecret`	Mereferensikan Secret yang menyimpan kata sandi akun bind. Secret ini secara otomatis dibuat saat opsi `--bind-password` disediakan dengan perintah `bobctl`.
`useTruststoreSpi`	Menentukan kapan sertifikat CA LDAP digunakan untuk validasi server. Nilai: `always` (default, untuk sertifikat CA privat atau yang diterbitkan secara internal), `ldapsOnly` (untuk sertifikat CA yang dipercaya publik), `never` (saat terhubung melalui `ldap://` yang tidak aman).
`ldapsCACertSecret`	Mereferensikan Secret yang berisi sertifikat CA server LDAP dalam format PEM. Secret ini secara otomatis dibuat saat `--ca-cert-file` disediakan.
`searchScope`	Menentukan kedalaman pencarian direktori. `2` mencari semua container dan subtree anak (default); `1` membatasi pencarian hanya pada entri anak langsung.
`customUserSearchFilter`	Filter tambahan yang diterapkan pada semua operasi pencarian pengguna, misalnya untuk mengecualikan service account atau membatasi pencarian ke tipe pengguna tertentu.
`userSync.enabled`	Saat diset ke `true`, semua pengguna diimpor saat provider pertama kali dikonfigurasi, dan perubahan direktori selanjutnya disinkronkan setiap lima menit. Direkomendasikan untuk sebagian besar deployment.
`userAttributeMappings`	Mendefinisikan cara atribut direktori dipetakan ke field profil pengguna Bob, seperti `email`, `firstName`, dan `lastName`.
`priority`	Menentukan urutan provider dievaluasi saat beberapa provider dikonfigurasi. Provider dengan nilai lebih rendah diperiksa terlebih dahulu. Default adalah `0`.
`groupMapper`	Menyinkronkan grup LDAP ke Keycloak. Lihat Mengonfigurasi sinkronisasi grup LDAP.

Perilaku sinkronisasi pengguna

Saat userSync.enabled diset ke true, Bob melakukan impor satu kali dari semua pengguna saat provider LDAP didaftarkan. Setelah impor awal selesai, sinkronisasi siklus hidup pengguna yang berkelanjutan ditangani secara otomatis melalui SCIM.

Tips:

Untuk direktori LDAP yang besar, pertimbangkan untuk membiarkan userSync.enabled diset ke false dan membiarkan pengguna diprovisioning saat mereka pertama kali masuk. Pendekatan ini dapat mengurangi waktu yang diperlukan untuk mendaftarkan provider LDAP.

Mengonfigurasi sinkronisasi grup LDAP

Gunakan konfigurasi groupMapper opsional untuk menyinkronkan grup LDAP dengan Keycloak. Sinkronisasi grup memungkinkan pengguna dan keanggotaan grup yang didefinisikan dalam direktori LDAP-mu untuk diimpor dan dikelola melalui Keycloak.

Parameter groupsDn wajib. Semua parameter lainnya opsional dan dapat dikustomisasi agar sesuai dengan skema direktori LDAP dan struktur grup-mu.

Pembatasan:

Grup bob-admins dan bob-users adalah grup yang dikelola platform dan secara otomatis dikecualikan dari sinkronisasi grup LDAP.

Parameter	Nilai default	Deskripsi
`groupsDn`	Wajib	Distinguished name (DN) dasar yang berisi entri grup LDAP.
`name`	`groups`	Nama tampilan mapper grup di Keycloak.
`groupNameLdapAttribute`	`cn`	Atribut LDAP yang digunakan Keycloak sebagai nama grup.
`groupObjectClasses`	`groupOfNames`	Kelas objek LDAP atau kelas-kelas yang mengidentifikasi entri grup.
`membershipLdapAttribute`	`member`	Atribut dalam entri grup yang berisi informasi anggota.
`membershipAttributeType`	`DN`	Format nilai anggota. Nilai yang didukung: `DN` (distinguished name) dan `UID` (user ID).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Metode yang digunakan untuk menentukan keanggotaan grup.
`memberOfLdapAttribute`	`memberOf`	Atribut pengguna yang berisi informasi keanggotaan grup saat `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` digunakan.
`customGroupSearchFilter`	Tidak ada	Filter LDAP tambahan yang digunakan saat mencari grup. Filter harus diapit dalam tanda kurung, misalnya `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Mode sinkronisasi. Nilai yang didukung: `LDAP_ONLY` dan `READ_ONLY`.
`groupsPath`	`/`	Lokasi dalam hierarki grup Keycloak tempat grup yang disinkronkan dibuat.

Strategi pengambilan keanggotaan grup

Parameter userRolesRetrieveStrategy mengontrol cara Keycloak mengidentifikasi keanggotaan grup pengguna.

Strategi	Deskripsi
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Mengambil keanggotaan grup dengan mencari entri grup yang berisi referensi ke pengguna.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Mengambil keanggotaan grup dari atribut `memberOf` pengguna.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Mengambil keanggotaan grup secara rekursif, termasuk grup bersarang jika didukung oleh direktori LDAP.

Tips:

Gunakan LOAD_GROUPS_BY_MEMBER_ATTRIBUTE kecuali direktori LDAP-mu menyimpan informasi keanggotaan grup dalam entri pengguna melalui atribut memberOf atau menggunakan struktur grup bersarang yang memerlukan pencarian rekursif.

Contoh konfigurasi

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

domains:
  - corp.example.com

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

useTruststoreSpi: always

userSync:
  enabled: true

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

# Opsional: sinkronisasi grup LDAP ke Keycloak
groupMapper:
  groupsDn: ou=Groups,dc=corp,dc=example,dc=com
  groupObjectClasses: groupOfNames
  membershipLdapAttribute: member

./bobctl add-ldap --config corp-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Memvalidasi konfigurasi LDAP sebelum menerapkannya

Sebelum menerapkan konfigurasi LDAP ke cluster, gunakan opsi --dry-run untuk memvalidasi konfigurasi dan melihat pratinjau resource yang akan dibuat. Menjalankan dry run dapat membantu mengidentifikasi masalah konfigurasi umum sebelum ada perubahan yang dilakukan ke cluster.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt \
  --dry-run

Dry run melakukan pemeriksaan berikut:

Memvalidasi bahwa semua parameter konfigurasi yang wajib ada dalam file konfigurasi.

Memverifikasi bahwa file sertifikat CA yang ditentukan tersedia secara lokal saat --ca-cert-file digunakan.

Menampilkan pratinjau custom resource BobLDAP yang akan dibuat atau diperbarui.

Menampilkan Kubernetes Secret yang akan dihasilkan sebagai bagian dari konfigurasi.

Keluar tanpa membuat, memodifikasi, atau menghapus resource apa pun di cluster.

Catatan:

Operasi dry-run tidak memvalidasi konektivitas jaringan ke server LDAP, mengautentikasi kredensial yang disediakan terhadap direktori, atau mengonfirmasi keberadaan Secret yang direferensikan di cluster. Validasi ini dilakukan hanya setelah konfigurasi diterapkan dan tercermin dalam kondisi status LDAPReachable dan LDAPAuthenticated.

Menerapkan konfigurasi

Setelah membuat dan memvalidasi file konfigurasi LDAP, jalankan perintah add-ldap untuk menerapkan konfigurasi ke cluster.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Flag	Wajib	Deskripsi
`--config <file>`	Ya	Menentukan path ke file konfigurasi LDAP.
`--bind-password <password>`	Tidak	Membuat `bindPasswordSecret` di cluster. Tidak diperlukan saat direktori mengizinkan akses anonymous bind.
`--ca-cert-file <path>`	Tidak	Membuat `ldapsCACertSecret` dari file PEM lokal. Dapat dihilangkan saat menggunakan CA yang dipercaya publik atau koneksi `ldap://` yang tidak aman.
`--dry-run`	Tidak	Memvalidasi konfigurasi dan menampilkan pratinjau resource yang akan dibuat atau diperbarui, tanpa menerapkan perubahan apa pun ke cluster.

Saat perintah berjalan, bobctl menunggu operator merekonsiliasi konfigurasi dan memvalidasi provider LDAP dengan memeriksa kondisi status yang dilaporkan oleh custom resource BobLDAP.

Pemeriksaan	Yang dikonfirmasikan
`Ready`	Provider berhasil dibuat dan didaftarkan.
`LDAPReachable`	Server LDAP dapat diakses dari cluster.
`LDAPAuthenticated`	Kredensial bind yang dikonfigurasi valid.
`UserSyncSucceeded`	Impor pengguna awal berhasil diselesaikan. Kondisi ini hanya dievaluasi saat `userSync.enabled` diset ke `true`.

Timeout validasi default adalah 600 detik (10 menit). Di lingkungan dengan direktori besar, sinkronisasi pengguna awal dapat memerlukan beberapa menit untuk diselesaikan. Untuk meningkatkan timeout, atur variabel lingkungan BOB_LDAP_WAIT_TIMEOUT:

BOB_LDAP_WAIT_TIMEOUT=900 ./bobctl add-ldap --config my-ldap.yaml

Mengonfigurasi beberapa provider LDAP

Untuk mengintegrasikan pengguna dari beberapa sumber LDAP atau Active Directory, buat file konfigurasi terpisah untuk setiap direktori dan tetapkan nilai unik ke field name di setiap konfigurasi.

./bobctl add-ldap --config ldap-corp.yaml
./bobctl add-ldap --config ldap-subsidiary.yaml

Memeriksa status resource LDAP

Untuk melihat status provider LDAP yang dikonfigurasi:

oc get bobldap -n <instance-namespace>

Untuk melihat informasi konfigurasi dan status terperinci untuk provider tertentu:

oc get bobldap <name> -n <instance-namespace> -o yaml

Memverifikasi integrasi

Setelah bobctl add-ldap berhasil diselesaikan, verifikasi bahwa integrasi LDAP berfungsi dengan benar.

Periksa status custom resource BobLDAP:

oc get bobldap <name> -n <instance-namespace> -o yaml

Verifikasi bahwa kondisi status berikut diset ke True:

Kondisi	Tujuan
`Ready`	Mengonfirmasi bahwa provider LDAP berhasil didaftarkan.
`LDAPReachable`	Mengonfirmasi bahwa cluster dapat berkomunikasi dengan server LDAP.
`LDAPAuthenticated`	Mengonfirmasi bahwa kredensial bind yang dikonfigurasi valid.
`UserSyncSucceeded`	Mengonfirmasi bahwa semua pengguna berhasil diimpor. Hanya ada saat `userSync.enabled: true`.

Jika ada kondisi yang bernilai False, tinjau field message yang sesuai untuk detail diagnostik.

Masuk menggunakan kredensial dari direktori LDAP yang terfederasi untuk memverifikasi bahwa autentikasi pengguna berfungsi.

Buka URL Bob:

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

Login yang berhasil mengonfirmasi bahwa konektivitas, autentikasi, routing domain, provisioning SCIM, dan pemetaan peran berfungsi dengan benar.

Setelah pengguna masuk untuk pertama kalinya, konfirmasi bahwa record pengguna tersedia di Bob.

Buka UI administrasi Bob:

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

Masuk sebagai administrator Bob dan verifikasi bahwa pengguna uji coba muncul dalam daftar pengguna.

Jika groupMapper dikonfigurasi untuk memetakan grup LDAP ke administrator Bob:

Masuk dengan akun pengguna yang termasuk dalam grup administrator yang dipetakan.
Konfirmasi bahwa pengguna dapat mengakses UI administrasi Bob.
Verifikasi bahwa fungsi tingkat administrator tersedia.

Jika userSync.enabled: true, pengguna diimpor secara otomatis setelah provider LDAP didaftarkan. Pengguna uji coba seharusnya muncul di Bob tanpa memerlukan login awal.

Jika pengguna tidak muncul setelah beberapa menit, tinjau log bob-admin untuk error provisioning:

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

Tinjau error terkait SCIM yang dilaporkan dan selesaikan sebelum mencoba ulang proses sinkronisasi.

Integrasi LDAP