LDAP commands – reading and changing a directory

The LDAP commands read and change objects in an LDAP directory, usually Microsoft Active Directory: they create users and groups, manage group memberships, set attributes and search the directory. This page describes all twelve commands. It is for administrators who automate user administration or read directory data into nexxcite.

---

1. At a glance

All commands are in the toolbar menu "LDAP". None of them needs a user interface.

Command	What it does	Answer in "Response Variable"
"LDAP Add Group"	Creates a group	true / false
"LDAP Add User To Group"	Adds a user to a group	true / false
"LDAP Add User With Password"	Creates a user with an initial password	true / false
"LDAP Clear Attribute"	Removes all values of an attribute	true / false
"LDAP Does Object Exist"	Checks whether an object exists	true / false
"LDAP Find Objects"	Searches the directory	JSON array of objects
"LDAP Get Attribute"	Reads the values of one attribute	JSON array of texts
"LDAP Move User"	Moves a user to another container	true / false
"LDAP Remove Object"	Deletes an object	true / false
"LDAP Remove User From Group"	Removes a user from a group	true / false
"LDAP Reset User Password"	Sets a new password	true / false
"LDAP Set Attribute"	Replaces the values of an attribute with one value	true / false

Summary

• Every command works with an "LDAP Credentials" definition: server, port, sign-in method and the account nexxcite uses (see API access and credentials).
• Objects are addressed by their full distinguished name (DN), for example CN=Jane Doe,OU=Staff,DC=example,DC=com – not by the login name.
• A failure does not stop the action. It sets "Has Error Variable" to true. Check it.
• Everything happens with the rights of the account in the credentials. Give that account only the rights in the directory that the actions need.

---

2. Common settings

"Display Name", "Description" and "Execution Condition" are on the tab "General" (see Actions), together with the settings of the command. All settings except the credentials and the variables are expressions.

Setting	Tab	Meaning	Default / Required
"LDAP Credentials"	General	The LDAP credentials; only credentials of the kind "LDAP Credentials" are offered	Required
"Response Variable"	Response	Receives the answer (see the table above)	Optional – without it, the answer of reading commands is lost
"Has Error Variable"	Response	true when the command could not run or the directory refused the operation, otherwise false	Optional

The LDAP credentials

Field	Used for
"Server"	Name or address of the directory server. Required.
"Port"	Port of the server. Empty or 0: the default port.
"Authentication Type"	"None" (anonymous), "Basic" (simple bind), "Secure" (Windows sign-in, Negotiate), "SSL" (simple bind over an encrypted LDAPS connection)
"Domain", "Username", "Password"	The account nexxcite signs in with. With a domain, the sign-in name is DOMAIN\Username.
"Start Path"	Not used by the LDAP commands – they always need full DNs

With "Basic", the password of the account travels unencrypted. Use "SSL" wherever the directory offers LDAPS.

---

3. Common behaviour

1. If the credentials are not set or no longer exist, the command is skipped and "Has Error Variable" is set to true.
2. Every command opens its own connection, signs in, carries out the operation and closes the connection.
3. On success, "Response Variable" receives the answer and "Has Error Variable" false.
4. If the connection, the sign-in or the operation fails – the object does not exist, the account has no right, the value violates a rule of the directory – "Response Variable" receives false (reading commands: []) and "Has Error Variable" true. The reason is written to the log.
5. The action continues in every case.

The answers are the texts true and false. Use "Has Error Variable" to tell a failure from a false answer of "LDAP Does Object Exist" or from an empty search result.

---

4. The commands

LDAP Add Group

Creates a group at CN=<Group Name>,<Parent DN>.

Setting	Meaning
"Parent DN"	DN of the container or OU, for example OU=Groups,DC=example,DC=com
"Group Name"	Name of the group; used as cn and as sAMAccountName

The group is created with the object class group and no further attributes. The directory decides the group type (in Active Directory by default a global security group).

LDAP Add User To Group

Adds the user to the member attribute of the group.

Setting	Meaning
"User DN"	Full DN of the user, for example CN=Jane Doe,OU=Staff,DC=example,DC=com
"Group DN"	Full DN of the group, for example CN=Sales,OU=Groups,DC=example,DC=com

Active Directory refuses to add a user who is already a member. The answer is then false and "Has Error Variable" is true – check membership first if that case is expected.

LDAP Add User With Password

Creates a user at CN=<User Name>,<Parent DN> and sets the initial password.

Setting	Meaning
"Parent DN"	DN of the container or OU, for example OU=Staff,DC=example,DC=com
"User Name"	Name of the user; used as cn and as sAMAccountName (the login name)
"Password"	The initial password; it must satisfy the password policy of the directory

The user is created with the object class user as a normal account that requires a password. It is enabled only after the initial password has been set. Further attributes – first name, last name, user principal name, mail – are set with "LDAP Set Attribute" afterwards.

Active Directory accepts a password only over an encrypted connection (Authentication Type "SSL"). Otherwise the user can be created while setting the password fails – the answer is then false, and the account exists but stays disabled.

LDAP Clear Attribute

Removes all values of an attribute.

Setting	Meaning
"Object DN"	Full DN of the object
"Attribute Name"	LDAP name of the attribute, for example telephoneNumber

LDAP Does Object Exist

Checks whether an object exists.

Setting	Meaning
"Object DN"	Full DN to look for

The answer is true or false. If the object does not exist, the answer is false and "Has Error Variable" is false; if the check itself failed, the answer is false and "Has Error Variable" is true.

LDAP Find Objects

Searches the subtree below a search base.

Setting	Meaning
"Search Base"	DN where the search starts, for example DC=example,DC=com
"LDAP Filter"	LDAP filter, for example (&(objectClass=user)(sAMAccountName=jdoe))
"Attributes"	Attribute names separated by commas, for example mail, displayName, memberOf. Empty: all attributes.

The answer is a JSON array with one object per result:

[
  {
    "distinguishedName": "CN=Jane Doe,OU=Staff,DC=example,DC=com",
    "attributes": {
      "mail": [ "jane.doe@example.com" ],
      "memberOf": [ "CN=Sales,OU=Groups,DC=example,DC=com" ]
    }
  }
]

Every attribute holds an array of texts, even if it has only one value. Use Iterate JSON to process the results and value modification rules to read values.

Escape values that come from users before you put them into the filter (*, (, ), \). nexxcite does not do this for you.

LDAP Get Attribute

Reads one attribute of one object.

Setting	Meaning
"Object DN"	Full DN of the object
"Attribute Name"	LDAP name of the attribute, for example mail or memberOf

The answer is a JSON array of texts, for example ["jane.doe@example.com"]. It is empty when the attribute has no value.

LDAP Move User

Moves a user into another container and keeps its name.

Setting	Meaning
"User DN"	Full DN of the user
"New Parent DN"	DN of the target container or OU, for example OU=Former,DC=example,DC=com

LDAP Remove Object

Deletes an object from the directory.

Setting	Meaning
"Object DN"	Full DN of the object to delete

The deletion cannot be undone from nexxcite. Containers that still contain objects cannot be deleted with this command.

LDAP Remove User From Group

Removes the user from the member attribute of the group.

Setting	Meaning
"User DN"	Full DN of the user
"Group DN"	Full DN of the group

LDAP Reset User Password

Sets a new password for a user.

Setting	Meaning
"User DN"	Full DN of the user
"New Password"	The new password; it must satisfy the password policy

As with creating a user, Active Directory accepts a password only over an encrypted connection (Authentication Type "SSL"). The command does not set "User must change password at next logon".

LDAP Set Attribute

Replaces all values of an attribute with one value.

Setting	Meaning
"Object DN"	Full DN of the object
"Attribute Name"	LDAP name of the attribute, for example telephoneNumber or description
"Value"	The new value, as text

To empty an attribute, use "LDAP Clear Attribute".

---

5. Examples

Create a user for a new employee and add it to a group.

1. "LDAP Add User With Password" with "Parent DN" OU=Staff,DC=example,DC=com, "User Name" = the login name field of the employee record, "Password" = a generated initial password; "Response Variable" UserCreated.
2. "LDAP Set Attribute" three times: givenName, sn and mail on CN= + login name + ,OU=Staff,DC=example,DC=com.
3. "LDAP Add User To Group" with "Group DN" CN=Sales,OU=Groups,DC=example,DC=com.

Give steps 2 and 3 the "Execution Condition" UserCreated = true.

Read the mail address of a user by login name. "LDAP Find Objects" with "Search Base" DC=example,DC=com, "LDAP Filter" (&(objectClass=user)(sAMAccountName=jdoe)), "Attributes" mail. A Modify Value expression with the rules JArrayFirstElement and JObjectJsonPathValue (path attributes.mail[0]) reads the address.

---

6. Limitations

• Objects are addressed by DN only; there is no lookup by login name except through "LDAP Find Objects".
• "LDAP Find Objects" reads the results in one request without paging. Directories limit the number of results per request (Active Directory: 1000 by default); in our assessment a search beyond that limit fails.
• Values are read and written as text. Binary attributes such as objectGUID or thumbnailPhoto are not returned in a usable form.
• "LDAP Set Attribute" writes exactly one value; attributes with several values can only be replaced as a whole.
• Passwords in actions are expressions and are stored readable in the definition or in the global value they come from (see API access and credentials).
• The LDAP credentials are not used for signing in to nexxcite (see Authentication providers).

---

7. Related pages

• Actions and Variables
• API access and credentials
• Iterate JSON
• Value modification rules