Integrating with LDAP servers

LDAP overview

You configure an LDAP sync connector for each Lightweight Directory Access Protocol (LDAP) or Active Directory (AD) server from which the Tanium Server must import users and user groups. The Tanium Server automatically synchronizes with each LDAP server every five minutes, and you can manually synchronize at any time. The synchronization updates the Tanium Server with any changes that occurred on the LDAP server, including: new, updated, disabled, or deleted users; new, updated, or deleted user groups; and changes to user group membership. In each LDAP sync connector configuration, you specify whether to authenticate the synchronized users through the LDAP server. Otherwise, the Tanium Server applies whatever other authentication methods you configured.

You require the Administrator reserved role to see and use the Configuration > Authentication > LDAP / AD Sync Configuration page.

Figure  1 illustrates LDAP synchronization and authentication for the following example deployment:

  • The Tanium Server is installed on a Tanium Appliance and uses Secure LDAP (LDAPS) encryption for connections to LDAP servers.

    The available encryption options depend on the operating systems of the Tanium Server and LDAP servers.

  • All the LDAP configurations specify that the LDAP servers will authenticate the imported users.
  • One account (Tanium_Admin) with the Administrator reserved role is not imported from an LDAP server, and the Tanium Appliance uses its local authentication service for that user. This configuration ensures that at least one user can access the Tanium Console even if LDAP connections go down.
Figure  1:  LDAP synchronization and authentication

The following steps summarize LDAP synchronization and authentication processes for this example deployment, and correspond to the numbers in Figure  1.

  1. When a synchronized user logs into the Tanium Console, the Tanium Server uses the login user name, such as [email protected], to search the directory for the corresponding distinguished name (DN), such as cn=jdoe,ou=noc,dc=acme,dc=com. The Tanium Server then uses that DN and the login password to authenticate through the LDAP server from which it imported the user account. After the LDAP server returns an authentication success message, the Tanium Server provides the user access to the Tanium Console.
  2. When a user configured locally (Tanium_Admin) logs in, the Tanium Server uses the local authentication service to authenticate the user, and then provides access to the Tanium Console.
  3. Each LDAP sync connector identifies which users and user groups to synchronize with which LDAP server. For details, see User and user group filtering.
  4. The Tanium Server initiates connections with the LDAP servers to perform the initial import of users and user groups, periodically query for updates, and send authentication requests for user logins. All the LDAP server configurations specify LDAPS encryption in this example, so the Tanium Server connects to port 636 on the LDAP servers.

User and user group filtering

Before configuring LDAP sync connectors, be sure to understand the interactions among the following settings, which the Tanium Server uses to filter users and user groups that it synchronizes with LDAP servers. For example, because the best practice is to configure role-based access control (RBAC) for Tanium users based on group permissions instead of user permissions, you might want to exclude users who are not assigned to groups. Figure  2 and Figure  3 illustrate an example of the steps that the servers perform in that use case, with separate workflows for filtering users on the LDAP servers and Tanium Server.

  • Group Base: When the Tanium Server sends a synchronization request (Step 1 in both figures), the LDAP server searches only for user groups that are under this base DN, such as cn=adm,ou=tanium,dc=acme,dc=com.
  • Group Filter: The LDAP server uses this field to filter the user groups in the Group Base. In this example, the LDAP server returns groups only if their objectClass attribute is set to group (Step 2 in both figures). The Tanium Server then synchronizes those groups (Step 3 in both figures).
  • Users Base: The LDAP server searches only for users that are under this base DN, such as cn=adm,ou=tanium,dc=acme,dc=com.
  • Users Filter: The LDAP server uses this field to filter the users in the Users Base. In this example, the LDAP server returns users only if their objectClass attribute is set to user (Step 4 in both figures).
  • Filter Users: If you want to exclude users who are not assigned to user groups that are synchronized with the Tanium Server, select one or both of the following options:
    • Filter on LDAP Server (Figure  2): The LDAP server returns users only if they have a value (DN) in their User’s Group Membership Attribute (the memberOf attribute, in this example) that matches one of the groups from the group search (Step 4). Selecting this option is the best practice because filtering on the LDAP server is faster and results in less network traffic than filtering on the Tanium Server. Most LDAP servers support this option. Upon receiving the filtered users, the Tanium Server synchronizes them (Step 5).
    • Filter on Tanium Server (Figure  3): The LDAP server returns all users to the Tanium Server if they match the Users Filter (Step 4); the LDAP server does not filter by the User’s Group Membership Attribute. The Tanium Server then discards any users (Step 5) if none of the synchronized user groups have the user DN in their Group Membership Attribute (the member attribute, in this example). This option is intended as a backup in cases where the LDAP server does not support filtering by the User’s Group Membership Attribute.

    After consolidating any duplicates in the synchronized users and groups, the Tanium Server updates the Tanium database (Step 6 in both figures).

The following figure illustrates user filtering on LDAP servers.

Figure  2:  Filtering on LDAP servers

The following figure illustrates user filtering on the Tanium Server.

Figure  3:  LDAP user and group filtering

Before you begin

  • For synchronization, the Tanium Server initiates the connection with the LDAP server. The standard port for LDAP is 389 (3268 for an AD global catalog). The standard port for LDAPS is 636 (3269 for an AD global catalog). In the LDAP sync configuration, you can specify whatever port your LDAP server listens on for its inbound LDAP traffic. Network security must be configured to allow this traffic.
  • You must know the base distinguished name (DN), IDs, and filter expressions for the users and user groups that you want to import.
  • The LDAP server must allow the LDAP sync connector user to query the LDAP server using the configured filter expressions.
  • Review the Best practices for integrating with an LDAP server.

Configure the LDAP server connection

  1. Go to Configuration > Authentication > LDAP / AD Sync.
  2. Click Add Server to display the Add Server Configuration page.
  3. Complete the settings using the guidance provided in Table 1.
  4. Click Show Preview to Continue and review the users and groups to be imported.
  5. Save the configuration.
Table 1:   LDAP server configuration
Settings Guidelines
Configuration Enable or Disable the configuration.

If you enable the configuration, synchronization occurs every five minutes.

As a best practice, never disable the configuration. If you do, at the next sync time (within five minutes) the Tanium Server locks out the users and deletes the user groups that it previously imported. If you subsequently re-enable the configuration, the Tanium Server unlocks the users and re-adds the user groups. The re-added user groups will not have any RBAC or management rights configured. Also note that the re-added groups will have new Tanium IDs but will use the same LDAP objectGUIDs as the deleted groups.

Name Enter a name to identify this LDAP sync connector.
Host Fully-qualified domain name (FQDN) or IP address of the LDAP server. If you connect using LDAPS, the Host value must match the hostname value in the LDAP server certificate.
Port Specify the number of the port on which your LDAP server listens for its inbound LDAP traffic. The standard port depends on the protocol:
  • LDAP: The standard port is 389 (3268 for an AD global catalog). The LDAP server uses this port for unencrypted connections, connections that use StartTLS, and AD connections that use the Sign and encrypt option.
  • LDAPS: The standard port is 636 (3269 for an AD global catalog).
Referrals Select this option to disable referrals. If the LDAP server is a Microsoft AD server, disabling referrals is mandatory.
Encryption Select one of the following options:
  • None. Do not use in production.
  • Sign and encrypt. The LDAP connector turns on the LDAP_OPT_SIGN and LDAP_OPT_ENCRYPT session options. The session is encrypted, but it does not use TLS. Use this option only for Tanium Server on Windows and the external LDAP server is an AD server.
  • StartTLS. The LDAP connector calls ldap_start_tls_s to set up a TLS connection. You can use this option with Tanium Server on Windows or the Tanium Appliance.
  • LDAPS. The LDAP connector initiates an SSL connection to the LDAPS server.
NTLM Uses NTLM for the connection with the LDAP server. This option is enabled by default. Using NTLM is a best practice when the Tanium Server is installed on a Windows Server and the connection is to an AD server. If you use NTLM, the Tanium Server service account is used, and you do not need to configure a user name and password. The LDAP server must allow this account to query with the filter expressions configured for the LDAP sync connector.
LDAP User Name / Password If you cannot use NTLM, specify an LDAP server user name and password. As a best practice, provision a special account for this purpose with permissions that are low but sufficient to query the LDAP server.
Group Base This is the base DN for the user groups container. The Tanium Server synchronizes groups from all locations below this path.

Example: cn=Ops,ou=TaniumAdmins,dc=tam,dc=local

Note: If setting the Group Base or Users Base to the root of a domain produces errors, select Disable referrals in the General section.

Group Filter The LDAP server uses this field to filter the user groups in the Group Base. For example, if you enter objectClass=group, the LDAP server returns groups only if their objectClass attribute is set to group.

Note: Use a backslash (\) to escape special characters in a group name. For Windows, use one backslash (example: name=\#myGroup). For the Appliance (Linux), use two backslashes (example: name=\\#myGroup).

Group Unique ID Property Enter the attribute (such as objectGUID) that uniquely identifies each user group.

Note: The value is case sensitive.

Group Name Property Enter the attribute (such as cn) that identifies the name of a user group.

Note: The value is case sensitive.

Group Membership Attribute Enter the user group attribute (such as member) that indicates which users are members.

Note: The value is case sensitive.

Filter Users If you want to exclude users who are not assigned to user groups that are synchronized with the Tanium Server, select one or both of the following options:
  • Filter on LDAP Server. Specify an attribute in the User's Group Membership Attribute text box. The most common LDAP attribute is memberOf. You must enter an attribute name, not an expression. The LDAP server returns users only if they have a value (DN) for that attribute that matches one of the groups from the group search. Selecting this option is the best practice because filtering on the LDAP server is faster and results in less network traffic than filtering on the Tanium Server. Most LDAP servers support this option.
  • Filter on Tanium Server. The LDAP server returns all users to the Tanium Server if they match the Users Filter; the LDAP server does not filter by the User’s Group Membership Attribute. The Tanium Server then discards any users if none of the synchronized user groups have the user DN in their Group Membership Attribute. This option is intended as a backup in cases where the LDAP server does not support filtering by the User’s Group Membership Attribute.
User Domain Enter the domain of the users (such as tam.local).
Users Base This is the base DN for the users container. The Tanium Server synchronizes users from all locations below this path.

Example: cn=Users,dc=tam,dc=local

Note: If setting the Group Base or Users Base to the root of a domain produces errors, select Disable referrals in the General section.

Users Filter The LDAP server uses this field to filter the users in the Users Base. For example, if you enter objectClass=user, the LDAP server returns users only if their objectClass attribute is set to user.

To exclude an account from synchronization, use the following filter, where <account_name> is the user name:

((&(objectClass=user)(!sAMAccountName=<account_name>)))

Note: If you create an LDAP sync connector for the local authentication service of a Tanium Server running on a Tanium Appliance, you must use the following user filter:

(&(objectClass=person)(uidNumber>=20000))

User Unique ID Property Enter the attribute (such as objectGUID) that uniquely identifies each user.

Note: The value is case sensitive.

User Name Property Enter the attribute (such as cn or sAMAccountName) that identifies the name of a user. The value that the Tanium Server imports for this field becomes the user name that users type to log into the Tanium Console. Be sure to specify the attribute that is suitable for this purpose and be sure to communicate the expected form to your users.

Note: The value is case sensitive.

User Display Name Property Enter the attribute that identifies the display name for users (typically displayName).
Authentication Select Use LDAP for user authentication to use the configured server as the authentication source. If you do not select this option, the Tanium Server will use the LDAP sync connection only to synchronize users and groups; to authenticate users, the server will use whatever other methods you configure, such as local, Windows, or SAML authentication.

Clone an LDAP server configuration

Cloning an LDAP server configuration enables you to quickly add connections for multiple domains.

  1. Go to Configuration > Authentication > LDAP / AD Sync.
  2. Click Clone in the panel that has the name of the LDAP server that you want to clone.
  3. Click Edit in the panel for the cloned configuration.
  4. Edit the settings (such as User Domain) as necessary using the guidance provided in Table 1.
  5. Click Show Preview to Continue and review the users and groups to be imported.
  6. Save the configuration.

Manually synchronize with an LDAP server

The Tanium Server automatically synchronizes with LDAP servers every five minutes. If you want to synchronize immediately to account for changes made on the LDAP servers (such as changes to user group membership), perform the following steps:

  1. Go to Configuration > Authentication > LDAP / AD Sync.
  2. Click Sync Now.

Delete an LDAP sync connector

When you delete an LDAP sync connector, the Tanium Server stops updating the users and user groups that it previously imported from the associated LDAP server. The next time the Tanium Server performs synchronization for the remaining LDAP sync connectors, it removes the users and groups associated with deleted connector.

Disabling a configuration and deleting a configuration have the same effect. Delete the configuration when you no longer want that information saved in the Tanium Server. For details about disabling a configuration, see Configuration.

Import or export the LDAP server configuration

You can export the LDAP server configuration to an XML file and import a signed XML file into the same or different Tanium Server. You might do this, for example, to share the connection information when troubleshooting the LDAP query with your LDAP administrator.

Export

  1. From any Content or Permissions page, click Export to XML in the top right of the Tanium Console.
  2. Select LDAP Synchronization Connectors and click Export.
  3. Enter a File Name or accept the default, and then click OK. The Tanium Server exports the XML file to the Downloads folder on the system you use to access the Tanium Console.

Import

  1. Use KeyUtility.exe to sign the XML configuration file before you import it. As a one-time action, you must also copy the associated public key to the correct folder. For the procedures, see Signing content XML files.
  2. Go to any Content or Permissions page and click Import from XML at the top right of the page.
  3. Click Choose File, find and select the configuration file, and click Open.
  4. Click Import. If object names in the file are the same as for existing objects, the Tanium Console itemizes the conflicts and provides resolution options for each one.
  5. Select resolutions for any conflicts. For guidance, see Conflicts and Best practices, or consult your TAM.
  6. Click Import again, and click Close when the import finishes.

Best practices

When transitioning from manually-created users to LDAP-synchronized users, you might inadvertently create multiple configuration objects for a single real user. For example, say you use the Tanium Console to manually create a user named john.doe, and you also synchronize with an LDAP server that returns the same user name. In this case, the Tanium Server has two user configurations for john.doe, and automatically assigns a unique object ID to each one (object IDs 2 and 3, in this example).

Figure  4:  Redundant user configurations

Before correcting such redundancies, it is important to understand the ramifications of deleting users in different ways:

  • If you delete a user configuration that was created manually on the Tanium Server, but the user still matches the filters defined in an LDAP sync connector, the Tanium Server retains a configuration for the user.
  • If you use the Tanium Console to delete a user account that is synchronized with an LDAP server, that user remains deleted after the next synchronization.
  • If you delete a user from the back-end LDAP server configuration, the Tanium Server marks that user as locked out after the next synchronization. The user cannot log in, but the Tanium Server does not automatically delete the user account. Any scheduled questions and actions that the user has configured continue to run. This gives other Tanium administrators the chance to re-create the scheduled questions and actions under a different user account if necessary.

When setting up and managing the integration between Tanium Servers and LDAP servers, the following are best practices to avoid unexpected issues:

  • When deleting user configurations to correct redundancies, be sure to understand the impact on associated configuration objects, such as scheduled actions, saved questions, Tanium Connect objects, solution plugins, or solution module services. In the Figure  4 example, the objects that john.doe - ID 2 created do not also belong to john.doe - ID 3. If you delete the john.doe - ID 2 configuration, you must be ready to re-create the configuration objects that run under that ID. See the user management topic for details.
  • On the back-end LDAP server, create LDAP user groups that correspond with Tanium user groups, and create user accounts for the users who require access to the Tanium system.
  • Manage Tanium access through the back-end LDAP server configuration instead of the front-end Tanium Console configuration. For example, the best way to on-board and off-board users is to modify the membership of synchronized user groups.
  • Control access to the back-end LDAP server configuration so that LDAP administrators who are not familiar with your Tanium deployment cannot make changes that affect it.
  • On the Tanium Server, maintain at least one account in the Users configuration that the Tanium Server does not import from an LDAP server. Assign the Administrator reserved role to this user so that you can use the account to log into the Tanium Console and re-configure the LDAP sync connectors in case they fail. Some organizations provision multiple administrator users outside of the LDAP sync connectors for this reason. To avoid creating duplicate user configurations in cases where the account name also exists on an LDAP server, you can configure the Users Filter in the LDAP sync connectors to prevent synchronization for the account (see Table 1).

Last updated: 10/15/2019 2:34 PM | Feedback