This documentation supports the 20.08 version of BMC Digital Workplace Advanced, which is available only to BMC Helix subscribers (SaaS). To view an earlier version, select the version from the Product Version menu.

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.

Related topics

Service-connector-overview

Workflow-designer-elements-overview

Control-of-workflow-with-gateways

Handling-errors-in-processes

Designing-a-workflow-to-send-notification

BMC Communities document: How to configure AD Connector on BMC Digital Workplace Catalog

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 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.
  • 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.

  • 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.

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.

  • No output
  • An exception

Find Active Directory Group

Returns the group if the group exists; otherwise, an error occurs.

  • 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.
  • No output
  • An exception

Computer Is Member of Group

Checks whether a computer belongs to a group.

  • 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.

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.

  • 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.

  • 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.

ErrorHandlingWorkflow.png

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

ErrorEndEvent.png

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. Cause: [RuntimeError: maximum recursion limit exceeded]. Click on this message for details.

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:

UpdateAttributeWorkflow.png

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.

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

UserRecordinAD.png

Group record in the Active Directory

GroupRecordinAD.png

Computer record in the Active Directory

ComputerRecordinAD.png



 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*