Working with Directory Services

Foresight Analytics Platform gets information about domain security subjects from the domain directory service or global directory that must be set up in the computer network. Interaction depends on the type of the directory service in use and the operating system installed at directory service server. The following directory services are supported: Active Directory, OpenLDAP.

NOTE. Interaction with directory services is executed only via the LDAP protocol.

If connection to the directory service of the current domain (global directory of the current network) is executed, and the service is based on Active Directory (Windows OS), advanced settings do not need to be done in Foresight Analytics Platform.

If the directory service is located at Linux OS server, or it is required to connect to the directory service in the network other than the current one (Linux or Windows OS server), then the OpenLDAP (open implementation of the LDAP protocol) will be used for communication. If the access to the directory service is executed in Linux OS, the OpenLDAP system libraries are used. In Windows OS one will require installation of the external software providing OpenLDAP implementation (for example, OpenLDAP for Windows).

If authentication should work using GSSAPI protocol, one should install MIT Kerberos for Windows 4.1 on LDAP and PostgreSQL servers (bitness should be the same as of Foresight Analytics Platform). It will also be necessary to adapt configuration files:

Examples of the settings.xml file depending on OS type, on which the directory service is based:

Linux OS Windows OS

<Configuration>
  <Root>
    <Key Name="PP">
      <BIS>
        <Key Name="System">
          <Ldap Proto="LDAP" url="ldap://IP address or domain server name:port" base="dc=...,dc=..." libldap="libldap-2.4.so.2" liblber="liblber-2.4.so.2">
            <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_sam_account="1" 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" make_sam_account="1"/>
              <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"/>
          </Ldap>
          <Gssapi libgssapi="libgssapi_krb5.so.2" libkrb5="libkrb5.so.3"/>
        </Key>
      </BIS>
    </Key>
  </Root>
</Configuration>

<Configuration>
  <Root>
    <Key Name="PP">
      <BIS>
        <Key Name="System">
          <Ldap Proto="LDAP" url="ldap://IP address or domain server name:port" base="dc=...,dc=..." libldap="libldap.dll" liblber="liblber.dll" >
            <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_sam_account="1" 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" make_sam_account="1"/>
              <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"/>
          </Ldap>
          <Gssapi libgssapi_32="gssapi32.dll" libgssapi_64="gssapi64.dll" libkrb5_32="krb5_32.dll" libkrb5_64="krb5_64.dll"/>
        </Key>
      </BIS>
    </Key>
  </Root>
</Configuration>

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 to domain users via domain groups, take into account then 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.

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. Specify 389 as a port for ldap and 636 as a port for ldaps.
base. Domain components. All necessary information can be obtained from administrator of the network, in which the server is located.

NOTE. An attribute can be set only in 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.

filter. Advanced search filter by subject type: user or group.
map_to. Correspondence ldap attributes for searching and adding 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 or group properties.
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>. If it is not specified, the value should be created using Name value with the make_sam_account attribute. In this case, domain user name will be created taking into account domain.

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 may contain the attributes:

The make_upn attribute with the 1 value creates UserPrincipalName based on the Name value taking into account domain.
The make_sam_account attribute with the 1 value creates SamAccountName based on the Name value taking into account domain.

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

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 values of SamAccountName and UserPrincipalName if the Name value is set with the make_sam_account or make_upn attributes. 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.

realm. Domain.
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 by means of 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 ldap protocol based directory 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.

Connecting Additional Domain Controllers

One can connect additional controllers for domain main controller and subdomains, which will be used as alternative ones if the domain main controller or subdomain are unavailable after three failed 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 domain additional controllers is set in the controllers section with the Key sections. Available attributes of the Key sections:

Working with Directory Services

Connecting Additional Domain Controllers

Domain Main Controller

Subdomains