The Compliance 360 Lightweight Directory Access Protocol Sync (LDAP Sync) application is a Microsoft Windows Service that synchronizes your local Active Directory (AD) with the Compliance 360 application. The service is very configurable. This document provides instructions for configuring and supporting LDAP Sync.

The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network.

The Compliance 360 LDAP Sync application application creates the following new objects based on mapping supplied in the configuration if they are not present in the Compliance 360 application:

• Employee with the following information:
  • * primary division (LDAP Sync will NOT create any missing divisions in the Compliance 360 application. Please create the division structure before starting the sync process.)
  • number
  • user name
  • first and last name
  • email
  • job title
  • department
  • groups assigned to
  • company
  • relationships (the related employee must already exist, and the type of relationship is created if it is not available)
  • * user status (which determines if the employee can log in or not)
    Note: Information preceded by an * is required to be included in the configuration mapping.
• Job Title (new values created in the Global division)
• Department (new values created in the employee's division)
• User Group (new values created in the Global division)
• Company (new values created in the Global division)

LDAP Sync also has configurable parameters for error processing and email notifications to the SAI Global Operations team member specified. The system will stop processing after the error threshold value is exceeded. This will stop processing for the current sync job, which will then execute again after the specified wait period. In addition to stopping the current processing, the system will attempt to send an email notification message using the configuration settings.

Compliance 360 LDAP Sync can be installed after obtaining the installation files and following the following steps. If you are interested in configuring this service, contact your account manager or GRC Professional Services representative.

1. Click Next on the first page of the Compliance 360 LDAP Sync Service Setup page.
2. Accept the license agreement.
3. Choose Typical.
4. Choose Install. When prompted for elevated access rights, click Yes because the installation will need administrative privileges to install the Windows service.
5. Choose Finish.

You may configure LDAP Sync by modifying the Compliance360.EmployeeSyncService.exe.config file that is located in the install directory. The default location is C:\Program Files (x86)\SAI Global\Compliance360 LDAP Sync\.

A full sample configuration is listed below. Details on how to configure each section and the purpose of each setting are listed below the sample.

<?xml version="1.0" encoding="utf-8"?>

<configuration>
  <configSections>
    <section
      name="compliance360.sync"
      type="Compliance360.EmployeeSync.Library.Configuration.SyncConfigurationSection, Compliance360.EmployeeSync.Library"
      allowLocation="true"
      allowDefinition="Everywhere" />
  </configSections>
  <compliance360.sync>
    <jobs>
      <job
        name="All Users"
        type="ActiveDirectory"
        domain="sample.org"
        ou="corporate"
        userName=""
        password=""
        ldapQuery="(&amp;(objectClass=user)(objectCategory=person)(!msExchResourceMetaData=ResourceType:Room))"
        removeGroupPrefix=""
        intervalSeconds="3600"
        errorThreshold="10"
        errorNotificationHost=""
        errorNotificationPort="587"
        errorNotificationUseSsl="true"
        errorNotificationUserName=""
        errorNotificationPassword=""
        errorNotificationDomain=""
        errorNotificationEmailFrom=""
        errorNotificationEmailTo=""
        errorNotificationSubject="LDAP Sync error threshold exceeded [ORG_NAME]">
        <attributes>
          <attribute name="domain" includeInQuery="false" filter="DomainAttributeFilter" />
          <attribute name="sAMAccountName" />
          <attribute name="manager" />
          <attribute name="department" />
          <attribute name="title" />
          <attribute name="userPrincipalName" />
          <attribute name="distinguishedName" />
          <attribute name="sn" />
          <attribute name="givenName" />
          <attribute name="mail" />
          <attribute name="isDeleted" />
          <attribute name="userAccountControl" filter="UacAttributeFilter" alias="isActive" />
          <attribute name="memberOf" filter="GroupsAttributeFilter" />
        </attributes>
        <allowedGroups>
          <group name="Compliance360-Users" />
        </allowedGroups>
        <outputStreams>
          <stream name="Csv" />
          <stream name="Compliance360ApiV2">
            <settings>
              <setting name="baseAddress" value="https://secure.compliance360.com" />
              <setting name="organization" value="[ORG_NAME]" />
              <setting name="username" value="[USER_NAME]" />
              <setting name="password" value="[PASSWORD]" />
              <setting name="culture" value="en-US" />
              <setting name="loginIntervalMinutes" value="20">
            </settings>
            <mapping>
              <map from="Main Division" to="PrimaryDivision"/>
              <map from="{domain}\{sAMAccountName}" to="EmployeeNum"/>
              <map from="{domain}\{sAMAccountName}" to="UserName"/>
              <map from="{givenName}" to="FirstName"/>
              <map from="{sn}" to="LastName"/>
              <map from="{mail}" to="Email"/>
              <map from="{title}" to="JobTitleId" type="lookup"/>
              <map from="{department}" to="Department"/>
              <map from="{memberOf}" to="Groups"/>
              <map from="{manager}" to="Relationships" type="Manager"/>
              <map from=="{company}" to="Company" type="company"/>
              <map from="true" to="CanLogin"/>
            </mapping>
          </stream>
        </outputStreams>          
      </job>
    </jobs>
  </compliance360.sync>
</configuration>

The job element contains one or more job elements. Each job defined will run independently and concurrently.

<jobs>
  <job .../>
</jobs>

Synchronization activities are defined as jobs. You can configure one or more jobs within LDAP Sync allowing a single instance of the service to handle multiple sources of users including those in multiple OUs or multiple Domains.

<job
  name="All Users"
  type="ActiveDirectory"
  domain="sample.org"
  ou="corporate"
  userName=""
  password=""
  ldapQuery="(&amp;(objectClass=user)(objectCategory=person)(!msExchResourceMetaData=ResourceType:Room))"
  removeGroupPrefix=""
  intervalSeconds="3600"
  errorThreshold="10"
  errorNotificationHost=""
  errorNotificationPort="587"
  errorNotificationUseSsl="true"
  errorNotificationUserName=""
  errorNotificationPassword=""
  errorNotificationDomain=""
  errorNotificationEmailFrom=""
  errorNotificationEmailTo=""
  errorNotificationSubject="LDAP Sync error threshold exceeded [ORG_NAME]">

The parameters are:

• name
  • The name of the job.
• type
  • The type of job to process. There is only one supported job type in this version of the service. This value must be set to ActiveDirectory for the service to work correctly.
• domain
  • The domain that contains the users you wish to synchronize with the Compliance 360 application specified in a dot-separated format like "mycompany.mydomain.com".
• ou (optional)
  • The organizational unit name which contains the users.
• userName (optional)
  • The username that should be used to connect to the LDAP server. If not specified then the service will connect to the server in the context of the current user.
• password (optional)
  • The password that should be used to connect to the LDAP server.
• ldapQuery
  • The base query used to fetch the Active Directory users. The example listed above will return all users that are not Microsoft Exchange rooms.
• removeGroupPrefix
  • A prefix value that will be removed from each group name. If within Active Directory you create a series of Compliance 360 related groups with a common prefix like Compliance360-Administrators. When the group is added to Compliance 360, you can use the removeGroupPrefix value to create the group Administrators.
• intervalSeconds
  • The number of seconds the system waits between job executions. The default value is one (1) hour.
• errorThreshold
  • The number of errors that may occur before stopping the sync process. If this value is exceeded, the system will also optionally send a notification email.
• errorNotificationHost
  • The SMTP host address. Example: smtp.google.com.
• errorNotificationPort
  • The SMTP port number. Example:: 25
• errorNotificationUseSsl
  • true if the smtp client should use SSL when communicating with the server.
• errorNotificationUserName
  • The SMTP user name
• errorNotificationPassword
  • The SMTP user password
• errorNotificationDomain (optional)
  • The SMTP windows domain
• errorNotificationEmailFrom
  • The address that the email is sent from
• errorNotificationEmailTo
  • The address the email is sent to
• errorNotificationSubject
  • The subject of the email, Ex: LDAP Sync error threshold for [ORG_NAME] was exceeded

Attribute elements are used to configure the attributes that are fetched from Active Directory which will then be mapped to the Compliance 360 employee property values.

  <attribute 
    name="userAccountControl" 
    filter="UacAttributeFilter" 
    includeInQuery="false" 
    alias="isActive" />

The parameters are:

• name
  • The name of the LDAP attribute to return. See https://msdn.microsoft.com/en-us/library/ms675090(v=vs.85).aspx for a complete listing of available LDAP (Active Directory) attributes and their meanings.
• filter (optional)
  • Filters provide special post-processing behavior. The list of available filters and their behavior are listed below in the Attribute Filters section.
• includeInQuery (optional)
  • Enter true if the attribute should be included in the query. The value is helpful when deriving a new value from other values returned from AD. Example: You can return the user's domain value by defining a new attribute called Domain. Then use the DomainAttributeFilter to return the domain value.
• alias (optional)
  • Optional alternate name to be used to rename an attribute in the returned result set.

• DomainAttributeFilter

  • Returns the domain name using the distinguisedName AD attribute to find the first domain component. So if the Distinguished Name value is CN=Marco Lombard,Ou=Users,DC=saig,DC=frd,DC=global" The returned value will be saig. This attribute filter depends on the distinguishedName being present in the attribute list.

  Example use:

  <attribute
    name="domain"
    filter="DomainAttributeFilter"
    includeInQuery="false"
  />

• GroupsAttributeFilter

  • Returns the user's group membership. The values returned respect the removeGroupPrefix job attribute and the <allowedGroups/> configuration.

  Example use:

  <attribute name="memberOf" filter="GroupsAttributeFilter" />

• UacAttributeFilter

  • Analyzes the userAccountControl value and returns a value indicating whether the user is active or has been deleted.

  Example use:

  <attribute name="userAccountControl" filter="UacAttributeFilter" alias="isActive" />

The allowedGroups element is used to filter the group membership and users that will be sent to the Compliance 360 application. If groups are specified, then Active Directory users must be a member of one of the specified groups or they will be filtered out of the result set. This list will also filter the group membership list.

Example: Marco Lombard is a member of the Compliance 360 Users and Hospital Employees groups. Gabriele Hoffman is a member of just the Hospital Employees group. If the allowedGroups section looks like the following:

<allowedGroups>
  <group name="Compliance 360 Users" />
</allowedGroups>

Then, only Marco Lombard will be a Compliance 360 user. Also, Marco Lombard will only be a member of the Compliance 360 Users group in Compliance 360. Hospital Employees will be ignored since it is not on the <allowedGroups> list.

Output streams are used to send the user content retrieved from Active Directory to a specific destination. There are currently two (2) supported streams in the current version of the service: CSsv and Compliance360ApiV2.

The Csv stream is used to write the results of the LDAP query to a *.csv file. This is very useful for testing out the queries and configuration to ensure the specified jobs are configured correctly.

Example:

<outputStream>
   <stream name="Csv">
     <settings>
       <setting name="path" value="C:\temp\ad-output.csv" />
     </settings>
   </stream>
</outputStreams>

The following setting is required:

• path: The full file path to the *.csv file that should be created.

The Compliance360Apiv2 stream handles the REST API calls to the Compliance 360 application, creating, updating, and deleting employee accounts based on the Active Directory information.

Example:

<stream name="Compliance360ApiV2">
  <settings>
    <setting name="baseAddress" value="https://secure.compliance360.com" />
    <setting name="organization" value="[ORG_NAME]" />
    <setting name="username" value="[USER_NAME]" />
    <setting name="password" value="[PASSWORD]" />
    <setting name="culture" value="[CULTURE_CODE]" />
    <setting name="loginIntervalMinues" value="[NUMBER_OF_MINUTES]" />
  </settings>
  <mapping>
    <map from="Main Division" to="PrimaryDivision"/>
    <map from="{domain}\{sAMAccountName}" to="EmployeeNum"/>
    <map from="{domain}\{sAMAccountName}" to="UserName"/>
    <map from="{givenName}" to="FirstName"/>
    <map from="{sn}" to="LastName"/>
    <map from="{mail}" to="Email"/>
    <map from="{title}" to="JobTitleId" type="lookup"/>
    <map from="{department}" to="Department"/>
    <map from="{memberOf}" to="Groups"/>
    <map from="{manager}" to="Relationships" type="Manager"/>
    <map from="{company}" to="Company" type="company"/>
    <map from="true" to="CanLogin"/>
  </mapping>
</stream>

The setting elements provide the information needed to connect with the Compliance 360 application. The parameters are:

• name: The setting name
• value: The setting value

The following settings are required:

• baseAddress: The base URL of the Compliance 360 application. Use the URL for the appropriate data center for this organization.
  UK data center: https://uk.compliance360.com/ with Culture of en-GB
  US data center: https://secure.compliance360.com/ with Culture of en-US
  APAC data center: https://c3602.grc.saiglobal.com/ with Culture of en-AU
• organization: The organization you are connecting to
• usename: The user name with API access rights
• password: The user's password
• culture: The Microsoft code to identify the culture that corresponds to the data center associated with the baseAddress setting. See baseAddress setting for cultures.
• loginIntervalMinutes: The number of minutes to wait before refreshing the authentication token. This token expires after a certain amount of time and needs to be replaced when long-running sync events are occurring. By default, that is 20 minutes.

The map elements provide the source attribute name/statement and the target field name in the Compliance 360 application so that the information can correctly populate the application. The parameters are:

• from: The source attribute name or statement. Attributes can be retreived with the syntax {ATTRIB_NAME}. Multiple attributes can be used together and combined with text to achieve the desired source value.
  • Example:

    <map from="{domain}\{sAMAccountName}" to="EmployeeNum"/>

    will result in from value being the domain name, a slash (\) followed by the account, as in saig\marcol.
• to: The Compliance 360 employee field name. The following To fields are required in order for Compliance 360 to function correctly:
  • PrimaryDivision: The Compliance 360 employee base division path in the format [DIVISION_NAME] \ [CHILD_DIVISION_NAME]. Please note that there is a space both before and after the slash.
  • EmployeeNum: The identifier supplied by the client used to uniquely identify the employee in the Compliance 360 application.
  • CanLogin: This is the value that sets the employee's user status which determines whether the user may login to the system.
• type attributes: There are several system attribute types that can be used to let the system handle complex field type mappings:
  • lookup: Tells the system that the destination field, the to value, is a Lookup type field. It is needed to find an existing lookup value or to create the lookup value if it is not present in the application.
  • company: Tells the system that the destination field is of Company type field. It is needed to find an existing company entity or to create the new company entity if it is not present in the application.

LDAP Sync will NOT create any missing Divisions in the Compliance 360 application. Please create the division structure before starting the sync process.

LDAP Sync will create the following new objects if they are not present in the Compliance 360 application:

• Job Title
• Department
• User Group
• Employee
• Company

It will also create lookup values if they are not present in the Compliance 360 application.

Application logging / tracing is done using NLog. By default, the application comes preconfigured to log all errors to the Application event log. To troubleshoot the service, please enable the file logging at the debug level as seen below by uncommenting the file logger rule entry in the NLog.config file.

<?xml version="1.0" encoding="utf-8"?>

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <targets>
    <target name="debugger" xsi:type="Debugger" layout="${shortdate}::${time}::${level}::${message}" />
    <target name="file" xsi:type="File"
            layout="${longdate} ${message} ${exception}"
            fileName="/logs/logfile.txt"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    <target name="eventlog" xsi:type="EventLog" layout="${message} ${exception}" source="Compliance 360" log="Application" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="file" />
    <logger name="*" minlevel="Error" writeTo="eventlog" />
  </rules>
</nlog>

LDAP Sync will cache Compliance 360 data information locally using isolated storage for security purposes. Please inspect the log files for the location of the cache files in the case that you need to remove them for a clean install.

This application depends on the following frameworks (Please note that the application installer handles the installation of all dependencies):

• Microsoft Window Server 2012 or newer with the latest .NET Framework 4.7.x installed.
• Installation package includes the following dependenceis:
  • Newtonsoft.Json - for JSON processing
  • NLog - for logging
  • Structuremap - for dependency injection
  • Rebex SFTP - for streaming user content to an sftp location