Integrating with LDAP servers

Integration with Lightweight Directory Access Protocol (LDAP) servers does not apply to a Tanium as a Service deployment.

LDAP overview

Lightweight Directory Access Protocol (LDAP) is a standard, cross-platform, client-server protocol for interacting with directory services such as Active Directory (AD) over an Internet Protocol (IP) network. The Tanium Core Platform supports LDAP for authenticating users and importing users and user groups. You can configure the Tanium Server to connect with multiple LDAP servers.

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 server configuration, you specify whether to authenticate the synchronized users through the LDAP server. Otherwise, the Tanium Server applies whatever other authentication methods you configured (see User authentication).

Configure the integration with LDAP servers before performing other RBAC configuration tasks.

You require the Administrator reserved role to see and use the Console > 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 (matching the numbers in Figure  1) summarize the LDAP synchronization process for this example deployment.

A1 Each LDAP server configuration identifies which users and user groups to synchronize with which LDAP server. For configuration details, see User and user group filtering and Configure an LDAP server.
2 The Tanium Server initiates connections with the LDAP servers to perform the initial import of users and user groups and to periodically query for updates. All the LDAP server configurations specify LDAPS encryption in this example, so the Tanium Server connects to port 636 on the LDAP servers.

The following steps (matching the letters in Figure  1) summarize the LDAP authentication process for this example deployment.

A A synchronized user enters a domain (if required), user name, and password to log into the Tanium Console.

B The Tanium Server uses the specified user name to find the corresponding external identifier (such as objectGUID) in the Tanium database. (In the LDAP server configuration, the User Unique ID Property specifies this identifier).

C The Tanium Server uses the external identifier to query the LDAP server for the matching distinguished name (DN) of the user, such as cn=jdoe,ou=noc,dc=acme,dc=com. (The query is based on the same settings as those used for synchronization: see User and user group filtering and Configure an LDAP server.) The LDAP server then authenticates the user based on the DN and login password. After the LDAP server returns an authentication success message, the Tanium Server provides the user access to the Tanium Console.

D When a user configured locally (Tanium_Admin) enters login credentials, the Tanium Server uses the local authentication service to authenticate the user, and then provides access to the Tanium Console.

User and user group filtering

Before configuring LDAP server connections, be sure to understand the interactions among the following settings, which the Tanium Server uses to filter users and user groups that it synchronizes. 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 server configuration, you can specify whatever port your LDAP server listens on for its inbound LDAP traffic. Your network administrator must configure network security 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 values are case sensitive.
  • The LDAP server must allow queries using the configured filter expressions.
  • Review the Best practices for integrating with an LDAP server.

Configure an LDAP server

  1. From the Main menu, select Console > Configuration > Authentication and click LDAP / AD Sync.
  2. Click Add Server to create a new LDAP server connection or click Edit in the tile for an existing connection to modify its settings.
  3. Configure 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 LDAP server configuration. After enabling the configuration, you have the option to Pause synchronization without fully disabling the configuration (authentication continues to work), and then resume synchronization later. Synchronization occurs every five minutes for enabled configurations.

As a best practice, never disable the configuration. If you do, at the next synchronization time 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 groups do not have any RBAC or computer management rights configured. Also note that the re-added groups have new Tanium IDs but use the same LDAP objectGUIDs as the deleted groups.

Name Enter a name to identify this LDAP server.
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. You must enter IPv6 addresses within square brackets (for example, [2001:db8::1]).
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 Microsoft NT LAN Manager (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 an LDAP User Name or LDAP Password. The LDAP server must allow this account to query with the configured filter expressions.
LDAP User Name / Password If you cannot use NTLM, specify the user name and password of the service account that the Tanium Server uses to query the LDAP server. 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 that the Tanium Server uses to match users in the Tanium database. Specify a NetBIOS name to match users who log in using the <domain>\<username> format (such as example-corp\user1) or specify a <domain>.<top-level_domain> name to match users who log in using the <username>@<domain.top-level_domain> format (such as [email protected]). Either domain format matches users who log in using only their user name.
Sync group members individually By default, the LDAP server searches for users to synchronize based on the Users Base value. However, if your LDAP implementation does not allow for a base user group that lists all users, select Sync group members individually to skip the Users Base search. Instead, this option directs the LDAP server to search for the DN of each user group member based on the Group Membership Attribute. The users must still match the Users Filter, which can exclude group members that are computers or other groups.

Compared to a Users Base search, a search based on Group Membership Attribute requires more processing and can take noticeably more time if you have many users.

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 add an LDAP server 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. Otherwise, the Tanium Server uses the LDAP server only to synchronize users and groups, and for authentication uses whatever other method you configured (see User authentication).

Clone an LDAP server

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

  1. From the Main menu, select Console > Configuration > Authentication and click 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 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. To make the Tanium Console immediately display changes made on the LDAP servers (such as user group membership updates), manually synchronize as follows:

  1. From the Main menu, select Console > Configuration > Authentication and click LDAP / AD Sync.
  2. Click Sync Now.

Pause or resume an LDAP server

If you are upgrading an LDAP server, or troubleshooting unexpected synchronization results, you can pause synchronization for a particular LDAP server without fully disabling its configuration (authentication continues to work). After you finish upgrading or troubleshooting, you can resume synchronization.

  1. From the Main menu, select Console > Configuration > Authentication and click LDAP / AD Sync.
  2. Click Edit in the panel for the LDAP server.
  3. Select the Pause check box to pause LDAP synchronization or deselect the check box to resume synchronization .
  4. Save your changes.

Delete an LDAP server

When you delete an LDAP server configuration, the Tanium Server stops updating the users and user groups that it previously imported from that LDAP server. When the Tanium Server next performs synchronization for the remaining LDAP servers, it removes the users and groups associated with deleted configuration. Delete the configurationas follows when you no longer want that information saved in the Tanium Server:

  1. From the Main menu, select Console > Configuration > Authentication and click LDAP / AD Sync.
  2. Click Delete in the panel for the LDAP server configuration.

Disabling an LDAP server configuration has the same effect as deleting it. For details about disabling a configuration, see Configuration.

Import or export the LDAP server configuration

You can export the LDAP server configuration to a JSON file and import a signed JSON or 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 the Main menu, select any Console > Content or Console > Permissions page.
  2. Click Export Content at the top right of the Tanium Console.
  3. Select LDAP Synchronization Connectors, select the Export Format (JSON or XML), and click Export.
  4. Enter a File Name or accept the default, and then click OK. The Tanium Server exports the file to the Downloads folder on the system you use to access the Tanium Console.

Import

You can import files that are in JSON or XML format.

  1. Digitally sign the content file and ensure a public key is in place to validate the signature, as described under Authenticating content files.
  2. From the Main menu, select any Console > Content or Console > Permissions page and click Import Content 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 the configuration for a user defined locally on the Tanium Server, but the user still matches the filters defined in an LDAP server, the Tanium Server retains a configuration for the user.
  • If you use the Tanium Console to delete a user account that was imported from 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 or transfer ownership for the configuration objects that run under that ID. For details, see Delete, undelete, or lock out a user.
  • 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 local user so that you can use the account to log into the Tanium Console and re-configure the LDAP server connections in case they fail. Some organizations provision multiple administrator users outside of the LDAP servers 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 servers to prevent synchronization for the account (see Table 1).