Konfigurasikan federasi LDAP atau Active Directory untuk IBM Bob self-hosted menggunakan custom resource BobIDP dan perintah bobctl configure-idp.

Gunakan bobctl configure-idp untuk menghubungkan lingkungan LDAP atau Active Directory-mu ke Keycloak sebagai federation provider pengguna. Kamu dapat menyelesaikan setup ini selama instalasi atau kapan saja setelah deployment.

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 IDP dari template yang tersedia sebelum mendaftarkan provider LDAP.

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

File konfigurasi memiliki dua bagian: field tingkat atas yang berlaku untuk seluruh deployment, dan daftar ldaps opsional di mana setiap entri mendeskripsikan satu federation provider LDAP.

Field tingkat atas

Field	Wajib	Deskripsi
`domains`	Ya	Daftar domain email yang diterima Bob saat login. Menghapus domain akan membatalkan pendaftarannya; pengguna dengan domain tersebut tidak akan dapat masuk.
`adminEmails`	Tidak	Daftar email pengguna yang akan diberikan akses admin Bob. Operator memperbarui grup `bob-admins` Keycloak dan database admin Bob secara atomik.
`ldaps`	Tidak	Daftar konfigurasi federation provider LDAP. Hilangkan sepenuhnya untuk deployment yang hanya menggunakan pengguna Keycloak langsung.

Field wajib (per entri provider LDAP)

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.

Penting:

Field domains adalah satu-satunya cara untuk mengonfigurasi routing berbasis domain dalam deployment on-premises. Jangan konfigurasikan domain melalui antarmuka pengguna administrasi Bob karena itu bukan metode yang benar dan dapat menyebabkan error autentikasi.

Field opsional (per entri provider LDAP)

Field	Deskripsi
`bindDn`	DN service account yang digunakan untuk mengautentikasi dan terhubung ke direktori. Dapat dihilangkan jika direktori mengizinkan akses anonymous bind.
`bindPasswordSecret`	Nama Secret yang sudah ada sebelumnya yang berisi kata sandi akun bind. Harus dibuat di namespace instance sebelum menjalankan `bobctl configure-idp`.
`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`	Nama Secret yang sudah ada sebelumnya yang berisi sertifikat CA server LDAP dalam format PEM. Harus dibuat di namespace instance sebelum menjalankan `bobctl configure-idp`.
`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. Dengan sinkronisasi grup, pengguna dan keanggotaan grup dari direktori LDAP-mu 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. Grup-grup ini tidak disertakan dalam 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

# Domain email yang harus diterima Bob saat login
domains:
  - corp.example.com

# Pengguna yang akan diberikan akses admin Bob
adminEmails:
  - alice@corp.example.com

# Federation provider LDAP
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

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

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

Memvalidasi konfigurasi IDP sebelum menerapkannya

Sebelum menerapkan konfigurasi IDP 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 configure-idp --config my-idp.yaml --dry-run

Dry run melakukan pemeriksaan berikut:

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

Menampilkan pratinjau custom resource BobIDP yang akan dibuat atau diperbarui.

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 IDP, jalankan perintah configure-idp untuk menerapkan konfigurasi ke cluster.

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

Flag	Wajib	Deskripsi
`--config <file>`	Ya	Menentukan path ke file konfigurasi IDP.
`--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 IDP dengan memeriksa kondisi status yang dilaporkan oleh custom resource BobIDP.

Pemeriksaan	Yang dikonfirmasikan
`Ready`	Konfigurasi berhasil diterapkan.
`LDAPRegistered`	Provider LDAP berhasil didaftarkan di Keycloak.
`LDAPReachable`	Server LDAP dapat diakses dari cluster.
`LDAPAuthenticated`	Kredensial bind yang dikonfigurasi valid.
`LDAPUserSyncSucceeded`	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_IDP_WAIT_TIMEOUT:

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

Mengonfigurasi beberapa provider LDAP

Untuk mengintegrasikan pengguna dari beberapa sumber LDAP atau Active Directory, tambahkan setiap direktori sebagai entri terpisah dalam daftar ldaps pada file konfigurasi IDP dan jalankan ulang configure-idp.

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

Memeriksa status resource IDP

Untuk melihat status konfigurasi IDP:

oc get bobidp -n <instance-namespace>

Untuk melihat informasi konfigurasi dan status terperinci:

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

Memverifikasi integrasi

Setelah bobctl configure-idp berhasil diselesaikan, verifikasi bahwa integrasi LDAP berfungsi dengan benar.

Periksa status custom resource BobIDP:

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

Verifikasi bahwa kondisi status berikut diset ke True:

Kondisi	Tujuan
`Ready`	Mengonfirmasi bahwa konfigurasi berhasil diterapkan.
`LDAPRegistered`	Mengonfirmasi bahwa provider LDAP berhasil didaftarkan di Keycloak.
`LDAPReachable`	Mengonfirmasi bahwa cluster dapat berkomunikasi dengan server LDAP.
`LDAPAuthenticated`	Mengonfirmasi bahwa kredensial bind yang dikonfigurasi valid.
`LDAPUserSyncSucceeded`	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