> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/microsoft/4-adpowershell.md).
# Active Directory PowerShell connector
This page describes how to use the OpenIAM Active Directory connector
## Active Directory PowerShell connector
The Active Directory connector is the one most OpenIAM deployments start with. It manages four kinds of object in AD — **users, groups, computers and file shares** — from a Windows host that reaches a domain controller, and exchanges requests with OpenIAM over RabbitMQ.
| Operation | Users | Groups | Computers | File shares |
| ------------------------ | ---------------------- | --------------------------- | ---------------------- | ------------------------------------ |
| Create / update (Save) | ✅ | ✅ | ✅ | ✅ |
| Delete | ✅ | ✅ | ✅ | ✅ |
| Search and synchronize | ✅ | ✅ | ✅ | ✅ |
| Suspend | ✅ Disables the account | ❌ AD cannot disable a group | ✅ Disables the account | ⚠️ **Removes the share** — see below |
| Resume | ✅ | ❌ | ✅ | ⚠️ Re-creates the share |
| Reset password | ✅ | ❌ | ❌ | ❌ |
| Check a password (Login) | ✅ | ❌ | ❌ | ❌ |
| Test connection | ✅ | | | |
{% hint style="warning" %}
**Suspending a file share deletes it.** AD has no notion of a disabled share, so the connector routes suspend to its delete path: access is closed by removing the share, and the data is left in the physical folder. Resume re-creates it. Anyone running a leaver process that suspends everything a user owns should know this before pointing it at file shares.
{% endhint %}
There is no separate create operation — OpenIAM sends a save, and the connector looks the identity up first, creating the object only when it does not find one.
### Use cases
* **Provisioning joiners** — creating the account, setting its attributes, putting it in the groups its role entitles it to, and enabling it once the password is set.
* **Keeping AD in step with HR data** as people move between departments, sites and managers.
* **Leavers** — disabling the account, then deleting it when the retention period ends.
* **Reconciling AD into OpenIAM**, including group membership, with full or incremental synchronization.
* **Managing computers and file shares** alongside the people who use them.
### Versions and compatibility
The end application is **Active Directory**, reached through the **ActiveDirectory PowerShell module** on the connector host rather than through LDAP. The connector has no version range of its own: its attribute names are the module's own cmdlet parameters — `New-ADUser`, `Set-ADUser`, `New-ADGroup`, `Set-ADGroup`, `New-ADComputer` — which is what [Attribute mapping and policy map](#attribute-mapping-and-policy-map) documents.
**Port 9389** must be open on the domain controller, since that is the AD Web Services port the module uses.
### Prerequisites
The operating system, `.NET Framework` and PowerShell requirements are the same for every .NET/PowerShell connector and are listed once in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#basic-requirements). Beyond those:
* The **ActiveDirectory PowerShell module** on the connector host.
* Network access to a domain controller on **port 9389**.
* A **service account** in the target domain with rights over the objects you intend to manage — see [Configuring the managed system](#configuring-the-managed-system).
### Installing the connector
Every .NET/PowerShell connector installs the same way. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md).
Where you put this one matters more than most:
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*.
### Starting, stopping, and restarting
The installer registers a pair of Windows services named after the connector name you supply. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#starting-stopping-and-restarting).
### Command-line parameters and properties
The connector takes no command-line parameters. Queue names, concurrency, logging, simulation mode and the RabbitMQ settings live in `Connector.config`, documented for the whole family in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md#working-with-the-connector-configuration).
### Verifying the connector is running
{% stepper %}
{% step %}
Confirm the connector's Windows services are running on the host.
{% endstep %}
{% step %}
Check that the connector's request queue in RabbitMQ has a consumer.
{% endstep %}
{% step %}
Run **Test Connection** on the managed system.
{% endstep %}
{% step %}
Run a search to prove the path end to end.
{% endstep %}
{% endstepper %}
### Troubleshooting
Connector troubleshooting is covered in the document that describes all .NET/PowerShell connector usage: [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md). Troubleshooting steps are the same for all connectors of this type. Following information is specific for this connector.
* **Use a domain name or FQDN — not an IP address — in the Managed System configuration.** When the connector server is a member of the same domain as the target AD, using a domain name or FQDN allows the connector to authenticate via Kerberos, which provides mutual authentication of the domain controller. If an IP address is used instead, the connection falls back to NTLM, which offers no mutual authentication and is considered lower security.
Preferred configurations (in order):
* `example.local` — the domain name; the connector resolves the nearest domain controller itself and uses Kerberos.
* `dc01.example.local` — an explicit FQDN of a specific domain controller, also uses Kerberos.
* `192.168.1.10` — an IP address; connection falls back to NTLM. **Avoid this in production.**
The connector raises a warning in its logs, and sends it back to OpenIAM, whenever an IP address is detected in the Managed System configuration:
> *AD server '192.168.1.10' is configured in the Managed System configuration as an IP address, so the connection to AD uses NTLM with no Kerberos mutual authentication of the domain controller. For best security, run the connector inside the same domain and configure the AD server as an FQDN — Kerberos is then used. The current configuration still works but at a reduced security level.*
The connector continues to function when an IP address is used, but the security level is reduced.
* 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:
{% code overflow="wrap" %}
```powershell
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:
```
{% endcode %}
#### Possible errors
Errors in the table below are captured thanks to feedback from our customers. These have been the ones most frequently reported.
| Symptom | Likely cause | Resolution |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cannot find newly created user X for further operations` | This is a top stack trace error indicating that the connector cannot process request due to error that occurred earlier. However, other information is not usually taken into account when such messages appear on the top. | Read full error message, as it should contain exact reason why the connector failed to create an object. |
| `Script that was specified for execution does not exist - xxx` | This message appears in logs if one specifies 'Add/Modify' (or other operations) Object Rules parameter inside the OpenIAM Managed System configuration. That section allows users to have custom scripts that handle exact operations. However, by default the connector uses the default Connector.ps1 script that is located inside the connector folder. So, if you have that value specified, you need to make sure that there is a custom handler present inside the connector folder. | Either remove the value and set it to empty which will make the connector work with the default script, or make sure that the custom connector script exists. |
| `X : The name provided is not a properly formed account name` | You are trying to create an object (where X is an object type), but trying to set SamAccountName more than 20 symbols which is not compatible. | Try setting SamAccountName to have less than 20 symbols. Check/fix provisioning groovy script at policy map for SamAccountName attribute |
| `Cannot process argument transformation on parameter 'Credential'. A command that alerts the user failed because the host program or the command type does not support user interaction` | This error occurs if you try to run sync but have not specified the password inside the Managed System configuration | Set password in the Managed System configuration |
### Registering the connector in OpenIAM
The connector's request queue name in OpenIAM has to match the queue in the connector's own `Connector.config` exactly. Getting the connection parameters out of OpenIAM and into the installer is covered in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#getting-connection-parameters-with-openiam).
### Configuring the managed system
Follow the standard steps in [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md). What is specific to this connector is the service account and the scope you give it.
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 the connector to part of the directory**
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.
### Attribute mapping and policy map
The connector holds no fixed attribute list. On each operation it asks PowerShell what the target cmdlet accepts — `New-ADUser`, `Set-ADUser`, `New-ADGroup`, `Set-ADGroup` or `New-ADComputer` — and passes through whatever matches. The tables below are therefore the module's own parameters: the descriptions say what each one is for, and Microsoft's cmdlet reference carries the detail. An attribute the cmdlet does not recognize is dropped rather than rejected, so a typo in the policy map fails quietly.
**Eighteen attributes are the connector's own** rather than cmdlet parameters. They tell it how to process the request and have no counterpart in the directory, so a DELETE operation on one of them clears nothing in AD: `RemoveUnknownGroupMembership`, `RemoveUnknownGroupMembers`, `EnvironmentControllers`, `LockedOut`, `Type`, `saveSimulation`, `UNCPath`, `PublishedLDAPPath`, `PreviousPublishedLDAPPath`, `PermissionsSet`, `OverwriteWithPermissions`, `DFSNPath`, `DFSNTargetPath`, `FileServerAddress`, `SMBFileServerAddress`, `SMBShareName`, `SMBPermissionsSet` and `SMBOverwriteWithPermissions`.
#### User provisioning
**Principal** - SamAccountName
| Parameter | Description | Required | Type |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of a user object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `AccountExpirationDate` | Specifies the expiration date for an account. | No | DateTime, for example "10/18/2018" |
| `AccountNotDelegated` | Indicates whether the security context of the user is delegated to a service. | No | True, False |
| `AccountPassword` | Specifies a new password value for an account. User accounts, by default, are created without a password. If you provide a password, an attempt will be made to set that password however, this can fail due to password policy restrictions. To have the new account enabled you should set AccountPassword and Enabled attribute both. | No if account initially not supposed to be enabled, Yes if it should be enabled | String |
| `AllowReversiblePasswordEncryption` | Indicates whether reversible password encryption is allowed for the account. | No | True, False |
| `CannotChangePassword` | Indicates whether the account password can be changed. This parameter sets the CannotChangePassword property of an account. | No | True, False |
| `ChangePasswordAtLogon` | Indicates whether a password must be changed during the next logon attempt. | No | True, False |
| `City` | Specifies the user's town or city. | No | String |
| `Company` | Specifies the user's company. | No | String |
| `Country` | Specifies the country or region code for the user's language of choice. | No | String |
| `Department` | Specifies the user's department. | No | String |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. | No | String |
| `Division` | Specifies the user's division. | No | String |
| `EmailAddress` | Specifies the user's e-mail address. | No | String |
| `EmployeeID` | Specifies the user's employee ID. | No | String |
| `EmployeeNumber` | Specifies the user's employee number. | No | String |
| `Enabled` | Specifies if an account is enabled. | No | True, False |
| `Fax` | Specifies the user's fax phone number. | No | String |
| `FolderName` | The path to the local folder that should be created or modified for provisioned user. | No | String C:\TestFolder |
| `GivenName` | Specifies the user's given name. | No | String |
| `MemberOf` | The list of groups distinguished names to which the current user should belong. Contains the dictionary of Key-Value pairs. Key – Distinguished name (DN) of the group for the operation. Value – 'add' or 'nochange' or 'delete'. On user creation only add or nochange values are accepted and mean the same. | No | Dictionary of Key-Value |
| `HomeDirectory` | Specifies a user's home directory. | No | String |
| `HomeDrive` | Specifies a drive that is associated with the UNC path defined by the HomeDirectory property. | No | String |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `HomePhone` | Specifies the user's home telephone number. | No | String |
| `Initials` | Specifies the initials that represent part of a user's name. | No | String |
| `KerberosEncryptionType` | Specifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. | No | String, one of the ones set in description |
| `LogonWorkstations` | Specifies the computers that the user can access. | No | String or multiple strings separated by comma (','), without whitespaces at separator |
| `Manager` | Sets manager for specified user. | No | String (SamAccountName) |
| `MobilePhone` | Specifies the user's mobile phone number. | No | String |
| `Office` | Specifies the location of the user's office or place of business. | No | String |
| `OfficePhone` | Specifies the user's office telephone number. | No | String |
| `Organization` | Specifies the user's organization. | No | String |
| `OtherName` | Specifies a name in addition to a user's given name and surname, such as the user's middle name. | No | String |
| `POBox` | Specifies the user's post office box number. | No | String |
| `PasswordNeverExpires` | Specifies whether the password of an account can expire. | No | String |
| `PasswordNotRequired` | Specifies whether the account requires a password. | No | True, False |
| `Path` | Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. | No | String. Example: OU=TestUsers,DC=DC1,DC=local |
| `Permissions` | Is applied only if folderName parameter is set. | No | Dictionary of Key-Value |
| `PostalCode` | Specifies the user's postal code or zip code. | No | String |
| `PrincipalsAllowedToDelegateToAccount` | Specifies an array of principal objects. | No | String (SamAccountName) |
| `ProfilePath` | Specifies a path to the user's profile. | No | String |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 20 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. | No | String |
| `ScriptPath` | Specifies a path to the user's log on script. | No | String |
| `SmartcardLogonRequired` | Specifies whether a smart card is required to log on. | No | True, False |
| `State` | Specifies the user's or Organizational Unit's state or province. | No | String |
| `StreetAddress` | Specifies the user's street address. | No | String |
| `Surname` | Specifies the user's last name or surname. | No | String |
| `Title` | Specifies the user's title. | No | String |
| `TrustedForDelegation` | Indicates whether an account is trusted for Kerberos delegation. | No | True, False |
| `UserPrincipalName` | Specifies a user principal name (UPN) in the format user\@DNS-domain-name. | No | String. Example user\@DNS-domain-name |
| `SMBFileServerAddress` | If you need to set SMB permissions to some folder for this user - this is the file server address | No | DNS Hostname |
| `SMBShareName` | If you need to set SMB permissions to some folder for this user - this is the Name of the SMB file share on the target server above | No | DNS Hostname |
| `SMBPermissionsSet` | Contains JSON descriptions of permissions that need to be merged with current permissions. | No | JSON |
| `SMBOverwriteWithPermissions` | Contains JSON descriptions of permissions that need to overwrite with current permissions. | No | JSON |
| `Certificates` | This attribute allows you to manage certificates for a specific user (that is, assign or delete certificates). Also, it must contain the Base64 format of the certificate in one line, without the headers '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----', spaces, and new lines. The certificate itself must be an X.509v3 certificate. **Note:** to delete all certificates from a user, this attribute must be empty and the DELETE operation. | No | String |
| `RemoveUnknownGroupMembership` | **Removes the user from any Active Directory group that OpenIAM does not know about.** When `True`, the connector reads the user's real group memberships and removes every one absent from the `MemberOf` map in the request. If that map is empty the connector refuses and logs a warning, rather than stripping every membership — an empty map means "no membership data in this request", not "this user belongs to nothing". To remove memberships deliberately, send explicit DELETE operations per group instead. | No | Boolean |
#### Group provisioning
**Principal** - SamAccountName
To add the new group, OpenIAM should send two attributes:
* Name
* GroupScope (DomainLocal or Global or Universal)
| Parameter | Description | Required | Type |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `GroupScope` | Specifies the scope of the group. | Yes | String |
| `MemberOf` | Key-Value pair, sets the groups in which the current group should be added. | No | Key-Value |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. The LDAP display name (ldapDisplayName) for this property is displayName. | No | String |
| `GroupCategory` | Specifies the category of the group. | No | String |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `Instance` | Specifies an instance of a group object to use as a template for a new group object. | No | String |
| `Members` | Should contain key-value pair if you need to input some members inside the current group. Key – Distinguished name of the object (user) for the operation. Value – 'add' or 'nochange' or 'delete'. On user creation only add or nochange values are accepted and mean the same (adding the member for the current group) | No | Key-Value |
| `ManagedBy` | Specifies the user or group that manages the object by providing one of the following property values. | No | String |
| `Path` | Specifies the destination Path in DistinguishedName format for the newly created object | No | String |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 20 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. | No | String |
| `RemoveUnknownGroupMembership` | **Removes this group from any parent group that OpenIAM does not know about.** The group equivalent of the user attribute of the same name: the connector reads the groups this one belongs to and removes every one absent from the `MemberOf` map. An empty map is refused with a warning rather than acted on. | No | Boolean |
| `RemoveUnknownGroupMembers` | **Removes members from this group when OpenIAM does not know about them.** The opposite direction to the attribute above: the connector reads the group's real members and removes every one absent from the `Members` map in the request. An empty map is refused with a warning rather than acted on. | No | Boolean |
**OpenIAM configuration**
To enable group provisioning add group provision filed to the managed system. Go to *Webconsole* -> *Provisioning* -> *Connectors* -> *AD Powershell CONNECTOR* -> *Connector configuration* and set checkboxes in front of:
* Base DN for Group
* Object Primary Key for Group
* Search Base DN for Group
* Search Filter for Group
Save changes. Go to managed system edit page and populate new fields for group, save changes. Make sure that you have policy map for group object, if not - create one, use out of the box managed system to copy policy map.
Now each group linked with the AD managed system will be identity generated and will be provisioned to AD.
#### Computer provisioning
**Principal** - SamAccountName
| Parameter | Description | Required | Type |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `AccountExpirationDate` | Specifies the expiration date for an account. | No | DateTime, for example "10/18/2018" |
| `AccountNotDelegated` | Specifies whether the security context of the user is delegated to a service. | No | True, False |
| `AllowReversiblePasswordEncryption` | Specifies whether reversible password encryption is allowed for the account. | No | True, False |
| `AuthenticationPolicy` | Specifies an Active Directory Domain Services authentication policy object. | No | String |
| `AuthenticationPolicySilo` | Specifies an Active Directory Domain Services authentication policy silo object. | No | String |
| `CannotChangePassword` | Specifies whether the account password can be changed. This parameter sets the CannotChangePassword property of an account. | No | True, False |
| `ChangePasswordAtLogon` | Specifies whether a password must be changed during the next log on attempt. | No | True, False |
| `CompoundIdentitySupported` | Specifies whether an account supports Kerberos service tickets which includes the authorization data for the user's device. | No | True, False |
| `DNSHostName` | Specifies the fully qualified domain name (FQDN) of the computer. | No | String |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. | No | String |
| `Enabled` | Specifies if an account is enabled. | No | True, False |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `KerberosEncryptionType` | Specifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. | No | String |
| `Location` | Specifies the location of the computer, such as an office number. | No | String |
| `ManagedBy` | Specifies the user or group that manages the object by providing one of the following property values. | No | String |
| `OperatingSystem` | Specifies an operating system name. | No | String |
| `OperatingSystemHotfix` | Specifies an operating system hotfix name. | No | String |
| `OperatingSystemServicePack` | Specifies the name of an operating system service pack. | No | String |
| `OperatingSystemVersion` | Specifies an operating system version. | No | String |
| `PasswordNeverExpires` | Specifies whether the password of an account can expire. | No | True, False |
| `PasswordNotRequired` | Specifies whether the account requires a password. | No | True, False |
| `Path` | Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. | No | String (DN format) |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 15 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. Note: If the SamAccountName string provided does not end with a $, a $ will be appended if needed. | No | String |
| `TrustedForDelegation` | Specifies whether an account is trusted for Kerberos delegation. | No | True, False |
| `UserPrincipalName` | Specifies a user principal name (UPN) in the format user\@DNS-domain-name. | No | String. Example: user\@DNS-domain-name |
### \*\*A computer object's `SamAccountName` silently gains a \`--- description: This page describes how to use the OpenIAM Active Directory connector icon: microsoft layout: width: wide title: visible: true description: visible: true tableOfContents: visible: true outline: visible: true pagination: visible: true metadata: visible: true tags: visible: true actions: visible: true anchors: visible: true
## Active Directory PowerShell connector
The Active Directory connector is the one most OpenIAM deployments start with. It manages four kinds of object in AD — **users, groups, computers and file shares** — from a Windows host that reaches a domain controller, and exchanges requests with OpenIAM over RabbitMQ.
| Operation | Users | Groups | Computers | File shares |
| ------------------------ | ---------------------- | --------------------------- | ---------------------- | ------------------------------------ |
| Create / update (Save) | ✅ | ✅ | ✅ | ✅ |
| Delete | ✅ | ✅ | ✅ | ✅ |
| Search and synchronize | ✅ | ✅ | ✅ | ✅ |
| Suspend | ✅ Disables the account | ❌ AD cannot disable a group | ✅ Disables the account | ⚠️ **Removes the share** — see below |
| Resume | ✅ | ❌ | ✅ | ⚠️ Re-creates the share |
| Reset password | ✅ | ❌ | ❌ | ❌ |
| Check a password (Login) | ✅ | ❌ | ❌ | ❌ |
| Test connection | ✅ | | | |
{% hint style="warning" %} **Suspending a file share deletes it.** AD has no notion of a disabled share, so the connector routes suspend to its delete path: access is closed by removing the share, and the data is left in the physical folder. Resume re-creates it. Anyone running a leaver process that suspends everything a user owns should know this before pointing it at file shares. {% endhint %}
There is no separate create operation — OpenIAM sends a save, and the connector looks the identity up first, creating the object only when it does not find one.
### Use cases
* **Provisioning joiners** — creating the account, setting its attributes, putting it in the groups its role entitles it to, and enabling it once the password is set.
* **Keeping AD in step with HR data** as people move between departments, sites and managers.
* **Leavers** — disabling the account, then deleting it when the retention period ends.
* **Reconciling AD into OpenIAM**, including group membership, with full or incremental synchronization.
* **Managing computers and file shares** alongside the people who use them.
### Versions and compatibility
The end application is **Active Directory**, reached through the **ActiveDirectory PowerShell module** on the connector host rather than through LDAP. The connector has no version range of its own: its attribute names are the module's own cmdlet parameters — `New-ADUser`, `Set-ADUser`, `New-ADGroup`, `Set-ADGroup`, `New-ADComputer` — which is what [Attribute mapping and policy map](#attribute-mapping-and-policy-map) documents.
**Port 9389** must be open on the domain controller, since that is the AD Web Services port the module uses.
### Prerequisites
The operating system, `.NET Framework` and PowerShell requirements are the same for every .NET/PowerShell connector and are listed once in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#basic-requirements). Beyond those:
* The **ActiveDirectory PowerShell module** on the connector host.
* Network access to a domain controller on **port 9389**.
* A **service account** in the target domain with rights over the objects you intend to manage — see [Configuring the managed system](#configuring-the-managed-system).
### Installing the connector
Every .NET/PowerShell connector installs the same way. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md).
Where you put this one matters more than most:
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*.
### Starting, stopping, and restarting
The installer registers a pair of Windows services named after the connector name you supply. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#starting-stopping-and-restarting).
### Command-line parameters and properties
The connector takes no command-line parameters. Queue names, concurrency, logging, simulation mode and the RabbitMQ settings live in `Connector.config`, documented for the whole family in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md#working-with-the-connector-configuration).
### Verifying the connector is running
{% stepper %} {% step %} Confirm the connector's Windows services are running on the host. {% endstep %}
{% step %} Check that the connector's request queue in RabbitMQ has a consumer. {% endstep %}
{% step %} Run **Test Connection** on the managed system. {% endstep %}
{% step %} Run a search to prove the path end to end. {% endstep %} {% endstepper %}
### Troubleshooting
Connector troubleshooting is covered in the document that describes all .NET/PowerShell connector usage: [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md). Troubleshooting steps are the same for all connectors of this type. Following information is specific for this connector.
* **Use a domain name or FQDN — not an IP address — in the Managed System configuration.** When the connector server is a member of the same domain as the target AD, using a domain name or FQDN allows the connector to authenticate via Kerberos, which provides mutual authentication of the domain controller. If an IP address is used instead, the connection falls back to NTLM, which offers no mutual authentication and is considered lower security.
Preferred configurations (in order):
* `example.local` — the domain name; the connector resolves the nearest domain controller itself and uses Kerberos.
* `dc01.example.local` — an explicit FQDN of a specific domain controller, also uses Kerberos.
* `192.168.1.10` — an IP address; connection falls back to NTLM. **Avoid this in production.**
The connector raises a warning in its logs, and sends it back to OpenIAM, whenever an IP address is detected in the Managed System configuration:
> *AD server '192.168.1.10' is configured in the Managed System configuration as an IP address, so the connection to AD uses NTLM with no Kerberos mutual authentication of the domain controller. For best security, run the connector inside the same domain and configure the AD server as an FQDN — Kerberos is then used. The current configuration still works but at a reduced security level.*
The connector continues to function when an IP address is used, but the security level is reduced.
* 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:
{% code overflow="wrap" %}
```powershell
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.
| Symptom | Likely cause | Resolution |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cannot find newly created user X for further operations` | This is a top stack trace error indicating that the connector cannot process request due to error that occurred earlier. However, other information is not usually taken into account when such messages appear on the top. | Read full error message, as it should contain exact reason why the connector failed to create an object. |
| `Script that was specified for execution does not exist - xxx` | This message appears in logs if one specifies 'Add/Modify' (or other operations) Object Rules parameter inside the OpenIAM Managed System configuration. That section allows users to have custom scripts that handle exact operations. However, by default the connector uses the default Connector.ps1 script that is located inside the connector folder. So, if you have that value specified, you need to make sure that there is a custom handler present inside the connector folder. | Either remove the value and set it to empty which will make the connector work with the default script, or make sure that the custom connector script exists. |
| `X : The name provided is not a properly formed account name` | You are trying to create an object (where X is an object type), but trying to set SamAccountName more than 20 symbols which is not compatible. | Try setting SamAccountName to have less than 20 symbols. Check/fix provisioning groovy script at policy map for SamAccountName attribute |
| `Cannot process argument transformation on parameter 'Credential'. A command that alerts the user failed because the host program or the command type does not support user interaction` | This error occurs if you try to run sync but have not specified the password inside the Managed System configuration | Set password in the Managed System configuration |
### Registering the connector in OpenIAM
The connector's request queue name in OpenIAM has to match the queue in the connector's own `Connector.config` exactly. Getting the connection parameters out of OpenIAM and into the installer is covered in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#getting-connection-parameters-with-openiam).
### Configuring the managed system
Follow the standard steps in [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md). What is specific to this connector is the service account and the scope you give it.
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 the connector to part of the directory**
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.
### Attribute mapping and policy map
The connector holds no fixed attribute list. On each operation it asks PowerShell what the target cmdlet accepts — `New-ADUser`, `Set-ADUser`, `New-ADGroup`, `Set-ADGroup` or `New-ADComputer` — and passes through whatever matches. The tables below are therefore the module's own parameters: the descriptions say what each one is for, and Microsoft's cmdlet reference carries the detail. An attribute the cmdlet does not recognize is dropped rather than rejected, so a typo in the policy map fails quietly.
**Eighteen attributes are the connector's own** rather than cmdlet parameters. They tell it how to process the request and have no counterpart in the directory, so a DELETE operation on one of them clears nothing in AD: `RemoveUnknownGroupMembership`, `RemoveUnknownGroupMembers`, `EnvironmentControllers`, `LockedOut`, `Type`, `saveSimulation`, `UNCPath`, `PublishedLDAPPath`, `PreviousPublishedLDAPPath`, `PermissionsSet`, `OverwriteWithPermissions`, `DFSNPath`, `DFSNTargetPath`, `FileServerAddress`, `SMBFileServerAddress`, `SMBShareName`, `SMBPermissionsSet` and `SMBOverwriteWithPermissions`.
#### User provisioning
**Principal** - SamAccountName
| Parameter | Description | Required | Type |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of a user object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `AccountExpirationDate` | Specifies the expiration date for an account. | No | DateTime, for example "10/18/2018" |
| `AccountNotDelegated` | Indicates whether the security context of the user is delegated to a service. | No | True, False |
| `AccountPassword` | Specifies a new password value for an account. User accounts, by default, are created without a password. If you provide a password, an attempt will be made to set that password however, this can fail due to password policy restrictions. To have the new account enabled you should set AccountPassword and Enabled attribute both. | No if account initially not supposed to be enabled, Yes if it should be enabled | String |
| `AllowReversiblePasswordEncryption` | Indicates whether reversible password encryption is allowed for the account. | No | True, False |
| `CannotChangePassword` | Indicates whether the account password can be changed. This parameter sets the CannotChangePassword property of an account. | No | True, False |
| `ChangePasswordAtLogon` | Indicates whether a password must be changed during the next logon attempt. | No | True, False |
| `City` | Specifies the user's town or city. | No | String |
| `Company` | Specifies the user's company. | No | String |
| `Country` | Specifies the country or region code for the user's language of choice. | No | String |
| `Department` | Specifies the user's department. | No | String |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. | No | String |
| `Division` | Specifies the user's division. | No | String |
| `EmailAddress` | Specifies the user's e-mail address. | No | String |
| `EmployeeID` | Specifies the user's employee ID. | No | String |
| `EmployeeNumber` | Specifies the user's employee number. | No | String |
| `Enabled` | Specifies if an account is enabled. | No | True, False |
| `Fax` | Specifies the user's fax phone number. | No | String |
| `FolderName` | The path to the local folder that should be created or modified for provisioned user. | No | String C:\TestFolder |
| `GivenName` | Specifies the user's given name. | No | String |
| `MemberOf` | The list of groups distinguished names to which the current user should belong. Contains the dictionary of Key-Value pairs. Key – Distinguished name (DN) of the group for the operation. Value – 'add' or 'nochange' or 'delete'. On user creation only add or nochange values are accepted and mean the same. | No | Dictionary of Key-Value |
| `HomeDirectory` | Specifies a user's home directory. | No | String |
| `HomeDrive` | Specifies a drive that is associated with the UNC path defined by the HomeDirectory property. | No | String |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `HomePhone` | Specifies the user's home telephone number. | No | String |
| `Initials` | Specifies the initials that represent part of a user's name. | No | String |
| `KerberosEncryptionType` | Specifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. | No | String, one of the ones set in description |
| `LogonWorkstations` | Specifies the computers that the user can access. | No | String or multiple strings separated by comma (','), without whitespaces at separator |
| `Manager` | Sets manager for specified user. | No | String (SamAccountName) |
| `MobilePhone` | Specifies the user's mobile phone number. | No | String |
| `Office` | Specifies the location of the user's office or place of business. | No | String |
| `OfficePhone` | Specifies the user's office telephone number. | No | String |
| `Organization` | Specifies the user's organization. | No | String |
| `OtherName` | Specifies a name in addition to a user's given name and surname, such as the user's middle name. | No | String |
| `POBox` | Specifies the user's post office box number. | No | String |
| `PasswordNeverExpires` | Specifies whether the password of an account can expire. | No | String |
| `PasswordNotRequired` | Specifies whether the account requires a password. | No | True, False |
| `Path` | Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. | No | String. Example: OU=TestUsers,DC=DC1,DC=local |
| `Permissions` | Is applied only if folderName parameter is set. | No | Dictionary of Key-Value |
| `PostalCode` | Specifies the user's postal code or zip code. | No | String |
| `PrincipalsAllowedToDelegateToAccount` | Specifies an array of principal objects. | No | String (SamAccountName) |
| `ProfilePath` | Specifies a path to the user's profile. | No | String |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 20 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. | No | String |
| `ScriptPath` | Specifies a path to the user's log on script. | No | String |
| `SmartcardLogonRequired` | Specifies whether a smart card is required to log on. | No | True, False |
| `State` | Specifies the user's or Organizational Unit's state or province. | No | String |
| `StreetAddress` | Specifies the user's street address. | No | String |
| `Surname` | Specifies the user's last name or surname. | No | String |
| `Title` | Specifies the user's title. | No | String |
| `TrustedForDelegation` | Indicates whether an account is trusted for Kerberos delegation. | No | True, False |
| `UserPrincipalName` | Specifies a user principal name (UPN) in the format user\@DNS-domain-name. | No | String. Example user\@DNS-domain-name |
| `SMBFileServerAddress` | If you need to set SMB permissions to some folder for this user - this is the file server address | No | DNS Hostname |
| `SMBShareName` | If you need to set SMB permissions to some folder for this user - this is the Name of the SMB file share on the target server above | No | DNS Hostname |
| `SMBPermissionsSet` | Contains JSON descriptions of permissions that need to be merged with current permissions. | No | JSON |
| `SMBOverwriteWithPermissions` | Contains JSON descriptions of permissions that need to overwrite with current permissions. | No | JSON |
| `Certificates` | This attribute allows you to manage certificates for a specific user (that is, assign or delete certificates). Also, it must contain the Base64 format of the certificate in one line, without the headers '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----', spaces, and new lines. The certificate itself must be an X.509v3 certificate. **Note:** to delete all certificates from a user, this attribute must be empty and the DELETE operation. | No | String |
| `RemoveUnknownGroupMembership` | **Removes the user from any Active Directory group that OpenIAM does not know about.** When `True`, the connector reads the user's real group memberships and removes every one absent from the `MemberOf` map in the request. If that map is empty the connector refuses and logs a warning, rather than stripping every membership — an empty map means "no membership data in this request", not "this user belongs to nothing". To remove memberships deliberately, send explicit DELETE operations per group instead. | No | Boolean |
#### Group provisioning
**Principal** - SamAccountName
To add the new group, OpenIAM should send two attributes:
* Name
* GroupScope (DomainLocal or Global or Universal)
| Parameter | Description | Required | Type |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `GroupScope` | Specifies the scope of the group. | Yes | String |
| `MemberOf` | Key-Value pair, sets the groups in which the current group should be added. | No | Key-Value |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. The LDAP display name (ldapDisplayName) for this property is displayName. | No | String |
| `GroupCategory` | Specifies the category of the group. | No | String |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `Instance` | Specifies an instance of a group object to use as a template for a new group object. | No | String |
| `Members` | Should contain key-value pair if you need to input some members inside the current group. Key – Distinguished name of the object (user) for the operation. Value – 'add' or 'nochange' or 'delete'. On user creation only add or nochange values are accepted and mean the same (adding the member for the current group) | No | Key-Value |
| `ManagedBy` | Specifies the user or group that manages the object by providing one of the following property values. | No | String |
| `Path` | Specifies the destination Path in DistinguishedName format for the newly created object | No | String |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 20 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. | No | String |
| `RemoveUnknownGroupMembership` | **Removes this group from any parent group that OpenIAM does not know about.** The group equivalent of the user attribute of the same name: the connector reads the groups this one belongs to and removes every one absent from the `MemberOf` map. An empty map is refused with a warning rather than acted on. | No | Boolean |
| `RemoveUnknownGroupMembers` | **Removes members from this group when OpenIAM does not know about them.** The opposite direction to the attribute above: the connector reads the group's real members and removes every one absent from the `Members` map in the request. An empty map is refused with a warning rather than acted on. | No | Boolean |
**OpenIAM configuration**
To enable group provisioning add group provision filed to the managed system. Go to *Webconsole* -> *Provisioning* -> *Connectors* -> *AD Powershell CONNECTOR* -> *Connector configuration* and set checkboxes in front of:
* Base DN for Group
* Object Primary Key for Group
* Search Base DN for Group
* Search Filter for Group
Save changes. Go to managed system edit page and populate new fields for group, save changes. Make sure that you have policy map for group object, if not - create one, use out of the box managed system to copy policy map.
Now each group linked with the AD managed system will be identity generated and will be provisioned to AD.
#### Computer provisioning
**Principal** - SamAccountName
| Parameter | Description | Required | Type |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `AccountExpirationDate` | Specifies the expiration date for an account. | No | DateTime, for example "10/18/2018" |
| `AccountNotDelegated` | Specifies whether the security context of the user is delegated to a service. | No | True, False |
| `AllowReversiblePasswordEncryption` | Specifies whether reversible password encryption is allowed for the account. | No | True, False |
| `AuthenticationPolicy` | Specifies an Active Directory Domain Services authentication policy object. | No | String |
| `AuthenticationPolicySilo` | Specifies an Active Directory Domain Services authentication policy silo object. | No | String |
| `CannotChangePassword` | Specifies whether the account password can be changed. This parameter sets the CannotChangePassword property of an account. | No | True, False |
| `ChangePasswordAtLogon` | Specifies whether a password must be changed during the next log on attempt. | No | True, False |
| `CompoundIdentitySupported` | Specifies whether an account supports Kerberos service tickets which includes the authorization data for the user's device. | No | True, False |
| `DNSHostName` | Specifies the fully qualified domain name (FQDN) of the computer. | No | String |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. | No | String |
| `Enabled` | Specifies if an account is enabled. | No | True, False |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `KerberosEncryptionType` | Specifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. | No | String |
| `Location` | Specifies the location of the computer, such as an office number. | No | String |
| `ManagedBy` | Specifies the user or group that manages the object by providing one of the following property values. | No | String |
| `OperatingSystem` | Specifies an operating system name. | No | String |
| `OperatingSystemHotfix` | Specifies an operating system hotfix name. | No | String |
| `OperatingSystemServicePack` | Specifies the name of an operating system service pack. | No | String |
| `OperatingSystemVersion` | Specifies an operating system version. | No | String |
| `PasswordNeverExpires` | Specifies whether the password of an account can expire. | No | True, False |
| `PasswordNotRequired` | Specifies whether the account requires a password. | No | True, False |
| `Path` | Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. | No | String (DN format) |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 15 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. Note: If the SamAccountName string provided does not end with a $, a $ will be appended if needed. | No | String |
| `TrustedForDelegation` | Specifies whether an account is trusted for Kerberos delegation. | No | True, False |
| `UserPrincipalName` | Specifies a user principal name (UPN) in the format user\@DNS-domain-name. | No | String. Example: user\@DNS-domain-name |
### .\*\* Active Directory appends it to every computer account name. OpenIAM stores and shows the value without it — because the same principal may be used by other managed systems — and the connector adds it back on each request. So an identity you see as `value` reaches AD as \`value--- description: This page describes how to use the OpenIAM Active Directory connector icon: microsoft layout: width: wide title: visible: true description: visible: true tableOfContents: visible: true outline: visible: true pagination: visible: true metadata: visible: true tags: visible: true actions: visible: true anchors: visible: true
## Active Directory PowerShell connector
The Active Directory connector is the one most OpenIAM deployments start with. It manages four kinds of object in AD — **users, groups, computers and file shares** — from a Windows host that reaches a domain controller, and exchanges requests with OpenIAM over RabbitMQ.
| Operation | Users | Groups | Computers | File shares |
| ------------------------ | ---------------------- | --------------------------- | ---------------------- | ------------------------------------ |
| Create / update (Save) | ✅ | ✅ | ✅ | ✅ |
| Delete | ✅ | ✅ | ✅ | ✅ |
| Search and synchronize | ✅ | ✅ | ✅ | ✅ |
| Suspend | ✅ Disables the account | ❌ AD cannot disable a group | ✅ Disables the account | ⚠️ **Removes the share** — see below |
| Resume | ✅ | ❌ | ✅ | ⚠️ Re-creates the share |
| Reset password | ✅ | ❌ | ❌ | ❌ |
| Check a password (Login) | ✅ | ❌ | ❌ | ❌ |
| Test connection | ✅ | | | |
{% hint style="warning" %} **Suspending a file share deletes it.** AD has no notion of a disabled share, so the connector routes suspend to its delete path: access is closed by removing the share, and the data is left in the physical folder. Resume re-creates it. Anyone running a leaver process that suspends everything a user owns should know this before pointing it at file shares. {% endhint %}
There is no separate create operation — OpenIAM sends a save, and the connector looks the identity up first, creating the object only when it does not find one.
### Use cases
* **Provisioning joiners** — creating the account, setting its attributes, putting it in the groups its role entitles it to, and enabling it once the password is set.
* **Keeping AD in step with HR data** as people move between departments, sites and managers.
* **Leavers** — disabling the account, then deleting it when the retention period ends.
* **Reconciling AD into OpenIAM**, including group membership, with full or incremental synchronization.
* **Managing computers and file shares** alongside the people who use them.
### Versions and compatibility
The end application is **Active Directory**, reached through the **ActiveDirectory PowerShell module** on the connector host rather than through LDAP. The connector has no version range of its own: its attribute names are the module's own cmdlet parameters — `New-ADUser`, `Set-ADUser`, `New-ADGroup`, `Set-ADGroup`, `New-ADComputer` — which is what [Attribute mapping and policy map](#attribute-mapping-and-policy-map) documents.
**Port 9389** must be open on the domain controller, since that is the AD Web Services port the module uses.
### Prerequisites
The operating system, `.NET Framework` and PowerShell requirements are the same for every .NET/PowerShell connector and are listed once in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#basic-requirements). Beyond those:
* The **ActiveDirectory PowerShell module** on the connector host.
* Network access to a domain controller on **port 9389**.
* A **service account** in the target domain with rights over the objects you intend to manage — see [Configuring the managed system](#configuring-the-managed-system).
### Installing the connector
Every .NET/PowerShell connector installs the same way. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md).
Where you put this one matters more than most:
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*.
### Starting, stopping, and restarting
The installer registers a pair of Windows services named after the connector name you supply. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#starting-stopping-and-restarting).
### Command-line parameters and properties
The connector takes no command-line parameters. Queue names, concurrency, logging, simulation mode and the RabbitMQ settings live in `Connector.config`, documented for the whole family in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md#working-with-the-connector-configuration).
### Verifying the connector is running
{% stepper %} {% step %} Confirm the connector's Windows services are running on the host. {% endstep %}
{% step %} Check that the connector's request queue in RabbitMQ has a consumer. {% endstep %}
{% step %} Run **Test Connection** on the managed system. {% endstep %}
{% step %} Run a search to prove the path end to end. {% endstep %} {% endstepper %}
### Troubleshooting
Connector troubleshooting is covered in the document that describes all .NET/PowerShell connector usage: [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md). Troubleshooting steps are the same for all connectors of this type. Following information is specific for this connector.
* **Use a domain name or FQDN — not an IP address — in the Managed System configuration.** When the connector server is a member of the same domain as the target AD, using a domain name or FQDN allows the connector to authenticate via Kerberos, which provides mutual authentication of the domain controller. If an IP address is used instead, the connection falls back to NTLM, which offers no mutual authentication and is considered lower security.
Preferred configurations (in order):
* `example.local` — the domain name; the connector resolves the nearest domain controller itself and uses Kerberos.
* `dc01.example.local` — an explicit FQDN of a specific domain controller, also uses Kerberos.
* `192.168.1.10` — an IP address; connection falls back to NTLM. **Avoid this in production.**
The connector raises a warning in its logs, and sends it back to OpenIAM, whenever an IP address is detected in the Managed System configuration:
> *AD server '192.168.1.10' is configured in the Managed System configuration as an IP address, so the connection to AD uses NTLM with no Kerberos mutual authentication of the domain controller. For best security, run the connector inside the same domain and configure the AD server as an FQDN — Kerberos is then used. The current configuration still works but at a reduced security level.*
The connector continues to function when an IP address is used, but the security level is reduced.
* 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:
{% code overflow="wrap" %}
```powershell
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.
| Symptom | Likely cause | Resolution |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cannot find newly created user X for further operations` | This is a top stack trace error indicating that the connector cannot process request due to error that occurred earlier. However, other information is not usually taken into account when such messages appear on the top. | Read full error message, as it should contain exact reason why the connector failed to create an object. |
| `Script that was specified for execution does not exist - xxx` | This message appears in logs if one specifies 'Add/Modify' (or other operations) Object Rules parameter inside the OpenIAM Managed System configuration. That section allows users to have custom scripts that handle exact operations. However, by default the connector uses the default Connector.ps1 script that is located inside the connector folder. So, if you have that value specified, you need to make sure that there is a custom handler present inside the connector folder. | Either remove the value and set it to empty which will make the connector work with the default script, or make sure that the custom connector script exists. |
| `X : The name provided is not a properly formed account name` | You are trying to create an object (where X is an object type), but trying to set SamAccountName more than 20 symbols which is not compatible. | Try setting SamAccountName to have less than 20 symbols. Check/fix provisioning groovy script at policy map for SamAccountName attribute |
| `Cannot process argument transformation on parameter 'Credential'. A command that alerts the user failed because the host program or the command type does not support user interaction` | This error occurs if you try to run sync but have not specified the password inside the Managed System configuration | Set password in the Managed System configuration |
### Registering the connector in OpenIAM
The connector's request queue name in OpenIAM has to match the queue in the connector's own `Connector.config` exactly. Getting the connection parameters out of OpenIAM and into the installer is covered in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#getting-connection-parameters-with-openiam).
### Configuring the managed system
Follow the standard steps in [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md). What is specific to this connector is the service account and the scope you give it.
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 the connector to part of the directory**
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.
### Attribute mapping and policy map
The connector holds no fixed attribute list. On each operation it asks PowerShell what the target cmdlet accepts — `New-ADUser`, `Set-ADUser`, `New-ADGroup`, `Set-ADGroup` or `New-ADComputer` — and passes through whatever matches. The tables below are therefore the module's own parameters: the descriptions say what each one is for, and Microsoft's cmdlet reference carries the detail. An attribute the cmdlet does not recognize is dropped rather than rejected, so a typo in the policy map fails quietly.
**Eighteen attributes are the connector's own** rather than cmdlet parameters. They tell it how to process the request and have no counterpart in the directory, so a DELETE operation on one of them clears nothing in AD: `RemoveUnknownGroupMembership`, `RemoveUnknownGroupMembers`, `EnvironmentControllers`, `LockedOut`, `Type`, `saveSimulation`, `UNCPath`, `PublishedLDAPPath`, `PreviousPublishedLDAPPath`, `PermissionsSet`, `OverwriteWithPermissions`, `DFSNPath`, `DFSNTargetPath`, `FileServerAddress`, `SMBFileServerAddress`, `SMBShareName`, `SMBPermissionsSet` and `SMBOverwriteWithPermissions`.
#### User provisioning
**Principal** - SamAccountName
| Parameter | Description | Required | Type |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of a user object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `AccountExpirationDate` | Specifies the expiration date for an account. | No | DateTime, for example "10/18/2018" |
| `AccountNotDelegated` | Indicates whether the security context of the user is delegated to a service. | No | True, False |
| `AccountPassword` | Specifies a new password value for an account. User accounts, by default, are created without a password. If you provide a password, an attempt will be made to set that password however, this can fail due to password policy restrictions. To have the new account enabled you should set AccountPassword and Enabled attribute both. | No if account initially not supposed to be enabled, Yes if it should be enabled | String |
| `AllowReversiblePasswordEncryption` | Indicates whether reversible password encryption is allowed for the account. | No | True, False |
| `CannotChangePassword` | Indicates whether the account password can be changed. This parameter sets the CannotChangePassword property of an account. | No | True, False |
| `ChangePasswordAtLogon` | Indicates whether a password must be changed during the next logon attempt. | No | True, False |
| `City` | Specifies the user's town or city. | No | String |
| `Company` | Specifies the user's company. | No | String |
| `Country` | Specifies the country or region code for the user's language of choice. | No | String |
| `Department` | Specifies the user's department. | No | String |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. | No | String |
| `Division` | Specifies the user's division. | No | String |
| `EmailAddress` | Specifies the user's e-mail address. | No | String |
| `EmployeeID` | Specifies the user's employee ID. | No | String |
| `EmployeeNumber` | Specifies the user's employee number. | No | String |
| `Enabled` | Specifies if an account is enabled. | No | True, False |
| `Fax` | Specifies the user's fax phone number. | No | String |
| `FolderName` | The path to the local folder that should be created or modified for provisioned user. | No | String C:\TestFolder |
| `GivenName` | Specifies the user's given name. | No | String |
| `MemberOf` | The list of groups distinguished names to which the current user should belong. Contains the dictionary of Key-Value pairs. Key – Distinguished name (DN) of the group for the operation. Value – 'add' or 'nochange' or 'delete'. On user creation only add or nochange values are accepted and mean the same. | No | Dictionary of Key-Value |
| `HomeDirectory` | Specifies a user's home directory. | No | String |
| `HomeDrive` | Specifies a drive that is associated with the UNC path defined by the HomeDirectory property. | No | String |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `HomePhone` | Specifies the user's home telephone number. | No | String |
| `Initials` | Specifies the initials that represent part of a user's name. | No | String |
| `KerberosEncryptionType` | Specifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. | No | String, one of the ones set in description |
| `LogonWorkstations` | Specifies the computers that the user can access. | No | String or multiple strings separated by comma (','), without whitespaces at separator |
| `Manager` | Sets manager for specified user. | No | String (SamAccountName) |
| `MobilePhone` | Specifies the user's mobile phone number. | No | String |
| `Office` | Specifies the location of the user's office or place of business. | No | String |
| `OfficePhone` | Specifies the user's office telephone number. | No | String |
| `Organization` | Specifies the user's organization. | No | String |
| `OtherName` | Specifies a name in addition to a user's given name and surname, such as the user's middle name. | No | String |
| `POBox` | Specifies the user's post office box number. | No | String |
| `PasswordNeverExpires` | Specifies whether the password of an account can expire. | No | String |
| `PasswordNotRequired` | Specifies whether the account requires a password. | No | True, False |
| `Path` | Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. | No | String. Example: OU=TestUsers,DC=DC1,DC=local |
| `Permissions` | Is applied only if folderName parameter is set. | No | Dictionary of Key-Value |
| `PostalCode` | Specifies the user's postal code or zip code. | No | String |
| `PrincipalsAllowedToDelegateToAccount` | Specifies an array of principal objects. | No | String (SamAccountName) |
| `ProfilePath` | Specifies a path to the user's profile. | No | String |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 20 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. | No | String |
| `ScriptPath` | Specifies a path to the user's log on script. | No | String |
| `SmartcardLogonRequired` | Specifies whether a smart card is required to log on. | No | True, False |
| `State` | Specifies the user's or Organizational Unit's state or province. | No | String |
| `StreetAddress` | Specifies the user's street address. | No | String |
| `Surname` | Specifies the user's last name or surname. | No | String |
| `Title` | Specifies the user's title. | No | String |
| `TrustedForDelegation` | Indicates whether an account is trusted for Kerberos delegation. | No | True, False |
| `UserPrincipalName` | Specifies a user principal name (UPN) in the format user\@DNS-domain-name. | No | String. Example user\@DNS-domain-name |
| `SMBFileServerAddress` | If you need to set SMB permissions to some folder for this user - this is the file server address | No | DNS Hostname |
| `SMBShareName` | If you need to set SMB permissions to some folder for this user - this is the Name of the SMB file share on the target server above | No | DNS Hostname |
| `SMBPermissionsSet` | Contains JSON descriptions of permissions that need to be merged with current permissions. | No | JSON |
| `SMBOverwriteWithPermissions` | Contains JSON descriptions of permissions that need to overwrite with current permissions. | No | JSON |
| `Certificates` | This attribute allows you to manage certificates for a specific user (that is, assign or delete certificates). Also, it must contain the Base64 format of the certificate in one line, without the headers '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----', spaces, and new lines. The certificate itself must be an X.509v3 certificate. **Note:** to delete all certificates from a user, this attribute must be empty and the DELETE operation. | No | String |
| `RemoveUnknownGroupMembership` | **Removes the user from any Active Directory group that OpenIAM does not know about.** When `True`, the connector reads the user's real group memberships and removes every one absent from the `MemberOf` map in the request. If that map is empty the connector refuses and logs a warning, rather than stripping every membership — an empty map means "no membership data in this request", not "this user belongs to nothing". To remove memberships deliberately, send explicit DELETE operations per group instead. | No | Boolean |
#### Group provisioning
**Principal** - SamAccountName
To add the new group, OpenIAM should send two attributes:
* Name
* GroupScope (DomainLocal or Global or Universal)
| Parameter | Description | Required | Type |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `GroupScope` | Specifies the scope of the group. | Yes | String |
| `MemberOf` | Key-Value pair, sets the groups in which the current group should be added. | No | Key-Value |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. The LDAP display name (ldapDisplayName) for this property is displayName. | No | String |
| `GroupCategory` | Specifies the category of the group. | No | String |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `Instance` | Specifies an instance of a group object to use as a template for a new group object. | No | String |
| `Members` | Should contain key-value pair if you need to input some members inside the current group. Key – Distinguished name of the object (user) for the operation. Value – 'add' or 'nochange' or 'delete'. On user creation only add or nochange values are accepted and mean the same (adding the member for the current group) | No | Key-Value |
| `ManagedBy` | Specifies the user or group that manages the object by providing one of the following property values. | No | String |
| `Path` | Specifies the destination Path in DistinguishedName format for the newly created object | No | String |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 20 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. | No | String |
| `RemoveUnknownGroupMembership` | **Removes this group from any parent group that OpenIAM does not know about.** The group equivalent of the user attribute of the same name: the connector reads the groups this one belongs to and removes every one absent from the `MemberOf` map. An empty map is refused with a warning rather than acted on. | No | Boolean |
| `RemoveUnknownGroupMembers` | **Removes members from this group when OpenIAM does not know about them.** The opposite direction to the attribute above: the connector reads the group's real members and removes every one absent from the `Members` map in the request. An empty map is refused with a warning rather than acted on. | No | Boolean |
**OpenIAM configuration**
To enable group provisioning add group provision filed to the managed system. Go to *Webconsole* -> *Provisioning* -> *Connectors* -> *AD Powershell CONNECTOR* -> *Connector configuration* and set checkboxes in front of:
* Base DN for Group
* Object Primary Key for Group
* Search Base DN for Group
* Search Filter for Group
Save changes. Go to managed system edit page and populate new fields for group, save changes. Make sure that you have policy map for group object, if not - create one, use out of the box managed system to copy policy map.
Now each group linked with the AD managed system will be identity generated and will be provisioned to AD.
#### Computer provisioning
**Principal** - SamAccountName
| Parameter | Description | Required | Type |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
| `Name` | Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. | Yes | String |
| `AccountExpirationDate` | Specifies the expiration date for an account. | No | DateTime, for example "10/18/2018" |
| `AccountNotDelegated` | Specifies whether the security context of the user is delegated to a service. | No | True, False |
| `AllowReversiblePasswordEncryption` | Specifies whether reversible password encryption is allowed for the account. | No | True, False |
| `AuthenticationPolicy` | Specifies an Active Directory Domain Services authentication policy object. | No | String |
| `AuthenticationPolicySilo` | Specifies an Active Directory Domain Services authentication policy silo object. | No | String |
| `CannotChangePassword` | Specifies whether the account password can be changed. This parameter sets the CannotChangePassword property of an account. | No | True, False |
| `ChangePasswordAtLogon` | Specifies whether a password must be changed during the next log on attempt. | No | True, False |
| `CompoundIdentitySupported` | Specifies whether an account supports Kerberos service tickets which includes the authorization data for the user's device. | No | True, False |
| `DNSHostName` | Specifies the fully qualified domain name (FQDN) of the computer. | No | String |
| `Description` | Specifies a description of the object. | No | String |
| `DisplayName` | Specifies the display name of the object. | No | String |
| `Enabled` | Specifies if an account is enabled. | No | True, False |
| `HomePage` | Specifies the URL of the home page of the object. | No | String |
| `KerberosEncryptionType` | Specifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. | No | String |
| `Location` | Specifies the location of the computer, such as an office number. | No | String |
| `ManagedBy` | Specifies the user or group that manages the object by providing one of the following property values. | No | String |
| `OperatingSystem` | Specifies an operating system name. | No | String |
| `OperatingSystemHotfix` | Specifies an operating system hotfix name. | No | String |
| `OperatingSystemServicePack` | Specifies the name of an operating system service pack. | No | String |
| `OperatingSystemVersion` | Specifies an operating system version. | No | String |
| `PasswordNeverExpires` | Specifies whether the password of an account can expire. | No | True, False |
| `PasswordNotRequired` | Specifies whether the account requires a password. | No | True, False |
| `Path` | Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. | No | String (DN format) |
| `SamAccountName` | Specifies the Security Account Manager (SAM) account name of the user, group, computer, or service account. The maximum length of the description is 256 characters. To be compatible with older operating systems, create a SAM account name that is 15 characters or less. This parameter sets the SamAccountName for an account object. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. Note: If the SamAccountName string provided does not end with a $, a $ will be appended if needed. | No | String |
| `TrustedForDelegation` | Specifies whether an account is trusted for Kerberos delegation. | No | True, False |
| `UserPrincipalName` | Specifies a user principal name (UPN) in the format user\@DNS-domain-name. | No | String. Example: user\@DNS-domain-name |
, and every operation on it uses the suffixed form.
#### FileShares provisioning
**Principal** - UNCPath
| Parameter | Description | Required | Type |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- |
| `Type` | Should be equal to 'fileshare' - it will tell connector that this GROUP request should be treated as a fileshare. | Yes | String |
| `Name` | Specifies the name of the object. A unique name identifying the share on the target server. Two shares on one server cannot carry the same name. | Yes | String |
| `Path` | The physical path on the target file share server where the share will be located. | Yes | String |
| `FileServerAddress` | The network address of the file server. Could be either IP or DNS hostname. Please note, that for running remoting operations in an AD environment you should preferably use DNS names. | Yes | String, like dc1.openiamdemo.com |
| `UNCPath` | Plays ID role for OpenIAM. Represents the network name like \dc12.openiamtest.local\FileShare | Yes | String, like on description example |
| `Description` | Specifies an optional description of the SMB share. | No | String |
| `CachingMode` | Specifies the caching mode of the offline files for the SMB share. | No | String, one of described |
| `PublishedLDAPPath` | Optionally applied for Windows Active directory environment. | No | String, like on description example |
| `PreviousPublishedLDAPPath` | Used when the PublishedLDAPPath value moves from one location to another. | No | String, like on description example |
| `ConcurrentUserLimit` | Specifies the set of share permissions that needs to be assigned to the share. | No | JSON array string |
| `OverwriteWithPermissions` | If set to 'True' - will remove all existing permissions for the shared folder and will set the default permission set. | No | True, False |
| `DefaultPermissionsSet` | Works like PermissionsSet attribute, but is being applied if OverwriteWithPermissions is set. | No | JSON array string |
### Reconciliation and 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](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-aduser), [Get-ADGroup](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-adgroup) or [Get-ADComputer](https://docs.microsoft.com/en-us/powershell/module/addsadministration/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.
The examples below use [Get-ADUser](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-aduser). Each one works the same way with [Get-ADGroup](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-adgroup) or [Get-ADComputer](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-adcomputer) in its place.
**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:
```powershell
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.
```powershell
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.
**The fast search processor**
Setting **`isFastSearchProcessorEnabled`** on the managed system switches the connector to a .NET searcher, which projects only the requested attributes and is considerably faster on large directories. It comes with two caveats, and the connector enforces the first rather than letting it pass:
* **It cannot apply a location restriction, so the connector refuses to run with one.** If `PermittedDN`, `SEARCH_BASE_DN` or `SearchBaseDN` is set, the search stops with an error rather than returning records from outside the permitted location. Either turn the fast processor off, or remove the restriction.
* **It skips per-record value formatting** — `DateTimeStringFormat`, the trailing dollar-sign trimming applied to a computer's `samaccountname`, and SID value extraction. That changes how values look, not which objects come back, so the connector warns and continues.
**Query syntax**
You can run a direct query using syntax described at [Get-ADUser](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-aduser), [Get-ADGroup](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-adgroup) or [Get-ADComputer](https://docs.microsoft.com/en-us/powershell/module/addsadministration/get-adcomputer) cmdlets.
{% hint style="info" %}
You do not need to pass `-Server` or `-Credential` in a search query — the connector opens the connection itself and supplies both.
{% endhint %}
If the managed system names no search attributes, the connector returns a default set: `Name`, `sAMAccountName`, `UserPrincipalName`, `DistinguishedName` and `Enabled`.
A search query has to be one pipeline that only reads. Beyond the general rule, this connector refuses the AD directory-services tools by name — `dsrm`, `dsmod`, `dsmove`, `dsadd` and `dsacls` — because they change the directory while looking like ordinary commands.
**How the search scope is decided.** Two managed system settings can narrow what a search returns, and only one of them applies:
1. **`PermittedDN` always wins.** If it is set, records outside it are dropped whatever else is configured.
2. Otherwise **`SEARCH_BASE_DN`** — or its legacy spelling **`SearchBaseDN`**, which is read first if both are set — applies, **unless the query passes `-SearchBase` itself**, in which case the query's own location is respected.
3. If neither is set, every record the query returned is included.
Neither setting is passed to the AD cmdlet. The query runs exactly as written and the records it returns are **filtered afterwards** by distinguished name, so a location restriction narrows what reaches OpenIAM but does not reduce what the domain controller had to produce. Every outcome is written to the connector log at info level, so the log says which setting was in force without debug logging turned on.
Query examples:
```powershell
Get-ADUser -Filter *
```
The query above gets all users from AD. If a location restriction is configured, results outside it are dropped before they reach OpenIAM.
```poaershell
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. Use the query shown above.
```powershell
Get-ADUser -Filter {Surname -eq 'Potter'}
```
The query above selects all users with surname 'Potter'. Because it does not pass `-SearchBase`, a configured `SEARCH_BASE_DN` applies to the results. State the location in the query to override it:
{% code overflow="wrap" %}
```powershell
Get-ADUser -Filter {Surname -eq 'Potter'} -SearchBase 'DC=openiamtest,DC=local'
```
{% endcode %}
Passing `-SearchBase` is the only way a query escapes a configured `SEARCH_BASE_DN`. Nothing escapes `PermittedDN`.
For example, one common scenario is filtering users that were modified after a certain date:
{% code overflow="wrap" %}
```powershell
Get-ADUser -LDAPFilter '(whenChanged>=20200726000000.0Z)' -Properties whenChanged
```
{% endcode %}
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.
{% code overflow="wrap" %}
```powershell
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'}
```
{% endcode %}
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:
```powershell
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:
```powershell
Get-ADUser -Filter * -Properties memberOf, PrimaryGroup
```
**OpenIAM configuration for AD user sync.**
OpenIAM supplies out of the box configuration named 'AD Powershell USER Example'.
#### 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:
```powershell
Get-ADGroup -Filter 'groupcategory -eq "Distribution"'
```
Gettiing all security groups in certain location:
{% code overflow="wrap" %}
```powershell
Get-ADGroup -Filter 'groupcategory -eq "Security"' -SearchBase 'CN=Users,DC=openiamtest,DC=local'
```
{% endcode %}
**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, to return everything available about every security group in the domain:
```powershell
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:
{% code overflow="wrap" %}
```powershell
Get-ADGroup -Filter 'groupcategory -eq "Security"' -Properties cn,whenCreated
```
{% endcode %}
That returns the basic attributes listed above, plus `CN` and `WhenCreated`.
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
**OpenIAM configuration for AD group sync.**
OpenIAM supplies out of the box configuration named 'AD Powershell GROUP Example'.
#### 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.
```powershell
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:
```powershell
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 the 'Modified' 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:
```powershell
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 agreement about how to treat DateTime strings. The format should be sent in request metadata and the parameter name should be 'DateTimeStringFormat'. Set it on the managed system, in the **Attributes** panel:
| Attribute Name | Attribute Value |
| ---------------------- | ----------------------- |
| `DateTimeStringFormat` | `yyyy-MM-dd'T'HH:mm:ss` |
#### Urgent queues
A connector is responsible for transferring data between systems, between AD and OpenIAM in this case. If some messages require immediate processing, an urgent queue can be implemented to prioritize them over regular traffic. To add connection, follow the steps below.
1. Open `Connector.config` file inside the connector folder on Windows machine and add a new record to `"RabbitMQQueues"` array, as shown below.
{% code title="Connector.config" overflow="wrap" %}
```json
"RabbitMQQueues": [
{
"RabbitMQReceiveQueue": "RemoteConnector_1_Request",
"RabbitMQResponseQueue": "RemoteConnector_1_Response",
"Concurrency": 1,
"QueueType": "quorum"
}
],
```
{% endcode %}
It is possible just to duplicate that record but append `URGENT_` to the `RabbitMQReceiveQueue` and `RabbitMQResponseQueue` properties. So, configuration that supports urgent queues would look like one below.
{% code title="Connector.config" overflow="wrap" expandable="true" %}
```json
"RabbitMQQueues": [
{
"RabbitMQReceiveQueue": "RemoteConnector_1_Request",
"RabbitMQResponseQueue": "RemoteConnector_1_Response",
"Concurrency": 1,
"QueueType": "quorum"
},
{
"RabbitMQReceiveQueue": "URGENT_RemoteConnector_1_Request",
"RabbitMQResponseQueue": "URGENT_RemoteConnector_1_Response",
"Concurrency": 1,
"QueueType": "quorum"
}
],
```
{% endcode %}
`Concurrency` can be set differently for the normal and the urgent queue.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.openiam.com/connector-configuration/microsoft/4-adpowershell.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
