The Active Directory PowerShell connector lets OpenIAM provision and reconcile identities in Microsoft Active Directory. It runs as part of the OpenIAM connector service on a Windows host, receives requests from OpenIAM over RabbitMQ, and executes them against AD using the Active Directory PowerShell module. The connector manages users, groups, and computers, and can additionally manage file shares (SMB shares, AD-published shares, and DFS targets). All business logic lives in a customizable Connector.ps1 script and its shared module, so behavior can be tailored per deployment.

Installation and connection to OpenIAM

All PowerShell connectors are installed in the same way, which is described in the document:

Details related to installing the PowerShell Active Directory connector

The AD PowerShell connector can be deployed on either:

• A domain-joined server inside the same domain which contains the identities the AD connector is supposed to manage. This is the recommended approach.
• A non-domain-joined server. However, the domain controller of the target domain must be network-reachable from the AD connector server.

Installing the AD PowerShell connector directly on domain controllers is possible as well, however, this is not recommended for production environments.

Regardless of where it runs, the host must have the Active Directory module for Windows PowerShell installed (RSAT AD PowerShell feature) and network access to a domain controller over port 9389 (Active Directory Web Services) and LDAP/LDAPS (389/636).

General usage

All PowerShell connectors are used in the same way, which is described in the document:

Service account information:

During Managed System configuration inside OpenIAM webconsole you should set Login and Password, which are the credentials of a dedicated service account — a regular Active Directory user account. To avoid confusion: this is an Active Directory account, not an OpenIAM application user or administrator.

Grant the service account only the permissions it needs for the operations you intend to use, delegated on the target OUs:

• Create / modify / delete user, group, and computer objects.
• Read object attributes (required for search and for the lookup that precedes every update).
• Reset password and unlock account (for password reset and account suspend/resume).
• Manage group membership (add/remove members).
• Move objects between OUs (required when a request changes an object's location).
• For cross-domain group membership: equivalent rights in the other domain(s).
• For file-share management: local administrative rights on the file server and rights to publish shares to AD/DFS.

For POC scenarios and test environments you can add the service account to administrative groups so the connector is not restricted. For production, use the minimum required permission set described above.

As an example, you can use Delegation control to give your service account permissions for a given OU. To do this you can select your OU inside ADUC (Active Directory Users and Computers) by right-clicking and picking the Delegation control wizard like shown below.

Limiting connector scope

It is strongly recommended that service accounts should have only the required set of permissions. For example, if the connector is used for one-way sync from AD, the service account should not be given permission to write to AD. Permissions for service accounts are controlled on the Active Directory side (for example, by applying permission delegation).

However, as an additional safety measure, you may use the PermittedDN parameter at the managed system level. If this setting is configured, the connector will skip all ADD operations if a new object would be created outside the specified OU or its sub-OUs. Similarly, all MODIFY operations will be stopped if the object being modified is located outside the PermittedDN scope. In both cases the connector returns a FAIL status with an appropriate message.

Supported operations

How attributes are processed

OpenIAM sends each attribute with an operation code:

• No change — the attribute is ignored.
• Add / Replace — the value is written to AD.
• Delete — the attribute is cleared. For attributes that cannot hold an empty value (booleans and certain enums), the connector applies a safe default instead of an empty value (for example, boolean flags are set to False; a group's scope/category and a computer's Kerberos encryption type fall back to their defaults).

Identity and renaming. The connector finds objects by the configured identity attribute (typically sAMAccountName). To rename the identity value, OpenIAM sends the previous value as the original identity; the connector locates the existing object and renames it. If the original identity is provided but the object cannot be found, the operation stops with an error — it is not silently turned into a create.

Name attribute changes the object's RDN/common name via a rename.

Path attribute moves the object to another OU/container; the connector first validates that the target is an existing OU or container.

Unknown attributes are ignored by default. They can optionally be written to AD by enabling isUnknownAttrBindAllowed in the managed-system settings (see Managed-system-level settings below). Attributes that are ignored are written to the log so you can see why a value was not applied.

Provisioning identities

The AD PowerShell connector supports working with the following identities:

• Users
• Groups
• Computers
• File shares

This document describes parameters that can be sent to the connector to modify certain attributes inside Active Directory. Each parameter is described in detail.

User provisioning

Principal — SamAccountName

Provisioning custom attributes in AD with extended schema

For provisioning user attributes related to the extended AD schema:

• These attributes must exist in the User Policy map.
• At the managed system level, create an ExtraUserAttributes attribute and add all provisioning attributes related to the extended AD schema to it, separated by commas.

Group provisioning

Principal — SamAccountName

To add a new group, OpenIAM must send two attributes:

• Name
• GroupScope (DomainLocal, Global, or Universal)

OpenIAM configuration

To enable group provisioning, add the group provision fields to the managed system. Go to Webconsole > Provisioning > Connectors > AD PowerShell Connector > Connector configuration and enable the checkboxes for:

• Base DN for Group
• Object Primary Key for Group
• Search Base DN for Group
• Search Filter for Group

Save changes. Go to the managed system edit page and populate the new fields for group, then save. Make sure that you have a policy map for the group object type — if not, create one by copying from the out-of-the-box managed system.

Now each group linked with the AD managed system will have an identity generated and will be provisioned to AD.

Group membership behaviour

Group membership is reconciled on every Save request. The connector adds or removes members as needed to match the requested state. Failures on individual membership changes are reported as warnings and do not fail the whole request.

Cross-domain membership is supported. Provide the relevant domain controllers via the EnvironmentControllers managed-system attribute (semicolon-separated list of DC hostnames) so the connector can target the correct domain for each membership change.

Two optional flags prune memberships not present in OpenIAM's map:

• RemoveUnknownGroupMembership — removes the object from groups that are not in its MemberOf map. The built-in Domain Users group is never removed.
• RemoveUnknownGroupMembers (groups only) — removes members from a group that are not in the group's Members map.

Computer provisioning

Principal — SamAccountName

File share provisioning

Principal — UNCPath

File shares are modelled as Group objects in OpenIAM with the policy-map attribute Type set to fileshare. The connector detects this and handles the request as a file share operation rather than a standard group operation.

Managed-system-level settings

The following can be set as additional attributes on the managed system in OpenIAM to control connector behaviour:

Password validation

A Login request validates a user password against Active Directory. By default the connector connects over LDAPS; if a port is configured on the managed system it connects to LDAP://<host>:<port> (port 636 is treated as LDAPS). LDAPLoginAddress can override the host for this check only.

The response reports:

• Whether the account was found and enabled.
• Whether the password must be changed at next logon.
• When the password is valid: the password expiration date and number of days until expiry.

A disabled or missing account, or an invalid password, is returned as a failed login.

Synchronization

Synchronizing AD users

Running synchronization is very similar to performing PowerShell queries targeted to AD. In most cases it leverages the functionality of Get-ADUser, Get-ADGroup or Get-ADComputer cmdlets.

General query execution logic

OpenIAM sends the query to the connector along with the list of attributes it expects to receive. The query result on the connector side is treated as key-value pairs. When this key-value structure is formed, the connector matches attributes requested from OpenIAM against the available keys (case-insensitive). If a key is matched, the value(s) are returned to OpenIAM. If a key is not found but an attribute was requested, the attribute value is returned as null.

While running search requests, the connector authenticates against AD using the service account. The query, although almost identical to PowerShell queries, is evaluated on the connector side and translated to real PowerShell commands. The connector allows you to run pure PowerShell requests but also offers simplified syntax described below.

In all examples below we will use Get-ADUser; the same examples apply with Get-ADUser replaced by Get-ADGroup or Get-ADComputer.

Returned attributes

If the query does not contain a -Properties parameter, the basic attributes the connector returns from AD are:

• DistinguishedName
• Enabled
• GivenName
• Name
• ObjectClass
• ObjectGUID
• SamAccountName
• SID
• Surname
• UserPrincipalName

Getting extra attributes. To add extra attributes, specify -Properties X,Y,Z or -Properties * where X, Y, Z are required attributes in a comma-separated list. If you need all attributes, specify *. Be aware that querying all attributes using * significantly decreases performance, so it is recommended to always specify only the attributes you need.

A full query example:

Get-ADUser -Filter * -Properties Mail,WhenCreated

The query above searches for all users inside AD (or inside SearchBaseDN) and returns the basic attribute set plus Mail and WhenCreated.

Get-ADUser -Filter * -Properties *

The query above searches for all users and returns all attributes from the user profile. This can be very slow and memory-intensive with large user directories.

Query syntax

You can run a direct query using the syntax described at Get-ADUser, Get-ADGroup or Get-ADComputer.

If you specify the Filter parameter without specifying SearchBase, the SearchBase value will be set to the SearchBaseDN setting on your managed system page.

Query examples:

Get-ADUser -Filter *

The query above gets all users from AD. If SearchBaseDN is set, the scope will be limited to that location.

Get-ADUser -Identity 'SamAccountName or SID, GUID or DN' -Properties *

Use this form to synchronize a single user — typically for testing or validating functionality.

Get-ADUser -Filter {Surname -eq 'Potter'}

The query above selects all users with the surname 'Potter'. The search is limited to SearchBaseDN because the -Filter parameter is present and no -SearchBase is specified. To override the SearchBaseDN:

Get-ADUser -Filter {Surname -eq 'Potter'} -SearchBase 'DC=openiamtest,DC=local'

If you run queries that do not use the -Filter parameter, they are not limited to SearchBaseDN.

One common scenario is filtering users modified after a certain date:

Get-ADUser -LDAPFilter '(whenChanged>=20200726000000.0Z)' -Properties whenChanged

Here the whenChanged attribute is specified in YYYYMMDD format (plus hours and minutes), so the query returns all users modified after 26 July 2020.

To sync user objects from specific locations inside AD, use filtering in your query (the -SearchBase parameter accepts only one location):

Get-ADUser -Filter * -Properties property1,property2 | Where-Object {$_.DistinguishedName -like '*OU=SomeOU1,DC=openiamtest,DC=local' -or $_.DistinguishedName -like '*OU=SomeOU2,DC=openiamtest,DC=local'}

This request gets all users inside AD but filters and returns only those whose DistinguishedName ends with the given locations, including child locations.

Synchronizing AD group memberships

Group memberships are synchronized as part of user synchronization. To get information about the groups a user belongs to, include the memberOf attribute in your request:

Get-ADUser -Filter * -Properties memberOf

Alternatively, use * to return all possible properties, though this greatly decreases performance.

Primary group membership — Active Directory does not return primary group membership inside the memberOf attribute by design. In the vast majority of cases the primary group for all users is Domain Users. If you need to sync the primary group membership, include the PrimaryGroup attribute in your request:

Get-ADUser -Filter * -Properties memberOf, PrimaryGroup

OpenIAM configuration for AD user sync

OpenIAM supplies an out-of-the-box configuration named AD PowerShell USER Example.

Synchronizing AD groups

AD group synchronization is performed in the same way as user synchronization. Replace Get-ADUser with Get-ADGroup in the filter expressions.

Getting all AD distribution groups:

Get-ADGroup -Filter 'groupcategory -eq "Distribution"'

Getting all security groups in a certain location:

Get-ADGroup -Filter 'groupcategory -eq "Security"' -SearchBase 'CN=Users,DC=openiamtest,DC=local'

Attributes returned by AD group sync

If you run requests like above, the connector returns the following default attributes for the AD Group object:

• DistinguishedName
• GroupCategory — Security or Distribution
• GroupScope — DomainLocal, Global, or Universal
• Name — the name of the group, which usually acts as the principal for group object provisioning in AD
• ObjectClass — always group
• ObjectGUID — unique identifier, e.g. d8168b10-f45e-43f4-bd9c-37a53896e4bc
• SamAccountName
• SID — security identifier, e.g. S-1-5-21-3577459162-1270948675-2189036518-2886

To get additional attributes, add -Properties prop1,prop2,... to your request, or use * for everything (note the performance impact). For example, to get all available information about all security groups in a domain:

Get-ADGroup -Filter 'groupcategory -eq "Security"' -Properties *

For better performance, specify only the properties you need:

Get-ADGroup -Filter 'groupcategory -eq "Security"' -Properties cn,whenCreated

The example above returns all basic attributes plus CN and WhenCreated.

You can also request the following additional properties:

• CanonicalName — e.g. openiamtest.local/Builtin/Administrators
• Created
• createTimeStamp
• Deleted
• Description
• HomePage
• isCriticalSystemObject
• isDeleted
• LastKnownParent
• ManagedBy
• MemberOf — DNs of the parent groups
• Members — DNs of members of this group
• Modified
• modifyTimeStamp
• ProtectedFromAccidentalDeletion
• whenChanged
• whenCreated

OpenIAM configuration for AD group sync

OpenIAM supplies an out-of-the-box configuration named AD PowerShell GROUP Example.

Synchronizing AD file shares

The AD connector can synchronize file shares located on domain-joined Windows servers. Target Windows servers must run Windows Server 2012 R2 or later.

Because file shares reside on individual servers and are not managed centrally by AD, the AD connector connects to each file share server directly using PowerShell Remoting and executes PowerShell commands over a remote session.

The AD connector service account must have the following permissions on the target file share server:

• Member of the local Remote Management Users group — to discover all file shares on the server.
• Member of the local Administrators group — to collect share permissions.

To synchronize file shares, use Get-SmbSharesInfo in your synchronization query:

Get-SmbSharesInfo -ComputerNames 'server1','server2'

In this scenario, the AD connector connects to server1 and server2 to retrieve information about the file shares stored there.

To get information about all file shares in your domain:

Get-SmbSharesInfo -DomainController 'yourDCHostname'

When the AD connector receives the query above, it connects to your domain controller (using the credentials stored in the managed system configuration), pulls all computers registered in AD, and then connects to each of them (using multithreading) to collect file share information.

Getting permissions. To determine whether the connector needs to collect permissions, the connector checks the list of requested attributes from OpenIAM. This list is set in the Attribute names lookup parameter of the OpenIAM synchronization configuration page. If this list contains the Permissions attribute, the connector retrieves permissions for each file share found. If the attribute is not listed, this step is skipped.

Incremental sync of users or groups

When running incremental sync, OpenIAM relies on the time of the last user/group modification in AD. Each user or group in AD has a Modified property that is updated each time the object is changed.

To get objects modified after a certain date:

Get-AdGroup -Filter "Modified -gt '$((Get-Date '?').ToUniversalTime())'"

In this example, OpenIAM replaces ? with a real value during runtime.

OpenIAM also needs to know the time format to use when receiving values from the connector. This format is sent in the request metadata as the DateTimeStringFormat parameter:

This setting can be changed in the configuration of your Managed System.

Urgent queues

A connector is responsible for transferring data between systems. If some messages require immediate processing, an urgent queue can be implemented to prioritize them over regular traffic. To add a connection, follow the steps below.

1. Open Connector.config inside the connector folder on the Windows machine and add a new record to the "RabbitMQQueues" array, as shown below.

Duplicate the existing queue record and append URGENT_ to the *ReceiveQueue and *ResponseQueue property values. The configuration that supports urgent queues looks like the one below.

Concurrency values can be set independently for the normal and urgent queues.

Connector troubleshooting and tips

Connector troubleshooting is covered in the document that describes all .NET/PowerShell connector usage:

• It is always better to specify the DNS hostname of your domain controller on the Managed System configuration page, especially when the connector server is a domain member. Specifying an IP address may lead to non-obvious errors.
• Port 9389 must be open on the domain controller side for the connector to reach it. It is open in almost all standard configurations.
• To validate the connection to AD in the same way as the connector, you can run the following script:

Import-Module ActiveDirectory
$dc = 'YOUR_DOMAIN_CONTROLLER_HOSTNAME'
$ADcred = Get-Credential

New-PSDrive -PSProvider ActiveDirectory -Server $dc -Credential $ADcred -Root "" -Name IamADDrv -FormatType Canonical
if((Test-Path IamADDrv:) -eq $false)
{
    throw "Unable to connect to AD"
}
Set-Location IamADDrv:

Possible errors

Errors in the table below are captured from customer feedback. These are the most frequently reported.