Microsoft Active Directory connector

The Microsoft Active Directory connector provides the ability to perform specific operations for users, groups, and computers in Microsoft Active Directory via the LDAP protocol.

The Active Directory connector supports only process workflow capability, and does not support catalog import and resource mapping operations.

External account requirements

You must have an Active Directory user account with sufficient permissions to perform read and write operations into the Active Directory server.

Configuration parameters for the Active Directory connector

Before you can use the Active Directory connector in workflows, you must configure a connection for Active Directory connector, as described in Configuring-service-connectors. The following table describes the parameters required to create a connection:

Parameter	Examples	Description
AD Host	adhost.server-1.com	Active Directory server host name
AD Port	389	Active Directory server LDAP port 389 is the default port.
Search Base	dc=adhost,dc=server-1,dc=com	Base directory for search operations
User Domain	server-1.com	Authentication domain
User Name	sbadmin	Authentication user
Password	sbP@ssw0rd	Password of authentication user
Certificate path	/etc/bmc/ARSystem/LDAPS.cert	The path of the SSL certificate. It is required only if SSL is used between the Active Directory server and the BMC Helix Digital Workplace Catalog server. Note: The certificate must be located inside the Docker container.

Active Directory actions overview

The following table provides an overview of all Active Directory connector actions:

Action category	Action	Description	Input parameters	Possible output
User	Add Active Directory User To Group	Adds a user to a group in Active Directory. When a user is added to a group, the following changes are made to Active Directory: A user profile is updated with a new memberOf attribute record that corresponds to the distinguishedName value of the group to which the user was added. A group profile is updated with a new member attribute record that corresponds to the distinguishedName value of the user added to the group.	Add Active Directory User To Group input parameters	No output An exception
	Remove Active Directory User From Group	Removes a user from a group in Active Directory. A user record and a group record are updated when an association is removed.	Remove Active Directory User From Group input parameters	No output An exception
	Find Active Directory User	Finds a user in Active Directory, and returns the user parameters. This action searches for the first filtering parameter in the following sequence: Logon Name Distinguished Name Full Name Email The returned object contains output properties that can be used in later workflow steps. If a search is performed without filtering parameters, the search will be performed only for the object type: User. If more than one user is found, an error is displayed.	Find Active Directory User and Find Active Directory Group input parameters	Find Active Directory User output parameters NULL
	Update User Attributes	Updates attributes for a user record in Active Directory. For details about how to build a workflow with this action, see an example workflow for updating user attributes.	Update User Attributes input parameters	No output An exception
	Find Active Directory Group	Returns the group if the group exists; otherwise, an error occurs.	Find Active Directory Group input parameters	No output An exception
	User is member of Group	Returns True if the user is a member of the group.		True False
Computer	Add Computer To Group	Adds a computer to a group in Active Directory. A computer record and a group record are updated when an association is created. When a computer is added to a group, the following changes are made to Active Directory: A computer profile is updated with a new memberOf attribute record that corresponds to the distinguishedName value of the group to which the computer was added. A group profile is updated with a new member attribute record that corresponds to the distinguishedName value of the computer added to the group.	Add User To Computer input parameters	No output An exception
	Computer Is Member of Group	Checks whether a computer belongs to a group.	Computer Is Member of Group input parameters	TRUE FALSE
	Find Computer	Finds a computer in Active Directory, and returns the computer details. The returned object contains output properties that can be used in later workflow steps.	Find Computer input parameters	Find Computer output parameters NULL
	Remove Computer From Group	Removes a computer from a group in Active Directory. A computer record and a group record are updated when an association is removed.	Remove Computer From Group input parameters	No output An exception
	Update Computer Attributes	Updates attributes to a computer record in Active Directory. This is very similar to the Update User Attributes action. For details about how to build a workflow with this action, see an example workflow for updating user attributes.	Update Computer Attributes input parameters	No output An exception

Tip

For all actions that return exceptions in case of a negative scenario (incorrect input), the workflow is interrupted, and a corresponding service request is failed with an error. You can catch these exceptions by using a Boundary Error, and handle them as you need by building alternative paths for your processes. For more details about error handling, see Handling-errors-in-processes.

For all actions that return NULL, TRUE, or FALSE, you can use an Exclusive gateway to define the alternative paths for your process. For more details, see example of error handling for Find AD user operation.

Example 1: Workflow for a service that returns a result of the Find Active Directory User operation

The following workflow shows how to configure error handling for a use case when no user is returned as a result of search.

If the queried user is not found, the service request is closed with a message configured in the Error End event:

The catalog administrator receives an in-app notification, whether the operation failed or succeeded. The Exclusive gateway configures this notification along with the corresponding messages in the Send In App Notification actions:

InAppNotification19.11.png

Click here to view JSON of this workflow

Failed to execute the [code] macro.

For configuration details about this service, save the attached Find AD user.zip, and import it to your environment.

Example 2: Workflow for a service that updates an attribute of a user

The following workflow example shows how to build a workflow that will update a user attribute in Active Directory:

In this workflow example, the Build Input Set action creates an input parameter mapped to a process input value. An output from this action is sent to the Update Entry Attributes action. The Send In App Notification action is configured to send a notification to the catalog administrator about success of the update operation.

For configuration details about this service, save the attached Update_attribute.zip, and import it to your environment.

Input and output parameters for actions

The tables in this section describe each workflow action and its significant parameters.

Input parameters for Add Active Directory User To Group and Remove Active Directory User From Group actions

Both of these actions have the same input parameters described in the following table:

Required	Parameter name	Data type	Example	Description
Required	Connection Id	String	Connection > Connection ID	Default Connection ID for this connector.
Required	Logon Name	String	"bob_manager"	sAMAccountName attribute of a user to be added or removed from a group.
Required	Group Name	String	"Domain Computers"	CN attribute of a group to be added to the user profile.

Find Active Directory User input parameters

Required	Parameter name	Data type	Example	Description
Required	Connection ID	String	Connection > Connection ID	Default Connection ID for this connector.
At least one of these parameters must be specified	Logon Name	String	"bob_manager"	sAMAccountName attribute of a queried user.
	Distinguished Name	String	"CN=Bobbi Baxter,CN=Users,DC=ADServer,DC=local"	distinguishedName attribute of a queried user.
	Full Name	String	"Bobbi Baxter"	cn attribute of a queried user.
	Email	String	"bob@calbroservices.com"	mail attribute of a queried user.

Find Active Directory User output parameters

Parameter name	Data type	Example
Attrs	Map	<Map of multiple values with keys of string type and values of string type>
Distinguished Name	String	CN=Bobbi Baxter,CN=Users,DC=ADServer,DC=local
Email	String	bob@calbroservices.com
Enabled	Boolean	1
Full Name	String	Bobbi Baxter
Logon Name	String	bob_manager

Update User Attributes input parameters

Required	Parameter name	Data type	Example	Description
Required	Connection Id	String	Connection > Connection ID	Default Connection ID for this connector.
Required	Attributes Input Set	String	Build Input Set > Inputs	Use the output from the Build Input Set. In the Build Input Set, you must create key and value pairs that you want to update as a part of this action.
Optional	Distinguished Name	String	"CN=Bobbi Baxter,CN=Users,DC=ADServer,DC=local"	distinguishedName attribute of a queried user.
Optional	Logon Name	String	"bob_manager"	sAMAccountName attribute of a queried user.
Optional	Full Name	String	"Bobbi Baxter"	cn attribute of a queried user.
Optional	Email	String	"bob@calbroservices.com"	mail attribute of a queried user.

Find Active Directory Group input parameters

Required	Parameter name	Data type	Example	Description
Required	Connection ID	String	Connection > Connection ID	Default Connection ID for this connector.
At least one of these parameters must be specified	Samaccount Name	String	"support_group"	sAMAccountName attribute of a queried group.
At least one of these parameters must be specified	Group Name	String	"Support"	groupName attribute of a queried group.

Input parameters for Add Computer To Group, Remove Computer From Group, and Computer Is Member Of Group actions

All of these actions have the same input parameters described in the following table:

Required	Parameter name	Data type	Example	Description
Required	Connection Id	String	Connection > Connection ID	Default Connection ID for this connector.
Required	Samaccount Name	String	"IgorPC"	sAMAccountName attribute of an Active Directory computer.
Required	Group Name	String	"Domain Computers"	cn attribute of Active Directory group to assign the computer.

Find Computer input parameters

Required	Parameter name	Data type	Example	Description
Required	Connection Id	String	Connection > Connection ID	Default Connection ID for this connector.
At least one of these parameters must be specified	Samaccount Name	String	"IgorPC"	sAMAccountName attribute of Active Directory computer.
	Distinguished Name	String	"CN=IgorPC,CN=Computers,DC=ADServer,DC=local"	distinguishedName attribute of an Active Directory computer.
	Full Name	String	"IgorPC"	cn attribute of an Active Directory computer.

Find Computer output parameters

Parameter name	Data type	Example
Attrs	Map	<Map of multiple values with keys of type String and values of type String.>
Distinguished Name	String	CN=IgorPC,CN=Computers,DC=ADServer,DC=local
Full Name	String	IgorPC
SamaAccount Name	String	IgorPC

Update Computer Attributes input parameters

Required	Parameter name	Data type	Example	Description
Required	Connection Id	String	Connection > Connection ID	Default Connection ID for this connector.
Required	Attributes Input Set	String	Build Input Set > Inputs	Use the output from the Build Input Set. In the Build Input Set you must create key and value pairs that you want to update as a part of this action.
Optional	Distinguished Name	String	"CN=IgorPC,CN=Computers,DC=ADServer,DC=local"	distinguishedName attribute of a queried computer.
Optional	Samaaccount Name	String	"IgorPC"	sAMAccountName attribute of a queried computer.
Optional	Full Name	String	"IgorPC"	cn attribute of a queried computer.

Reference screenshots

This section includes helpful screenshots about information referenced in this topic.

User record in the Active Directory

Group record in the Active Directory

Computer record in the Active Directory

Required licensing

SaaS subscribers who use BMC Helix ITSM or BMC-Helix-Virtual-Agent-Basic-service are entitled to this feature.