# LDAP Authentication Extension

This article describes the LDAP Authentication extension, which integrates EasyDCIM with LDAP directories such as Microsoft Active Directory and OpenLDAP. It covers automatic synchronisation of users and administrators and the authentication flow against the configured directory server.

# About

LDAP Authentication For EasyDCIM (opens new window) extension effortlessly integrates with widely-used LDAP directory services such as Microsoft Active Directory and OpenLDAP, facilitating the automatic synchronization of users and administrators into the EasyDCIM platform.

# Features

  • Create/Delete Synchronization Servers
  • Test Connection For Synchronization Servers
  • List Synchronization Servers With Connection Status
  • Automatic Connection Status Update For Synchronization Servers
  • Edit Synchronization Server Connection Data
  • Choose Search Bases For Each Synchronization Server
  • Choose Directory Service Groups To Synchronize Users With EasyDCIM
  • View Synchronized Users List
  • Authenticate synchronized users with directory credentials
  • Manage Password Synchronization Settings
  • Synchronize Account Status With The Directory
  • Configure LDAP encryption, certificate validation, and directory-login access
  • Add Synchronization Jobs For Each Synchronization Server
  • Define Automatic Synchronization Interval For Each Synchronization Server
  • Synchronizations:
    • View Synchronization Status
    • View Synchronizations List
    • View/Delete Synchronizations Records
    • View Detailed Synchronizations Logs
  • Supported Directory Services:
    • FreeIPA
    • Microsoft Active Directory
    • OpenLDAP

# Adding synchronization server

In order to begin using the LDAP Authentication extension you need to firstly add a server to connect to a directory service, for example: OpenLDAP. To do this, go to the LDAP Authentication extension and then select the "Servers" tab. From the action menu, select the "Add Server" option. The form contains the following fields:

  • Submodule - select from the list the directory services module on the basis of which the rest of the server connection form will be dynamically generated
  • Name - any name for the server

OpenLDAP / Active Directory/ FreeIPA

  • Port - port used for connection with the server (default: 389)
  • Hostname - the name of the host or server IP address
  • Username - name of the user
  • Base DN - the starting point used by the LDAP server when searching for user authentication in the directory service
  • Password - the user's password
  • Encryption - choose how EasyDCIM connects to the directory:
    • None - an unencrypted LDAP connection. Do not use this mode for directory login.
    • SSL (LDAPS) - connect using LDAPS.
    • StartTLS - upgrade the LDAP connection to TLS.
  • Validate TLS Certificate - validate the TLS certificate presented by the directory server (enabled by default). Disable this only when a test server uses a self-signed certificate.
  • Directory Login - allow synchronized users to sign in to EasyDCIM with their directory credentials (disabled by default). The password is verified by an LDAP bind and is not stored in EasyDCIM.
  • User Object Classes - object classes used to find users for import and synchronization. The field is filled in with the default classes of the selected submodule. Type a class name to add it.
  • Group Object Classes - object classes used to find groups for the synchronization configuration. The field is filled in with the default classes of the selected submodule. Type a class name to add it.

After entering the access data, you can perform the "Test Connection" action which will verify if the connection can be established correctly. If there are no errors, save the changes. The connection will be added to EasyDCIM and you will be redirected to step 2 of server edition.

# LDAP login

When Directory Login is enabled for a server, synchronized users can authenticate to EasyDCIM with their LDAP credentials. Keep Encryption set to SSL (LDAPS) or StartTLS for login; an encrypted connection is required before user credentials are sent to the directory. Leave Directory Login disabled when a server is used only for synchronization.

If a directory login fails, EasyDCIM records an LDAP Login Failed notification with the attempted username, server, failure reason, and client IP address. Configure its delivery in Settings → Notifications like any other system notification.

# Editing synchronization server

# Server information

The form comprises fields that align with the dynamically generated settings during the server's creation for a specific directory service. You can also perform a Test Connection action here, which will verify whether the connection can be established correctly, if not, edit the connection configuration fields so that the connection can be established successfully. After saving the changes or clicking on Step Two, if the connection is established correctly, you will be redirected to the synchronization configuration.

# Server configuration

Step two is the key part of the synchronization configuration. You can configure there how users are to be mapped, from which search databases they are to be synchronized, and how often the synchronization is to take place. The form consists of the following fields:

  • Search Base - select the search base, that is, where the search for user account entries begins in the hierarchical structure of the directory service.
  • Groups Mapping - depending on the number of groups in the EasyDCIM panel, that many groups mapping fields will appear (one for each group), in which you select the directory service group from which users will be mapped to a given group in EasyDCIM.
  • Sync Priority - set a non-negative priority for each group mapping. When a user belongs to multiple mapped LDAP groups, the mapping with the highest priority determines the EasyDCIM role. Mappings with the same priority are processed in their configured order; an omitted priority defaults to 0.
  • Synchronization Interval - choose between:
    • Hourly - synchronization will be performed every hour (default option).
    • Daily - an additional field (Hour) will appear, the synchronization will be performed every day at the selected in "Hour" field time:
    • Hour - choose the time of synchronization.
    • Weekly - synchronization will be performed once a week, at the selected day and time:
      • Day Of The Week - select the day of the week to perform the synchronization.
      • Hour - choose the time of synchronization.
  • Password Synchronization - a password of 16 characters is always generated for newly imported users:
    • Yes (default) - a password of 16 characters will also be generated for existing users who do not have a password yet.
    • No - existing users without a password are left unchanged.
  • Send Email Info To Client - when enabled, each time a password is generated for a user, an email is sent to inform them of the password change (disabled by default).
  • Account Status Synchronization - deactivate users whose directory account is disabled and activate them again when the account is enabled. Deactivated users are signed out. This applies only to users with account status synchronization enabled on the Users list: users created by the synchronization, or existing users enabled there explicitly. Banned users are never changed (disabled by default).
  • Deactivate Missing Users - also deactivate users with account status synchronization who are no longer returned by any mapped group, for example after being deleted from the directory or removed from all mapped groups. This step is skipped when any mapped group could not be read or found, or when the mapped groups returned no users (disabled by default).
  • Disabled Account Attribute (OpenLDAP only) - the directory attribute that marks a disabled account, used by Account Status Synchronization. Enter the attribute name when any value means disabled (e.g. pwdAccountLockedTime), or attribute=value when only that value does (e.g. employeeType=disabled). The bind account must be able to read it. Leave it empty when the directory has no such attribute: users returned by mapped groups are then treated as enabled. Active Directory servers use the userAccountControl attribute and FreeIPA servers use the nsAccountLock attribute instead.

Once the synchronization settings have been configured, you are presented with two choices:

  • Save Changes - after saving the changes, we will be redirected to the list of synchronization servers, and the synchronization will be performed according to the set interval.
  • Save Changes & Start Synchronization - you will be redirected to the view added to the synchronization queue. The synchronization will be performed according to the set interval just like in the case of "Save Changes" choice.

# List of synchronization servers

This section lists all the servers that have been created. The table contains relevant information on each server:

  • ID
  • Name - server name
  • Module name - directory service module
  • Connection status - after hovering over it, a tooltip providing a more comprehensive status report of the connection appears.
  • Directory Login - shows whether directory login is enabled for the server.
  • Allowed actions:
    • Edit - manage server details
    • Delete - remove the server
    • Synchronize - manually add a synchronization task to the queue for a designated synchronization server.

Servers can be freely filtered and sorted as needed based on the following filters:

  • ID
  • Name
  • Module Name
  • Connection Status

Servers with 'Error' status will not undergo synchronization until the connection data is rectified and the connection is successfully established. The automatic update of connection statuses for synchronization servers will occur as part of daily tasks.

# Synchronizations list

This section lists all synchronizations that have been added to the queue or completed. The table contains relevant information for each synchronization:

  • ID
  • Name - server name for which the synchronization has been performed
  • Module Name - directory service module
  • Synchronization status with a tooltip that appears on hoover:
    • "Started" - logs can be check in the tooltip on hoover
    • "Scheduled" - information on adding the synchronization task to the que ue
    • "Error" - information or the error during synchronization
    • "Success" - information which users have been synchronized
  • Duration - determines how long it took to synchronize
  • Synchronization Date - determines when the synchronization was performed
  • Allowed actions:
    • View detailed logs - open to precisely check which groups and users were synchronized during the synchronization
    • Delete - remove single synchronization
    • Mass delete - press "Shift" on your keyboard and mark selected items, use "With Selected" action button to delete marked items
    • Clear All - remove all synchronization records

Synchronizations can be freely filtered and sorted as needed based on the following filters:

  • ID
  • Server Name
  • Module Name
  • Connection Status

# Users list

This section presents a list of all the users who have been synchronized. The table contains relevant information on each user:

  • ID
  • Users - first and last name, email address, on pressing you will be redirected to the summary page of this user
  • Imported Group - the LDAP group the user has been synchronized from
  • Target Group - the group to which the user has been assigned in EasyDCIM, linked to the editing view of this group in EasyDCIM
  • Server - the synchronization server the user comes from
  • Distinguished Name - the user's entry in the directory (additional column)
  • Account Status Synchronization - shows whether the account status of the user is synchronized with the directory
  • Synchronization Date - date of user synchronization

Users can be freely filtered and sorted as needed based on the following filters:

  • ID
  • Email
  • Imported Group
  • Target Group
  • Account Status Synchronization

To change the account status synchronization for chosen users, mark them and use the "Enable Account Status Synchronization" or "Disable Account Status Synchronization" mass action. Do not enable it for local emergency administrator accounts. The "Clear All" action removes all records from the list.

# Notifications

The extension sends the following notifications to help track activities:

  • LDAP Server Created - sent every time new LDAP server is created in the system
  • LDAP Server Deleted - sent the moment the LDAP server is removed from the system
  • LDAP Server Updated - sent when any of the LDAP servers in the system has been modified
  • LDAP Server Synchronization Started - notification sent to inform that the LDAP server synchronization has started
  • LDAP Server Synchronization Finished - notification sent to inform that the LDAP server synchronization has been completed
  • LDAP Server Synchronization Error - notification sent to inform that the LDAP server synchronization has been interrupted
  • LDAP Login Failed - sent when a directory login attempt fails; includes the username, LDAP server, failure reason, and source IP address

# Object class settings for groups and users

Users and groups are searched in the LDAP directory based on their object classes. You can change the classes for each server in the "User Object Classes" and "Group Object Classes" fields of the server form. Each submodule fills in these fields with its own default classes, which are defined in the files below. The defaults are also used for servers that have no classes saved.

# OpenLDAP

  • Default classes for users:
    /opt/easydcim/modules/addons/LDAPAuthentication/Submodules/OpenLDAP/config/objectClass/users.php
    By default:
    'inetOrgPerson','posixAccount'
  • Default classes for groups:
    /opt/easydcim/modules/addons/LDAPAuthentication/Submodules/OpenLDAP/config/objectClass/groups.php
    By default:
    'posixGroup'

# Active Directory

  • Default classes for users:
    /opt/easydcim/modules/addons/LDAPAuthentication/Submodules/ActiveDirectory/config/objectClass/users.php
    By default:
    'user','person','organizationalPerson'
  • Default classes for groups:
    /opt/easydcim/modules/addons/LDAPAuthentication/Submodules/ActiveDirectory/config/objectClass/groups.php
    By default:
    'group'

# FreeIPA

  • Default classes for users:
    /opt/easydcim/modules/addons/LDAPAuthentication/Submodules/FreeIPA/config/objectClass/users.php
    By default:
    'inetOrgPerson','posixAccount','mepManagedEntry'
  • Default classes for groups:
    /opt/easydcim/modules/addons/LDAPAuthentication/Submodules/FreeIPA/config/objectClass/groups.php
    By default:
    'ipausergroup'