تخطي إلى المحتوى الرئيسي

LDAP Security

نظره عامه ​

Managing user credentials across multiple services can be challenging. LDAP ( Lightweight Directory Access Protocol) offers a centralized solution, enabling single sign-on (SSO) and streamlining user management.

Ilum integrates smoothly with LDAP servers. Configuration is handled via Helm, allowing you to set connection details, define authentication queries, and map LDAP attributes to Ilum’s internal user model.

Attribute mapping is flexible: you can link LDAP groups and roles—including relationships such as user-to-group and group-to-role—and map user attributes like email, full name, and description directly to Ilum profiles.

Once LDAP integration is set up, users log in to Ilum using their LDAP credentials. Ilum automatically synchronizes user data from the LDAP server according to your Helm configuration, creating and updating profiles and permissions as needed.

بداية سريعة ​

LDAP is available as a module in Ilum, making the setup straightforward.

Set the following values:

إيلوم كور : 
  أمن : 
    نوع : LDAP 

OpenLDAP : 
  تمكين :  صحيح

This configuration deploys an OpenLDAP server with default settings and connects Ilum Core to it.

The default OpenLDAP server is accessible at ldap://ilum-openldap:389 and includes two sample users:

  • ilumadmin (password: المشرف )
  • ilumuser (password: مستخدم )
معلومات

For more details on Ilum’s OpenLDAP usage, visit our Artifact Hub page.

Manual OpenLDAP Setup​

After testing the default configuration, you may wish to set up your own OpenLDAP instance. Here are some configuration options to consider:

عالمي : 
  ldapDomain: ilum.cloud # Your LDAP domain (requirement of the OpenLDAP chart, not Ilum)

إيلوم كور : 
  أمن : 
    نوع : LDAP 
    LDAP : 
      عناوين URL : 
        - LDAP : إيلوم - OpenLDAP : 389 # OpenLDAP URL
      ilumToLdapSync:  خطأ  # More on this below
      قاعدة :  "dc=ilum,dc=cloud" # Base DN for LDAP
      مسؤولالمستخدمون :  # Usernames of users which should be made admins
        -  ilumadmin
      كلمة السر التشفير : التكيف 
      خريطة المستخدم :  # Mapping between LDAP and Ilum user attributes
        # The enabled and enabledValue attributes are important for user activation
        تمكين :  employeeType
        enabledالقيمة :  active
        # ... 
      تعيين المجموعة :  # Mapping between LDAP and Ilum group attributes
        # ... 
      roleMapping :  # Mapping between LDAP and Ilum role attributes
        # ...

Default OpenLDAP LDIF files Ilum uses:

00-root.ldif:  | -  # This file is used to create the root domain - the first step in the LDAP setup
  [د] :  dc=ilum, dc=cloud
  الكائن : أعلى 
  الكائن : المجال 
  o: إيلوم 

01-organizational-units.ldif:  | -  # This file is used to create the organizational units in the LDAP
  [د] :  ou=groups, dc=ilum, dc=cloud
  الكائن : أعلى 
  الكائن : الوحدة التنظيمية 
  أوي : المجموعات 

  [د] : ou = مجموعات فرعية , dc=ilum, dc=cloud
  الكائن : أعلى 
  الكائن : الوحدة التنظيمية 
  أوي : مجموعات فرعيه 

  [د] : ou = الناس , dc=ilum, dc=cloud
  الكائن : أعلى 
  الكائن : الوحدة التنظيمية 
  أوي : شعب 

02-admin-user.ldif:  | -  # This file is used to create the admin user in the LDAP
  [د] :  uid=ilumadmin, ou = الناس , dc=ilum, dc=cloud
  الكائن : أعلى 
  الكائن : شخص 
  الكائن : شخصي تنظيمي 
  الكائن : inetOrgPerson 
  سي إن :  Ilum Admin
  SN :  Admin
  UID :  ilumadmin
  بريد :  [البريد الإلكتروني محمي] 
  وصف :  Ilum Admin
  كلمة مرور المستخدم : المشرف 
  employeeType:  active

03-user.ldif:  | -  # This file is used to create the user in the LDAP
  [د] :  uid=ilumuser, ou = الناس , dc=ilum, dc=cloud
  الكائن : أعلى 
  الكائن : شخص 
  الكائن : شخصي تنظيمي 
  الكائن : inetOrgPerson 
  سي إن :  Ilum User
  SN : مستخدم 
  UID :  ilumuser
  بريد :  [البريد الإلكتروني محمي] 
  وصف :  Ilum User
  كلمة مرور المستخدم : مستخدم 
  employeeType:  active
ملاحظه

For more information about the OpenLDAP chart used by Ilum, see its مستودع GitHub أو Artifact Hub page.

LDAP with SSL​

For secure connections, Ilum fully supports LDAPS (LDAP over SSL).

To enable LDAPS:

  • Provide a truststore containing your LDAP server’s CA certificate. See the Truststore documentation for details.
  • (Optional) Provide a keystore if your LDAP server requires mutual TLS (mTLS) with a client certificate.

بداية سريعة ​

ملاحظه

This section uses a convenience tool called mkcert to generate a self-signed certificate. You can learn more about it هنا .

Let’s begin by generating a TLS certificate for our LDAP server with mkcert: 

mkcert ilum-openldap ldap localhost 127.0.0.1

The arguments passed to mkcert are the domains we want our certificate to cover.

This command will output two files:

  • ilum-openldap+3-key.pem: Private key for the certificate
  • ilum-openldap+3.pem: Certificate itself

Now, we need to load-in the certificate into our kubernetes cluster:

kubectl create secret tls openldap-tls --cert=./ilum-openldap+3.pem --key=./ilum-openldap+3-key.pem

This will create a TLS secret named openldap-tls containing the certificate and private key.

Lastly, we need to load the mkcert certificate authority into our cluster as well. You can see where the CA is stored by running mkcert -CAROOT. It should give you a path, where a file named rootCA.pem is located. Point to this file when executing the following command:

kubectl create secret generic mkcert-ca --from-file=ca.crt=/path/to/rootCA.pem

This will create a Kubernetes secret named mkcert-ca containing the CA certificate.

Now, it is enough to adjust your Helm configuration to use the TLS secret and CA secret:

إيلوم كور : 
  أمن : 
    نوع : LDAP 
    LDAP : 
      عناوين URL : 
        - LDAPS : إيلوم - OpenLDAP : 636 # Use ldaps:// and the correct port
    
    # Basic configuration for importing the CA certificate to Ilum's trust store
    TrustStore : 
      تمكين :  صحيح 
      طريقة :  single
      اسم سري :  mkcert- ca

OpenLDAP : 
  تمكين :  صحيح 
  initTLSSecret: 
    tls_enabled:  صحيح 
    سر :  "openldap-tls" # Point to the TLS secret created earlier

With this configuration Ilum will use the TLS certificate to connect to LDAPS.

Keystore Configuration​

However, we can go a step further and use a keystore to authenticate our client.

Prepare a PKCS#12 file containing your client certificate and private key:

openssl pkcs12 -export -in ilum-openldap+3.pem -inkey ilum-openldap+3-key.pem -certfile <your-CA-cert> -name "client-cert" -out client.p12 -password pass:yourpassword

Create a Kubernetes secret with the keystore:

kubectl create secret generic ilum-keystore --from-file=keystore.p12=client.p12

Now, add to the values:

إيلوم كور : 
  أمن : 
    # ... 
    كي ستور : 
      تمكين :  صحيح 
      اسم سري :  "ilum-keystore" # Name of the Kubernetes secret
      secretFileName :  "keystore.p12"  # File name within the secret
      شعار :  "CHANGEMEPLEASE"  # Keystore password

ILUM ↔ LDAP Synchronization​

Ilum supports bidirectional synchronization with LDAP. When enabled, changes to users, groups, or roles in Ilum are automatically reflected in LDAP.

To enable synchronization, set ilum-core.security.ldap.ilumToLdapSyncل صحيح in your Helm configuration.

LDAP Sync From in Ilum UI Selecting this checkbox in the UI enables user synchronization with LDAP

Synchronization covers users, groups, and roles, provided attribute mappings are correctly defined in your Helm القيم.yaml .

التكوين الكامل ​

A complete configuration example:

إيلوم كور : 
    أمن :  
        نوع : LDAP 
        LDAP :  
            قاعدة :  "<your_base_dn>" 
            عناوين URL : 
            - LDAP : < النطاق > : < الميناء > 
            اسم المستخدم :  "<your_admin_username>" 
            شعار :  "<your_admin_password>" 
            كلمة السر التشفير : <chosen_password_encoder > 
            مسؤولالمستخدمون :  
                - < المشرف - مستخدم > 
            خريطة المستخدم : 
                قاعدة :  "<your_user_base>" 
                راووق :  "<your_filter>" 
                شعار :  "<your_password>" 
                اسم المستخدم :  "<your_username>" 
                الاسم الكامل :  "<your_fullname>" 
                وصف :  "<your_description>" 
                قسم :  "<your_department>" 
                البريد الإلكتروني :  "<your_email>" 
                تمكين :  "<your_enabled>" 
                enabledالقيمة :  "<your_enabled_value>" 
            تعيين المجموعة : 
                قاعدة :  "<your_group_base>" 
                راووق :  "<your_filter>" 
                memberAttribute :  "<your_member_attribute>" 
                roleFilterAttribute :  "<your_role_filter_attribute>" 
                اسم :  "<your_name>" 
                وصف :  "<your_description>" 
                ادوار :  "<your_roles>" 
                تمكين :  "<your_enabled>" 
                enabledصحيح :  "<your_enabled_true>" 
            roleMapping : 
                قاعدة :  "<your_role_base>" 
                راووق :  "<your_filter>" 
                memberAttribute :  "<your_member_attribute>" 
                اسم :  "<your_name>" 
                وصف :  "<your_description>" 
                تمكين :  "<your_enabled>" 
                enabledصحيح :  "<your_enabled_true>"

تمكين , enabledصحيح ​

These options map the ENABLED/DISABLED state from LDAP to Ilum.

  • تمكين : Name of the LDAP attribute containing the state.
  • enabledصحيح (أو enabledالقيمة for users): Value representing ENABLED.

Example mapping:

DN: UID = جورج ، OU = الناس ، DC = Springframework ، DC = org 
فئة الكائن: أعلى 
ObjectClass: شخص 
objectclass: organizationalPerson 
objectclass: inetOrgPerson 
cn: جورج أردنسون 
بريد: [البريد الإلكتروني محمي] 
الوصف: عالم بيانات في الكشف عن الاحتيال 
UID: جورج 
userPassword: تمرير 
الحالة: في

Configuration:

خريطة المستخدم : 
    تمكين :  "الحالة" 
    enabledالقيمة :  "تشغيل"

You can similarly map states for roles and groups.

ملاحظه

By default, صحيح و تمكين are interpreted as ENABLED.

تحذير

Ensure a valid value is set for the تمكين attribute. Otherwise, Ilum will treat users as DISABLED by default.

ادوار و roleFilterAttribute ​

These options map group-to-role relationships from LDAP to Ilum.

  • ادوار : Group attribute containing role names.
  • roleFilterAttribute : Optionally binds values from ادوار to an attribute in the LDAP role.

Example mapping:

DN: CN = عالم البيانات ، OU = مجموعات فرعية ، DC = Springframework ، DC = org 
فئة الكائن: أعلى 
objectclass: groupOfNames 
CN: عالم البيانات 
العضو: UID = جورج 
businessCategory: "تحليل البيانات الشاملة" 
المعرف: "KQ320" 

DN: CN = المستخدمون ، OU = المجموعات الفرعية ، DC = Springframework ، DC = ORG 
فئة الكائن: أعلى 
objectclass: groupOfNames 
CN: عالم البيانات 
العضو: UID = أليس 
العضو: UID = بوب 
العضو: UID = جورج 
businessCategory: "تحليل البيانات الشاملة" 
الأدوار: KQ320 
الأدوار: BR200 
الأدوار: 100 ليرة لبنانية

Configuration:

تعيين المجموعة : 
    ادوار : مجموعات فرعيه 
    roleFilterAttribute : هوية
ملاحظه

If roleFilterAttribute is not set, Ilum will match LDAP roles by name or create new ones as needed

كلمة السر التشفير ​

Supported values:

  • التكيف
  • بكريبت
  • MD5
  • ش256

These specify the password encoder used by your LDAP server.

By default, Ilum uses the adaptive encoder, which detects the prefix (e.g., {bcrypt}أو {noop}) and selects the appropriate encoder for credential verification. If no prefix is present, no encoder is applied.