LDAP Configuration and Troubleshooting

This document provides a step-by-step guide for configuring and troubleshooting LDAP integration in ServiceOps. Follow the instructions carefully to ensure a successful setup and to resolve common issues effectively.

Prerequisites

• The ports required are: LDAP - 389 and LDAPS – 636
• To use self-service features, an LDAPS certificate is required
• To implement LDAPS configuration in a high-availability architecture, it must be installed on both machines, i.e., the Master and the Slave.

Configuring LDAP

To configure LDAP, follow the steps below:

1. Navigate to Admin > Users > LDAP Configurations and click the Create LDAP Configurations button. The following popup appears.

2. Enter the required details and click Create. For more details, refer to the ServiceOps Documentation.
3. Once the LDAP server is configured, you can import the users and view the history below. For more details, refer to the Show History section.

4. Next, you can configure the Self-Service Settings for AD users to use features like Reset Password and Unblock Account.

Configuring LDAPS Certificate

For self-service password resets and account unlocks, the tool must communicate with Active Directory to modify user account details. This communication occurs over LDAPS (Lightweight Directory Access Protocol Secure), which ensures that directory information is accessed and updated securely.

An LDAPS (LDAP over SSL/TLS) certificate is essential for,

• Encrypting communication between the AD server and LDAP clients
• Preventing eavesdropping and man-in-the-middle attacks
• Ensuring secure authentication and data transfer when modifying AD accounts

To configure the LDAPS certificate, refer to the Configuring LDAPS Certificate section.

Troubleshooting Steps

LDAP Test Connection Failed

Possible Reasons:

• Incorrect LDAP username and password.
• Incorrect LDAP URL and port.
• Mismatch in the mapping attributes.
• Mismatch in the case sensitivity of attribute names.

Solution:

If the test connection fails, check the following:

1. Username and Password:

• Verify that the correct Active Directory (AD) username and password are entered.
• Verify the credentials. Ensure the username has permission to access the LDAP directory (Example: Administrator User).

2. LDAP URL and Port:

Ensure the correct LDAP server URL and ports are configured

• Syntax for LDAP URL: ldap://<AD_Server_Hostname>:389 Example URL: ldap://ldap.example.com.

• Syntax for LDAPS URL: ldaps://<AD_Server_Hostname>:636 Example URL: ldaps://ldap.example.com

• Common ports:

  • LDAP: 389
  • LDAPS: 636

3. Mapping Attributes:

Confirm that the mapping attributes match the LDAP server properties.

You can find the correct attribute names in Active Directory, as shown in the example below.

Alternatively, right-click on a username, go to Properties > Attribute Editor, and double-click the specific attribute. For example, to view the mail attribute, follow the steps shown below.

a. Ensure all mapping fields (e.g., username, email, etc.) align with the LDAP server's configuration (e.g., sAMAccountName, mail).

b. The attributes are case-sensitive, so please ensure their letter casing matches exactly.

c. Incorrect attributes may result in failed connections or improper data retrieval.

Users Not Imported After Successful Test Connection

Possible Reasons:

• Incorrect Base DN: The specified Base DN may be incorrect or not point to the correct location in the LDAP directory.

• AD Users Are Disabled: If a user is disabled in the Active Directory but still marked as active in ServiceOps, the next sync will block or archive the user, based on the "Block missing users" setting. As a result, the user will not appear as newly imported.

• User Already Exists in Archived List: If a technician or Requester to be imported already exists in the archived list in ServiceOps, or has the same email address (unique identifier) as an archived user, they won't be imported as new. Instead, you need to restore the archived user manually.

Solution: If users are not imported even after a successful connection test:

1. Base DN:

a. Verify that the Base DN is correct. b. Copy the exact Base DN from the LDAP server's properties.

2. User Status:

• Verify whether the users in the LDAP directory are active by checking the "userAccountControl" attribute as shown in the figure below:
  • A value of 512 indicates the user is active.
  • A value of 514 indicates the user is disabled.

• Alternatively, check the user icon. A user icon with a downward arrow indicates that the account is inactive or disabled.

• Only active (enabled) users will be imported into ServiceOps. Disabled users will be skipped during the import process.

3. ServiceOps Requester/Technician:

Ensure the users are not listed in the Archived Requester/Technicians page.

Users of a Group Not Imported

Possible Reasons:

• Incorrect Group Base DN.
• AD users are not members of the Group.
• AD users may be disabled.

Solution:

If users from a specific group of the AD server are not imported:

1. Group Base DN:

a. Make sure the group's Base DN is correctly configured in ServiceOps. To check this, click on the group name, go to Properties > Attribute Editor, and look for the value of the Distinguished Name attribute.

b. Ensure the users you want to import are members of the specified group. You can view the group members by opening the group's Properties and checking the Members tab.

2. User Status in the Group:

a. Check the status of each user in the group. Disabled users are not imported. You can check the status in the following ways:

• Checking the user icon.
• Right-click and check the option Enable/Disable Account.
• View the value of the userAccountControl attribute from the Properties > Attribute Editor tab.

3. Group Filter Configuration:

a. Validate the group filter used in ServiceOps as shown below.

Syntax: (memberOf=CN=GroupName,OU=Groups,DC=example,DC=com)

For example: CN=IT Group,OU=sunil,OU=india,DC=flotomate,DC=local

Imported Users Are Blocked or Archived

Possible Reasons:

• The user may not be part of the Organizational Unit (OU).
• The user is disabled.
• The user has been deleted from the LDAP directory.

Solution:

If users are being blocked or archived after import:

1. User OU:

a. Verify that the user still exists in LDAP's configured Organizational Unit (OU). b. If the users have been moved out of the OU or deleted, they will be blocked or archived in ServiceOps based on the Block missing users field configuration.

General Configuration Checks

1. Server Type:

a. Ensure the correct server type is selected during configuration:

i. Microsoft AD: Select this when integrating with Microsoft Active Directory. Enterprise environments typically use this to manage users and authentication through Microsoft's domain services.

ii. Open LDAP: OpenLDAP is an open-source implementation of the Lightweight Directory Access Protocol (LDAP), a protocol used to access and manage directory information over a network. It is used for authentication and fetching user details from the AD directory. ServiceOps currently handles OpenLDAP integration without pagination support.

2. Connection Logs:

a. Check the logs for specific errors to narrow down issues. For more details, refer to the "Additional Troubleshooting Steps" section below.

Additional Troubleshooting Steps

If you still encounter issues with LDAP configuration or synchronization, follow these steps to analyze the logs:

1. Command-Line Testing

Use ldapsearch to validate the LDAP connectivity.

For example, you can perform an LDAP search in the Microsoft AD server using the following sample command:

ldapsearch -x -H ldap://172.16.12.247:389 \
-D "administrator@flotomate.local" \
-W \
-b "OU=sunil,OU=india,DC=flotomate,DC=local" \
"(objectClass=*)"

Enter the LDAP Password, and the response will appear below.

2. Locate the Logs: You can get the logs from two locations:

a. User Interface: Navigate to Admin > Organization > Application Maintenance > Log Download tab. The following page appears. Here, select the LDAP option and download it.

b. Server-Side:

Open the terminal server and navigate to the ServiceOps logs directory using the path below:

cd /opt/flotomate/main-server/logs/apolo

3. Check LDAP Logs:

a. View the specific LDAP logs to identify errors:

cat ldap.log

4. Analyze Errors:

a. When configuring LDAP (Lightweight Directory Access Protocol), error logs are critical for diagnosing issues. If authentication or directory access fails, check the LDAP server logs for specific error codes or messages that reveal the root cause. The common error codes are:

• 0x525 (1317): User not found.
• 0x52e (1326): Invalid credentials.
• 0x531 (1329): Account disabled.
• 0x532 (1330): Account expired.
• 0x533 (1331): Password expired.
• 0x534 (1332): Account locked out.
• 0x701 (1793): Account restricted (e.g., time-based login restriction).

5. Error Log Analysis:

a. Check the error log for additional details:

cat error.log

6. Error Code Reference:

a. Check the error codes from the logs. The sample error code appears like the screenshot below.

The error codes appearing will mean the following:

• 0x525 (1317): User not found.
• 0x52e (1326): Invalid credentials.
• 0x531 (1329): Account disabled.
• 0x532 (1330): Account expired.
• 0x533 (1331): Password expired.
• 0x534 (1332): Account locked out.
• 0x701 (1793): Account restricted (e.g., time-based login restriction).
• 34: Invalid DN Syntax: The distinguished name (DN) provided is incorrectly formatted.
• 49: Invalid Credentials. Authentication failed due to incorrect username and/or password. [ERROR while LDAP user tries to log in]
• 50: Insufficient Access Rights. The operation failed because the user had no permission to perform it.
• 68: Entry Already Exists. This error is encountered during an add operation when the entry you are trying to import already exists in the directory.
• 81: LDAP Server Down: The LDAP server is unreachable. This could be due to network issues, an offline server, or incorrect server address/port configuration.
• 85: Timeout: The connection attempt to the LDAP server timed out, which might indicate network latency or server performance issues.

7. Service Log Analysis:

Service logs record events and activities of the ServiceOps application, helping with troubleshooting, monitoring, and auditing system behavior. They are essential for identifying issues and ensuring smooth operation.

1. Test LDAP Connection (Success Check)

To verify if the "Test Connection" to the LDAP server was successful, analyze the service log using the following command:

cat service.log | grep "[POST /test/ldapconfiguration]"

This will show logs related to test connection attempts, including success or failure responses.

2. Import LDAP Users

To review logs related to importing users from a specific LDAP configuration, use:

cat service.log | grep "[GET /ldapconfiguration/<ID>/import]"

Replace {ID} with the actual LDAP configuration ID. This helps identify whether the import process was triggered, completed, or failed.

3. Logs for Blocked LDAP Users

To investigate issues related to blocked users during the LDAP import process, search the service log, which is shown below.

note

Specific log patterns for blocked users can vary—look for error messages or status codes in the import logs above.

Additional Notes

• Ensure the LDAP server and ServiceOps remain in sync to avoid user access or data issues.
• To avoid issues, changes in LDAP server properties such as Base DN, mapping attributes, or OU structure should be updated in ServiceOps.
• Check user accounts regularly and ensure disabled users are handled properly, based on your company's rules.

By following this procedure, your team can configure LDAP effectively and easily resolve common issues.