This article will lead you through the configuration options that are specific to the Microsoft Active Directory (AD) target system connector. Information about configuration options that are common among all target systems can be found here.
Configure the Microsoft Active Directory target system
On the target systems overview, click the wrench icon for the Microsoft Active Directory target that you wish to configure. This will take you to the configuration page for that system.
Enter the fully qualified (FQDN) Domain name of the Active Directory domain to which you will be connecting. Then select the Connect button.
If HelloID can establish a connection, the button will turn green and additional tabs will appear along the top of the pane. If an error is encountered, more information will be displayed. Connections are made through the HelloID Agent that is installed within the target domain.
These settings determine which domain controller(s) your HelloID Agent will use for Entitlement actions.
By default (when the Manual domain controller selection toggle is turned off) your HelloID Agent uses your primary domain controller as long as it is available. If it becomes unavailable, Agent switches to another domain controller (selected randomly) and uses it until the primary is available again. Note that entitlement actions are batched, and domain controllers are only switched in between batches.
To override this default behavior, follow these instructions:
- Select the wrench button for Domain Controller.
- Turn on the Manual domain controller selection toggle.
- Drag and drop entries in the Available domain controllers column into the Selected domain controllers column. Drag and drop these entries up and down to place them in order of descending priority. Provisioning will only use domain controllers placed into the latter column for entitlement actions.
- Select the Close button.
- Select the target system's Save button.
Here, you can specify which Agent(s) can be used by this target system (if you have multiple Agents installed). See Agent configuration for on-premise systems.
On the Exchange tab, you may integrate HelloID Provisioning with Microsoft Exchange. The instance of Exchange can be a local, hybrid, or remote configuration.
NOTE: If you plan to connect to a local Exchange server, you must first enable communication between HelloID Agent and Exchange.
When enabled, a mailbox is created when the Account entitlement is granted. The mailbox is initially hidden from the global address list (GAL). It is displayed in the GAL only when the Account Access entitlement is granted.
The options on this tab are as follows:
The PowerShell connection URL for your Exchange instance. E.g.,
The username and password with which HelloID will connect to Exchange. Required for all authentication modes.
- Authentication Mode
Exchange supports several methods of authentication, such as Basic, Digest, and Kerberos. Select the method appropriate to your instance and environment.
- Use Hybrid/Remote Exchange Integration
Enable this option if your instance of Exchange is remote or hybrid. This will cause HelloID to issue the
Enable-RemoteMailboxcmdlet and other remote commands instead of the local Exchange equivalents.
- Skip CA Check
When connecting over HTTPS, enabling this setting will cause HelloID to not validate that the server certificate is signed by a trusted certificate authority.
- Skip CN Check
When enabled, the certificate common name (CN) does not need to match the host name of the server. This is useful when you have installed a wildcard certificate, for example.
- Skip Revocation Check
When enabled, the revocation status of the certificate will not be checked.
On the Directories tab, you may configure the creation and archival of home/profile directories for both local and terminal services. When enabled, HelloID creates or archives these directories when the Account entitlement is granted or revoked. For each created directory, the user receives read/write permissions and the service account receives permission to move the directory.
In the left column is a card for each directory type. Select the one you wish to configure and turn on the Enabled toggle.
To statically configure directory creation and archival, leave the Use PowerShell toggle turned off. Specify your configuration using the following options:
The UNC path where HelloID will create the user's directory. The path should be in the format
\\server-name\share\optional-subfolder. The user's
sAMAccountNameis appended as the final folder name.
- Set AD Attributes
Update attributes in Active Directory that are relevant to the selected directory type, in addition to creating the directory. These attributes include:
The drive that will be mapped to the user's directory upon login. Not available for Profile or TSProfile directories.
Move the directory to the path specified in Archive Path when the user's Account entitlement is revoked.
- Archive Path
The UNC path used by the Archive toggle. The path should be in the format
\\server-name\share\optional-subfolder. For performance reasons, it's not possible to choose an archive path outside the user's share or directory. Archive folders can only be stored in the same share or directory specified in the Path field.
Alternatively, you can dynamically configure home or profile directory creation using PowerShell.
The Account tab lets you configure how account entitlements are handled, including which Person fields are mapped onto which AD attributes.
- Use account data from systems
If other target systems have been configured to store data inside the Person object, you can add those systems here to reference their data in your AD attribute mappings. For example, you could use a username from another target system as the AD
sAMAccountNameto ensure a match.
- Configure Attribute Mappings
Selecting the Configure button lets you customize the values that HelloID maps from Person fields onto AD account attributes. For example, you can change how HelloID generates and maps the
cn. See more information in the Configure Attribute Mappings section below.
- Export / Import Attribute Mappings
Export or import a JSON definition of your mappings in order to easily clone them to another target system.
- Synchronize unique fields
When this toggle is turned on, all attributes' complex field mappings for a given AD account will have their numeric
Iterationvariables synchronized. HelloID will take the highest value among unique attributes being mapped onto a given account, and use it for all unique attributes being mapped onto the account. Learn more about the Iteration variable.
- Check on external systems
Turning on this toggle reveals a Configure button. Select it to launch the Uniqueness check on external systems dialog box:
Here, you can write custom PowerShell code to cross-check the uniqueness of attribute values against system(s) other than the target AD system itself. This is helpful when your use case requires you to avoid reusing attributes like usernames or email addresses across different company systems.
Note that in this context, "system" may (but does not necessarily) refer to other target systems in HelloID Provisioning. In other words, this feature can be used to compare against values from other target systems which have been added under Use account data from systems. However, since you may write any PowerShell code you wish, you are not limited to those systems. You can also connect to a separate API, a flat CSV file, or anything else you can script in PowerShell.
When enabled, this feature is invoked for each Person receiving an Account entitlement during a business rule enforcement. For example: Suppose that John Doe's Person record is set to be mapped to a target AD account with the
john.doe. This feature will run your custom logic, which should confirm that no
john.doeuser already exists in any specified external system(s). Your script reports this result by returning nothing for the
$resultwhen the value is unique, and returning the name(s) of the non-unique attribute(s) for
NonUniqueFieldswhen there is duplication. To easily see a list of attributes you can return, preview any user's mappings as described in the Configure Attribute Mappings section below.
When a duplicate is found, the attribute's complex field mapping function is re-run (if one exists) after its
Iterationvariable has been incremented. This process is repeated until a unique value is found, which is then used as the target attribute value (in the current example, the
sAMAccountName). To avoid an endless loop, the process is terminated if the mapping function returns two consecutive identical values. Note that this will occur immediately if the attribute is mapped as a fixed or field value rather than a complex value. The process also terminates if your script returns an unmapped attribute name.
This feature is similar to the Ensure this field is unique option described in the Configure Attribute Mappings section below. But whereas this feature checks values against arbitrary external system(s) and therefore requires custom logic, the latter checks values only against the target AD system and does not require custom logic. Note that you don't need to turn on any Ensure this field is unique toggles to enable external system checks. However, if any are turned on, they will be evaluated just prior to external system checks during the enforcement process.
You may select a Person from the drop down to see how HelloID will map their attributes. This lets you preview what will happen during business rule enforcement.
Configure Attribute Mappings
Select the Configure button under the Mapping section to launch the attribute mapping screen. You are presented with a list of (known) attributes in the target AD system's user schema:
To preview mappings, select a Person from the drop down list in the upper-right-hand corner.
To add an additional attribute, select the desired field from the Map Additional Field drop down and select the Add button.
Newly added attributes are appended to the bottom of the mapping list:
If the attribute you want to add isn't in the Map Additional Field drop down, then select it and type a new attribute name. Select the Add button to confirm. Note that attributes added this way must already be defined and available in the target AD system's user schema.
Select an existing attribute to expand it and edit its options:
Common attribute options include:
- Ensure this field is unique
When turned on, HelloID will attempt to generate a new, unique value for this attribute if a duplicate exists in the target AD system. This option is particularly useful to avoid collisions on variables like
cnwhich must be unique in AD. The new value is generated by re-running the complex field mapping function (if one exists) after its
Iterationvariable has been incremented. Also see the Check on external systems option above, which works similarly but checks for duplication in external systems instead of the target AD system. (Alternately, use the Correlate feature if you wish to link together duplicate accounts instead of merely preventing collision by generating unique values.)
- Update this field
When this toggle is turned on, this attribute will be updated in the target AD system whenever the Person data mapped to this attribute changes and an enforcement is run. (It also allows Force update accounts to update the attribute when the mapping has changed, but the Person data itself has not.) When this toggle is turned off, no changes whatsoever are allowed to this attribute in the target AD system.
- Store this field in person account data
See How to use data from one target system in another target system.
Under the Administration tab are options for assigning OU paths during user lifecycle stage changes:
- Account Create (Initial container)
- Account Enable (Move account on enable)
- Account Disable (Move account on disable)
- Account Update (Move account on update)
Options on this tab include:
- Delete the account when revoking the entitlement
When enabled, the Person's account will be deleted in the target system when their Account entitlement is revoked. If this setting is disabled, then the entitlement is still revoked, but the account remains in place and becomes unmanaged by HelloID. Use the Correlate feature if you wish to re-associate unmanaged accounts.
- Set primary manager when an account is created
When enabled, HelloID will set the manager attribute of the target account to the Person's primary manager during the Create lifecycle stage. If this setting is disabled, the manager attribute will remain blank.
- Update manager when account is updated
When enabled, HelloID will set the manager attribute of the target account to the Person's primary manager during the Update lifecycle stage. If this setting is disabled, HelloID will not update the manager attribute.
- Initial container
The organizational unit (OU) on the target AD system in which user accounts will be placed during the Create lifecycle stage. This field is required. If you don't select an OU, new account entitlements will fail.
- Move account on enable/disable/update
The OUs on the target AD system to which user accounts will be moved during the Enable, Disable, and Update lifecycle stages, respectively. Users will only be moved if the respective Enabled toggles are turned on. For example, using the Move account on update option in combination with PowerShell, you could write custom logic to move Persons to a different OU when their department changes within the organization, by reading the department field of the Person object. See more information by following the below link on dynamic PowerShell OU placement.
Only the OU assigned on Account Create (Initial container) is required. To enable OU changes during other lifecycle stages, turn on their respective Enabled toggles.
You may set a static OU using the drop down menus:
Alternatively, you can dynamically configure OU placement using PowerShell.
Often, accounts for some people within your organization already exist in a target system. To avoid creating new (duplicate) accounts, you may configure the target system's correlation options.
When correlation is enabled, HelloID looks for existing accounts in the target system that match with Persons records generated from the source system(s). It does this by matching the correlation fields defined in this tab. In the screenshot above, we have told HelloID that if the
ExternalID field in the Person object matches the
Employee ID attribute in Active Directory, then no new account should be created—rather the existing account should be updated.
Note that HelloID only correlates objects with the
Important: You should audit your target system to ensure the uniqueness of the chosen Account Correlation Field. If two accounts within the target system share the same unique identifier, then HelloID will correlate both accounts to the source record.
After configuring the correlation options for the target system, you may generate a correlation report once the system is saved. This report will allow you to see which accounts have or have not yet been correlated with source Person records. This is useful for identifying accounts in the target system that still need to be correlated with source Person records.
The Account displayname column contains a concatenation of the Person's displayName (first) plus the correlated AD account's sAMAccountName (second, in parentheses). This ensures every row is unique, and helps you easily recognize which Person record is correlated with which AD account.
At the bottom of the Correlation report tab, you will find the Manually correlate area. In this area, you may select from a list of Persons who have not yet been correlated to an account (left), and then select from a list of accounts that have not yet been correlated to a Person (right), and tie them together within HelloID.
After you have selected a Person (left) and a target system account (right), you will be able to select the Link account to person button, as shown below. When you manually correlate accounts in this way, HelloID will update the target account with the source record's external ID. The field that will be updated is the one selected in the Account Correlation Field dropdown in the Correlate tab.
Export a report
Select the Export button on Correlated persons with accounts, Uncorrelated persons, or Uncorrelated accounts to download a CSV report.