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 domain joined server inside the same domain, which identities AD connector is supposed to manage. It is also possible to install connector on non domain joined server. However, domain controller of the target domain should be network reachable from AD connector server. Installing AD PowerShell connector directly on domain controllers is possible as well, however, we do not recommend this scenario for production environmeents.

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 AD and OpenIAM definition - service account is a regular user account inside Active Directory that has permissions to perform operations that you need to do using connector.

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

So, 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 connector would not be restricted to do any actions. For production environment you should consider particular permission set for this account.

As 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) - make right click and pick Delegation control wizard like shown below.

Delegation control for service account

Limiting connector scope

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

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

Provisioning identities

AD PowerShell connector supports working with following identities:

  • Users
  • Groups
  • Computers
  • File shares

This document describes parameters that could be sent to 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 pair with 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 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 – connector will try to move the object. However, movement would not be successful if 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. Is the set of Key-Value pair 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 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 logon. 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 logon dialog box.NoString. Example user@DNS-domain-name

Group provisioning

Principal - SamAccountName

To add the new group, OpenIAM should send, at least, 2 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 group 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 nameNoString
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 logon 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 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 logon name. When logging on using a UPN, users no longer have to choose a domain from a list on the logon dialog box.NoString. Example: user@DNS-domain-name

Attention! While working with computer object in Active Directory it is important to take into account that Microsoft side will put $ at the end of any computer samaccountname. As samaccountname is used as principal name and it’s 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 – connector can see that this request is regarding 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 unique name that will identify this share within 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 – 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 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 no description, or 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 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 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 other 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 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 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 side sends query to connector to execute and the list of attributes it expects to receive. Query result on a connector side is being treated as key-values pair. When this key-values pair is formed, connector makes match between attributes that were requested from OpenIAM side and keys available. If key is matched (case insensitive) – the value(s) will be returned to OpenIAM. If key is not found, but attribute was requested – attribute value will be returned as null.

While running search requests connector should be authenticated against AD using service account. Therefore, query, even being almost identical to PowerShell queries is being evaluated on the connector side and modified to real PowerShell commands. Connector leaves your ability to run pure PowerShell requests, but also can offer 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 *

Query above would return all basic attributes for users from whole AD in case SearchBaseDN is not specified on 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 as:

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

So, if OpenIAM requests connector extra attributes, but uses 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 bee returned, you can specify * instead of specifying particular attributes.

But you should note that querying all attributes using * significantly decrease performance. And there are not a lot of use cases when you really need everything from user profile. So, it is recommended always to specify only those attributes that you need.

Full query example would look like:

Get-ADUser * -Properties Mail,WhenCreated

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

Get-ADUser * -Properties *

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 process, for demonstrations and validating functionality. In this case query could be used like:

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

Full syntax

You can run 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 connector does it behind the scenes.

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

Query examples:

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

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 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 of common scenarios is filtering users that were modified after certain date:

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

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

Sometimes it could be useful to sync user objects only from certain several 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 query above does not look optimal, and it would be optimal to pass required location to the pipeline and run Get-ADUser for those locations only. But connector does some modifications for the queries before the run, so that method would not be possible. At the same time, filtering will help to reach your aim.

Synchronizing AD group memberships

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

Get-ADUser * -Properties memberOf

Alternatively, you can use * to grab all possible properties instead 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 absolute majority of cases primary group for all users is 'Domain Users'. However, if in your scenario you need for some reason sync primary group membership for your user - you need to include '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 above chapter as example and just replace 'Get-ADUser' to 'Get-ADGroup' expressions inside filter.

Just several queries examples. 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, connector would return following set of attributes which are default for 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 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 example above we will get all basic attributes that are mentioned in this chapter and + CN and WhenCreated attributes.

You can request 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

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, AD connector connects to each file share Windows server directly using PowerShell remoting and executes PowerShell commands using this remote session.

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

  • Member of local 'Remote Management Users' group on 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,s you should use query 'Get-SmbSharesInfo' inside your synchronization query. The syntax is described below.

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

In this scenario 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 following query can be useful:

Get-SmbSharesInfo -DomainController 'yourDCHostname'

When AD connector receives 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 AD connector will try (using multithreading) to connect to each of them to collect information about file shares.

Getting permissions. To identity if connector needs to collect permissions (who has which type of access for the file shares), connector relies on the list of requested attributes from OpenIAM side. The list of such attributes is set in 'Attribute names lookup' parameter of OpenIAM synchronization configuration page. If this list contains 'Permissions' attribute - connector will try to pull permissions for each file share that was found. If this attribute will not be listed - 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 property that is updated each time the object is modified. In OpenIAM PowerShell connector you can use 'Mdified' property to address that value.

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

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

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

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

DateTime format requested from AD connector

Above setting could be changed in 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 sprcific for this connector.

  • It is always better to specify DNS hostname of your domain controller at Managed system configuration page. Especially when connector server is the member of domain. Specifying IP address may lead to non obvious errors.
  • Port 9389 should be opened on domain controller side, so connector could reach it. It should be opened almost in all cases.
  • Sometimes it is useful to try connection to AD in the same way as AD connector does. Just to make sure that 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 feedbacks from our customers. As we receive them, most frequent and/or tricky errors could be found here.

ErrorPossible causeHow to fix
Cannot find newly create user X for further operationsThis is a top stack trace error indicating that connector cannot proceed request due to error that occured a bit earlier. However, other information is not usually taken into account when such message appears on the top.Read full error message, as it should contain exact reason why connector failed to create 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 OpenIAM Managed System configuration. That section allows users to have custom scripts that handle exact operation. However, by default connector uses default Connector.ps1 script, that is located inside connector folder. So, if you have that value specified, you need to make sure that there is a custom handler present inside connector folder.Either remove value and set it to empty - which will make connector work with default script, or make sure that custom connector script exists.
X : The name provided is not a properly formed account nameYou are trying to create 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 prompts 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 password inside Managed System configurationSet password in Managed system configuration