Installation and connection to OpenIAM

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

Details related to installing the PowerShell Active Directory connector

The AD PowerShell connector can be deployed on either:

• Domain joined server inside the same domain which contains the identities the AD connector is supposed to manage. This is the recommended approach
• Non-domain joined server. However, the domain controller of the target domain should 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 recommend for production environments.

General usage

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

Service account information:

During Managed System configuration inside OpenIAM /webconsole section you should set Login ID, which will be used as a service account for OpenIAM. To avoid confusion between the AD and OpenIAM definition, a service account is a regular user account inside Active Directory that has permissions to perform operations that you need to do using the connector.

Please note that service account should be set to include your domain name. For example, 'openiamtest\serviceAccount'

The connector will perform all operations on behalf of the user that you specify. For POC scenarios and test environments you can simply add your user to administrative groups so the connector would not be restricted to do any actions. For a production environment you should consider a particular permission set for this account.

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 required set of permissions. That means if, for example, the connector is used to one-way sync from AD, the service account should not be given permission to write to AD. Permissions for service accounts are being controlled on the Active Directory side (for example, by applying permission delegation).

However, as an additional tool for safety, you may use PermittedDN parameter on the managed system level. If this setting is set, the connector would skip all 'ADD' operations if a new object should be created outside this (PermittedDN) or sub-OU. Also, all 'MODIFY' operations would be stopped if the object that is going to be modified is located outside of PermittedDN (or sub-OU). In both cases the connector would return 'FAIL' status containing appropriate message.

Provisioning identities

The AD PowerShell connector supports working with following identities:

• Users
• Groups
• Computers
• File shares

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

User provisioning

Principal - SamAccountName

Group provisioning

Principal - SamAccountName

To add the new group, OpenIAM should send two attributes:

• Name
• GroupScope (DomainLocal or Global or Universal)

Computer provisioning

Principal - SamAccountName

Attention! While working with a computer object in Active Directory it is important to take into account that the Microsoft side will put $ at the end of any computer samaccountname. As samaccountname is used as principal name and its value could also be used in some other managed systems - OpenIAM stores and handles it as normal value. When OpenIAM sends request to the connector, the connector can see that this request is regarding the AD computer object and will add $ at the end of samaccountname automatically. So, OpenIAM will operate identity with samaccountname 'value' while connector will silently be transforming it to 'value$' and will process all other requested operations.

FileShares provisioning

Principal - UNCPath

Synchronization

Synchronizing AD users

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

General query execution logic

OpenIAM sends the query to the connector to execute the list of attributes it expects to receive. The query result on the connector side is being treated as a key-values pair. When this key-values pair is formed, the connector makes a match between attributes that were requested from OpenIAM and keys available. If the key is matched (case insensitive) the value(s) will be returned to OpenIAM. If the key is not found, but attribute was requested the attribute value will be returned as null.

While running search requests the connector should be authenticated against AD using service account. Therefore, the query, even being almost identical to PowerShell queries, is being evaluated on the connector side and modified to real PowerShell commands. The connector leaves your ability to run pure PowerShell requests, but also offers simplified syntax that is described below.

In all examples below we will use Get-ADUser cmdlet, however same examples could be used with replacement of Get-ADUser to Get-ADGroup or Get-ADComputer.

Returned attributes

If query does not contain -Properties parameter, the basic attributes that connector will get from AD are:

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

Getting extra attributes. To add extra attributes you need to specify '-Properties X,Y,Z' or '-Properties *' parameter where X, Y, Z are required attributes in a comma separated list. If you need all attributes to be returned, you can specify instead of specifying particular attributes. But you should note that querying all attributes using significantly decreases performance and there are not a lot of use cases when you really need everything from the user profile. So, it is recommended to always specify only those attributes that you need.

A full query example would look like:

Get-ADUser -Filter * -Properties Mail,WhenCreated

The query above would search for all users inside AD (or inside SearchBaseDN) and will be able to get a basic set of attributes (described above) + Mail and WhenCreated.

Get-ADUser -Filter * -Properties *

The query above would search for all users inside AD (or inside SearchBaseDN) and will be able to get all attributes from user profile. This could be very slow and RAM consuming if there are lots of users in AD.

Query syntax

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

Please note that you do not need to specify 'Server' and 'Credential' parameters because the connector already handles connection himself.

If you specify the 'Filter' parameter and do not specify 'SearchBase', the 'SearchBase' value will be set to 'SearchBaseDN' setting inside your managed system page.

Query examples:

Get-ADUser -Filter *

Query above gets all users from AD, but if SearchBaseDN is set - the scope will be limited to SearchBaseDN like described above.

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

Sometimes it is good to synchronize a single user - this scenario is usually being used to test sync processes, for demonstrations and validating functionality. In this case the query could be used like above.

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

The query above would select all users with surname 'Potter'. Search would be limited to SearchBaseDN, because we have not specified it AND the search query contains -Filter parameter. We could override SearchBaseDN by setting the SearchBase parameter. If we do it, query would look like:

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

If you run other queries than having 'Filter' parameter inside, you will not be limited to SearchBaseDN.

For example, one common scenario is filtering users that were modified after a certain date:

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

Here the whenChanged attribute is specified in YYYYMMDD (+hours, min), so the query would return all users that were modified after the 26th of July 2020.

Sometimes it could be useful to sync user objects only from certain locations inside AD. -Search base parameter accepts only one location, but you can add filtering inside your query.

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'}

Such request would get all users inside AD, but will filter and return only users whose DistinguishedName ends with given locations. So, it will also include child locations. Some of you may say that for pure PowerShell the query above does not look optimal, and it would be optimal to pass the required location to the pipeline and run Get-ADUser for those locations only. But the connector does some modifications for the queries before the run, so that method would not be possible. At the same time, filtering will help reach your aim.

Synchronizing AD group memberships

Group memberships are synchronized using user synchronization. To get information about groups in which a current user is a member you need to include the memberOf attribute inside your request. For example:

Get-ADUser -Filter * -Properties memberOf

Alternatively, you can use * to grab all possible properties instead of specifying memberOf. However, as it was described before, it greatly decreases performance.

Primary group membership - Active Directory by its design does not return primary group membership inside memberOf attribute. In an absolute majority of cases the primary group for all users is 'Domain Users'. However, if in your scenario you need for some reason to sync the primary group membership for your user you need to include the 'PrimaryGroup' attribute inside your request. So, our request would look like:

Get-ADUser -Filter * -Properties memberOf, PrimaryGroup

Synchronizing AD groups

AD groups synchronization is performed in the same way as AD users synchronization. You can take the above chapter as an example and just replace 'Get-ADUser' to 'Get-ADGroup' expressions inside the filter.

Getting all AD distribution groups:

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

Gettiing all security groups in certain location:

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

Attributes that are returned by AD Group sync

If you run requests like above, the connector would return the following set of attributes which are default for the AD Group object:

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

You may need additional attributes about groups that are returned by sync. In this case you should add '-Properties prop1, prop2...' in your request. Or if you don't want to specify exact properties you can just leave '*' instead. For example, let's get all available information about all security groups in a domain:

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

As we mentioned above, running '-Properties *' significantly decreases performance, so we suggest specifying only those properties that you need. For example:

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

In the example above we will get all basic attributes that are mentioned in this chapter and + CN and WhenCreated attributes.

You can request the following properties in your requests:

• CanonicalName - for example '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

Synchronizing AD File shares

The AD connector can synchronize file shares that are located on Windows Servers that are domain joined. Target Windows servers that contain file shares should run Windows Server 2012 R2 at least.

As file shares are located inside each separate server and AD does not manage them in the centralized way, the AD connector connects to each file share Windows server directly using PowerShell remoting and executes PowerShell commands using this remote session.

Based on the above, the AD connector service account should have permissions to connect to the file share server remotely. We assume that the AD connector server is joined to the same domain as the file share server. The AD connector should use a service account (regular user account that has certain permissions) from the same domain and this account should possess the ollowing permissions:

• Member of local 'Remote Management Users' group on the target file share server to be able to discover all file shares on the given server.
• Member of local 'Administrators' group on target file share server to be able to collect the set of permissions for each file share (who and what type of access does someone have for each file share).

To synchronize File shares, you should use 'Get-SmbSharesInfo' inside your synchronization query. The syntax is described below.

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

In this scenario the AD connector will try to connect to 'server1' and 'server2' to get information about file shares that are stored there.

Sometimes it may be useful to try to get information about all file shares inside your domain that are hosted on domain servers. In this case the following query can be useful:

Get-SmbSharesInfo -DomainController 'yourDCHostname'

When the AD connector receives the query above, it will try to connect to your domain controller (using credentials stored inside your managed system configuration) and pull all computers registered in AD. Having that list, the AD connector will try (using multithreading) to connect to each of them to collect information about file shares.

Getting permissions. To identity if the connector needs to collect permissions (who has which type of access for the file shares), the connector relies on the list of requested attributes from OpenIAM. The list of such attributes is set in the 'Attribute names lookup' parameter of the OpenIAM synchronization configuration page. If this list contains 'Permissions' attribute the connector will try to pull permissions for each file share that was found. If this attribute will not be listed the connector will skip this operation.

Incremental sync of users or groups

When you run incremental sync, OpenIAM relies on the time of last user/group modification in AD. Each user or group in AD has a property that is updated each time the object is modified. In the PowerShell connector you can use 'Mdified' property to address that value.

When you run synchronization, you can use the following query to get objects that are modified later than a certain date:

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

In this example OpenIAM will replace '?' with a real value during runtime and send a modified string to the connector.

Additionally, OpenIAM should send information about the time format that it should receive from connector. We need this because OpenIAM and the connector run on different platforms and need agrement about how to treat DateTime strings. The format should be sent in request metadata and the parameter name should be 'DateTimeStringFormat'. You can use following format:

The above setting could be changed in the configuration of your Managed System.

Connector Troubleshooting and Tips

Connector troubleshooting is covered in the document that describes all .NET/PowerShell connector usage: PowerShell connector usage. Troubleshooting steps are the same for all connectors of this type. Following information is specific for this connector.

• 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 the member of a domain. Specifying an IP address may lead to non-obvious errors.
• Port 9389 should be opened on the domain controller side so the connector could reach it. It should be opened almost in all cases.
• Sometimes it is useful to try a connection to AD in the same way as the AD connector does to make sure that the AD connector would work. You may run a tiny script to validate connection:

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 thanks to feedback from our customers. These have been the ones most frequently reported.