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.

Complete list of Active Directory LDAP Plugin Actions

To see all available actions with the Active Directory LDAP plugin, see the Documentation tab of the Extension Library.

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)

User Account Privileges and Logging

Remember your InsightConnect connection to Active Directory LDAP will inherit all privileges of the domain user account configured in the connection. Use of the least privilege model is recommended. All actions taken by this account will be logged according to your logging configuration in Active Directory.

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.

Add connection in InsightConnect

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

    • Give the connection a unique and identifiable name, select the orchestrator the plugin should run on, and choose the Active Directory LDAP plugin from the list. If it’s not available, then import the plugin from the Installed Plugins tab.
  2. 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.

Active Directory LDAP Connection

Success!

The AD LDAP plugin is ready to use.

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.

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.

Success

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.

Failed

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

View Recent Connection Test

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

View Connection 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 your Orchestrator 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 your Orchestrator 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.

Action NamePermissions Required
Add UserDomain Admins
DeleteDomain Admins
Disable UserDomain Admins
Enable UserDomain Admins
Force Password ResetDomain Admins
Modify GroupsDomain Admins
Add or Remove an Object from GroupDomain Admins
Move ObjectDomain Admins
QueryDomain Users
Query Group MembershipDomain Users
Reset PasswordDomain Admins
Unlock UserDomain Admins

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:

LDAP Query ExampleUse Case
(&(objectClass=user)(objectCategory=Person))Returns administrators in groups Domain Admins and Enterprise Admins
(&(objectClass=user)(objectCategory=Person)(adminCount=1))Returns administrators in groups Domain Admins and Enterprise Admins
(&(objectCategory=person)(objectClass=user)(|(accountExpires=0)(accountExpires=9223372036854775807)))Returns users with accounts that do not expire
(&(objectCategory=group)(!groupType:1.2.840.113556.1.4.803:=2147483648))Returns all distribution groups
(&(objectCategory=group)(samaccountname=*CISO*))Returns all groups with the CISO key in the group name
(&(objectCategory=group)(!member=*))Returns all empty AD groups
((objectClass=user)(objectCategory=Person)(whenCreated>=20200101000000.0Z&<=20201201000000.0Z&))Returns all users created for the specified period
(&(objectClass=computer)(userAccountControl:1.2.840.113556.1.4.803:=2))Returns all disabled computer accounts in AD
(&(objectCategory=group)(member=CN=Example Name,OU=exampleOu,DC=exampleDomain,DC=com))Returns the groups the user is a member of
((objectClass=user)(objectCategory=Person)(MemberOf=CN=groupName,OU=exampleOu,OU=exampleOu,DC=exampleDomain,DC=com))Returns users with membership in a specific Active Directory group
(&(objectCategory=person)(objectClass=user)(!useraccountcontrol:1.2.840.113556.1.4.803:=65536))Returns users with the “Password never expires option” enabled

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