Active Directory Powershell

Installation and connection to OpenIAM

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

Details related to PowerShell AD connector installation:

Normaly we recommend installing AD PowerShell connector on a domain joined server inside the same domain, which contains the identities the AD connector is supposed to manage. It is also possible to install the connector on a 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, we do not recommend this scenario for production environments.

General usage

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

Service account information:

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

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

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

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

Delegation control for service account

Limiting connector scope

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

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

Provisioning identities

The AD PowerShell connector supports working with following identities:

  • Users
  • Groups
  • Computers
  • File shares

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

User provisioning

Principal - SamAccountName

ParameterDescriptionRequiredType
NameSpecifies 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.YesString
AccountExpirationDateSpecifies the expiration date for an account. When you set this parameter to 0, the account never expires. This parameter sets the AccountExpirationDate property of an account object. The LDAP display name (ldapDisplayName) for this property is accountExpires. Use the DateTime syntax when you specify this parameter. Time is assumed to be local time unless otherwise specified. When a time value is not specified, the time is assumed to 12:00:00 AM local time. When a date is not specified, the date is assumed to be the current date.NoDateTime, for example "10/18/2018"
AccountNotDelegatedIndicates whether the security context of the user is delegated to a service. When this parameter is set to $True, the security context of the account is not delegated to a service even when the service account is set as trusted for Kerberos delegation. This parameter sets the AccountNotDelegated property for an Active Directory account. This parameter also sets the ADS_UF_NOT_DELEGATED flag of the Active Directory User Account Control (UAC) attribute. Note – checking this parameter back requires UAC int attribute (NOT_DELEGATED) converting back. There is no PowerShell parameter that is appropriate for this provisioning attributeNoTrue, False
AccountPasswordSpecifies 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 inititially not supposed to be enabled, Yes if it should be enabledString
AllowReversiblePasswordEncryptionIndicates whether reversible password encryption is allowed for the account. This parameter sets the AllowReversiblePasswordEncryption property of the account. This parameter also sets the ADS_UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED flag of the Active Directory User Account Control (UAC) attributeNoTrue, False
CannotChangePasswordIndicates whether the account password can be changed. This parameter sets the CannotChangePassword property of an account.NoTrue, False
ChangePasswordAtLogonIndicates whether a password must be changed during the next logon attempt.NoTrue, False
CitySpecifies the user's town or city. This parameter sets the City property of a user object. The LDAP display name (ldapDisplayName) of this property is l.NoString
CompanySpecifies the user's company. This parameter sets the Company property of a user object. The LDAP display name (ldapDisplayName) of this property is company.NoString
CountrySpecifies the country or region code for the user's language of choice. This parameter sets the Country property of a user object. The LDAP display name (ldapDisplayName) of this property is c.NoString
DepartmentSpecifies the user's department. This parameter sets the Department property of a user object. The LDAP display name (ldapDisplayName) of this property is department.NoString
DescriptionSpecifies a description of the object. This parameter sets the value of the Description property for the user object. The LDAP display name (ldapDisplayName) for this property is description.NoString
DisplayNameSpecifies the display name of the object. This parameter sets the DisplayName property of the user object. The LDAP display name (ldapDisplayName) for this property is displayName.NoString
DivisionSpecifies the user's division. This parameter sets the Division property of a user object. The LDAP display name (ldapDisplayName) of this property is division.NoString
EmailAddressSpecifies the user's e-mail address. This parameter sets the EmailAddress property of a user object. The LDAP display name (ldapDisplayName) of this property is mail.NoString
EmployeeIDSpecifies the user's employee ID. This parameter sets the EmployeeID property of a user object. The LDAP display name (ldapDisplayName) of this property is employeeID.NoString
EmployeeNumberSpecifies the user's employee number. This parameter sets the EmployeeNumber property of a user object. The LDAP display name (ldapDisplayName) of this property is employeeNumber.NoString
EnabledSpecifies if an account is enabled. An enabled account requires a password. This parameter sets the Enabled property for an account object. This parameter also sets the ADS_UF_ACCOUNTDISABLE flag of the Active Directory User Account Control (UAC) attribute.NoTrue, False
FaxSpecifies the user's fax phone number. This parameter sets the Fax property of a user object. The LDAP display name (ldapDisplayName) of this property is facsimileTelephoneNumber.NoString
FolderNameThe path to the local folder that should be created or modified for provisioned user. This attribute can work in tandem with the Permissions attribute that sets NTFS permissions to current FolderName.NoString C:\TestFolder
GivenNameSpecifies the user's given name. This parameter sets the GivenName property of a user object. The LDAP display name (ldapDisplayName) of this property is givenName.NoString
MemberOfThe 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.NoDictionary of Key-Value
HomeDirectorySpecifies a user's home directory. This parameter sets the HomeDirectory property of a user object. The LDAP display name (ldapDisplayName) for this property is homeDirectory.NoString
HomeDriveSpecifies a drive that is associated with the UNC path defined by the HomeDirectory property. The drive letter is specified as DriveLetter: where DriveLetter indicates the letter of the drive to associate. TheDriveLetter must be a single, uppercase letter and the colon is required. This parameter sets the HomeDrive property of the user object. The LDAP display name (ldapDisplayName) for this property is homeDrive.NoString
HomePageSpecifies the URL of the home page of the object. This parameter sets the homePage property of a user object. The LDAP display name (ldapDisplayName) for this property is wWWHomePage.NoString
HomePhoneSpecifies the user's home telephone number. This parameter sets the HomePhone property of a user object. The LDAP display name (ldapDisplayName) of this property is homePhone.NoString
InitialsSpecifies the initials that represent part of a user's name. You can use this value for the user's middle initial. This parameter sets the Initials property of a user object. The LDAP display name (ldapDisplayName) of this property is initials. Maximum default attribute length on AD side is 6 symbolsNoString
KerberosEncryptionTypeSpecifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. This value sets the encryption types supported flags of the Active Directory msDS-SupportedEncryptionTypes attribute. Possible values for this parameter are: DES, RC4, AES128, AES256. None removes all encryption types from the account, resulting in the KDC being unable to issue service tickets for services using the account. DES is a weak encryption type that is not supported by default since Windows 7 and Windows Server 2008 R2. Warning: Domain-joined Windows systems and services such as clustering manage their own msDS-SupportedEncryptionTypes attribute. Therefore, any changes to the flag on the msDS-SupportedEncryptionTypes attribute are overwritten by the service or system that manages the setting.NoString, one of the ones set in description
LogonWorkstationsSpecifies the computers that the user can access. To specify more than one computer, create a single comma-separated list. You can identify a computer by using the Security Account Manager (SAM) account name (sAMAccountName) or the DNS host name of the computer. The SAM account name is the same as the NetBIOS name of the computer. The LDAP display name (ldapDisplayName) for this property is userWorkStations.NoString or multiple strings separated by comma (‘,’), without whitespaces at separator
ManagerSets manager for specified user. Contains samaccountname of the manager that should be set for the user. It is allowed to have just one manager for a user.NoString (samaccountname)
MobilePhoneSpecifies the user's mobile phone number. This parameter sets the MobilePhone property of a user object. The LDAP display name (ldapDisplayName) of this property is mobile.NoString
OfficeSpecifies the location of the user's office or place of business. This parameter sets the Office property of a user object. The LDAP display name (ldapDisplayName) of this property is office.NoString
OfficePhoneSpecifies the user's office telephone number. This parameter sets the OfficePhone property of a user object. The LDAP display name (ldapDisplayName) of this property is telephoneNumber.NoString
OrganizationSpecifies the user's organization. This parameter sets the Organization property of a user object. The LDAP display name (ldapDisplayName) of this property is o.NoString
OtherNameSpecifies a name in addition to a user's given name and surname, such as the user's middle name. This parameter sets the OtherName property of a user object. The LDAP display name (ldapDisplayName) of this property is middleName.NoString
POBoxSpecifies the user's post office box number. This parameter sets the POBox property of a user object. The LDAP display name (ldapDisplayName) of this property is postOfficeBox.NoString
PasswordNeverExpiresSpecifies whether the password of an account can expire. This parameter sets the PasswordNeverExpires property of an account object. This parameter also sets the ADS_UF_DONT_EXPIRE_PASSWD flag of the Active Directory User Account Control attribute.NoString
PasswordNotRequiredSpecifies whether the account requires a password. A password is not required for a new account. This parameter sets the PasswordNotRequired property of an account object.NoTrue, False
PathSpecifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. If no Path is set – BaseDN parameter will be used. Note! If OpenIAM sends new Path to existing user, the connector will try to move the object. However, movement would not be successful if the object is protected from accidental deletion (protection on Microsoft side). Please also note that if you change Path, AD will set new DN for your user like CN={NAME},{NEW_PATH}NoString. Example: OU=TestUsers,DC=DC1,DC=local
PermissionsIs applied only if folderName parameter is set. It's the set of Key-Value pairs where the Key is the text value of one of the following enum values: https://docs.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.filesystemrights?view=netframework-3.5 And the Value is one of ‘add’, ‘delete’NoDictionary of Key-Value
PostalCodeSpecifies the user's postal code or zip code. This parameter sets the PostalCode property of a user object. The LDAP display name (ldapDisplayName) of this property is postalCode.NoString
PrincipalsAllowedToDelegateToAccountSpecifies an array of principal objects. This parameter sets the msDS-AllowedToActOnBehalfOfOtherIdentity attribute of a computer account object. Warning: by default the connector supports sending one principal, however that behavior could be extended by demand.NoString (samaccountname)
ProfilePathSpecifies a path to the user's profile. This value can be a local absolute path or a Universal Naming Convention (UNC) path. This parameter sets the ProfilePath property of the user object. The LDAP display name (ldapDisplayName) for this property is profilePath.NoString
SamAccountNameSpecifies 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.NoString
ScriptPathSpecifies a path to the user's log on script. This value can be a local absolute path or a Universal Naming Convention (UNC) path. This parameter sets the ScriptPath property of the user object. The LDAP display name (ldapDisplayName) for this property is scriptPath.NoString
SmartcardLogonRequiredSpecifies whether a smart card is required to log on. This parameter sets the SmartCardLoginRequired property for a user object. This parameter also sets the ADS_UF_SMARTCARD_REQUIRED flag of the Active Directory User Account Control attribute.NoTrue, False
StateSpecifies the user's or Organizational Unit's state or province. This parameter sets the State property of a user object. The LDAP display name (ldapDisplayName) of this property is st.NoString
StreetAddressSpecifies the user's street address. This parameter sets the StreetAddress property of a user object. The LDAP display name (ldapDisplayName) of this property is streetAddress.NoString
SurnameSpecifies the user's last name or surname. This parameter sets the Surname property of a user object. The LDAP display name (ldapDisplayName) of this property is sn.NoString
TitleSpecifies the user's title. This parameter sets the Title property of a user object. The LDAP display name (ldapDisplayName) of this property is title.NoString
TrustedForDelegationIndicates whether an account is trusted for Kerberos delegation. A service that runs under an account that is trusted for Kerberos delegation can assume the identity of a client requesting the service. This parameter sets the TrustedForDelegation property of an account object. This value also sets the ADS_UF_TRUSTED_FOR_DELEGATION flag of the Active Directory User Account Control attribute.NoTrue, False
UserPrincipalNameSpecifies a user principal name (UPN) in the format user@DNS-domain-name. A UPN is a friendly name assigned by an administrator that is shorter than the LDAP distinguished name used by the system and easier to remember. The UPN is independent of the user object's distinguished name, so a user object can be moved or renamed without affecting the user logon name. When logging on using a UPN, users no longer have to choose a domain from a list on the log on dialog box.NoString. Example user@DNS-domain-name

Group provisioning

Principal - SamAccountName

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

  • Name
  • GroupScope (DomainLocal or Global or Universal)
ParameterDescriptionRequiredType
NameSpecifies 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.YesString
GroupScopeSpecifies the scope of the group. The acceptable values for this parameter are: DomainLocal, Univeersal, Global. This parameter sets the GroupScope property of a group object to the specified value. The LDAP display name of this property is groupType.YesString
MemberOfKey-Value pair, sets the groups in which the current group should be added.NoKey-Value
DescriptionSpecifies a description of the object. This parameter sets the value of the Description property for the object. The Lightweight Directory Access Protocol (LDAP) display name (ldapDisplayName) for this property is description.NoString
DisplayNameSpecifies the display name of the object. The LDAP display name (ldapDisplayName) for this property is displayName.NoString
GroupCategorySpecifies the category of the group. The acceptable values for this parameter are: Distribution, Security. This parameter sets the GroupCategory property of the group. This parameter value combined with other group values sets the LDAP display name (ldapDisplayName) attribute named groupType.NoString
HomePageSpecifies the URL of the home page of the object. This parameter sets the homePage property of an Active Directory object. The LDAP display name (ldapDisplayName) for this property is wWWHomePage.NoString
InstanceSpecifies an instance of a group object to use as a template for a new group object. You can use an instance of an existing group object as a template or you can construct a new group object.NoString
MembersShould 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)NoKey-Value
ManagedBySpecifies the user or group that manages the object by providing one of the following property values. Note: The identifier in parentheses is the LDAP display name for the property. The acceptable values for this parameter are: A distinguished name; A GUID (objectGUID); A security identifier (objectSid); SAM account name (sAMAccountName)NoString
PathSpecifies the desitnation Path in DestinguishedName format for the newly created objectNoString
SamAccountNameSpecifies 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.NoString

Computer provisioning

Principal - SamAccountName

ParameterDescriptionRequiredType
NameSpecifies 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.YesString
AccountExpirationDateSpecifies the expiration date for an account. When you set this parameter to 0, the account never expires. This parameter sets the AccountExpirationDate property of an account object. The Lightweight Directory Access Protocol (LDAP) display name (ldapDisplayName) for this property is accountExpires. Use the DateTime syntax when you specify this parameter. Time is assumed to be local time unless otherwise specified. When a time value is not specified, the time is assumed to 12:00:00 AM local time. When a date is not specified, the date is assumed to be the current date.NoDateTime, for example "10/18/2018"
AccountNotDelegatedSpecifies whether the security context of the user is delegated to a service. When this parameter is set to true, the security context of the account is not delegated to a service even when the service account is set as trusted for Kerberos delegation. This parameter sets the AccountNotDelegated property for an Active Directory account. This parameter also sets the ADS_UF_NOT_DELEGATED flag of the Active Directory User Account Control (UAC) attribute.NoTrue, False
AllowReversiblePasswordEncryptionSpecifies whether reversible password encryption is allowed for the account. This parameter sets the AllowReversiblePasswordEncryption property of the account. This parameter also sets the ADS_UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED flag of the Active Directory User Account Control (UAC) attribute.NoTrue, False
AuthenticationPolicySpecifies an Active Directory Domain Services authentication policy object. Specify the authentication policy object in one of the following formats: A distinguished Name; A GUID; A name;NoString
AuthenticationPolicySiloSpecifies an Active Directory Domain Services authentication policy silo object. Specify the authentication policy silo object in one of the following formats: A distinguished name; A GUID; A name;NoString
CannotChangePasswordSpecifies whether the account password can be changed. This parameter sets the CannotChangePassword property of an account.NoTrue, False
ChangePasswordAtLogonSpecifies whether a password must be changed during the next log on attempt.NoTrue, False
CompoundIdentitySupportedSpecifies whether an account supports Kerberos service tickets which includes the authorization data for the user's device. This value sets the compound identity supported flag of the Active Directory msDS-SupportedEncryptionTypes attribute. Warning: Domain-joined Windows systems and services such as clustering manage their own msDS-SupportedEncryptionTypes attribute. Therefore, any changes to the flag on the msDS-SupportedEncryptionTypes attribute is overwritten by the service or system which manages the setting.NoTrue, False
DNSHostNameSpecifies the fully qualified domain name (FQDN) of the computer. This parameter sets the DNSHostName property for a computer object. The LDAP display name for this property is dNSHostName.NoString
DescriptionSpecifies a description of the object. This parameter sets the value of the Description property for the object. The LDAP display name (ldapDisplayName) for this property is description.NoString
DisplayNameSpecifies the display name of the object. This parameter sets the DisplayName property of the object. The LDAP display name (ldapDisplayName) for this property is displayName.NoString
EnabledSpecifies if an account is enabled. An enabled account requires a password. This parameter sets the Enabled property for an account object. This parameter also sets the ADS_UF_ACCOUNTDISABLE flag of the Active Directory User Account Control (UAC) attribute.NoTrue, False
HomePageSpecifies the URL of the home page of the object. This parameter sets the homePage property of an Active Directory object. The LDAP display name (ldapDisplayName) for this property is wWWHomePage.NoString
KerberosEncryptionTypeSpecifies whether an account supports Kerberos encryption types which are used during the creation of service tickets. This value sets the encryption types supported flags of the Active Directory msDS-SupportedEncryptionTypes attribute. The acceptable values for this parameter are: None; DES; RC4; AES128; AES256. None will remove all encryption types from the account which may result in the KDC being unable to issue service tickets for services using the account. DES is a weak encryption type which is not supported by default since Windows 7 and Windows Server 2008 R2. Warning: Domain-joined Windows systems and services such as clustering manage their own msDS-SupportedEncryptionTypes attribute. Therefore any changes to the flag on the msDS-SupportedEncryptionTypes attribute is overwritten by the service or system which manages the setting.NoString
LocationSpecifies the location of the computer, such as an office number. This parameter sets the Location property of a computer. The LDAP display name (ldapDisplayName) of this property is location.NoString
ManagedBySpecifies the user or group that manages the object by providing one of the following property values. Note: The identifier in parentheses is the LDAP display name for the property. The acceptable values for this parameter are: A distinguished name; A GUID (objectGUID); A security identifier (objectSid); A SAM account name (sAMAccountName). This parameter sets the Active Directory attribute with an LDAP display name of managedBy.NoString
OperatingSystemSpecifies an operating system name. This parameter sets the OperatingSystem property of the computer object. The LDAP Display Name (ldapDisplayName) for this property is operatingSystem.NoString
OperatingSystemHotfixSpecifies an operating system hotfix name. This parameter sets the operatingSystemHotfix property of the computer object. The LDAP display name for this property is operatingSystemHotfix.NoString
OperatingSystemServicePackSpecifies the name of an operating system service pack. This parameter sets the OperatingSystemServicePack property of the computer object. The LDAP display name (ldapDisplayName) for this property is operatingSystemServicePack.NoString
OperatingSystemVersionSpecifies an operating system version. This parameter sets the OperatingSystemVersion property of the computer object. The LDAP display name (ldapDisplayName) for this property is operatingSystemVersion.NoString
PasswordNeverExpiresSpecifies whether the password of an account can expire. This parameter sets the PasswordNeverExpires property of an account object. This parameter also sets the ADS_UF_DONT_EXPIRE_PASSWD flag of the Active Directory User Account Control attribute.NoTrue, False
PasswordNotRequiredSpecifies whether the account requires a password. This parameter sets the PasswordNotRequired property of an account, such as a user or computer account. This parameter also sets the ADS_UF_PASSWD_NOTREQD flag of the Active Directory User Account Control attribute.NoTrue, False
PathSpecifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. If no Path is set – BaseDN parameter will be usedNoString (DN format)
SAMAccountNameSpecifies 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.NoString
TrustedForDelegationSpecifies whether an account is trusted for Kerberos delegation. A service that runs under an account that is trusted for Kerberos delegation can assume the identity of a client requesting the service. This parameter sets the TrustedForDelegation property of an account object. This value also sets the ADS_UF_TRUSTED_FOR_DELEGATION flag of the Active Directory User Account Control attribute.NoTrue, False
UserPrincipalNameSpecifies a user principal name (UPN) in the format user@DNS-domain-name. A UPN is a friendly name assigned by an administrator that is shorter than the LDAP distinguished name used by the system and easier to remember. The UPN is independent of the user object's distinguished name, so a user object can be moved or renamed without affecting the user log on name. When logging on using a UPN, users no longer have to choose a domain from a list on the log on dialog box.NoString. Example: user@DNS-domain-name

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

FileShares provisioning

Principal - UNCPath

ParameterDescriptionRequiredType
NameSpecifies the name of the object. This is a unique name that will identify this share within the target share server. There could be no duplication of this attribute on the same file share server.YesString
PathThe physical path on the target file share server where the share will be located. If the path does not exist, the connector will create it even with nested sub-folders (if supplied credentials have sufficient permissions).YesString
FileServerAddressThe 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.YesString, like dc1.openiamdemo.com
UNCPathPlays ID role for OpenIAM. Represents the network name like \dc12.openiamtest.local\FileShareYesString, like on description example
DescriptionSpecifies an optional description of the SMB share. A description of the share is displayed by running the Get-SmbShare cmdlet. The description may not contain more than 256 characters. The default value is an empty description.NoString
CachingModeSpecifies the caching mode of the offline files for the SMB share. There are five caching modes: None. Prevents users from storing documents and programs offline.; Manual. Allows users to identify the documents and programs they want to store offline.; Programs. Automatically stores documents and programs offline.; Documents. Automatically stores documents offline.; BranchCache. Enables BranchCache and manual caching of documents on the shared folder.;NoString, one of described
PublishedLDAPPathOptionally applied for Windows Active directory environment. Share link could be published in AD and this should be the LDAP path like LDAP://OU=Australia,DC=openiamtest,DC=localNoString, like on description example
PreviousPublishedLDAPPathThis attribute is used if we need to move the value of PublishedLDAPPath from one location to another one. In this case PublishedLDAPPath (above attribure) should contain the new destination location, while this attribute (PreviousPublishedLDAPPath) should contain the current location from where we are going to move the record in AD. This attribute only works if PublushedLDAPPath attribute is set and Operation code for that attribute is 2 (replace). Example LDAP://OU=Australia,DC=openiamtest,DC=localNoString, like on description example
ConcurrentUserLimitSpecifies the set of share permissions that needs to be assigned to the share. This is a JSON string that contains the following values: Operation – either ‘Grant’ or ‘Revoke’; AccountName – samaccountname of the target user or the special names like ‘Everyone’; AccessRight – one of ‘Full’, ‘Change’, ‘Read’. While ‘Change’ permission allows read/execute/write/delete folders/files, ‘Full’ permission would additionally allow to manage permissions. NB! Share permissions are combined with NTFS permissions (the most restrictive permissions are applied).; If OverwriteWithPermissions attribute is not set – PermissionsSet will be applied to existing permissions and will owerwrite matching permissions with appending new ones. However, it will not remove existing permissions. Example: [{"Operation": "Grant","AccountName": "SomeUser","AccessRight": "Read"}, {"Operation": "Grant", "AccountName":"Alex", "AccessRight":"Read"}]NoJSON array string
OverwriteWithPermissionsIf set to ‘True’ – will remove all existing permissions for the shared folder and will set the default permission set. And only after this will apply PermissionsSet if it is present (or will leave default permissions set if not). This attribute would not work if DefaultPermissionsSet is not set.NoTrue, False
DefaultPermissionsSetWorks like PermissionsSet attribute, but is being applied if OverwriteWithPermissions is set. This is the set of default permissions to share the object. This attribute would not work if OverwriteWithPermissions is not set to ‘True’. Example: [{"Operation": "Grant","AccountName": "SomeUser","AccessRight": "Read"}, {"Operation": "Grant", "AccountName":"Alex", "AccessRight":"Read"}]NoJSON array string

Synchronization

Synchronizing AD users

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

General query execution logic

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

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

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

Simplified syntax

Get-ADUser *

The query above would return all basic attributes for users from whole AD in case SearchBaseDN is not specified on the Managed System configuration page. If SearchBaseDN is specified, search would be limited to that location. Using this query, you would be able to get only basic attributes such as:

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

So, if OpenIAM requests connector extra attributes, but uses a query like above, extra attributes would be returned as null.

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

A full query example would look like:

Get-ADUser * -Properties Mail,WhenCreated

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

Get-ADUser * -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.

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

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

Full syntax

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

Please note that you do not need to specify ‘Server’ and ‘Credential’ parameters because the connector does it behind the scene.

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

Query examples:

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

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

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

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

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

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

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

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

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

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

Synchronizing AD group memberships

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

Get-ADUser * -Properties memberOf

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

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

Get-ADUser * -Properties memberOf, PrimaryGroup

Synchronizing AD groups

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

Getting all AD distribution groups:

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

Gettiing all security groups in certain location:

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

Attributes that are returned by AD Group sync

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

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

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

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

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

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

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

You can request the following properties in your requests:

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

Synchronizing AD File shares

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

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

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

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

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

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

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

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

Get-SmbSharesInfo -DomainController 'yourDCHostname'

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

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

Incremental sync of users or groups

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

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

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

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

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

DateTime format requested from AD connector

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

Connector Troubleshooting and Tips

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

  • It is always better to specify the DNS hostname of your domain controller on the Managed System configuration page especially when the connector server is the member of a domain. Specifying an IP address may lead to non-obvious errors.
  • Port 9389 should be opened on the domain controller side so the connector could reach it. It should be opened almost in all cases.
  • Sometimes it is useful to try a connection to AD in the same way as the AD connector does to make sure that the AD connector would work. You may run a tiny script to validate connection:
Import-Module ActiveDirectory
$dc = 'YOUR_DOMAIN_CONTROLLER_HOSTNAME'
$ADcred = Get-Credential
New-PSDrive -PSProvider ActiveDirectory -Server $dc -Credential $ADcred -Root "" -Name IamADDrv -FormatType Canonical
if((Test-Path IamADDrv:) -eq $false)
{
throw "Unable to connect to AD"
}
Set-Location IamADDrv:

Possible errors

Errors in the table below are captured thanks to feedback from our customers. These have been the ones most frequently reported.

ErrorPossible causeHow to fix
Cannot find newly created user X for further operationsThis is a top stack trace error indicating that the connector cannot process request due to error that occured 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 - xxxThis 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 nameYou 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 interactionThis error occurs if you try to run sync but have not specified the password inside the Managed System configurationSet password in the Managed System configuration