Working with Directory Services

Foresight Analytics Platform gets information about domain security subjects from the domain catalog service or global catalog that must be set up in the computer network. Interaction with the directory service is executed via the LDAP/LDAPS protocol.

If repository login is to be executed via domain/integrated domain authentication, to search and add domain users and/or groups in the security manager set the parameters of comparison between directory service attributes and security subject attributes in Foresight Analytics Platform and specify user credentials to connect to the directory service in the settings.xml file. If required, connect additional controllers for domains or subdomains.

NOTE. Configuration settings in the settings.xml file for the web application and desktop application must match if the same repository is used to work at the same time in Windows OS and Linux OS.

Examples of the settings.xml file for the Active Directory service depending on OS type, on which Foresight Analytics Platform works:

Linux OS Windows OS

<Configuration>
  <Root>
    <Key Name="PP">
      <BIS>
        <Key Name="System">
          <MultiDomain>
            <Key Name="domain 1 name" aliases="list of alternative name of domain 1" Proto="LDAP" url="ldap[s]://IP address or server domain -address or server domain name:[port]" base="dc=...,dc=..." libldap="libldap-2.4.so.2" liblber="liblber-2.4.so.2">
              <controllers>
                <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
                <Key Name="controller 2 name" url="ldap[s]://IP address or domain server name:[port]" />
              </controllers>
              <user filter="(&amp;(objectClass=user)(sAMAccountType=805306368))" groupsFilter="(&amp;(member=%1)(objectClass=group)(sAMAccountType=268435456))">
                <Key Name="a0" filter="user" ldap="objectClass"/>
                <Key Name="a1" map_to="DistinguishedName" ldap="distinguishedName" get_full_domain="1"/>
                <Key Name="a2" map_to="Name" ldap="sAMAccountName" make_upn="1"/>
                <Key Name="a3" map_to="Sid" ldap="objectSid"/>
                <Key Name="a4" map_to="DisplayName" ldap="cn"/>
                <Key Name="a5" map_to="Descr" ldap="displayName"/>
                <Key Name="a6" map_to="LookupName" ldap="sAMAccountName"/>
                <Key Name="a7" map_to="LookupName" ldap="userPrincipalName"/>
                <Key Name="a8" map_to="LookupName" ldap="displayName"/>
                <Key Name="a9" map_to="LookupName" ldap="cn"/>
              </user>
              <group filter="(&amp;(objectClass=group)(sAMAccountType=268435456))">
                <Key Name="a0" filter="group" ldap="objectClass"/>
                <Key Name="a1" map_to="DistinguishedName" ldap="distinguishedName" get_full_domain="1"/>
                <Key Name="a2" map_to="Name" ldap="sAMAccountName"/>
                <Key Name="a3" map_to="Sid" ldap="objectSid"/>
                <Key Name="a4" map_to="DisplayName" ldap="cn"/>
                <Key Name="a5" map_to="Descr" ldap="description"/>
                <Key Name="a6" map_to="LookupName" ldap="sAMAccountName"/>
                <Key Name="a7" map_to="LookupName" ldap="description"/>
              </group>
              <credentials realm="" Crs="..." Crsa="..." mechanism="GSSAPI"/>
            </Key>
            <Key Name="subdomain 1 name" aliases="list of alternative names of subdomain 1" url="ldap[s]://IP addressor domain server name:[port]" base="dc=...,dc=...">
              <controllers>
                <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
                <Key Name="controller 2 name" url="ldap[s]://IP address or domain server name:[port]" />
              </controllers>
              <user filter="(&amp;(objectClass=user)(sAMAccountType=805306368))" groupsFilter="(&amp;(member=%1)(objectClass=group)(sAMAccountType=268435456))">
                ...
              </user>
              <group filter="(&amp;(objectClass=group)(sAMAccountType=268435456))">
                ...
              </group>
              <credentials realm="" Crs="..." Crsa="..." mechanism="GSSAPI"/>
            </Key>
            <Key Name="subdomain 2 name" aliases="list of alternative names of subdomain 2" url="ldap[s]://IP address or domain server name:[port]" base="dc=...,dc=...">
              <controllers>
                <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
                <Key Name="controller 2 name" url="ldap[s]://IP address or domain server name:[port]" />
              </controllers>
              <user filter="(&amp;(objectClass=user)(sAMAccountType=805306368))" groupsFilter="(&amp;(member=%1)(objectClass=group)(sAMAccountType=268435456))">
                ...
              </user>
              <group filter="(&amp;(objectClass=group)(sAMAccountType=268435456))">
                ...
              </group>
              <credentials realm="" Crs="..." Crsa="..." mechanism="GSSAPI"/>
            </Key>
            <Key Name="domain 2 name" aliases="list of alternative names of domain 2" Proto="LDAP" url="ldap[s]://IP address or server domain name:[port]" base="dc=...,dc=..." libldap="libldap-2.4.so.2" liblber="liblber-2.4.so.2">
              ...
            </Key>
          </MultiDomain>
          <Gssapi libgssapi="libgssapi_krb5.so.2" libkrb5="libkrb5.so.3"/>
        </Key>
      </BIS>
    </Key>
  </Root>
</Configuration>

<Configuration>
  <Root>
    <Key Name="PP">
      <BIS>
        <Key Name="System">
          <MultiDomain>
            <Key Name="domain 1 name" aliases="list of alternative names of domain 1" Proto="LDAP" url="ldap[s]://IP address or server domain name:[port]" base="dc=...,dc=..." libldap="libldap.dll" liblber="libldap.dll">
              <controllers>
                <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
                <Key Name="controller 2 name" url="ldap[s]://IP address or domain server name:[port]" />
              </controllers>
              <user filter="(&amp;(objectClass=user)(sAMAccountType=805306368))" groupsFilter="(&amp;(member=%1)(objectClass=group)(sAMAccountType=268435456))">
                <Key Name="a0" filter="user" ldap="objectClass"/>
                <Key Name="a1" map_to="DistinguishedName" ldap="distinguishedName" get_full_domain="1"/>
                <Key Name="a2" map_to="Name" ldap="sAMAccountName" make_upn="1"/>
                <Key Name="a3" map_to="Sid" ldap="objectSid"/>
                <Key Name="a4" map_to="DisplayName" ldap="cn"/>
                <Key Name="a5" map_to="Descr" ldap="displayName"/>
                <Key Name="a6" map_to="LookupName" ldap="sAMAccountName"/>
                <Key Name="a7" map_to="LookupName" ldap="userPrincipalName"/>
                <Key Name="a8" map_to="LookupName" ldap="displayName"/>
                <Key Name="a9" map_to="LookupName" ldap="cn"/>
              </user>
              <group filter="(&amp;(objectClass=group)(sAMAccountType=268435456))">
                <Key Name="a0" filter="group" ldap="objectClass"/>
                <Key Name="a1" map_to="DistinguishedName" ldap="distinguishedName" get_full_domain="1"/>
                <Key Name="a2" map_to="Name" ldap="sAMAccountName"/>
                <Key Name="a3" map_to="Sid" ldap="objectSid"/>
                <Key Name="a4" map_to="DisplayName" ldap="cn"/>
                <Key Name="a5" map_to="Descr" ldap="description"/>
                <Key Name="a6" map_to="LookupName" ldap="sAMAccountName"/>
                <Key Name="a7" map_to="LookupName" ldap="description"/>
              </group>
              <credentials realm="" Crs="..." Crsa="..." mechanism="GSSAPI"/>
            </Key>
            <Key Name="subdomain 1 name" aliases="list of alternative names of subdomain 1" url="ldap[s]://IP addressor domain server name:[port]" base="dc=...,dc=...">
              <controllers>
                <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
                <Key Name="controller 2 name" url="ldap[s]://IP address or domain server name:[port]" />
              </controllers>
              <user filter="(&amp;(objectClass=user)(sAMAccountType=805306368))" groupsFilter="(&amp;(member=%1)(objectClass=group)(sAMAccountType=268435456))">
                ...
              </user>
              <group filter="(&amp;(objectClass=group)(sAMAccountType=268435456))">
                ...
              </group>
              <credentials realm="" Crs="..." Crsa="..." mechanism="GSSAPI"/>
            </Key>
            <Key Name="subdomain 2 name" aliases="list of alternative names of subdomain 2" url="ldap[s]://IP address or domain server name:[port]" base="dc=...,dc=...">
              <controllers>
                <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
                <Key Name="controller 2 name" url="ldap[s]://IP address or domain server name:[port]" />
              </controllers>
              <user filter="(&amp;(objectClass=user)(sAMAccountType=805306368))" groupsFilter="(&amp;(member=%1)(objectClass=group)(sAMAccountType=268435456))">
                ...
              </user>
              <group filter="(&amp;(objectClass=group)(sAMAccountType=268435456))">
                ...
              </group>
              <credentials realm="" Crs="..." Crsa="..." mechanism="GSSAPI"/>
            </Key>
            <Key Name="domain 2 name" aliases="list of alternative names of domain 2" Proto="LDAP" url="ldap[s]://IP address or domain server name:[port]" base="dc=...,dc=..." libldap="libldap.dll" liblber="libldap.dll">
              ...
            </Key>
          </MultiDomain>
          <Gssapi libgssapi_32="gssapi32.dll" libgssapi_64="gssapi64.dll" libkrb5_32="krb5_32.dll" libkrb5_64="krb5_64.dll"/>
        </Key>
      </BIS>
    </Key>
  </Root>
</Configuration>

The MultiDomain Section

The MultiDomain section contains settings of domains and subdomains. One can connect additional domain controllers for domains and subdomains. Parameters of connection to domains and subdomains are specified in Key child elements.

If user names do not contain domain name, when setting up multi-domain authentication, first, reconnect users in the current repository.

NOTE. Specification of several domains is supported only if built-in authorization is used. If built-in authorization is not used, it is recommended to specify one domain to avoid work issues, for example, on using groups with equal names in different domains.

Features of attributes use in the Key element:

Name. Domain or subdomain name. Attribute value is case insensitive. When working with Active Directory, one sets NetBIOS domain name (unique name within the configuration of the settings.xml file). The specified name will be used to create a domain user name when he is added in the security manager.
aliases. The list of alternative names of domain or subdomain specified via semicolon. It is used to search for domain/subdomain settings in various name contents (NC). Attribute value is case insensitive.

Take into account the following features of working with Active Directory:

If NetBIOS domain name specified in the Name attribute matches with part of FQDN specified before the first point, it is only needed to specify full domain name FQDN in the aliases attribute. For example:

<Key Name="DOMAIN" aliases="domain.server.name" Proto="LDAP" url="ldap://domain.server.name" base="dc=domain,dc=server,dc=name" libldap="libldap-2.4.so.2" liblber="liblber-2.4.so.2">

If NetBIOS domain name specified in the Name attribute does not match with part of FQDN specified before the first point, the aliases attribute should contain two alternative names - full domain name FQDN and its first part. For example:

<Key Name="DMN" aliases="domain.server.name;domain" Proto="LDAP" url="ldap://domain.server.name" base="dc=domain,dc=server,dc=name" libldap="libldap-2.4.so.2" liblber="liblber-2.4.so.2">

Proto. The used implementation of interaction with directory services:

LDAP. For OpenLDAP client.
GC. For Active Directory Windows client. Is it supported only in Windows OS and is recommended to be used.

When setting up access permissions and granting privileges for domain users, take into account the following:

If an attribute is set to GC, repository connection returns information about all domain groups included nested ones.
If an attribute is set to LDAP, repository connection returns information only about first0level domain groups.

IMPORTANT. Values of the Proto, libldap and liblber attributes are taken into account only in the first specified Key element. The rest of the settings of domains and subdomains should correspond to the same value of the Proto attribute.

url. Directory service server URL in the format: ldap[s]://<IP address or domain server name>:<[port]>. Specify the ldap scheme if the server is set up by TCP protocol, or specify the ldaps scheme if TLS/SSL protocol is used. The default port number: 389 for ldap, 636 for ldaps.

NOTE. If global directory port (3268 for ldap, 3269 for ldaps) is set, when selecting users or groups in the Search Users and Groups dialog box, the web application will search for all subjects within the domain and its subdomains, regardless of the specific domain.

base. Unique identifier corresponding to the root element of domain or subdomain for searching objects in the directory. The identifier contains includes a set of domain or subdomain components as a string: Distinguished Names in the directory service. All necessary information can be obtained from administrator of the network, in which the server is located.

NOTE. The attribute can be set only on one of the files: ldap.conf or settings.xml. By default, ldap.conf is contained in the folder: /etc/ldap in Debian-based distributions, /etc/openldap in RedHat-based distributions, and ALT Linux, C:\OpenLDAP in Windows OS.

When a domain user is added in the security manager, the system takes into account the UseUPN parameter from repository connection settings:

UseUPN=True. The value of the UserPrincipalName attribute will be used as the name of the added user.
UseUPN=False. The user name is created based on the value of the map_to="Name" (or map_to="SamAccountName" if Name is not defined) attribute and domain name from the Name attribute of the Key element in the MultiDomain subsection. Platform versions earlier than 10.8 use the domain name obtained from Distinguished Names.

Additional Domain Controllers

Additional domain controllers are used as alternative ones if the main domain controller or subdomain are unavailable after three connection attempts. If connection with one controller is interrupted, and another controller becomes active, the active user session is maintained active too.

The list of additional domain controllers is set in the controllers section with the Key elements in the Key parent element, which corresponds to the specified main domain controllers or subdomain. Available attributes of the Key sections:

Name. Controller name.
url. Controller URL in the format: ldap[s]://<IP address or domain server name>:<[port]>. It is set identically to the url attribute that determines the catalog service server URL.

The example of the controllers section:

<controllers>
  <Key Name="controller 1 name" url="ldap[s]://IP address or server domain name:[port]" />
  <Key Name="controller 2 name" url="ldap[s]://IP address or server domain name:[port]" />
</controllers>

Domain or Subdomain Settings

Each domain or subdomain can contain the user and group sections, in which Key elements are determined.

Features of attributes use in the Key element:

filter. Advanced search filter by subject type: user or group.
map_to. Correspondence of ldap attributes to search and add domain subjects (users or groups) in the security manager. The attribute contains the following values:

Descr. Subject description. It is displayed as a value of the Description parameter in user properties or groups.
DisplayName. Full domain user name. It is displayed as a value of the Full Name parameter in user properties.
EMail. Default subject email. It is set as a value of the IUserProfile.Email property.

SamAccountName. User name without taking into account domain in the format <domain>\<name>.

UserPrincipalName. User name taking into account domain in the format <name>@<domain>. If it is not specified, the value should be created using Name value with the make_upn attribute. It is set as a value of the ISecuritySubject.UserPrincipalName property.
Name. Subject name creation method. It can contain the make_upn attribute with the 1 value to create "U based on the value of Name" taking into account the domain.

NOTE. If the Name value is used with the make_upn attribute, DistinguishedName should be set with the get_full_domain attribute.

If the map_to attribute is set to Name, and the ldap attribute is set to sAMAccountName, the domain name is always added to the value obtained from LDAP directory: DOMAIN\ATTRVALUE.

DistinguishedName. Unique subject name in the format determined for the directory service, for example: CN=user,OU=group,DC=domain,DC=ru. It is used to create the UserPrincipalName value if the Name value is set with the make_upn attribute. It may contain the get_full_domain attribute with the 1 value. It is set as a value of the ISecuritySubject.DistinguishedName property.
Sid. Subject identifier. It may contain the sid_prefix attribute with the 1 value that adds the LDAP- prefix to the original SID identifier. It is set as a value of the ISecuritySubject.Sid property.
LookupName. The value of ldap attribute, by which domain subjects will be searched.

NOTE. At least one map_to attribute with the LookupName value should be specified for ldap attribute.

When specifying a name creation method for the Name subject make sure that the following conditions are satisfied for subject names:

Name cannot be empty, should not end with \ and contains the (DOMAIN\NAME) domain.
Name can match with UPN. Name cannot be empty for UPN users and should contain the @ character.
Sid cannot be empty.

Subjects with invalid names are skipped, and one of the following errors is displayed in the log:

LDAP: Name cannot be empty;
LDAP: Name '<NAME>' should contain domain;
LDAP: Name '<NAME>' should not end with '\\' symbol;
LDAP: Sid cannot be empty;
LDAP: UserPrincipalName cannot be empty;
LDAP: UserPrincipalName '<UPN>' should contain '@'.

If all subjects were skipped, check again settings of the map_to attribute.

Credentials for Connecting to Directory Service Server

Each main domain or subdomain should contain the credentials element with the attributes:

realm. Domain name.
Crs/Crsa. Credentials for connecting to directory service server in the encrypted form. Encrypted values of these attributes can be obtained using the PP.Util utility, use the encrypt_creds parameter.
username/password. User name and password in the opened form. They are used to provide compatibility with earlier versions of Foresight Analytics Platform. If both pairs of attributes are specified, encrypted credentials will be used.

TIP. For safety reasons, it is recommended to use encrypted credentials. If both pairs of attributes Crs/Crsa and username/password are specified, the higher priority is given to the Crs/Crsa attributes.

mechanism. Directory server connection mechanism, for example, GSSAPI. If an empty string is specified or ldaps protocol based catalog service server URL is set in the url attribute, the SASL SIMPLE mechanism is used.

NOTE. Make sure that the used mechanism is supported by directory service server.