ILST configuration reference guide

Wiki HomeTitle Index

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> 

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>:

ElementDescription
<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>:

ElementDescription
<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>:

ElementDescription
<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:

ElementDescription
<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:

ElementDescription
<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.

0 Comments

Sorry, comments are closed.
  • 1,069 views
  • 14 previews
  • 4 versions
  • 0 comments
  • 1 follower
     
    1 subscriber is following updates on this item.
Labels:

Member Management

Avg. Rating:
Updated By:
Jesse Langstaff
 
June 9, 2022
Posted By:
Jesse Langstaff
 
May 9, 2022
Versions:
v.4
Search this area
Viewed 1,069 times