Using LDAP


You can configure an LDAP sync connector to import users and user groups from a Lightweight Directory Access Protocol (LDAP) or Active Directory (AD) server. In the configuration, you specify whether to authenticate the imported users through the LDAP server. Alternatively, the users can authenticate through:

  • An AD server for the domain to which the Tanium Server is joined.
  • The local accounts on the Tanium Server host computer (Windows). Deployments with the Tanium Appliance can use the local authentication service or a pluggable authentication module (PAM); consult your technical account manager (TAM) for details.

User and user group updates are automatically synchronized from the LDAP server every five minutes. At each synchronization, users and user groups are added or deleted, and group members might be added or deleted.

User role requirements

Only users assigned the Administrator reserved role can see and use the Configuration pages, including the LDAP Sync configuration page.

Before you begin

  • The Tanium Server initiates a connection to the back-end 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 you want to import.
  • The LDAP server must allow the LDAP sync connector user to query the LDAP server using the configured filter expression(s).

Configure the LDAP server connection

  1. Go to Configuration > Authentication > LDAP Sync.
  2. Click Add Server to display the 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 Sync 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 Configuration name.
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:
  • The standard port is 389 (3268 for an AD global catalog). This port is used for unencrypted connections, connections that use StartTLS, and Active Directory connections that use sign and encrypt options.
  • LDAPS: The standard port is 636 (3269 for an AD global catalog).
Referrals Select this option to disable referrals. Referrals must be disabled if the LDAP server is a Microsoft Active Directory server.
  • 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. Enabled by default. Recommended when the Tanium Server is installed on a Windows Server and the connection is to an Active Directory 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 expression(s) configured for the LDAP sync connector.

LDAP User Name / Password If you cannot use NTLM, specify an LDAP server user name and password. We recommend that you provision a special account for this purpose. The account should have privileges that are sufficient to query the LDAP server but otherwise be an account with low privileges.
Group Base The base DN for the user group. The LDAP query does not return subgroups, so you must create sync connection configurations for each subgroup you want to import.

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

Note: If the Tanium Server is an Appliance (Linux), the Base User or the Base Group values cannot be the root of a domain.

Group Filter The filter for user groups.

Example: objectClass=group

Note: You can use the 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 Example: objectGUID

Note: Case sensitive.

Group Name Property Example: cn

Note: Case sensitive.

Group Membership Attribute Example: member

Note: Case sensitive.

Filter Users
  • Filter on LDAP Server. Select this option and specify an attribute in the User's Group Membership Attribute text box. The LDAP attribute memberOf is most commonly used. When this option is enabled, filtering is done by the LDAP server. The LDAP server returns only the groups and group members that match the filter. You must enter an attribute name, not an expression.
  • Filter on Tanium Server. Select this option when you have configured multiple LDAP sync connectors, and you want the Tanium Server to perform group/user filtering after running all LDAP sync connectors. For example, suppose you have configured one connector with an LDAP query that returns groups and some users, and another connector with an LDAP query that returns additional users of some of those groups (from another server). You can use this option when you want the Tanium Server to reconcile the two sources and avoid duplication.
User Domain Example: tam.local
Base Users The base DN for users.

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

Tanium Appliance Note: If the Tanium Server is an Appliance (Linux), the Base User or the Base Group values cannot be the root of a domain.

Users Filter The filter for user names.

Example: objectClass=user

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


Tanium Appliance Note: If you create an LDAP sync connector for the Tanium Server local authentication service, you must use the following user filter: (&(objectClass=person)(uidNumber>=20000))

User Unique ID Property Example: objectGUID

Note: Case sensitive.

User Name Property Example: cn or sAMAccountName

The value imported for this field becomes the user name that users type to log into the Tanium Console. Be sure to specify the field that is suitable for this purpose and be sure to communicate the expected form to your users.

Note: Case sensitive.

User Display Name Property 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 LDAP sync connection will be used only to synchronize the users and groups, and authentication is handled by a local authentication service.

Clone an LDAP sync configuration

You can clone an LDAP sync configuration, change the user domain, base DN, and other LDAP query fields, and then save the configuration. Configuration cloning enables you to quickly add connections for multiple domains or multiple groups (The LDAP query does not return subgroups, so you must create sync connection configurations for each subgroup you want to import.)

  1. Go to Configuration > Authentication > LDAP Sync.
  2. Click Copy .

Delete an LDAP sync configuration

When you delete an LDAP sync configuration:

  • Users and user groups are no longer updated from the LDAP server.
  • Users and user groups that had been imported are deleted from Tanium at the next sync time (within 5 minutes).

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/export the LDAP sync configuration

You can export the 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.


  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.


  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. From any Content or Permissions page, click Import from XML at the top right of the Tanium Console.
  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

The Tanium Server synchronizes (imports) users and user groups from the external LDAP server every five minutes. Each LDAP sync connector populates a set of configuration objects. It is therefore possible to create multiple configuration objects for a single real user. For example, if you use the Tanium Console to manually create a user john.doe, and also configure two LDAP sync connectors to import from two LDAP servers, the Tanium Server will have three user configurations for john.doe.

Figure  1:  LDAP sync populating the Users and User Groups configuration

Consequently, it is important to understand the ramifications when deleting users in different ways:

  • If you delete a user configuration that was created manually, but the user still matches the LDAP sync filter, a configuration for the user remains in the Tanium Console.
  • If you use the Tanium Console to delete a user imported through LDAP, that user remains deleted after the next synchronization.
  • If you delete a user from the back-end LDAP server configuration, the user is marked as locked out upon next import into the Tanium Console. The user cannot log in, but the user account is not deleted automatically. Any scheduled questions and scheduled actions that the user has configured continue to run. This gives other Tanium administrators the opportunity to take stock of situation and re-create the scheduled questions and actions under a different user account if necessary.

The following are best practices to avoid unexpected issues:

  • Plan to do some work on the back-end LDAP server to create LDAP user groups that correspond with the Tanium user groups you want to create and the users you want to associate with Tanium access.
  • Plan to manage Tanium access by managing the back-end LDAP server configuration, not the front-end Tanium Console configuration. For example, the best way to on-board and off-board users is by adding them to a group that is imported or deleting them from a group that is imported.
  • Be sure to 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.
  • Maintain at least one user in the Users configuration that is not populated by the LDAP sync connector. This configuration should be assigned the Administrator reserved role and can be used to log into the Tanium Console and re-configure the LDAP sync connector in case it fails. Some organizations provision multiple admin users outside of the LDAP sync connector for this reason. When configuring the LDAP sync connector, you can configure a users filter to prevent synchronization for an account.
  • Be careful when you delete user configurations. As you transition from manually-created users to imported users, you probably want to clean up the apparent duplicates. However, the john.doe configuration that was created manually and the john.doe configuration that was imported have different object IDs. For example, let's say the first john.doe has object ID 2, and the second john.doe has object ID 3. The Tanium Console objects—such as scheduled actions, saved questions, Tanium Connect objects, solution plugins, or solution module services—that were created by the john.doe user that has object ID 2 do not also belong to the user with object ID 3. If you delete the john.doe configuration that has ID 2, you must be ready to re-create the configuration objects that run under that ID. See the user management topic for details.

Last updated: 6/4/2019 4:33 PM | Feedback