This article explains how to configure Lightweight Directory Access Protocol (LDAP) authentication in OrangeHRM Starter. We go through the fundamentals, advanced concepts, and some troubleshooting parts to help the user enable and manage LDAP in OrangeHRM.
Before activating the LDAP service, make sure that all LDAP settings are functioning properly
Step 01: Enabling LDAP Authentication
To enable LDAP, go to Admin - Configurations - LDAP Configuration and enable the toggle button located in the top right of the page.
Step 02: LDAP Server Setting
Next, update your LDAP server settings to set up the connection to your LDAP server. You will need to provide the following information.
Name (or IP address in dotted format) of the LDAP server. For example: localhost or 192.168.1.100
Port number of the LDAP server. This field accepts any number between 0 to 65535 as valid port numbers.
If no custom port is specified, use either 389 as the standard port for TLS or use 636 for SSL as default values
Choose TLS or SSL if enabled in your LDAP server.
When ldap:// is specified, standard LDAP is used to connect to the LDAP servers over TLS. When ldaps:// is set, LDAP over SSL is used to connect to the LDAP server.
Apart from open LDAP, OrangeHRM supports MS Active Directory.
Select either Open LDAP v3 or MS Active Directory based on the platform used to run your LDAP server.
Step 03: Choose your Bind Settings
Binding is the step where the LDAP server authenticates the user and, if the user is successfully authenticated, allows the user access to the LDAP server based on that user's privileges.
You can set this to “Bind Anonymously” by enabling the toggle switch. Anonymous binding allows a client to connect and search the directory (bind and search) without logging in because a distinguished name and password are not needed.
If you disable “Bind Anonymously”, then you need to provide a distinguished username and password to authenticate the user to LDAP. Ensure the user has permission to search the entire directory to import all users to OrangeHRM.
Step 04: User lookup Settings
You can define the users and groups lookup information under these configurations.
Base Distinguished Name
Base Distinguished Name is the starting point an LDAP server uses when searching for users authentication within your Directory.
For example, if you specify a base distinguished name of ou=users,dc=orangehrm, the LDAP search operation initiated examines only the OU=users subtree in the dc=orangehrm directory tree.
Specifying a subtree as the base entry limits the set of eligible users and groups. A limited set of users and groups can improve performance of LDAP searches by reducing the amount of LDAP data to be searched. LDAP searches that run more efficiently help improve OrangeHRM login.
Subtree option will allow searching base directory and subdirectories. One level will only search within the base directory
If you have any sub-organizational units (subcontexts) hanging from ou=users,dc=orangehrm and you want OrangeHRM to search there too, set this to Subtree. Otherwise, set this to One level.
LDAP Attribute field to use when loading the username. Ex: cn, SMA account name. The value of this attribute will be used in the OrangeHRM Login page Username field to login to OrangeHRM.
User Search Filter
Your search scope can contain a substantial number of files that may not be relevant when creating OrangeHRM user credentials. You can further narrow down your search by being more specific about your query.
For example, set this field as “objectClass=person” to if you want to filter for objects with “person” object class in your search
User Unique ID attribute
The attribute used to identify user objects in an immutable manner. This is optional and is used to monitor username changes. User renames won't be recognized if this property is not set (or if it is set to an erroneous value), in which case OrangeHRM application will be treated as first a user deletion and then an addition of a new user.
This setting exists because User Unique ID is known under different names on some servers.
Ex: entryUUID, objectGUID
Step 05: Data Mapping
When LDAP user data is synchronized with OrangeHRM, LDAP user attributes should be matched with the relevant OrangeHRM employee fields. In this part, you may provide the data mapping as needed.
By providing the name of the related LDAP property name in the appropriate textbox, the following OrangeHRM fields can be mapped to LDAP user attributes.
- First Name
- Middle Name
- Last Name
- User Status
- Work Email
- Employee ID
Step 06: Additional Settings
By enabling the given toggle switch, you may choose to merge the LDAP credentials with existing user accounts. When the option is turned off, user account creation is skipped without merging with existing ones in OrangeHRM.
This merge users switch may be beneficial for systems that used the LDAP add-on in OrangeHRM 4.x versions.
Next, the sync interval time can then be set. Enter your preferred sync interval time in hours in the provided field. If you enter X as your preferred sync interval time, OrangeHRM will connect to your LDAP server once every X hours behind the screens. This guarantees that LDAP-stored user credentials are correctly synchronized with OrangeHRM.
If you want to restrict user access through LDAP, you may make the change from LDAP, and OrangeHRM will be informed of the change during the subsequent sync run. After that, the user's LDAP credentials will no longer work to access OrangeHRM.
Step 07: Test Connection
You must save your LDAP configurations on this page for synchronization to take place, and then test the connection to make sure the connection was formed successfully.
If the connection is successful, you will be provided with a confirmation message as below with all indicators showing green.
If the test connection status shows any red indicator, revisit your LDAP configurations and network connection to rectify the errors indicated.
Manually triggering a sync with the LDAP server
Once the connection with your LDAP server is established, OrangeHRM facilitates manual triggering of a synchronization flow via “Sync Connection”. Sync Connection shows the most recent successful synchronization or whether the most recent synchronization has failed. Clicking "Sync Now" will start a sync immediately, bypassing the need to wait for the next scheduled run.
Changing OrangeHRM password of users imported from LDAP
If the ESS user account is synchronized with the LDAP server, ESS users are not permitted to change their passwords via Forgot password or Change password screens.
The passwords of these user accounts can be changed by admin users. However, doing so will override the user's LDAP password and force them to input the updated OrangeHRM password whenever they wish to login to OrangeHRM.
Importing LDAP Credentials for existing users
If you intend to give them access via LDAP, it is recommended that you delete the current user accounts in OrangeHRM. Current users cannot access OrangeHRM using their LDAP credentials since syncing over existing users will not override user credentials created by OrangeHRM.