AIE can ingest user records, group records, and access control lists (ACLs) along with the usual documents and data. As a result, the index engine can filter not only by query criteria but also by access criteria.
In a secure system, every incoming query is accompanied by the user's security credentials. AIE's Security Module rewrites the query to JOIN the query's results with the set of documents that this user is allowed to view. The index engine returns only the matching documents that this user can view.
These features require that the security module, and sometimes the security-ad module, be included when you run createproject to create the project directories.
AIE's security module provides the basic framework for content security. This framework includes the ability to define users and groups, the ability to attach access control information to documents during ingestion, and the ability to apply that access control information to the search user and return only those documents to which the user has access. These general abilities are provided by fully-configurable components.
The security-ad module can be used in addition to the security module, to support integration with Active Directory (AD). This module supplies a simple configuration for web browser authentication to AD. It also provides connectors for ingesting AD users and groups into the AIE index. The most common use cases of this are:
- Requiring web browser authentication to AD for SAIL, Admin UI, or other AIE web apps.
- Ingesting AD users and groups for API security rules applied to Dictionary Management.
- Ingesting Windows ACLs applied to Windows files.
View incoming links.
The following high-level diagram illustrates the changes required to secure the content in an AIE instance:
- Configuring a Content Security Model
- Configuring Users and Groups Scanners
- Configure Document Scanners to extract ACL definitions
- Apply a "Run As" principal to all Queries
Once configured, the Security Model intercepts every query and re-writes it to include the appropriate security filters. The generated query enforces permissions by joining the document's ACLs with all groups (and nested groups) for the given user.
A key benefit of applying ACLs at query time is a change to group membership does not require re-ingestion of the documents. For instance, if a user Joe is promoted to be a Manager then when the user/group scanner is re-run, the JOIN will automatically match documents that reference the Manager group.
Configure a Content-Security Model
By adding the security module to a project, the following XML elements will be added in the security directory found under features. The contentSecurity feature will inject the Full Security Model into the system.
The adminUsers element for Content Security defines a special principal that is always considered to be an AIE administrators. The security model will not apply query re-writing for these users and thus, they will see all content. The AIE Administrative "root" users defined in the top level configuration.xml file are treated the same and also will see all content (see AIE Administrative Users).
<ff:features xmlns:ff="http://www.attivio.com/configuration/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:security="http://www.attivio.com/configuration/features/security" xsi:schemaLocation="http://www.attivio.com/configuration/config http://www.attivio.com/configuration/config.xsd http://www.attivio.com/configuration/features/security http://www.attivio.com/configuration/features/securityFeatures.xsd"> <security:adminUsers enabled="true" name="adminUsers"> <security:attivioPrincipal name="Administrator" principalId="Administrator" realmId="Anonymous"/> </security:adminUsers> </ff:features>
The default contentSecurity feature, as seen below, injects the security components into the indexer, searcher, and defaultResponse workflows to secure the default AIE index.
<ff:features xmlns:ff="http://www.attivio.com/configuration/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:security="http://www.attivio.com/configuration/features/security" xsi:schemaLocation="http://www.attivio.com/configuration/config http://www.attivio.com/configuration/config.xsd http://www.attivio.com/configuration/features/security http://www.attivio.com/configuration/features/securityFeatures.xsd"> <security:contentSecurity allowUnsecuredDocuments="false" class="com.attivio.security.model.FullSecurityModelImpl" enabled="true" name="contentSecurity" secureResponseWorkflow="defaultResponse" securedIndex="index" allowUpdates="false"/> </ff:features>
If allowUnsecuredDocuments is set to true, then non-authenticated, Anonymous users will be able to see documents ingested without any ACLs on them. For a more secure environment it is recommended to leave this set to false and specify ACLs on all documents.
The contentSecurity feature also automatically generates two more workflows; ingestPrincipals and ingestXmlPrincipals for faster principal ingestion which skips linguistics processing. If multiple indexes are to be secured, or different workflows to be used, these defaults can be overridden by changing the securedIndex attribute and the secureResponse workflows appropriately, as follows.
<ff:features xmlns:ff="http://www.attivio.com/configuration/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:security="http://www.attivio.com/configuration/features/security" xsi:schemaLocation="http://www.attivio.com/configuration/config http://www.attivio.com/configuration/config.xsd http://www.attivio.com/configuration/features/security http://www.attivio.com/configuration/features/securityFeatures.xsd"> <security:contentSecurity allowUnsecuredDocuments="false" class="com.attivio.security.model.FullSecurityModelImpl" enabled="true" name="contentSecurityTwo" secureResponseWorkflow="defaultResponseTwo" securedIndex="indexTwo"/> </ff:features>
When overridden in this fashion, the generated principal ingestion workflows will be suffixed with "To" followed by the workflow name. For example, in the case above, the two generated workflows would be ingestPrincipalsToIndexerTwo and ingestXmlPrincipalsToIndexerTwo.
Realm ID Mapping
The contentSecurity feature also has an optional setting that allows users to map realmIds to alternate values when persisting users, groups and ACLs. For example, to map all security objects with realmId "realm1before" to "realm1after", and all "realm2before" to "realm2after", configure a map bean, and set the realmMapping element on the contentSecurity feature. realmMapping.xml is placed in the conf/bean directory. For example:
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.springframework.org/schema/beans" xmlns:util="http://www.springframework.org/schema/util" xmlns:sec="http://www.springframework.org/schema/security" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-3.1.xsd"> <bean name="realmMapping" class="org.springframework.beans.factory.config.MapFactoryBean"> <property name="sourceMap"> <map key-type=""> <entry key="realm1before"> <value>realm1after</value> </entry> <entry key="realm2before"> <value>realm2after</value> </entry> </map> </property> </bean> </beans>
Then in your conf/features/security/ContentSecurity.contentSecurity.xml feature file, you must add the reference to the realm Mapping as an attribute of the security:contentSecurity element.
Configuring Users and Groups Scanners
Users and groups matching the ACLs must be ingested into the AIE index (see User and Group Sources (Principals)). AIE supports the following methods of ingesting User and Groups.
- Active Directory Principal Scanner - To ingest Active Directory users, groups, and memberships
- LDAP Principal Scanner - To ingest LDAP users, groups, and memberships
- XML-based User and Group Ingestion - To ingest XML files specifying custom users, groups and aliases
- Using the Content Security and Principal Ingestion in the Java APIs - To ingest users, groups and aliases via the Attivio Java API
Configure Document Scanners to Extract ACL Definitions.
AIE supports the following methods of ingesting Document ACLs. If allowUnsecuredDocuments=true then documents without ACL definitions will be treated as public.
- Windows ACL File Scanner - To ingest Windows files along with their ACLs (permissions)
- Using the Content Security and Principal Ingestion in the Java APIs - To use the Attivio API to ingest content with ACLs (permissions)
Content Security in the Java APIs
Security principals and ACLs can be added to the index through AIE's Java APIs. See Content Security and Principal Ingestion in the Java APIs for more information.
Apply a "Run As" Principal to all Queries
Securing Searches on SAIL - AD Authentication
Once Content Security is enabled, SAIL will generate the following error because the anonymous user will be used by default. To solve this problem either enable Authentication on the SAIL Webapp or set allowUnsecuredDocuments="true" on the security model.
There was a problem encountered while executing the search.
SECURITY-9007 : Error: denied access to anonymous user since unsecured documents aren't allowed.
Debug Search - Administrators Only
The "debug search" feature on the Admin UI is configured, by default, to use the first administrative user's realmId and principalId. This allows all content to be easily retrieved for debugging purposes, but can also be considered a security hole because anyone with access to debug search can see and search all indexed AIE content.
To prevent non-administrators from using debug search, please follow the instructions on AIE Web Application (webapp) Security to limit access to the /admin application to actual administrators.
You can also use the debug search to test search results for different users by entering their realmId and principalId or realmId and principalName in the appropriate input fields. If you specify a principalName instead of a principalId, this will cause an extra search to be executed in order to look up the principalid for the user. This information may be cached until the next index commit but if principalids are available they should be used to avoid this extra processing.
Setting "Run As" Principal via Query API.
See the Content Security and Principal Ingestion in the Java APIs for detailed information regarding setting AttivioPrincipal on a QueryRequest.
Principal Ingestion Performance Implications
It is recommended that the "ingestPrincipals" workflow be used for principal ingestion (but not for documents and ACLs). This workflow bypasses linguistics processing for better performance. The default "ingest" workflow will work for principal ingestion as well if desired.
Testing and Debugging Access Control
Note that AIE provides a AIE Role Assignments page for testing user access to documents, as part of the AIE Administrator.