Active Directory LDAP

Active Directory is a directory server that uses LDAP - Lightweight Directory Access Protocol. The Active Directory LDAP plugin allows you to query and modify items in your Active Directory. Additionally, the plugin enables you to manage user accounts and AD objects, perform and force password resets. Moreover, you can run custom LDAP queries against your Active Directory to retrieve the information you need.

Configure Active Directory LDAP Connection in InsightConnect

The Active Directory LDAP plugin requires the following:

• A domain username and password
• The fully qualified hostname or IP address of an Active Directory Domain Controller
• The port (389 or 636) for LDAP or LDAPS (default is LDAP/port 389)

Once you obtain the above information follow these steps:

1. In InsightConnect, open the connection configuration for the Active Directory LDAP plugin.

   • You can do this when selecting the Active Directory LDAP plugin during a workflow building session or by creating the connection independently by choosing Plugins & Tools from the Settings tab on the left menu. On the Plugins & Tools page, select the Connections tab and click Add Connection in the upper-right corner.

2. Configure the connection for the Active Directory LDAP plugin:

   • Give the connection a unique and identifiable name, select where the plugin should run, and choose the Active Directory LDAP plugin from the list. If it’s not available, then import the plugin from the Installed Plugins tab.

3. Configure your Active Directory LDAP credentials and connection details:

   • In the Credentials field, select existing Active Directory LDAP credentials or enter a new username and password.
   • In the Host field enter the fully qualified hostname or IP address for your AD domain controller (if you have multiple domain controllers, any one that your Orchestrator can communicate with will do).
   • In the Port field, enter the port number that your LDAP server is using. The default port is 389 for AD LDAP connections. If you have enabled LDAPS on your domain controller, then the port should be changed to 636 (if you're unsure, try 389 first and be sure to check your connection test after saving!)
   • Set SSL field to false for LDAP connections over port 389. Set SSL to true for LDAPS connections over port 636 (please note that you will be unable to reset user password with SSL set to false)
   • In most cases, Chase Referrals should be set to true to ensure LDAP requests are completed. An LDAP Referral provides a reference to an alternate location in which an LDAP Request may be processed. In a partitioned directory, by definition, the entire directory is not always available on any Directory Service Agent. Setting this value to true ensures your request will be routed to an Active Directory server that can process it.
   • Click Save and check if the connection succeeded.

Test Your Connection

When you save the connection, the connection test will attempt to authenticate to your Active Directory LDAP server. A blue circle on the Connection tile indicates that the Connection test is in progress.

Successful Connection Tests

If there is no circle, the connection succeeded, and you're ready to begin orchestrating your processes with Active Directory LDAP.

Failed Connection Tests

A red circle indicates that the connection test failed. If this occurs, check your connection details (including the username and password, host address, port, ssl and chase referrals) before trying again.

The log may contain useful troubleshooting information. First, click View to see a list of your recent connection tests.

Under the Test Status tab, expand the dropdown for the test that encountered an error to view its log.

Troubleshooting

Issues with Active Directory LDAP connections are typically related to either networking issues, where your Orchestrator cannot communicate with the domain controller, or credential issues, where the provided username and password fail to authenticate to the specified domain controller. Some common error messages and associated troubleshooting recommendations are below.

Invalid Server Address

You might receive the below error message when the plugin cannot communicate with the specified host. Confirm you have the correct hostname or IP address in the connection configuration. Additionally, you can try using the IP address of the server instead of the FQDN name - this will rule out any DNS resolution issues. If the issue persists, it is likely your Orchestrator cannot contact the specified domain controller host due to a networking issue. Consult your network administrator for help.

text
1
The service this plugin is designed for is currently unavailable. Try again later.
2
If the issue persists, please contact support.
3
Response was: invalid server address
4

Connection Reset by Peer

You might receive the below error message when the port and SSL settings in your connection are misaligned. Be sure to use port 389 (LDAP) with SSL set to false and port 636 (LDAPS) with SSL set to true.

text
1
The service this plugin is designed for is currently unavailable. Try again later.
2
If the issue persists, please contact support.
3
Response was: socket ssl wrapping error: [Errno 104] Connection reset by peer
4

Invalid Credentials

You might receive the below error message when the plugin cannot authenticate to the domain controller with the provided username and password. Edit the credential and update the username and/or password, then retry your connection test.

text
1
Invalid username or password provided. Verify your username and password are correct.
2
Response was: automatic bind not successful - invalidCredentials
3

Best Practices

The plugin is an interface to your Active Directory server meaning that it will work best if you follow the Active Directory best practices.

Active Directory User Management

One of the best practices for the adding new users is to create an organizational unit and put users in there, rather than using the default Users folder. Please note that this plugin will not work with objects that are contained in the default users container.

Plugin Permissions

It is recommended to use the least privileged access control - not all the actions available in the plugin require Domain Administrator permissions. If you wish to restrict the permissions on your account, please review the table below which lists available actions within the plugin and the permissions needed to perform them. Please note that the permissions might differ depending on how your Active Directory instance is configured - we use the default Security Groups to show the permissions required.

Multi Domain Environment

In case if you are working with a multi domain environment, please set the Chase Referrals connection input as true. An LDAP Referral provides a reference to an alternate location in which an LDAP Request may be processed. This will enable the plugin to follow the referrals from one Active Directory server to another one that can process the request.

LDAP Sample Queries

Please see below table with some popular LDAP query examples for Active Directory LDAP Query Action:

• Return all the attributes of the users from a specific organizational unit (OU):

  json
  1
    {
  2
      "attributes": [
  3
        "*"
  4
      ],
  5
      "search_base": "OU=exampleOu,DC=exampleDomain,DC=com",
  6
      "search_filter": "(&(objectClass=user)(objectCategory=Person))"
  7
    }
  8
  
  

• Return email addresses attribute of the users reporting to a given manager in a given domain:

  json
  1
    {
  2
      "attributes": [
  3
        "mail"
  4
      ],
  5
      "search_base": "DC=exampleDomain,DC=com",
  6
      "search_filter": "(&(objectClass=user)(objectCategory=Person)(manager=CN=Example Name,OU=ExampleOU,DC=exampleDomain,DC=com))"
  7
    }
  8
  
  

• Return sAMAccountName attribute for all the users in a given domain:

  json
  1
    {
  2
      "attributes": [
  3
        "sAMAccountName"
  4
      ],
  5
      "search_base": "DC=exampleDomain,DC=com",
  6
      "search_filter": "(&(objectClass=user)(objectCategory=Person))"
  7
    }
  8
  
  

• Return email address for a given user's name:

  json
  1
    {
  2
      "attributes": [
  3
        "mail"
  4
      ],
  5
      "search_base": "DC=exampleDomain,DC=com",
  6
      "search_filter": "(&(objectClass=user)(objectCategory=Person)(name=Example Name))"
  7
    }
  8
  
  

• Return username for a user with a given email address:

  json
  1
    {
  2
      "attributes": [
  3
        "sAMAccountName"
  4
      ],
  5
      "search_base": "DC=exampleDomain,DC=com",
  6
      "search_filter": "(&(objectClass=user)(objectCategory=Person)(mail=user@example.com))"
  7
    }
  8
  
  

Below, you can find some additional useful queries for the Search Filter input:

In addition to using the above filters, you can utilize the following inputs for the Query plugin:

• Search Base - to limit down the results to a specific organizational unit or to search an entire domain by providing - provide a distinguished name of whichever object you wish to query against
• Attributes - to filter the attributes returned by LDAP query

References

• LDAP
• Microsoft Active Directory
• LDAP Filter Syntax