ILST configuration reference guide

Features and Functionality

Last Updated:

June 9, 2022

Jesse Langstaff

| Version: 4

| 1,733 views

| 0 followers

Last Updated:

June 9, 2022

Jesse Langstaff

| Version: 4

1,733

Publication details

Member Management

The following sections and tables describe the elements of the ILST configuration file and their typical values.

For step-by-step instructions on configuring the ILST, see Configuring the ILST.

Sections in this article:

<Connections>
<UserAccounts>
<Groups>
<OneToOneGroups>
<ApplicationSettings>
<CommunityApi>

<Connections>

The <Connections> element contains one or more <Connection> elements. Each <Connection> element contains connection information to a specific LDAP supported data source (e.g., Microsoft Active Directory, Azure AD).

An example <Connections> element with a single <Connection> element:

<Connections>
   <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>
</Connections

The following table describes the elements of a <Connection>:

Element	Description
<Id>	Contains an integer value that is unique amongst all <Connection> elements. If you have a single <Connection> element use the default value of `1`. However, if you have multiple <Connection> elements, give each <Id> a unique integer value.
<Title>	Contains a unique name that identifies the <Connection>.
<Host>	Contains the hostname or IP Address of your data source.
<Port>	Contains the port number used for the connection. Enter `389` if you are using LDAP. Enter `636` if you are using LDAPS.
<IsSSL>	Contains a boolean value that flags the use of LDAPS or not. Enter `true` if you are using LDAPS. Enter `false` if you are using LDAP.
<AuthenticationType>	Contains the authentication type that the ILST uses to connect to your data source. Enter `Basic` to have the ILST use the provided credentials to log into your data source. Enter `NTLM` to have the ILST use the credentials of the user logged into the machine the ILST is running on. Enter `Negotiate` to have the ILST use either Kerberos (preferred) or NTLM credentials of the user logged into the machine the ILST is running on. `Basic` is strongly recommended for most use cases.
<Username>	Contains the username of a user who has read access to your data source. This value is used to authenticate the user to your data source when using an <AuthenticationType> of `Basic`. This value will be a user's Distinguished Name or User Principal Name. For example: cn=username,ou=users,dc=community,dc=com For more information about distinguished names, see Microsoft \| Distinguished Names.
<PasswordEncrypted>	Contains the password associated with then <Connection> element's <Username> value. This value is used to authenticate the user to your data source when using an <AuthenticationType> of `Basic`. Enter this value as plain text; it will be encrypted during Phase 1 of the configuration process.
<BaseDN>	Contains the Distinguished Name of the point in the data source's hierarchy where the login query will begin from. This must be high enough up in the directory to include the user you are connecting with. For example: dc=community,dc=com For more information about distinguished names, see Microsoft \| Distinguished Names.
<ProtocolVersion>	Contains the LDAP Protocol version to be used. This value should be set to `3`.
<PageSize>	Contains the number of results to be returned on each page from the data source. This value should be set to `1000`.
<ReferralChasingOption>	Contains any referral chasing preferences the query should have. This element is typically left empty unless Igloo Support requests that you add a value.

<UserAccounts>

The <UserAccounts> element contains one or more <UserAccount> elements. Each <UserAccount> element contains information for syncing users and user profile information.

You are required to have a <UserAccount> element for each <Connection> you have.

An example <UserAccounts> element with a single <UserAccount> element and a single additional <Attribute>:

<UserAccounts>
    <UserAccount>
      <Title>User Accounts</Title>
      <ConnectionId>1</ConnectionId>
      <SearchString>(&amp;(objectclass=user)(mail=*)(givenName=*)(sn=*)((!userAccountControl:1.2.840.113556.1.4.803:=2)))</SearchString>
      <SearchScope>Subtree</SearchScope>
      <RevokeIfFoundInSearch>false</RevokeIfFoundInSearch>
      <RevokeDisabled>false</RevokeDisabled>
      <!-- BaseDN for the query -->
      <BaseDN>OU=users,dc=community,dc=com</BaseDN>
      <AccessControlAttribute>userAccountControl</AccessControlAttribute>
      <EmailAttribute>
        <ActiveDirectoryName>mail</ActiveDirectoryName>
        <IglooName>email</IglooName>
        <DataTypeParser>DirectString</DataTypeParser>
      </EmailAttribute>
      <UniqueIdentiferAttribute>
        <ActiveDirectoryName>objectGUID</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>l</ActiveDirectoryName>
          <IglooName>city</IglooName>
          <DataTypeParser>DirectString</DataTypeParser>
          <ClearIfEmpty>false</ClearIfEmpty>
        </Attribute>
      </Attributes>
    </UserAccount>
  </UserAccounts>

The following table describes the elements of a <UserAccount>:

Element	Description
<Title>	Contains a unique name that identifies the <UserAccount>.
<ConnectionId>	Contains an integer value that matches the <Id> of the associated <Connection>. If you have a single <Connection> element, use the default value of `1`.
<SearchString>	Contains an LDAP search string that the ILST will use to return a pool of users from your data source that will then be synced to your digital workplace. For examples of common LDAP search strings, see Common LDAP Search Strings used with the ILST.
<SearchScope>	Contains a value that indicates how far down the <SearchString>should look in the directory structure for results. Enter `SubTree` to set the scope of the <SearchString> to all child objects at any depth of the <BaseDN>. Enter `Base` to set the scope of the <SearchString> to only the <BaseDN> itself. Enter `OneLevel` to set the scope of the <SearchString> to the immediate children of the <BaseDN>. Typically this will be set to `SubTree`.
<RevokeIfFoundInSearch>	Contains a boolean value that determines whether the ILST will revoke all user accounts returned by the <SearchString> from your digital workplace. Enter `true` to revoke all users returned by the <SearchString>. Enter `false` to not revoke all users returned by the <SearchString>.
<RevokeDisabled>	Contains a boolean value that determines whether the ILST will revoke all disabled user accounts returned by the <SearchString>from your digital workplace. Enter `true` to revoke disabled user accounts returned by the <SearchString>. Enter `false` to not revoke disabled user accounts returned by the <SearchString>. Disabled user accounts will be added and updated, similar to active user accounts. In Microsoft Active Directory, a disabled user account will have a value of ACCOUNTDISABLE in their AccessControlAttribute.
<BaseDN>	Contains the Distinguished Name of the point in the data source's hierarchy where the <SearchString> will begin from. All users you want to sync with your digital workplace need to be at or below this point in your data source. For example: ou=users,dc=community,dc=com For more information about distinguished names, see Microsoft \| Distinguished Names.
<AccessControlAttribute>	Contains the attribute name that has information about a user's account status. The default value is `userAccountControl`.
<EmailAttribute>	Contains elements that identify the name of the email attribute in your data source and digital workplace. These elements are: <ActiveDirectoryName>: Contains the name of the email attribute in your data source. The default value is `mail`. <IglooName>: Contains the name of the email attribute in your digital workplace. The default value is `email`. <DataTypeParser>: Contains the data type that the attribute uses. The default value is `DirectString`.
<UniqueIdentiferAttribute>	Contains elements that identify the name of the unique ID attribute in your data source and digital workplace. These elements are: <ActiveDirectoryName>: Contains the name of the unique ID attribute in your data source. The default value is `objectGUID`. <IglooName>: Contains the name of the unique ID attribute in your digital workplace. The default value is `customIdentifier`. <DataTypeParser>: Contains the data type that the attribute uses. The default value is `Guid`. The value used for the <UniqueIdentiferAttribute> should: Be unique across your organization. Never change.
<FirstNameAttribute>	Contains elements that identify the name of the first name attribute in your data source and digital workplace. These elements are: <ActiveDirectoryName>: Contains the name of the first name attribute in your data source. The default value is `givenName`. <IglooName>: Contains the name of the first name attribute in your digital workplace. The default value is `firstname`. <DataTypeParser>: Contains the data type that the attribute uses. The default value is `DirectString`.
<SurnameAttribute>	Contains elements that identify the name of the last name attribute in your data source and digital workplace. These elements are: <ActiveDirectoryName>: Contains the name of the last name attribute in your data source. The default value is `sn`. <IglooName>: Contains the name of the last name attribute in your digital workplace. The default value is `lastname`. <DataTypeParser>: Contains the data type that the attribute uses. The default value is `DirectString`.
<ManagerAttribute>	Contains elements that identify the name of the manager attribute in your data source. These elements are: <ActiveDirectoryName>: Contains the name of the manager attribute in your data source. The value for this field in Active Directory is `manager`. <ClearIfEmpty>: Contains a boolean value that determines whether the ILST should clear the manager attribute in your digital workplace if the data source no longer contains a value for it. Enter `true` to clear manager profile fields in your digital workplace that are empty in your data source. Enter `false` to not clear manager profile fields in your digital workplace that are empty in your data source. The <ManagerAttribute> can only be synced from an on-prem Active Directory.
<ProfilePictureAttribute>	Contains elements that identify the name of the profile picture in your data source. These elements are: <ActiveDirectoryName>: Contains the name of the profile picture attribute in your data source. The default value is `thumbnailPhoto`. <DataTypeParser>: Contains the data type that the attribute uses. The default value is `RawBytes`. This attribute automatically syncs when a new user is created in your digital workplace. However, to make updates to existing digital workplace users, the ILST must be run with the `-pictures` argument. The <ProfilePictureAttribute> can only be synced from an on-prem Active Directory.
<Attributes>	Contains additional <Attribute> elements that you want to sync from your data source to your digital workplace. Each <Attribute> element must contain the following elements: <ActiveDirectoryName>: Contains the attribute's name as it appears in your data source. <IglooName>: Contains the attribute's name as it appears in your digital workplace. For a list of available fields, see Profile fields reference table. <DataTypeParser>: Contains the data type that the attribute uses. Enter `DirectString` if the attribute is a string of text. Enter `Guid` if the attribute is a binary GUID value such as objectGUID. Enter `SecurityIdentifier` if the attribute is a SID value. Enter `DateTime` if the attribute is a date and time. <ClearIfEmpty>: Contains a boolean value that determines whether the ILST should clear the attribute in your digital workplace if the data source no longer contains a value for the attribute. Enter `true` to clear profile fields in your digital workplace that are empty in your data source. Enter `false` to not clear profile fields in your digital workplace that are empty in your data source. Example of the <Attributes> element that contains two additional <Attribute> elements: <Attributes> <Attribute> <ActiveDirectoryName>example_start_date</ActiveDirectoryName> <IglooName>work_start_date</IglooName> <DataTypeParser>DateTime</DataTypeParser> <ClearIfEmpty>false</ClearIfEmpty> </Attribute> <Attribute> <ActiveDirectoryName>example_title</ActiveDirectoryName> <IglooName>occupation</IglooName> <DataTypeParser>DirectString</DataTypeParser> <ClearIfEmpty>false</ClearIfEmpty> </Attribute> <Attributes>

<Groups>

The <Groups> element contains one or more <Group> elements. Each <Group> element contains information for syncing a specific collection of users in your data source to a specific group in your digital workplace.

The <Groups> element is optional and commented out by default. To begin syncing groups, remove the comments and fill out a <Group> element for each group you want the ILST to populate.

An example <Groups> element with a single <Group> element:

<Groups>
   <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>
</Groups>

The following table describes the elements of a <Group>:

Element	Description
<Title>	Contains a unique name that identifies the <Group>. Using the name of the Igloo group you are syncing to is recommended.
<ConnectionId>	Contains an integer value that matches the <Id> of the associated <Connection>. If you have a single <Connection> element, use the default value of `1`.
<SearchString>	Contains an LDAP search string that the ILST will use to return a pool of users from your data source that will then be synced to the <IglooGroup> in your digital workplace. If users are not returned by the <SearchString> in the associated <UserAccount> element, they are ignored and not synced to the specified <IglooGroup>. For examples of common LDAP search strings, see Common LDAP Search Strings used with the ILST.
<SearchScope>	Contains a value that indicates how far down the <Group> element's <SearchString> should look in the directory structure for results. Enter `SubTree` to set the scope of the <SearchString> to all child objects at any depth of the <BaseDN>. Enter `Base` to set the scope of the <SearchString> to only the <BaseDN> itself. Enter `OneLevel` to set the scope of the <SearchString> to the immediate children of the <BaseDN>. Typically this will be set to `SubTree`.
<RevokeIfFoundInSearch>	Contains a boolean value that determines whether the ILST will remove all user accounts returned by the <Group> element's <SearchString> from their associated <IglooGroup>. Enter `true` to revoke all users returned by the <Group> element's <SearchString>. Enter `false` to not revoke all users returned by the <Group> element's <SearchString>.
<RevokeDisabled>	Contains a boolean value that determines whether the ILST will remove all disabled user accounts returned by the <Group> element's <SearchString> from their associated <IglooGroup>. Enter `true` to revoke disabled user accounts returned by the <Group> element's <SearchString>. Enter `false` to not revoke disabled user accounts returned by the <Group> element's <SearchString>. Disabled user accounts will be added and updated, similar to active user accounts. In Microsoft Active Directory, a disabled user account will have a value of ACCOUNTDISABLE in their AccessControlAttribute.
<IglooGroup>	Contains the GUID of an existing digital workplace group that you want to sync users with. For instructions on finding the GUID values of groups in your digital workplace, see Finding group GUIDs for ILST group mapping. An example group GUID: 3d184726-fcb4-4719-8773-e132221e1b18
<AccessControlAttribute>	Contains the attribute name that has information about a user's account status. The default value is `userAccountControl`.
<BaseDN>	Contains the Distinguished Name of the point in the data source's hierarchy where the <Group> element's <SearchString> will begin from. All users you want to sync with a digital workplace group need to be at or below this point in your data source. For example: ou=users,dc=community,dc=com For more information about distinguished names, see Microsoft \| Distinguished Names.

<OneToOneGroups>

The <OneToOneGroups> element contains one or more <GroupId> elements. Each <GroupId> element contains the GUID of an existing digital workplace group that you want to have the ILST manage. When doing this, keep in mind the following:

A managed group will have its membership determined by the results of a <Group> element's <SearchString>.
<GroupId> should contain the value of the associated <Group> element's <IglooGroup> element.
Groups managed by the ILST should not be manually managed from within your digital workplace.

The <OneToOneGroups> element is optional and commented out by default. To have the ILST manage the membership of groups, remove the comments and fill out a <GroupID> element for each group you want the ILST to manage.

An example <OneToOneGroups> element with a single <GroupId> element:

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

<ApplicationSettings>

The <ApplicationSettings> element contains elements that determine how the ILST functions and how it revokes users.

An example of a default <ApplicationSettings> element:

  <ApplicationSettings>
    <TestMode>true</TestMode>
    <TestOutputDirectory>.\</TestOutputDirectory>
    <RevokeAdmins>false</RevokeAdmins>
    <RevokeIfNotInSearch>false</RevokeIfNotInSearch>
    <RevokeNonDelegateUsers>false</RevokeNonDelegateUsers>
    <RevokeUsersNotManagedByLdap>false</RevokeUsersNotManagedByLdap>
    <AllowIdChange>true</AllowIdChange>
  </ApplicationSettings>

The following table describes the elements contained in the <ApplicationSettings > element:

Element	Description
<TestMode>	Contains a boolean value that determines whether the ILST will output the resulting sync to a file on your computer rather than making changes to your digital workplace. Enter `true` to have the ILST sync user account changes to a test file. Enter `false` to have the ILST sync user account changes to your digital workplace.
<TestOutputDirectory>	Contains the location where <TestMode> files are saved. The ILST will create this location if it does not already exist. The default value is `.\`.
<RevokeAdmins>	Contains a boolean value that determines whether the ILST will revoke digital workplace administrators. Enter `true` to allow the ILST to revoke digital workplace administrators. Enter `false` to prevent the ILST from revoking digital workplace administrators. To learn more about common revoke configurations, see Revoking users with the ILST.
<RevokeIfNotInSearch>	Contains a boolean value that determines whether the ILST will revoke users not found in a <UserAccount> element's <SearchString>. Enter `true` to allow the ILST to revoke users not found in a <UserAccount> element's <SearchString>. Enter `false` to prevent the ILST from revoking users not found in a <UserAccount> element's <SearchString>. To learn more about common revoke configurations, see Revoking users with the ILST.
<RevokeNonDelegateUsers>	Contains a boolean value that determines whether the ILST will revoke users who have only authenticated to your digital workplace with Igloo authentication. Enter `true` to allow the ILST to revoke users who have only authenticated to your digital workplace with Igloo authentication. Enter `false` to prevent the ILST from revoking users who have only authenticated to your digital workplace with Igloo authentication. To learn more about common revoke configurations, see Revoking users with the ILST.
<RevokeUsersNotManagedByLdap>	Contains a boolean value that determines whether the ILST will revoke users who are not flagged as being managed by the ILST. Enter `true` to allow the ILST to revoke users who are not flagged as being managed by the ILST. Enter `false` to prevent the ILST from revoking users who are not flagged as being managed by the ILST. To learn more about common revoke configurations, see Revoking users with the ILST.
<AllowIdChange>	Contains a boolean value that determines whether the ILST can update customIdentifiers. Enter `true` to allow the ILST to update customIdentifiers. Enter `false` to prevent the ILST from updating customIdentifiers.

<CommunityApi>

The <CommunityApi> element contains elements that describe how the ILST connects to and interacts with your digital workplace.

An example of a <CommunityApi> element:

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

The following table describes the elements contained in the <CommunityApi> element:

Element	Description
<Domain>	Contains the fully qualified root domain of your digital workplace. For example: https://www.yourcommunity.com
<Username>	Contains the email address of a digital workplace administrator's user account. This user account should not be used for normal interaction (i.e., creating content or other administration) in the workplace. For example: syncadmin@emailaddress.com
<PasswordEncrypted>	Contains the Igloo authentication password associated with the <CommunityApi> element's <Username> value. Enter this value as plain text; it will be encrypted during Phase 1 of the configuration process.
<UniqueIdentifierName>	Contains the name of the attribute that the ILST uses as a unique identifier. This value should always be `customIdentifier`.
<ManagedByLdapFieldName>	Contains the name of the attribute that the ILST uses to flag as being managed by it. This value should always be `managedByLdap`.
<ProfileBatchSize>	Contains the number of users returned by the Igloo API. The default value is `250`.
<ManagerNameFieldName>	Contains the name of the attribute that the ILST uses to sync the manager name. This value should always be `i_report_to`.
<ManagerEmailFieldName>	Contains the name of the attribute that the ILST uses to sync the manager's email address. This value should always be `i_report_to_email`.