Page tree
Skip to end of metadata
Go to start of metadata

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.

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:

<project-dir>\conf\connectors\MyWinAclConnector.xml
<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:

Property

Default

Description

aie-host

none

The name of the host which ingests the Windows file content and ACL's. (required)

aie-port

none

The port which the ingest node is using on the host specified by "aie-host". (required)

aie-acl-update-workflow

none

The name of the workflow used by the ACL monitoring service to notify AIE about near real-time permissions changes. This is only necessary when using the monitoring service, it is not required to run Windows file connectors. The retries attribute can be set to 0, meaning no retries or < 0, which means retry forever. This specifies what the service should do if the AIE node is unavaialble. The timeout attributue specifies the number of milliseconds to wait in between attempts. By default, the commitEveryAcl attribute is set to false. It is strongly recommended that users keep the default, otherwise each monitored ACL change will force a commit in the AIE index. This could overwhelm the AIE ingest node if permission changes are made on a large number of monitored files. A better approach is to schedule regular commits via the Scheduler Service .

path

none

Within the directories element, you must specify one or more directory elements which can contain one path element each. The body of the element is a string specifying either a local path or a UNC path (mapped network paths are not supported). The modify attribute specifies whether you want to monitor ACL changes to files in the file share, its default value is false. Note that this value only needs to be true if you're using the ACL monitoring service, it is not necessary for running Windows file connectors. Furthermore, if you set this value to true, you must also set the MonitorEnabe value to true in Security-AD-ACLService.exe.config or Environment.config.

Performing Windows ACL ingestion/monitoring from a Linux platform raises issues about length and format of paths, including some prohibitions and some exceptions. 

included-file-types

all file types

Allows you to specify which file types the service will monitor. By default, all file types are monitored.

excluded-file-types

no file types

Allows you to specify which file types the service will exclude from monitoring. By default, all no file types are excluded from monitoring.

max-depthroot levelSpecifies how many directory levels will be monitored by the service. NOTE that the default is the top level directory of the file share only, unlike typical AIE file connectors which default to scanning all sub-directories recursively.
max-file-sizeno maximumSpecifies the maximum file size (in megabytes) to monitor. By default all files will be monitored regardless of size.

 

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:

 

<project-dir>\conf\components\aclMonitorTranslator.xml
<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:

<project-dir>\conf\workflow\ingest\ingestAcls.xml
<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

If the Attivio Active Directory Principal Scanner was used to ingest principals, the Realm ID for those users is most likely different than their Windows Domain. To handle this case, configure the Content Security feature's "Realm ID Mapping" ability to map these domain based realms to AIE principal realms (ex: map "CORP" to "AttivioWindowsRealm"). See Content Security#RealmIdMapping for configuration instructions.

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:

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:

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:

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:

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:

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:

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.

  • No labels