Caching Principal Resolution Service

Installation and Configuration

Caching Principal Resolution Service (Active Directory LDAP)

1. Add a “CachingLdapPrincipalResolution” service under “Services” in the “Indices” tab.

1. “LDAP Server Hostname“ should only be configured to overwrite the configuration of “Preferred LDAP Server” under “LDAP Settings” (in the “Network”  tab). The required login information “LDAP Credential” can be selected either directly here or in the “Network” tab under “Endpoints.”
2. 

1. The Location can be configured as dns://<domain> (e.g. dns://mycompany.com) to use these credentials for multiple LDAP servers at the same time in one DNS domain. It is also possible to assign a credential directly to an LDAP server: ldap://<ldapserver hostname> (e.g. ldap://ldapserver.mycompany.com).

1. If no login information is configured, Kerberos is used. To do this, a valid keytab must first be uploaded under Linux and selected for this service under “Setup Kerberos Authentication.”

1. In the Kerberos authentication case, the UPN (User Principal Name) attribute of the user from the LDAP directory is used as a key for cache search. If another authentication method is used, which would send the user’s e-mail address for instance, the corresponding LDAP attributes, in this case mail, should be configured as “Alias Name LDAP Attribute”.  In addition, the “Identity Alias Name Property” field should contain the property name provided by authentication. The attributes “msDS-principalName” und “userPrincipalName” are automatically saved for all users because they are used by the client service during Kerberos authentication. Therefore, they should not be configured as user aliases. If only one domain is configured, the attribute “sameaccountname” is also automatically added.

1. If the ACLs are not normalized during indexing, i.e. they are not converted to DN format and they correspond, for example, to the “msDS-principalName“ attribute of a group in the active directory, then the “Group Alias Name LDAP Attribute“ should also be configured.

1. If users have different alias names in multiple domains, aliases from certain domains can be deprioritized using “Deprioritize Alias Names From Domain.” As a result, the principals in these domains are not added to the list of user principals.
2. Using “Suppress ‘Everyone’ Principal For Domain“ and “Suppress ‘Authenticated Users‘ Principal For Domain“ prevents users from being treated as members of these groups.

1. Specify the directory path for the cache in the “Database Directory Path“ field and change the “Cache In Memory Items Size” if necessary, depending on the available memory capacity of the JVM. Specify the time (in minutes) to wait before the cache is refreshed in the “Cache Update Interval“ field. This time interval is ignored the first time the service is started. The next time the service is started, this time is taken into account. The settings “Health Check Interval“, “Health Check max. Retries On Failure“ and “Heath Check Request Timeout“ allow this service to be restarted if, for instance, there are persistent connection problems.
2. The service is called up on the specified “Webservice Port”.

1. “Preserve Case for Principals Matching Pattern“ allows you to keep certain principals (defined by Regex pattern) in the original format (not lower case). “Exclude Principals Pattern“ allows you to remove certain principals for all users from their principals list. “Suppress Anonymous Users Principals“ makes it possible, for example, to suppress the “Everyone” principal for anonymous users, meaning anonymous users cannot even find public documents. “Resolve non anonymous principal to all registered users“ determines whether "normal" (non-anonymous) users belong to the group that contains all users. “Include Principals Rule“ allows you to add new principals for all users (if these users match a configured regex pattern). If a user's groups are not stored in the cache, selecting “Suppress LDAP Queries“ prevents LDAP queries from being made to find these groups.

1. Finally, select this service in the crawler configuration under “Caching Principal Resolution Service”. See chapter 5.

Using LDAP Caching Principal Resolution Service with Kerberos

Preparation

For configuring authentication via Active Directory with Kerberos protocol for the Mindbreeze InSpire Appliance, a few preparing steps are necessary:

Kerberos configuration on the Mindbreeze InSpire System

A service user must be added for the Mindbreeze services on the Active Directory Server and a HTTP service principal name for the hostname of the Mindbreeze InSpire Server must be configured for this user.

A privileged user is needed with read access to the file shares that are crawled.

Keytab files for the service and the privileged user should be created.

Kerberos Konfiguration

On the InSpire Management Center access the “System” configuration section. Then using the “File Manager” tool, edit the /etc/krb5.conf file and configure the Kerberos REALMs and KDC servers.

A minimal Kerberos configuration file is:

[logging]

default = FILE:/var/log/krb5libs.log

kdc = FILE:/var/log/krb5kdc.log

admin_server = FILE:/var/log/kadmind.log

[libdefaults]

default_realm = MYREALM.MYCOMPANY.COM

dns_lookup_kdc = false

[realms]

MYREALM.MYCOMPANY.COM = {

   default_domain = mydomain.mycompany.com

   kdc = 192.168.123.124

}

[domain_realm]

mydomain.mycompany.com = MYREALM.MYCOMPANY.COM

Keytab Files

For creating the keytab files for the service user and the privileged crawler user several tools can be used, like ktpass on Microsoft Windows systems or ktutil on Linux.  

Example: create a keytab for the privileged user with ktutil

Start ktutil on the command line and carry out these commands in the ktutil shell:

addent -password -p <principal>@<REALM> -k 0 -e arcfour-hmac

(for example: addent -password -p crawler_user@MYREALM.COM -k 0 -e arcfour-hmac)

Enter the user password.

wkt <keyab_path>

The principal name in the keytab should be in the form of

username@MYREALM.COM in case of the privileged user

HTTP/<inspire_host_name>@MYREALM.COM in case of the service user (username should be the service principal name here)

Upload the keytab file using the Mindbreeze InSpire Management Center:

Open the “Configuration” menu in the Mindbreeze InSpire Management Center, then navigate to the “Authentication”. Here you can upload the generated keytab files, using the upload form from “Configure Kerberos Authentication” section. The uploaded keytab files are listed in the “Available Keytabs” section.

Caching Principal Resolution Service (Novell LDAP)

1. Add a “CachingNovellLdapPrincipalResolution” service under “Services” in the “Indices” tab.

1. “LDAP Server Hostname” should only be configured to overwrite the configuration “Preferred LDAP Server” in the “LDAP Settings” in the “Network” tab. The required login information “LDAP Credential” can either be selected directly here or in the “Network” tab under “Endpoints.”
2. 

1. The location for an LDAP server has this format: ldap://<ldapserver hostname> (e.g. ldap://ldapserver.mycompany.com).

1. The “Username” must be specified in DN format and the “Domain” field must be left blank.

1. For further configuration parameters see: Caching Principal Resolution (Active Directory LDAP).

Caching Principal Resolution Service (SharePoint Principal Cache)

1. Add the SharePointPrincipalCache service under “Services” in the “Indices” tab. (MicrsoftSharePointConnector x.x.x.zip must first be installed in the tab “Plugins”).

1. Specify the “SharePoint Server URL”. Configure the required login information in the Network tab under Endpoints. The “Include URL” and “Excluded Sites URL” fields should be the same as the crawler fields of the same name.

1. In the “LDAP Persisted Cache Service Port” field, enter the previously configured “Web Service Port” of the LDAP Principal Resolution Service. In the SharePoint Crawler configuration, the option “Resolve SharePoint Groups” should not be selected.

1. The option “SharePoint Site Groups Resolution Threads” configures the number of threads that find the SharePoint Site Groups of the sites at the same time. The “SharePoint Site Group Members Resolution And Inversion Threads” option specifies the number of threads that SharePoint Group members will find parallel to each other. The “Suppress External Service Calls” option prevents external services such as LDAP or SharePoint from being queried during the search if no SharePoint groups are found in the cache for a user. For further configuration parameters see: Caching Principal Resolution (Active Directory LDAP).

1. It is possible to save the SharePoint groups of only certain specific sites by using the following parameters.
   • All Sites File: The path to a CSV file containing the site URLs that are to be crawled. If this field is empty, all sites are detected by the SiteDiscovery service.
   • Include Sites File: The path to a CSV file containing the site URLs that are to be crawled.
   • Exclude Sites File: The path to a CSV file containing the site URLs that should not be crawled.

1. Finally, select this service in the crawler configuration under Caching Principal Resolution Service. See chapter 5.

Caching Principal Resolution Service (SharePoint ACL Reference Cache)

1. Add a “SharePointACLReferenceCache” service under “Services” in the “Indices” tab. (MicrsoftSharePointConnector x.x.x.zip must first be installed in the tab “Plugins”).

1. Specify the “SharePoint Server URL”. Configure the required login information in the Network tab under Endpoints. “Include Sites File”, “Include URL”, “Excluded Sites URL”, “Exclude Sites With These Features”, and “Resolve SharePoint Groups” can only be selected if the port of “CachingLdapPrincipalResolution” service is entered in the “Parent Service Port.” The “Normalize ACLs” field should then be configured as in the crawler.

1. In the “Parent Service Port” field, enter the previously configured “Web Service Port” of the “SharePoint Principal Cache” service. If "Resolve SharePoint Groups" is selected in the crawler, the LDAP Principal Resolution Service Port can be used here and the option "Resolve SharePoint Groups" must be selected.

1. You can use the following parameters to save the SharePoint ACLs of only certain sites.
   • All Sites File: The path to a CSV file containing the site URLs that are to be crawled. If this field is empty, all sites are detected by the SiteDiscovery service.
   • Include Sites File: The path to a CSV file containing the site URLs that are to be crawled.
   • Exclude Sites File: The path to a CSV file containing the site URLs that should not be crawled.

1. Finally, select this service in the crawler configuration under Caching Principal Resolution Service. See chapter 5.

Caching Principal Resolution Service (Confluence und Jive)

1. Add the CachingConfluencePrincipalResolutionService (ConfluenceAccess x.x.x.zip must first be installed in the tab “Plugins”).

1. Specify the “Confluence Server URL”.

1. The necessary credentials to access the “Confluence Server URL” must be configured in the “Network” tab and assigned to the “Confluence Server URL” endpoint. The “Suppress Confluence Service Calls” option allows you to suppress confluence service calls if a user cannot find any confluence groups in the cache.

1. Finally, select this service in the crawler configuration under Caching Principal Resolution Service. See chapter 5.

Configuring the data sources for the Caching Principal Resolution Service.

Select one of the configured caching principal resolution services in “Data Source”. For example, Caching LDAP Principal Resolution can be selected for a file system data source (in the screenshot “FS Data Source”).

Principal Resolution Service REST API