HomeGuidesAPI
HomeGuidesRecipesAPI
HomeGuidesAPILog In

Windows Active Directory Operations Connector

Suggest Edits

This connector is aimed at the designer wishing to interact with a Windows Active Directory Domain Controller for users and groups.

Versions

Version 4.0 (released 14 July 2020)

  • Compatibility with SmartIQ 13

Version 3.1 (released 18 September 2019)

  • Further cleanup of actions; common code refactored
  • Completed implementation of Get All OUs data object
  • Support Impersonation for Create/Update/Delete actions
  • [Breaking] "Other Attributes" input on Create/Edit User actions are now key-value style input
  • [Breaking] Data Source connection settings override the Connector Settings instead of the other way around

Version 3.0 (released 22 October 2018)

  • Upgrade to Custom Extension framework
  • Addition of a a few data source methods
  • Refactoring for clarity and robustness.
  • Complete re-haul to simplify and use Object Names rather than Object Types for everything.

Version 2.0 (released 4 May 2018)

  • Refactoring and addition of the Edit function

Version 1.0 (released 12 December 2016)

  • Initial build

Actions

  • Create AD User
  • Edit AD User
  • Delete AD User
  • Create AD group
  • Edit AD Group
  • Delete AD Group

Data Source Object Types and corresponding Object Lists

User

  • Get Members Of Group
  • Search All Properties
  • Get User Details
  • User Searcher

Group

  • Group Searcher
  • Get Group Details
  • Get User's List of Groups

OU

  • Get All OUs

Unique Usernames

  • Get Unique Usernames

Installation Requirements

Before installing this connector, you must consider the following requirements:

  • You must have administrator/elevated permissions to the SmartIQ web server, including the ability to copy and replace files in the SmartIQ installation folder. This is usually c:\inetpub\wwwroot\SmartIQ however may vary from system to system.
  • You must have an appropriate Active Directory account with admin rights.
  • You must have the ActiveDirectoryExtension.dll, System.DirectoryServices.AccountManagement.dll and System.DirectoryServices.Protocols.dll files.
  • You must have a licence for the Windows Active Directory Operations Connector (contact your account manager for details)

Use the instructions below to install the connector. If you are upgrading the extension from a previous version, refer to the section Upgrading the Connector.

Note that [SmartIQ Produce Path] refers to the installation path on the web server running SmartIQ, where the Produce site has been installed. By default this is c:\inetpub\wwwroot\SmartIQ\produce however may vary from environment to environment. Equally, [SmartIQ Manage Path] refers to where the Manage site has been installed.

Installing the Connector

How to install the Windows AD Operations Connector

  1. Copy the files listed above into the following folder on the SmartIQ web server:
    [SmartIQ Produce Path]\

  2. Using a text editor such as Notepad, open the following file:
    [SmartIQ Produce Path]\appsettings.json

  3. Locate the <Extensions> section and add the following entries:

"ActiveDirectoryConnector.Datasource,ActiveDirectoryConnector",
"ActiveDirectoryConnector.CreateUserAction,ActiveDirectoryConnector",
"ActiveDirectoryConnector.EditUserAction,ActiveDirectoryConnector",
"ActiveDirectoryConnector.DeleteUserAction, ActiveDirectoryConnector",
"ActiveDirectoryConnector.CreateGroupAction,ActiveDirectoryConnector",
"ActiveDirectoryConnector.EditGroupAction,ActiveDirectoryConnector",
"ActiveDirectoryConnector.DeleteGroupAction, ActiveDirectoryConnector"

  1. Copy the files listed above into the following folder on the SmartIQ web server:
    [SmartIQ Manage Path]\

  2. Using a text editor such as Notepad, open the following file:
    [SmartIQ Manage Path]\appsettings.json

  3. Locate the <Extensions> section and add the same entries as above.

Using a web browser, navigate to the SmartIQ Produce application and SmartIQ Manage to allow the system to register the Connector.

In Manage, go to Settings -> Connector Settings -> Select the Active Directory Connector and complete the 3 required settings. If at least one of these is not provided, the connector will attempt to use Windows Authentication of the user currently logged in. This option is not recommended for production.

The Connector should now be installed, ready for configuration and usage.

Upgrading the Connector

If your SmartIQ environment is already running an earlier version of the Active Directory connector and you are simply upgrading to a new version for SmartIQ, please follow these simple upgrade steps below.

How to upgrade a Legacy Active Directory Connector

  1. Make sure you remove all files of the current Active Directory Connector from your SmartIQ web server. Navigate to your [SmartIQ Produce Path]\ folder, then remove these following files (if they are present):
  • ActiveDirectoryConnector.dll
  • System.DirectoryServices.AccountManagement.dll
  • System.DirectoryServices.Protocols.dll
  1. Navigate to your [SmartIQ Manage Path]\ folder, then remove the same files listed in Step 1 (if they are present).
  2. Using a text editor such as Notepad, open [SmartIQ Manage Path]\appsettings.json. Locate the “Extensions” section of the appsettings.json file and replace all legacy entries related to the ACtive Directory Connector with the lines specified in the standard installation instructions above. Locate all Legacy Action sections related to the Active Directory Connector and remove them.
  3. Repeat the same processes in the [SmartIQ Produce Path].

Using the Windows AD Operations Connector

Configuration

Three Connector Settings are available for the connector:

  • Username
  • Password
  • Domain

These specify the credentials of the service account which should be used to perform the Action operations (create/update/delete users and groups).
If they are not provided, the Actions will not function.

They also act as a fallback for the data source credentials, which can otherwise be specified at the data source level as mentioned below.
If no credentials are supplied for the data source, it will use the Connector Settings credentials instead.

Actions

The connector contains a series of actions to create, edit and delete users. Once the connector is installed, these will be available for use in Design. Required inputs are indicated by a star symbol at the end of the input key.

Create AD User Action

This action requires an Account Name and Email and can take any number of optional attributes.

  • Account Name* : This is the new users Account Name and will be populated as the SamAccountName AD parameter.
  • Email* : The new user's email address
  • Enable user? : True or False - Defaults to True.
  • Expire Password? : True or False - Defaults to False.
  • Firstname/Surname/Password: These are optional but recommended self explanatory inputs.
  • OU : The Organisation Unit.
  • Template Username: The SamAccountName of a template user that can be used as an example user for generic account creation.
  • Other Attributes name=value: This is a key input, that can take any number of inputs as text values in the format 'name=value'. An example could be 'GivenName=John'. The name must match existing AD user account parameters.
Edit AD User Action

This action requires an Account Name and Email and can take any number of optional attributes.

  • Account Name* : This is the new users Account Name and will be populated as the SamAccountName AD parameter.
  • Enable user? : True or False - Defaults to True.
  • Expire Password? : True or False - Defaults to False.
  • Group Name to Add: Add user to named group.
  • Group Name to Remove: Remove user from named group.
  • OU : The Organisation Unit.
  • Other Attributes name=value: This is a key input, that can take any number of inputs as text values in the format 'name=value'. An example could be 'GivenName=John'. The name must match existing AD user account parameters.
Delete AD User Action

This action takes only the Account Name (AD's SamAccountName) as input and deletes the user.

Data Sources

This Data Source contains a series of Object Types (User, Group) which related broadly with what sort of item the data source should return. Then,
each object type contains a list of object names, which are essentially the various methods associated with returning this type of object.

When setting up the various data source objects, the designer should select the object type they are looking for, and the corresponding object name for their use case.

The Data Sources will use the individual Data Source credentials (username, password, domain/container) to query the domain if supplied.
If not supplied, the credentials and domain from the Connector Settings will be used.
The datasource-level connection string should be of the format name=<domain name>;container=<container name>, where the domain is required
and the container is optional.

These are brief descriptions of the various Data Source method names available in this connector. All filter fields are prefixed by an @ symbol.

User Searcher

The primary method to search for users. It's designed to be as efficient as possible and to be potentially used as an Autocomplete data source type.
The number of available filters is limited to the most common use cases. If for more information on users is required, please use the 'Get User Details' method
with an input obtained from this method.

This method takes a user filter string, which is used to search for users, comparing against user's SamAccountName, Given Name, Surname and email address and returns a list
of unique users that match any of these. If the wildcard string is contained in any of these parameters, the user is returned.
A second optional input is the Minimum Characters field. Please set to an integer number of characters (e.g: @MinimumCharacters = 3). If specified, the datasource will only return results
once the User Filter field contains at least this many characters. This is in place to avoid triggering the data source on too few characters which may take too long.

Note: Use the 'No Data Text' data source optional field in Design to display a message when nothing is found or when the minimum number of characters has yet to be reached.

  • Filters:
    • @UserFilter
    • @MinimumCharacters

Get User Details

Obtains all the info for user of interest based on a unique Identifier that corresponds directly with one of the AD's standard parameters.
This Data source should use only a single filter field but 5 possibilities are given as options. The idea behind this object is that the designer
will use the 'User Searcher' to first find the user of interest, and then use one of the filters here to query the specific user for extra details.
This is the case because a lot of ADs contain a large number of users and querying all details for all of them takes a long time.

An example case would be: Using the 'User Searcher' to just return the user's account name and Guid, select a user of interest, and then configuring this data source
to grab further user details with the @Guid filter corresponding to the selected user's Guid.

  • Filters:
    • @SamAccountName
    • @UserPrincipalName
    • @DistinguishedName
    • @Sid
    • @Guid

Group Searcher

The primary method to search for groups. It's designed to be as efficient as possible and to be potentially used as an Autocomplete data source type.
The number of available filters is limited to the most common use cases. If for more information on groups is required, please use the 'Get Group Details' method
with an input obtained from this method. This method can take wildcard filters.

This will search for groups that contain the provided string in the group name as a wildcard.

  • Filters:
    • @GroupName

Get Group Details

Obtains the full group details for a provided group name.

  • Filters:
    • @GroupName

Get Members Of Group

Obtain a list of members belonging to the supplied group according to an identity field.

  • Filters:
    • @GroupName
    • @DistinguishedName
    • @Sid
    • @Guid

Note that if multiple filters are supplied, the first of the above-listed filter order will be used.

Get User's List of Groups

Obtain a list of all groups a given user is a member of. The filter is the user's Guid. Suggestion: Use the 'User Searcher' method to first select the given user.

  • Filters:
    • @Guid

Search All Properties

Find all user properties based on a recursive search

  • Filters: @SearchSubtree -> Optional recursive search.

Get All OUs

Obtain the list of all Organisation Units created in the Active Directory

  • Filters:
    • @OU -> Filter by OU
    • @SearchSubtree -> Optionally do a recursive search.

Get Unique Usernames

Obtain all unique usernames based on a seed.

  • Filters:
    • @Seed -> seed for username search.
    • @Count -> number of unique usernames to return

Updated over 3 years ago