Vai al contenuto principale

LDAP Security

Panoramica​

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.

Avvio rapido​

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

Set the following values:

ilum-core:
  sicurezza:
    digitare: LDAP

openldap:
  Abilitato: vero

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: Admin)
  • ilumuser (password: utente)
Informazioni

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:

globale:
  ldapDomain: ilum.cloud # Your LDAP domain (requirement of the OpenLDAP chart, not Ilum)

ilum-core:
  sicurezza:
    digitare: LDAP
    LDAP:
      Url:
        - LDAP://ilum-openldap:389 # OpenLDAP URL
      ilumToLdapSync: falso # More on this below
      base: "dc=ilum,dc=cloud" # Base DN for LDAP
      adminUsers: # Usernames of users which should be made admins
        - ilumadmin
      passwordEncoder: adattativo
      userMapping: # Mapping between LDAP and Ilum user attributes
        # The enabled and enabledValue attributes are important for user activation
        Abilitato: employeeType
        enabledValue: active
        # ...
      groupMapping: # 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
  Dn: dc=ilum,dc=cloud
  objectclass: In alto
  objectclass: dominio
  o: Ilum

01-organizational-units.ldif: |- # This file is used to create the organizational units in the LDAP
  Dn: ou=groups,dc=ilum,dc=cloud
  objectclass: In alto
  objectclass: unità organizzativa
  Ou: Gruppi

  Dn: ou=sottogruppi,dc=ilum,dc=cloud
  objectclass: In alto
  objectclass: unità organizzativa
  Ou: Sottogruppi

  Dn: ou=persone,dc=ilum,dc=cloud
  objectclass: In alto
  objectclass: unità organizzativa
  Ou: gente

02-admin-user.ldif: |- # This file is used to create the admin user in the LDAP
  Dn: uid=ilumadmin,ou=persone,dc=ilum,dc=cloud
  objectclass: In alto
  objectclass: persona
  objectclass: organizzativoPersona
  objectclass: inetOrgPerson
  Cn: Ilum Admin
  Sn: Admin
  Uid: ilumadmin
  posta: [email protected]
  descrizione: Ilum Admin
  userPassword: Admin
  employeeType: active

03-user.ldif: |- # This file is used to create the user in the LDAP
  Dn: uid=ilumuser,ou=persone,dc=ilum,dc=cloud
  objectclass: In alto
  objectclass: persona
  objectclass: organizzativoPersona
  objectclass: inetOrgPerson
  Cn: Ilum User
  Sn: Utente
  Uid: ilumuser
  posta: [email protected]
  descrizione: Ilum User
  userPassword: utente
  employeeType: active
nota

For more information about the OpenLDAP chart used by Ilum, see its Repository GitHub o 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.

Avvio rapido​

nota

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

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:

ilum-core:
  sicurezza:
    digitare: LDAP
    LDAP:
      Url:
        - LDAP://ilum-openldap:636 # Use ldaps:// and the correct port
    
    # Basic configuration for importing the CA certificate to Ilum's trust store
    trustStore:
      Abilitato: vero
      modo: single
      Nome segreto: mkcert-ca

openldap:
  Abilitato: vero
  initTLSSecret:
    tls_enabled: vero
    segreto: "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-core:
  sicurezza:
    # ...
    Negozio chiave:
      Abilitato: vero
      Nome segreto: "ilum-keystore" # Name of the Kubernetes secret
      secretFileName: "keystore.p12" # File name within the secret
      parola d’ordine: "CAMBIAMIPER favore" # 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 A vero 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 valori.yaml.

Configurazione completa​

A complete configuration example:

ilum-core:
    sicurezza: 
        digitare: LDAP
        LDAP: 
            base: ""
            Url:
            - LDAP://<domain>:<>
            nome utente: ""
            parola d’ordine: ""
            passwordEncoder: >
            adminUsers: 
                - -utente>
            userMapping:
                base: ""
                filtro: ""
                parola d’ordine: ""
                nome utente: ""
                nome completo: ""
                descrizione: ""
                dipartimento: ""
                E-mail: ""
                Abilitato: ""
                enabledValue: ""
            groupMapping:
                base: ""
                filtro: ""
                memberAttribute: ""
                roleFilterAttribute: ""
                nome: ""
                descrizione: ""
                Ruoli: ""
                Abilitato: ""
                enabledTrue: ""
            roleMapping:
                base: ""
                filtro: ""
                memberAttribute: ""
                nome: ""
                descrizione: ""
                Abilitato: ""
                enabledTrue: ""

Abilitato, enabledTrue​

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

  • Abilitato: Name of the LDAP attribute containing the state.
  • enabledTrue (oppure enabledValue for users): Value representing ENABLED.

Example mapping:

DN: UID=George,OO=PEOPLE,DC=SpringFramework,DC=ORG
Classe di oggetti: superiore
ObjectClass: Persona
classe di oggetti: organizationalPerson
classe di oggetti: inetOrgPerson
cn: George Ardenson
posta: [email protected]
Descrizione: Datascientist nel rilevamento delle frodi
UID: George
userPassword: pass
Stato: On

Configuration:

userMapping:
    Abilitato: "Stato"
    enabledValue: "acceso"

You can similarly map states for roles and groups.

nota

By default, vero e Abilitato are interpreted as ENABLED.

avvertimento

Ensure a valid value is set for the Abilitato attribute. Otherwise, Ilum will treat users as DISABLED by default.

Ruoli e roleFilterAttribute​

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

  • Ruoli: Group attribute containing role names.
  • roleFilterAttribute: Optionally binds values from Ruoli to an attribute in the LDAP role.

Example mapping:

DN: CN=Datascientist,OU = Sottogruppi, DC = SpringFramework, DC = ORG
Classe di oggetti: superiore
classe dell'oggetto: groupOfNames
CN: Scienziato dei dati
Membro: UID=George
businessCategory: "analisi complessiva dei dati"
Ident: "KQ320"

DN: CN=Utenti,OU = Sottogruppi, DC = SpringFramework, DC = ORG
Classe di oggetti: superiore
classe dell'oggetto: groupOfNames
CN: Scienziato dei dati
Membro: UID=Alice
Utente: UID=bob
Membro: UID=George
businessCategory: "analisi complessiva dei dati"
Ruoli: KQ320
Ruoli: BR200
Ruoli: LL100

Configuration:

groupMapping:
    Ruoli: Sottogruppi
    roleFilterAttribute: Ident
nota

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

passwordEncoder​

Supported values:

  • adattativo
  • bcrypt
  • MD5
  • sha256

These specify the password encoder used by your LDAP server.

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

Last updated on