# 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
- 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
- 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 - connect using LDAPS.
- StartTLS - upgrade the LDAP connection to TLS.
- Validate Certificate - validate the TLS certificate presented by the directory server. 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. The password is verified by an LDAP bind and is not stored in EasyDCIM.
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 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 checkbox (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:
- Yes - a password of 16 characters will always be generated for newly imported users. Such password will also be generated for existing users who do not have a password yet. Each time a password is updated, an email will be sent to the user informing them of the change.
- No - a password of 16 characters will always be generated for newly imported users. Each time a password is updated, an email will be sent to the user informing them of the password change.
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.
- 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
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
- Username - first and last name, email address, on pressing you will be redirected to the summary page of this user
- LDAP group - the group the use has been synchronized from
- EasyDCIm group - the group to which the user has been assigned in EasyDCIM, linked to the editing view of this group in EasyDCIM
- Date of user synchronization
Users can be freely filtered and sorted as needed based on the following filters:
- ID
- LDAP Group
- EasyDCIM Group
- Email Address
# 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 certain attributes. Each submodule has a different set of default classes, which can be freely modified as needed. Below you will instructions on how to do this:
# OpenLDAP
- Changing classes for users:
by adding or changing the set of attributes that are used when searching for users. By default:/opt/easydcim/modules/addons/LDAPAuthentication/Submodules/OpenLDAP/config/objectClass/users.php'inetOrgPerson','posixAccount' - Changing classes for groups:
by adding or changing the set of attributes that are used when searching for groups. By default:/opt/easydcim/modules/addons/LDAPAuthentication/Submodules/OpenLDAP/config/objectClass/groups.php'posixGroup'
# Active Directory
- Changing classes for users:
by adding or changing the set of attributes that are used when searching for users. By default:/opt/easydcim/modules/addons/LDAPAuthentication/Submodules/ActiveDirectory/config/objectClass/groups.php'user','person','organizationalPerson' - Changing classes for groups:
by adding or changing the set of attributes that are used when searching for groups. By default:/opt/easydcim/modules/addons/LDAPAuthentication/Submodules/OpenLDAP/config/objectClass/groups.php'group'
# FreeIPA
- Changing classes for users:
by adding or changing the set of attributes that are used when searching for users. By default:/opt/easydcim/modules/addons/LDAPAuthentication/Submodules/FreeIPA/config/objectClass/users.php'inetOrgPerson','posixAccount','mepManagedEntry' - Changing classes for groups:
by adding or changing the set of attributes that are used when searching for groups. By default:/opt/easydcim/modules/addons/LDAPAuthentication/Submodules/FreeIPA/config/objectClass/groups.php'ipausergroup'