Overview

The AIE Windows ACL File scanner is provided as part of the Secured Content Framework in order to facilitate the extraction of ACL's for files residing on Windows machines.  

Related modules: security, security-ad

View incoming links.

• Active Directory and LDAP Configuration ,
• Content Security

Windows File Ingestion

Windows files and ACLs are ingested by the ServiceBasedWindowsAclFileScanner Attivio scanner/connector, working with an external Windows ACL Service to ingest content along with its associated ACLs.

A Windows File Connector can be configured by using the Connector UI in the AIE Administrator.  It can can also be configured in a project's configuration files. Here is a sample configuration:

<connector xmlns="http://www.attivio.com/configuration/type/connectorType" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
name="MyWinAclConnector" 
xsi:schemaLocation="http://www.attivio.com/configuration/type/connectorType http://www.attivio.com/configuration/type/connectorType.xsd http://www.attivio.com/configuration/type/componentType http://www.attivio.com/configuration/type/componentType.xsd ">
    <scanner class="com.attivio.securityad.connector.ServiceBasedWindowsAclFileScanner">
      <properties xmlns="http://www.attivio.com/configuration/type/componentType">
        <property name="excludePermissions" value="false"/>
        <property name="maxFileSize" value="5"/>
        <property name="followSymbolicLinks" value="true"/>
        <property name="aclServicePort" value="16995"/>
        <property name="maxDepth" value="-1"/>
        <property name="deleteAfterCrawl" value="false"/>
        <property name="incrementalDeletes" value="true"/>
        <property name="startDirectory" value="\\MyFileServer\MySharedDirectory"/>
        <property name="aclServiceHost" value="winqlttst01"/>
        <property name="securityRealmId" value="AttivioRealm"/>
        <list name="wildcardFilter">
          <entry value="*.doc"/>
          <entry value="*.docx"/>
          <entry value="*.xls"/>
          <entry value="*.xlsx"/>
        </list>
        <list name="wildcardExcludeFilter">
          <entry value=".*"/>
          <entry value="*~"/>
        </list>
      </properties>
    </scanner>
    <feeder>
      <properties xmlns="http://www.attivio.com/configuration/type/componentType">
        <property name="commitInterval" value="0"/>
        <property name="waitForCompletionTimeout" value="-1"/>
        <property name="commitAfterCrawl" value="true"/>
        <property name="maxDocs" value="-1"/>
        <property name="logInterval" value="1000"/>
        <property name="createUniqueContentPointerIds" value="true"/>
        <property name="optimizeInterval" value="0"/>
        <property name="messageResultPollingInterval" value="-1"/>
        <property name="waitForCompletion" value="true"/>
        <property name="optimizeAfterCrawl" value="false"/>
        <property name="documentBatchSize" value="1"/>
        <property name="orderedCommits" value="true"/>
        <property name="sendSynchronously" value="true"/>
        <property name="waitFlushInterval" value="60000"/>
        <property name="ingestWorkflowName" value="fileIngest"/>
      </properties>
    </feeder>
</connector>

Windows ACL Service

The Windows ACL Service provides the ability to retrieve ACL's from a given Windows file system.

Prerequisites

The following prerequisites must be met before the AIE Windows ACL Service is installed on a given machine:

1. The webservice module must be installed on the ingest node(s) that the ACL service will be using.  Most likely this is the same node(s) that runs the Windows File Scanner.
2. Microsoft .NET Framework version 3.5 must be installed on the machine.
3. If you plan to use the file system monitoring capabilities (for near-realtime updates) then Microsoft Message Queue (MSMQ) is required on a machine accessible by the server which is to host the AIE ACL Security Service. You will need to install MSMQ on each machine whose file content is to be monitored by the AIE ACL Security Service.
4. If using SSL you will need to configure certificates and assign them to port 16996. See below for more details.

Configuring Microsoft Message Queue (MSMQ)

Configuring MSMQ 3.0 on Windows XP

To check whether MSMQ is installed and to install it if it is not:

1. Open the Windows Control Panel from the start menu, double-click on Add/Remove Programs, then click on the Windows Components tab to launch and display the Windows components wizard.
2. Click on Application Server, then click Details.
   
3. If the Message Queuing checkbox is selected it means the service is already installed and you can thus skip the rest of this section. If it is not, then you need to follow the rest of the steps below to install the message queuing service. In the Application Server dialog, click on Message Queuing, then click Details.
   
4. In the Message Queuing dialog, select the Core functionality checkbox, then click OK.
   
5. In the Application Server dialog, click OK, then click Next in the Windows Components Wizard window to start installing the message queuing service.
   
6. When the installation of the message queuing service is complete, click Finish in the Windows Components Wizard. The Message Queuing Service is now installed.

Configuring MSMQ on Windows Server 2008

1. From the Windows 2008 Server Manager, choose Features.
2. Select Add Feature.
   
3. Expand Message Queuing.
4. Expand Message Queuing Services.
5. Ensure the following are selected; select if necessary. If the components are already selected, they are already installed on the server:
   • Message Queuing Server
   • Message Queuing Trigger
   • Multicasting Support
     
6. Select Install to finish the MSMQ configuration.

Configuring MSMQ on Windows 7

1. Choose Start->Control Panel->Programs.
2. Choose Turn Windows features on or off.
   
3. Expand Microsoft Message Queue (MSMQ) Server Core.
   
4. Select Microsoft Message Queue (MSMQ) Server and MSMQ DCOM Proxy.
5. Select OK.

Windows ACL Service Installation

Installation Overview

Use an account with administrator privileges on the target machine to install the AIE ACL Service. Run AIE_ACL_Security_Service.msi (located in <attivio-install-dir>/bin) either from command prompt or by double clicking in Windows Explorer. As part of the install, AIE ACL Service opens port 16995 for HTTP traffic and 16996 for secure HTTPS traffic. During the install, you will be prompted to specify an install location. This path is referred to as <acl-service-install-dir> below.

To troubleshoot/generate the log of your Service installation, run the .msi installation program with the /lv <output-file-name> option.

To Enable HTTP or HTTPS Service Connections

Once the install is complete, both HTTP and HTTPS service endpoints are configured for use by the AIE ACL Service. To enable/disable the preferred connection type:

1. Open service configuration file, Security-AD-ACLService.exe.config, found in the install directory.
2. Find the services node.

3. Within each of the two service nodes, comment out either the HTTP or HTTPS endpoint:

   <services>
       <service>
           <servicename="Attivio.SecurityAD.ACLService.ACL.ACLSvc" ...
           <endpointaddress="https://localhost:16996/attivio" ...
           <endpointaddress="http://localhost:16995/attivio/" ...
       </service>
       <service>
           <servicename="Attivio.SecurityAD.ACLService.Monitor.FSMonitorSvc" ...
           <endpointaddress="https://localhost:16996/attivio/monitor" ...
       <endpointaddress="http://localhost:16995/attivio/monitor/" ...
       </service>
   </services>
   

Configuring the Windows ACL Service Account

Once the install has completed:

1. Open the Service Control Manager.
2. Right click on the AIE ACL Security Service.
3. Select Properties.
4. In the Service Properties window:
   1. Choose Log On.
   2. Select This account.
   3. Provide user name and password for the Service Account.
      • Ensure this account has Administrator rights on the local machine.
      • If the user is a member of the local system domain, you may specify it as '.'.  In any case, the domain is required.  Do not leave it blank.
   4. Click Apply.
   5. Click OK.
      

Configuring ports

If you install AIE ACL Security Service while the Windows Firewall Service is not running the ports the service uses will not be opened. If you later turn on the Windows Firewall Service, you will need to manually add an exception for the AIE ACL Security Service.

On Windows XP:
Open Control Panel and select Windows Firewall

On Windows Vista and Windows 2008 Server:
Open Control Panel and Select Windows Firewall. Then choose Allow a program through Windows Firewall.

On all other operating systems:
On the Windows Firewall dialog, click the Exceptions tab and choose Add Port...

On the Add a Port dialog, provide the name and port number. Add port 16995 for the HTTP and 16996 for the HTTPS endpoint. Choose TCP, then OK.

Windows ACL Service Uninstallation

To uninstall the Service:

1. Open the Windows Control Panel and select Programs.
2. Select Uninstall a program.
   
3. Right click AIE_ACL_Security_Service and choose uninstall.
   
4. Confirm uninstall if prompted.

Configuration

General Configuration

The general configuration file for the Service, Security-AD-ACLService.exe.config, can be found in the <acl-service-install-dir> directory. Any overrides to settings in this file can be made in the Environment.config configuration file.

Typically, the Security-AD-ACLService.exe.config file will contain the following settings:

<appSettings>
    <!--Enable ACL Service-->
    <add key="ACLEnable" value="true" />
    <!--Enable Monitor Service-->
    <add key="MonitorEnable" value="false" />
    <!--Monitor Configuration file-->
    <add key="MonitorConfiguration" value="Monitor.xml" />
    <!--MSMQ used by notify services-->
    <add key="QueueName" value=".\Private$\AttivioMonitorQueue" />
    <!--URL for ingest service-->
    <add key="IngestServerURL"
        value="http://{0}:{1}/ws/bean.attivioIngestWebService/com.attivio.webservice.service.IngestApi" />
</appSettings>

Monitor Configuration

To configure the ACL monitoring service, you need to modify the Monitor.xml file also found in the <acl-service-install-dir> directory.  

Configuration settings:

Here's a sample configuration:

<Monitor>
       <config>
       <!--This portion of the Monitor configuration is for the AIE Server-->
       <!--Use this to configure the AIE Server-->
       <!--REQUIRED:-->
       <aie-host>localhost</aie-host>
       <aie-port>17000</aie-port>
       <aie-acl-update-workflow retries="-1" timeout="30000" commitEveryAcl="false">aclIngest</aie-acl-update-workflow>
       <!--retries is the number of attempts to pass an update to the AIE before logging a failure to the Event Log -->
       <!--timeout = time to wait between attempts, timeout < 0 = retry forever -->
       <!--Element value is the name of the AIE workflow service to call-->
       </config>
   	   <directories>
         <directory>
           <!--Uncomment the sections below to monitor a local or remote file system for changes-->
           <!--Path of share, t is recommended you use fully qualified network name in the UNC path.-->
           <!--modify must be set to true to monitor ACL changes-->
           <!--REQUIRED-->
           <!--<path modify="true" >\\MyFileServer\MySharedDirectory</path>-->
           	 
           <!--Add entry elements to include files. Valid Windows Search criteria is used for both
           	   include and exclude values.-->
           <!--OPTIONAL: default will include all files-->
           <!--<included-file-types>
               <entry value="somefile.*" />
               <entry value="*somevalue.*" />
           </included-file-types>-->
           
 <!--Add entry elements to exclude files-->
          <!--OPTIONAL: default will exclude no files--
          <!--<excluded-file-types>
              <entry value="*.exe" />
              <entry value="foo*.txt" />
              <entry value="*.dll" />
              <entry value="*.cmd" />
              <entry value="*.zip" />
          </excluded-file-types>-->-->
          
          <!--Maximum depth of subfolders to notify on.-->
          <!--OPTIONAL: default is the root folder of the file share-->
          <!--<max-depth>10</max-depth>-->
          <!--Maximum file size to notify on.-->
          
          <!--OPTIONAL: default is no size limit-->
          <!--<max-file-size>5</max-file-size>-->
        </directory>
      </directories>
</Monitor>

ACL Workflow Configuration

If you need to deploy near real-time ACL monitoring, you need to create an ingest workflow which references the AclMonitorTranslate component as well as the standard ingest component.  This can be configured by using the Workflows page in the AIE Administrator.  It can can also be configured in a project's configuration files.  The workflow configuration involves the following steps:

1. Create a new document workflow, in the sample below, we'll name it ingestAcls.
2. Add the aclMonitorTranslator transformer to the workflow.
3. Add the standard ingest workflow as a subflow to the ingestAcls workflow.
4. Save the new workflow and redeploy your project configuration if you've made the changes directly in configuration files.  Otherwise, if you've made the changes via Dynamic Configuration, no configuration redeployment is necessary.
5. Stop the Windows ACL service.  This can be done from the Windows Services manager.
6. Modify the service configuration file Monitor.xml, specifically the  aie-acl-update-workflow element.  Change the workflow name to the one for the workflow you created in steps 1-4.  For example, with the above example of Monitor.xml, the  aie-acl-update-workflow would be updated like this:

<aie-acl-update-workflow retries="-1" timeout="30000" commitEveryAcl="false">ingestAcls</aie-acl-update-workflow>

Here is a sample configuration for the new transformer:

<component xmlns="http://www.attivio.com/configuration/type/componentType" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
name="aclMonitorTranslator" 
class="com.attivio.aclservice.AclMonitorTranslate" 
xsi:schemaLocation="http://www.attivio.com/configuration/type/componentType http://www.attivio.com/configuration/type/componentType.xsd ">
    <performance maxInstances="1"/>
    <properties>
      <property name="generateMessageResultsOnOk" value="false"/>
      <property name="documentTimeout" value="-1"/>
      <property name="dropDocumentOnException" value="false"/>
    </properties>
</component>

This is a sample configuration of the workflow:

<workflow xmlns="http://www.attivio.com/configuration/type/workflowType" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
name="ingestAcls" 
type="ingest" 
xsi:schemaLocation="http://www.attivio.com/configuration/type/workflowType http://www.attivio.com/configuration/type/workflowType.xsd ">
    <documentTransformer name="aclMonitorTranslator"/>
    <subflow name="ingest"/>
</workflow>

Configuring the ACL Service and MSMQ on Separate Hosts

If you are using real-time ACL monitoring, it is possible to deploy MSMQ on a host that is separate from the one that the monitoring service is using.  Configuring a separate MSMQ host involes the following steps:

1. Configure the MSMQ service on the target host, as described in the Configuring Microsoft Message Queue (MSMQ) section above.
2. Open the Windows Services manager.  
3. Expand the Message Queueing node via Services and Applications or Features, depending on which version of Windows you are running.
4. Right click on the Public Queues item and choose New -> Public Queue.  If you do not see the Public Queues option, you may need to add Directory Services Integration to the Message Queueing Service via Add Features.
5. Give the queue a name and click OK (it does not need to be Transactional).
6. Be sure to give Full Control access to the queue for the network account that the ACL monitoring service runs under.  You can see/modify the queue's access by right clicking on it in the Services window and choosing Properties -> Security.

7. In the ACL service configuration file, specify the remote host's public queue like this:

   <add key="QueueName" value="MyHost\MyQueue" /> 

   Where MyHost is the name of the remote machine and MyQueue is the public queue name.

AIE Realm IDs and Windows ACLs

When ingesting Windows ACLs, special attention must be paid to how the realm ID is determined. This Windows ACL service maps the following principal information when ingesting ACLs:

• Windows Domain Users
  • AIE Realm ID is set from the user's window's domain
  • AIE Principal ID is the Active Directory SID
  • AIE Principal Name is the user's name
• Everyone (mapped to Anonymous access)
  • AIE Realm ID is set as Anonymous
  • AIE Principal ID is set as Anonymous
  • AIE Principal Name is set as Anonymous
• Local User Accounts
  • AIE Realm ID is the server name for that machine
  • AIE Principal ID is the SID
  • AIE Principal Name is the local user's name

Configuring The Windows ACL Service To Work With SSL Enabled AIE Web Services

If you are running AIE Web Services with SSL enabled, you will have to configure The Windows ACL Service accordingly to be able to appropriately communicate with those services.

In the ACL service configuration file, make the following three changes:

1. Change scheme in client endpoint from http to https

Before:

<client>
    <endpoint address="http://localhost:17000/ws/bean.attivioIngestWebService/com.attivio.webservice.service.IngestApi" 
              binding="basicHttpBinding" 
              bindingConfiguration="IngestApiSoapBinding" 
              contract="WebSvcIngest.IngestApi" 
              name="IngestApiImplPort" />
</client>

After:

<client>
    <endpoint address="https://localhost:17000/ws/bean.attivioIngestWebService/com.attivio.webservice.service.IngestApi" 
              binding="basicHttpBinding" 
              bindingConfiguration="IngestApiSoapBinding" 
              contract="WebSvcIngest.IngestApi" 
              name="IngestApiImplPort" />
</client>

2. Change security mode in basicHttpBinding element from "None" to "Transport"

Before:

<basicHttpBinding>
    <binding name="IngestApiSoapBinding" 
             closeTimeout="00:01:00" 
             openTimeout="00:01:00" 
             receiveTimeout="00:10:00" 
             sendTimeout="00:01:00" 
             allowCookies="false" 
             bypassProxyOnLocal="false" 
             hostNameComparisonMode="StrongWildcard" 
             maxBufferSize="65536" 
             maxBufferPoolSize="524288" 
             maxReceivedMessageSize="65536" 
             messageEncoding="Text" 
             textEncoding="utf-8" 
             transferMode="Buffered" 
             useDefaultWebProxy="true">
        <readerQuotas maxDepth="32" 
                      maxStringContentLength="8192" 
                      maxArrayLength="16384" 
                      maxBytesPerRead="4096" 
                      maxNameTableCharCount="16384" />
        <security mode="None">
            <transport clientCredentialType="None" proxyCredentialType="None" realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
        </security>
    </binding>
</basicHttpBinding>

After:

<basicHttpBinding>
    <binding name="IngestApiSoapBinding" 
             closeTimeout="00:01:00" 
             openTimeout="00:01:00" 
             receiveTimeout="00:10:00" 
             sendTimeout="00:01:00" 
             allowCookies="false" 
             bypassProxyOnLocal="false" 
             hostNameComparisonMode="StrongWildcard" 
             maxBufferSize="65536" 
             maxBufferPoolSize="524288" 
             maxReceivedMessageSize="65536" 
             messageEncoding="Text" 
             textEncoding="utf-8" 
             transferMode="Buffered" 
             useDefaultWebProxy="true">
        <readerQuotas maxDepth="32" 
                      maxStringContentLength="8192" 
                      maxArrayLength="16384" 
                      maxBytesPerRead="4096" 
                      maxNameTableCharCount="16384" />
        <security mode="Transport">
            <transport clientCredentialType="None" proxyCredentialType="None" realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
        </security>
    </binding>
</basicHttpBinding>

3. Change scheme from http to https in IngestServerURL in appSettings element

Before:

<appSettings file="environment.config">
    <add key="MonitorConfiguration" value="Monitor.xml" />
    <add key="QueueName" value=".\Private$\AttivioMonitorQueue" />
    <add key="MonitorEnable" value="false" />
    <add key="ACLEnable" value="true" />
    <add key="IngestServerURL" value="http://{0}:{1}/ws/bean.attivioIngestWebService/com.attivio.webservice.service.IngestApi" />
</appSettings>

After:

<appSettings file="environment.config">
    <add key="MonitorConfiguration" value="Monitor.xml" />
    <add key="QueueName" value=".\Private$\AttivioMonitorQueue" />
    <add key="MonitorEnable" value="false" />
    <add key="ACLEnable" value="true" />
    <add key="IngestServerURL" value="https://{0}:{1}/ws/bean.attivioIngestWebService/com.attivio.webservice.service.IngestApi" />
</appSettings>

Remember to restart your Windows ACL Service after making the above changes.

Web Test

The following URLs may be accessed via the browser in order to make sure the AIE ACL Service is up and running:

1. For the ACL Service:

   http://[Host]:16995/attivio/acl?path=[FullPath][FileName] or http://[Host]:16995/attivio/Ping

Troubleshooting

All critical errors are logged to the Windows Application Event Log and to a rolling flat file in the service install folder. The file is Security.AD.ACLService.log. Both logs will contain details describing any problems you may encounter with AIE ACL Security Service. The ACLService log file is a "rolling" log file, which stops at 1MB, saves off the log contents into a timestamped file, then starts the log over.