This article is useful for: Community Administrators.

What is the Igloo LDAP Sync Tool?

The Igloo LDAP Sync Tool (ILST) is a dedicated, installable application which allows IT Administrators to automatically sync their corporate Active Directory with the Igloo platform. Functions supported by ILST include the following:

1. Creating users
2. Updating user data and group membership
3. Revoking users

ILST syncs both Group and Personal Profile data stored corporate Active Directory (AD) to the Igloo Platform. ILST is installed and runs on the AD server, and updates the Igloo Platform to mirror the AD structure it is synced with. ILST only reads data from the corporate LDAP directory; it will not modify or remove any data. 

Where to find the Igloo LDAP Sync Tool

The ILST is available to administrators whose communities have LDAP Syncing enabled. Speak to your account manager to gain access and download the tool.

How ILST Works

ILST uses two major aspects to create a sync:

1. User Accounts (UAs): Define the overall membership structure in the Igloo Platform, as well as the personal profile data mapping between the AD and the Igloo Platform. During a User Account sync, ILST performs LDAP queries to generate a list of User Accounts. IT Administrators can customize how users should be treated for each UA entry in the configuration.
2. Groups:  Define group membership of users found in UAs. During a Group Sync, ILST performs LDAP queries, and uses the resulting list to match each entry to the appropriate User Account from the previous step.
3. ILST gets the current Igloo Platform membership data (e.g. user account information, profile data and the groups each user belongs to).
4. ILST matches Igloo Platform users to corporate AD users, and updates the Igloo Platform to match the corporate AD list.

Security

• ILST can run on any server in the domain. ILST is 100% in the control of the user. Igloo does not collect any data from the LDAP connection.
• ILST can use LDAP or LDAPS (LDAP + SSL), and can use any port, not just the standard LDAP ports.
• If the Igloo Platform is configured to authorize connections via the Igloo API, it will use HTTPS using port 443.
• The LDAP connection and API passwords are encrypted using AES encryption.

Setting up ILST:

Step 1: Set up your application settings in the Config.xml file

 <ApplicationSettings>
    <TestMode>true</TestMode>
    <TestOutputDirectory>C:\temp\LDAP1</TestOutputDirectory>
    <RevokeAdmins>true</RevokeAdmins>
    <RevokeIfNotInSearch>true</RevokeIfNotInSearch>
    <RevokeNonDelegateUsers>true</RevokeNonDelegateUsers>
    <RevokeUsersNotManagedByLdap>false</RevokeUsersNotManagedByLdap>
    <AllowIdChange>false</AllowIdChange>
  </ApplicationSettings> 

• Until you are ready to go live with your sync, ensure that <TestMode> is set to True. This will output the resulting sync data to an excel sheet instead of connecting to the Igloo Platform.
• Fill in <TestOutputDirectory> to a directory you wish to output the test excel sheet to (the application will create the directory if it does not exist).
• If the Igloo Platform is configured to be a 100% enabled LDAP site (e.g. meaning all users should be managed by ILST), ensure the following settings are made:
• 
  
  • <RevokeNonDelegateUsers> should be True. This will allow the tool to manage all of your users, regardless of how they login.
  • <RevokeUsersNotManagedByLdap> should be True. This will allow the tool to manage all of your users, regardless of whether they were created or modified by ILST.
• If the Igloo Platform is managed by both ILST, and via the Igloo Platform, ensure the following settings are configured
• 
  
  • <RevokeNonDelegateUsers> To be False. Users are marked as delegate when they are created by ILST, or when they first log in using LDAP or SAML authentication within the Igloo Platform if it is configured.
  • <RevokeUsersNotManagedByLdap> to be False. This will cause ILST to ignore any user that was not explicity created by, or modified by ILST.
• <RevokeAdmins> should be set depending on IT requirements.
• 
  
  • If false, ILST marks users with admin privileges within the Igloo Platform. The result is that admin users will NOT be revoked.
  • If set to true, admins can be revoked.
  • This is used to provide a level of safety to your sync. It ensures that Administrators are not accidentally revoked from the Igloo Platform. You can still revoke Administrators from the Igloo Platform using the Control Panel. This is available even if <RevokeAdmins> is set to false.
• <RevokeIfNotInSearch> should be set depending on your corporate requirements. 
• 
  
  • If set to True, any users not found in the UserAccount search results that are currently members in the Igloo Platform will be revoked Use this setting to ensure that the Igloo Platform is always in sync with your LDAP directory.
  • Even if <RevokeIfNotInSearch> is set to True, it will respect the following application settings:
  • 
    
    • <RevokeAdmins> Even if a user is marked to be revoked from <RevokeIfNotInSearch>, if they are an Administrator, they will be skipped if <RevokeAdmins> is set to False.
    • <RevokeNonDelegateUser> Even if a non-delegated user is marked to be revoked from <RevokeIfNotInSearch>, they will be skipped if <RevokeNonDelegatedUsers> is set to False.
    • <RevokeUsersNotManagedByLdap>. Even if a user not managed by LDAP is marked to be revoked from <RevokeIfNotInSearch>, they will be skipped even if <RevokeUsersNotManagedByLdap> is set to False.
• <AllowIdChange> will only need to be True if the sync is needed to update the customIdentifiers of the users in the community, and should otherwise be set to False.

Step 2: Setup Logging

Out of the box, ILST will log errors to the same directory that the application resides in, as "syncLog.log". If you wish to further configure Nlog, you may do so. When sending issues to your support representative, please incude the syncLog file. Your support representative may ask you to re-run the sync on Trace or Debug mode to get further information from the process (See below on how to do that).

ILST uses NLog (http://nlog-project.org/) to provide logging feedback. When run, the application will read configuration data from NLog.config in the same directory as the .exe. To change the level of detail output, set "minlevel" to be one of the following values:

• 
  
  • Trace
  • Debug
  • Info
  • Error
• Note: When you are done testing, ensure that logging is set to Info or Error, as Debug and Trace output a lot of data, and will cause performance degredation.
• You can also configure where the log file is created by altering the "fileName" attribute from "syncLog.log" to the file path of your choice.
• If you wish to further customize logging, please read the NLog documentation for the various options you have.

Step 3: Set up your connection data

To set up your LDAP connection, open the config file provided in the ILST package, and look for the first item. (This will be line 3 of your config document.)

<Connection>
      <Id>1</Id>
      <Title>LDAP Connection</Title>
      <Host>ldap.community.com</Host>
      <Port>636</Port>
      <IsSSL>true</IsSSL>
      <AuthenticationType>Basic</AuthenticationType>
      <Username>cn=username,ou=users,dc=community,dc=com</Username>
      <PasswordEncrypted>mypassword</PasswordEncrypted>
      <BaseDN>OU=users,dc=community,dc=com</BaseDN>
      <ProtocolVersion>3</ProtocolVersion>
      <PageSize>1000</PageSize>
      <ReferralChasingOption></ReferralChasingOption>
</Connection>

For your LDAP connection, update the following fields:

• Id: If you only have a single connection, do not update this. If you have multiple, give each connection a unique integer value.
• Title: This is only used for logging feedback, if you wish to give your connection a friendly name, do so here.
• Host: Enter the hostname or IP value of where you LDAP connection can be reached.
• Port: Enter the port through which the LDAP connection will operate. The default port for LDAP is 389, and the default for LDAPS is 636.
• IsSSL: If you have LDAP + SSL (LDAPS) enabled, and wish to use this, set to True. Otherwise set to False.
• AuthenticationType: Currently ILST only supports the following authentication types. If you do not know what this value means, please leave it as Basic.
• 
  
  • Basic
  • Ntlm
  • Negotiate
  • 
    
    • Note: if you are using Ntlm or Negotiate authentication, the application will treat the current user that is running the application as the sync user. Ensure this user has rights to perform LDAP queries.
  • Anonymous
• Username: If you are using Basic authentication, this is the Distinguished Name (DN) of the user to login with. The format should look something like this (CN=user,OU=users,DC=ldap,DC=com). Do not use the account name for this user.
• PasswordEncrypted: When first entering this value, enter it as plain text. Before you run your first sync test, ensure you follow the steps in "Encrypting your Password".
• PageSize: Typically set to 1000, this determines the amount of results returned in each page from the AD. 
• ReferralChasingOption: This is a setting designed to address a paging issue in specific AD implementations. If your sync is only returning a thousand members in its query, setting this option to "none" can resolve the issue. 

Step 4: Setup a User Account

For a basic sync, you will need to set a UserAccount entry. This will consist of an LDAP query, and attribute mapping. To build and use an LDAP query, we recommend using a 3rd party LDAP browser tool. Softerra's LDAP Browser (http://www.ldapbrowser.com/) is a free, lightweight LDAP browser tool that can help you gather information for your sync. See documentation at Softerra's site for instructions on how to perform directory searches.

Note: The provided example in the ILST package will search the BaseDN in Connection for all users that have an email address, a first name and a last name. This is the required data to perform a sync to Igloo.    

 <UserAccount>
      <Title>Employees</Title>
      <ConnectionId>1</ConnectionId>
      <SearchString>(&(mail=*)(givenName=*)(sn=*))</SearchString>
      <SearchScope>Subtree</SearchScope>
      <RevokeIfFoundInSearch>false</RevokeIfFoundInSearch>
      <RevokeDisabled>true</RevokeDisabled>
      <BaseDN>OU=IglooSoftware,DC=igloosoftware,DC=pvt</BaseDN>
      <AccessControlAttribute>userAccountControl</AccessControlAttribute>
      <EmailAttribute>
        <ActiveDirectoryName>mail</ActiveDirectoryName>
        <IglooName>email</IglooName>
        <DataTypeParser>DirectString</DataTypeParser>
      </EmailAttribute>
      <UniqueIdentiferAttribute>
        <ActiveDirectoryName>userGUID</ActiveDirectoryName>
        <IglooName>customIdentifier</IglooName>
        <DataTypeParser>Guid</DataTypeParser>
      </UniqueIdentiferAttribute>
      <FirstNameAttribute>
        <ActiveDirectoryName>givenName</ActiveDirectoryName>
        <IglooName>firstname</IglooName>
        <DataTypeParser>DirectString</DataTypeParser>
      </FirstNameAttribute>
      <SurnameAttribute>
        <ActiveDirectoryName>sn</ActiveDirectoryName>
        <IglooName>lastname</IglooName>
        <DataTypeParser>DirectString</DataTypeParser>
      </SurnameAttribute>
      <ManagerAttribute>
        <ActiveDirectoryName>manager</ActiveDirectoryName>
      </ManagerAttribute>
      <ProfilePictureAttribute>
        <ActiveDirectoryName>thumbnailPhoto</ActiveDirectoryName>
        <DataTypeParser>RawBytes</DataTypeParser>
      </ProfilePictureAttribute>
      <Attributes>
        <Attribute>
          <ActiveDirectoryName>title</ActiveDirectoryName>
          <IglooName>occupation</IglooName>
          <DataTypeParser>DirectString</DataTypeParser>
          <ClearIfEmpty>false</ClearIfEmpty>
        </Attribute>
       </Attributes>
</UserAccount>      

• Title: Enter a friendly name for the entry. This is used for logging.
• ConnectionId: This matches to the Entry with the same ID in the Connections. Keep as 1, unless you have multiple connections.
• SearchString: The sync will perform this search against your AD server. To validate, this has to be XML encoded (i.e. ampersand (&) characters should be encoded to "&"). Use Softerra's LDAP Browser or another LDAP browser application to create an LDAP query.
• SearchScope: This represents how far down the search should look in the directory structure for results. Values can be Base, OneLevel or Subtree.
  • Base: Object level. This will only return the object in BaseDN, if it meets the search query.
  • OneLevel: Returns all objects that are direct children of the BaseDN.
  • SubTree: Returns all objects of any depth of the baseDN.
• RevokeIfFoundInSearch: If set as "true", instead of adding the users found in this search, the sync tool will mark all users from from this search to be revoked from the community. This should be used if you have a custom way of determining disabled users, and need to reflect that in the sync.
• RevokeDisabled: If set as "true", users that are marked as disabled (from the AccessControlAttribute attribute in your AD) will be revoked from the community. If "false", users will be added/updated, and the UserAccessControl value will be ignored.
• AccessControlAttribute: The active directory attribute that represents the user's account status. This is usually userAccountControl (It is rare, if not impossible, for this value to be different).
• BaseDN: Distinguished name to perform searches with. 
• EmailAttribute: The Attribute in Active Directory that stores the user's email address. This is a required field, and must be available in AD. See Attributes section for details on how to create and fill out an attribute.
• 
  
  • Note: The default attribute is usually mail.
• UniqueIdentifierAttribute: The Attribute in Active Directory that stores a unique value to identify the user. This is a required field, and must be available in the AD.              
  • if using multiple connections, please ensure that user values are indeed unique. If two distinct users have the same unique identifier value, they will be treated as the same user in the sync. (See Order of operations/Priority for more information.)
  • The default attribute is usually objectGUID.
  • objectSID will not work as a unique identifier.
• FirstNameAttribute: The Attribute in Active Directory that stores the user's first name. This is a required field, and must be available in the AD. See Attributes section for details on how to create and fill out an attribute              
  • Note: The default attribute is usually givenName.
• SurnameAttribute: The Attribute in Active Directory that stores the user's surname. This is a required field, and must be available the in AD. See Attributes section for details on how to create and fill out an attribute.              
  • Note: The default attribute is usually sn.
• ManagerAttribute: The Attribute in Active Directory that stores the user's manager. This is an optional field, only used if it's available the in AD. The AD field name is all that's required in this area.           
  • Note: the default attribute is usually manager.
• ProfilePictureAttribute:
  • The Attribute in Active Directory that stores the user's profile picture. This is an optional field, only used if it's available the in AD. The AD field name is all that's required in this area.           
    • Note: the default attribute is usually thumbnailPhoto.
    • To sync profile pictures, run the tool with the -pictures argument in the command line.
• Attributes: This represents a list of other, optional attributes to map to Igloo. See Attributes section for details on how to create and fill out an attribute.              
  • The Clear If Empty field empowers the ILST to clear the attribute field in Igloo if the AD field is empty. 
  • Note: Do not include first, last name or email in the list of attributes.

Step 5: Set Up Attributes

If you require more than the basic required attributes to sync, (first name, lastname, email address) then other profile fields can be entered in the List in the user account. For each attribute, enter the AD attribute name, the attribute name in Igloo, and what kind of object that is.      

<Attribute>
          <ActiveDirectoryName>title</ActiveDirectoryName>
          <IglooName>occupation</IglooName>
          <DataTypeParser>DirectString</DataTypeParser>
</Attribute>        

• ActiveDirectoryName: This is the attribute name in the AD. This can be found through the LDAP browser, or in your Active Directory schema.
• IglooName: This is the system attribute for the profile in Igloo. A list of available profile fields are available in your community under Bulk Member Upload. If you have custom profile fields, please contact your account representative to get this list, if one was not provided with the package.
• DataTypeParser: This dictates how the data should be gathered from the AD server. Before running the sync live, you should run a test to ensure data is properly returned in the output excel sheet. Parser types include the following values:
• 
  
  • DirectString: This is a simple string of text and is the data type to choose for most attibutes.
  • Guid: This is a binary GUID value, such as objectGUID. (If the GUID is any form other than a byte array, then use DirectString.)
  • SecurityIdentifier: This is primarily for the SID value, if you need to sync it.
  • DateTime: This represents a date and time in your LDAP directory.

Step 6: Set Up Group Mapping

If you are only setting up community membership, and do not need to setup custom group or space membership, this step can be skipped. If you wish to sync groups in the future, this can be added at a later time as well.

Note: If a user is not found the User Account search, but is found in the Group Mapping, that user will be ignored in the Group sync.

To setup a group sync, you'll need to know the system ID of the group(s) you wish to sync in your community. You can acquire those yourself by following these steps, or you can request a support representative can provide you with a list of those group IDs. 

For each group to set up, add a new group item with the following configuration:

 <Group>
      <Title>Users</Title>
      <ConnectionId>1</ConnectionId>
      <SearchString>(&(mail=*)(giveName=*)(sn=*))</SearchString>
      <SearchScope>Subtree</SearchScope>
      <RevokeIfFoundInSearch>false</RevokeIfFoundInSearch>
      <RevokeDisabled>true</RevokeDisabled>
      <IglooGroup>{Group ID Here}</IglooGroup>
      <AccessControlAttribute>userAccountControl</AccessControlAttribute>
      <BaseDN>Ou=users,DC=community,DC=com</BaseDN>
</Group>

• Title: Friendly name for the entry, used for logging.
• ConnectionId: This matches the group to the entry in Connections with the same ID.
• SearchString: The sync will perform this search against your LDAP server. To validate, this has to be XML encoded (i.e. ampersand (&) characters should be encoded to "&"). Use Softerra's LDAP Browser, or another LDAP browser application to create an LDAP query.
• SearchScope: Again, the options here are Base, OneLevel or Subtree. This determines how deep the search will go in your AD structure to get results.              
  • Base: Object level. This will only return the object in BaseDN, if it meets the search query.
  • OneLevel: Returns all objects that are direct children of the BaseDN.
  • SubTree: Returns all objects of any depth of the BaseDN.
• RevokeIfFoundInSearch: If set as "true", instead of adding the users found in this search to the group, the sync tool will mark all users from from this search to be revoked from the group.
• RevokeDisabled: If set as "true", users that are marked as disabled (from the AccessControlAttribute attribute in your AD) will be revoked from the group. If "false", users will be added to the group, and the UserAccessControl value will be ignored.
• IglooGroup: The Igloo System ID of the Group to add the user to. This will be a GUID value as described above
• AccessControlAttribute: The AD attribute that represents the user's account status.              
  • This is usually userAccountControl (It is rare, if not impossible, for this value to be different).
• BaseDN: Distinguished Name to perform searches with. If blank, it will use BaseDN value from the corresponding Connection.

If any of your groups should be One-to-One, which means that users that are not found in the Group search should be revoked from the group, you have to add the IglooGroup value in the group to the list of GroupIds in . For example, if your group id was "3d184726-fcb4-4719-8773-e132221e1b18", your One To One Groups should look like this:

<OneToOneGroups>
    <GroupId>3d184726-fcb4-4719-8773-e132221e1b18</GroupId>        
</OneToOneGroups>

A group should be set as One-To-One if this group is solely managed by the LDAP tools, and should not have other members added to it through the community.

Step 7: Setup API Settings

To connect to your community's API, you must have a user created in the community with administrator privileges. See https://support.igloosoftware.com/discover/features/members for details on how to create a new user in your community. This user account should not be used for normal interaction (i.e. creating content or other administration). If you change this user's password in the community, you must update the password in your configuration as well.

<CommunityApi>
    <Domain>https://www.yourcommunity.com</Domain>
    <Username>syncadmin</Username>
    <PasswordEncrypted>syncpassword</PasswordEncrypted> 
    <UniqueIdentifierName>customIdentifier</UniqueIdentifierName>
    <ManagedByLdapFieldName>managedByLdap</ManagedByLdapFieldName>
    <ManagerNameFieldName>i_report_to</ManagerNameFieldName>
    <ManagerEmailFieldName>i_report_to_email</ManagerEmailFieldName>
    <ProfileBatchSize>250</ProfileBatchSize>
</CommunityApi>

• Domain: This is the root domain to your community. if your community has HTTPS enabled, please prepend https:// to the URL. If the community does not, please prepend http://
• Username: The email address, or LDAP account name of the user to login to your community with (the value will be different depending on how your community's Authentication is set up).
• PasswordEncrypted: The password for this user, which will be either LDAP, or Igloo Auth, depending on your authentication settings. When first entering this value, enter it as plain text. Before you run your first sync test, ensure you follow the steps in "Encrypting your Password".
• UniqueIdentifierName: This will be how the sync matches the Igloo user to the LDAP Directory user. This should match the value in your User Account section. If you use email to identify the user, use "mail". If you use a unique value other than email (for example, userGUID), enter "customIdentifier".
• ManagedByLdapFieldName: if RevokeUsersNotManagedByLdap is set to false in your application, this value has to be filled out. Unless otherwise instructed, enter "managedByLdap" for this field.
• ManagerNameFieldName: This will select the Igloo field that the manager's name is synced to. Unless otherwise instructed, enter i_report_to in this field.
• ManagerEmailFieldName: This will select the Igloo field that the manager's email is synced to. Unless otherwise instructed, enter i_report_to_email in this field.
• ProfileBatchSize: This determines the number of users returned through the Igloo API. The minimum is 100, and the maximum is 1000. 

Step 8: Encrypt your password

For the sync process to work, passwords have to first be encrypted by the tool. To update your passwords, follow these steps:

1. Enter your passwords in plain text in the configuration file. (Make sure that you have entered a password in both the and sections.)
2.  In your command prompt, navigate to the folder containing the sync tool.
3.  Run "ILST.exe encrypt". The command window will prompt that the encryption has started, and when it has completed. Press any key to exit.
4. Running this will encrypt the password of config.xml in the same directory as ILST.exe. If you have multiple configurations, or they are in different locations, run "ILST.exe encrypt -f  [configLocation]".
5. To confirm, re-open your config.xml file and view the passwords, they should now have changed, and should be unrecognizable.

Step 9: Run Sync

Before you run the sync, make sure that everything is correct, and especially that in Application Settings is set to True. Run the sync by calling "ILST.exe -f [configLocation]". Replace [configLocation] with the physical path of the config file. For example, if your file is located at C:\Ldap\community.config, you should call: 

ILST.exe -f C:\Ldap\community.config 

Alternately, if you do not provide a value for configLocation, it will default to "config.xml" located in the same directory the ILST.exe file.

If the sync was successfull, an Excel sheel should have been created in the directory that TestOutputDirectory specifies in your application configuration. Additionally, the console will output "Sync Completed", and provide statistics for how many users would have been added, modified and revoked. If not, then an error occured. See the output error logs (set up in "Step 2: Setup Logging") for details as to why this error occured. If the error log did not provide enough information for you to continue, please try again with a greater minimum log level selected (debug or trace, for example).

If you still are getting errors, and are unable to determine why the sync is giving errors, please visit our support forums and ask a question, or contact your support agent.

Step 10: Review Results

Before running the sync in real time, go through the output excel sheet to ensure that all data is correct. Make sure to check the following:

• Each user has a first and last name set, as well as an email address. These fields are required for new users.
• The action for each user (Add, Modify or Revoke) is correct.
• User attributes are in the correct format.
• Attributes are populated correctly, and that each mapped attribute has the correct data from the AD.
• Users that are already in the community are not being revoked innappropriately.

Step 11: Run the Sync in Live Mode

In the configuration file, ensure that is set to False, and then run the sync again. Whenever you change a value in the configuration file (other than ), it is good practice to set TestMode to true, and try a sync with the new data before you do it live. To sync profile pictures, run the sync with the -pictures argument. Syncing all of the profile pictures in the community can take more time than a regular sync. 

Step 12 (Optional): Setup a scheduled task to run Sync

We recommend setting up a new Windows Scheduled Task to run the sync tool periodically.

Note about order of operations/Priority

If conflicting data is found in the sync (for exmaple, in one UserAccount, user A is added, and in second user account, the user is revoked), the last run UserAccount data will override earlier user accounts.

Learn More

Click on the links below to learn more about LDAP syncing and authentication.

• LDAP Authentication