Integrating with 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
• Changes to user group membership

After the Tanium Server imports new users and user groups, you must assign roles, computer groups, and personas to them. If you import any user accounts that are not assigned to user groups, you must manually configure those assignments also. See:

• Managing users

• Managing user groups

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 role-based access control (RBAC) configuration tasks.

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

If a user account that is imported from an LDAP server cannot sign in to the Tanium Console, ask the LDAP administrator to check the account status. To troubleshoot other issues with your LDAP integration, review the LDAP logs. See Tanium Core Platform Deployment Reference Guide: LDAP logs.

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.

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

	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.
	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 synchronized user enters a domain (if required), user name, and password to sign in to the Tanium Console.
	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).
	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 sign in password. After the LDAP server returns an authentication success message, the Tanium Server provides the user access to the Tanium Console.
	When a user configured locally (Tanium_Admin) enters sign in 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 ( 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 ( in both figures). The Tanium Server then synchronizes those groups ( 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 ( 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 (). 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 ().
  • Filter on Tanium Server (Figure  3): 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 (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 ( in both figures).

The following figure illustrates user filtering on LDAP servers.

The following figure illustrates user filtering on the Tanium Server.

Best practices for LDAP integrations

When transitioning from manually-created users to LDAP-synchronized users, you might inadvertently create multiple configuration objects for a single real user. For example, you might use the Tanium Console to manually create a user named john.doe and 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).

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 sign 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, un-delete, 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 sign in to 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).

Before you begin

• For synchronization, the Tanium Server initiates the connection with the LDAP server. The standard LDAP port is 389 (3268 for an AD global catalog) for unencrypted connections, connections that use StartTLS, or AD connections that use the Sign and encrypt option for Encryption. The standard port for LDAPS encryption 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.
• (Tanium Appliance only) If you plan to use LDAPS or StartTLS as the Encryption option, you must first import the certificate authority (CA) certificate for the LDAP server and enable the encryption configuration on the Appliance. In an active-active deployment, upload the certificate and enable encryption on both Tanium Servers. See Tanium Appliance Deployment Guide: Configure additional security.
• 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 LDAP integrations for integrating with an LDAP server.

Configure an LDAP server

1. From the Main menu, go to Administration > Configuration > LDAP/AD Sync Configurations.
2. Click Add Server to create a new LDAP server connection or click Edit in the row for an existing connection to modify its settings.
3. Configure the following settings:

    Table 1: LDAP server configuration

   Settings	Guidelines
   Set Status	Set the synchronization and authentication state of the LDAP server connection: Enable: Synchronization occurs every five minutes and users can authenticate through the LDAP server if you select Use LDAP for user authentication. Disable: The Tanium Server does not synchronize with, or allow users to authenticate through, the LDAP server. 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 group assignments. Also note that the re-added groups have new Tanium IDs but use the same LDAP objectGUIDs as the deleted groups. Pause: The Tanium Server does not synchronize with the LDAP server but authentication continues to work and existing RBAC assignments are preserved.
   Name	Enter a name to identify this LDAP server.
   Host	Fully-qualified domain name (FQDN) of the LDAP server. If you connect using LDAPS, the Host value must match the Common Name (CN) or one of the Subject Alternative Names (SANs) of the LDAP 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	Disable referrals if the LDAP server is a Microsoft AD server. Disabling referrals is optional for other server types.
   Encryption	Select an encryption option: None. Do not use this option in a production environment. 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 Transport Layer Security (TLS). Use this option only for Tanium Server on Windows. The external LDAP server must be an AD server. StartTLS. The LDAP connector calls the ldap_start_tls_s function to set up a TLS connection. You can use this option with Tanium Server on Windows or the Appliance. LDAPS. The LDAP connector initiates an SSL connection to the LDAPS server. You can use this option with Tanium Server on Windows or the Appliance. (Appliance only) If you plan to use LDAPS or StartTLS, you must first import the LDAP server CA certificate and enable the encryption configuration on the Appliance. In an active-active deployment, upload the certificate and enable encryption on both Tanium Servers. See Tanium Appliance Deployment Guide: Configure additional security.
   NTLM	Select whether the Tanium Server uses Microsoft NT LAN Manager (NTLM) for the connection with the LDAP server. This option is enabled by default. If you use NTLM, the Tanium Server uses its service account to access the LDAP server, 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. Use NTLM if the Tanium Server is installed on a Windows Server and the connection is to an AD server.
   LDAP User Name and Password	If you selected Do not use NTLM, specify the user name and password of an account on the LDAP server that the Tanium Server can use for LDAP queries. If the account credentials ever change, be sure to update them in the LDAP server configuration on the Tanium Server. Provision a special account for this purpose with permissions that are low but sufficient to query the LDAP server.
   Group Sync	Enable (Yes) or disable (No) user group synchronization. If you enable the feature, the Tanium Server synchronizes with the groups on the LDAP server based on the settings that you configure in the Groups section. If you disable user group synchronization, at the next synchronization time the Tanium Server deletes the groups that it previously imported. If you subsequently re-enable group synchronization, the Tanium Server re-adds the user groups but with no RBAC or computer management group assignments.
   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 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 objectCategory=group, the LDAP server returns groups only if their objectCategory attribute is set to group. 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). See the LDAP server documentation for a list of special characters.
   Group Unique ID Property	Enter the attribute (such as objectGUID) that uniquely identifies each user group. The value is case sensitive.
   Group Name Property	Enter the attribute (such as cn) that identifies the name of a user group. The value is case sensitive.
   Group Membership Attribute	Enter the user group attribute (such as member) that indicates which users are members. 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 via User's Group Membership Attribute. 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 sign in using the <domain>\<username> format (such as example-corp\user1) or specify a <domain>.<top-level_domain> name to match users who sign in using the <username>@<domain.top-level_domain> format (such as [email protected]). Either domain format matches users who sign 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 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 objectCategory=user, the LDAP server returns users only if their objectCategory attribute is set to user. You must precede special characters in the filter with a backslash \ to escape them. See the LDAP server documentation for a list of special characters. Use the following filter to exclude an account from synchronization, where <account_name> is the user name: ((&(objectCategory=user)(!(sAMAccountName=<account_name>)))) 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: (&(objectCategory=person)(uidNumber>=20000))
   User Unique ID Property	Enter the attribute (such as objectGUID) that uniquely identifies each user. The value is case sensitive.
   User Name Property	Enter the attribute 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 sign in to 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. Use sAMAccountName for AD providers and cn for other LDAP providers. 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 user groups, and for authentication uses whatever other method you configured (see User authentication).

4. Click Show Preview to Continue, review the users and groups to import, and click Save.

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), you must synchronize manually.

At any given time in an active-active deployment, only one Tanium Server synchronizes with LDAP servers and records synchronization events in the LDAP logs.

1. From the Main menu, go to Administration > Configuration > LDAP/AD Sync Configurations.

   If the Sync Now button is enabled, proceed to the next step. If the button is disabled, sign in to the Tanium Console of the other Tanium Server to manually synchronize.

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. When synchronization is paused, authentication continues to work and existing RBAC assignments are preserved. After you finish upgrading or troubleshooting, you can resume synchronization.

1. From the Main menu, go to Administration > Configuration > LDAP/AD Sync Configurations.
2. Click Edit in the row for the LDAP server.
3. Select the Pause check box to pause LDAP synchronization or select Enable to resume synchronization.
4. Click Show Preview to Continue, review the affected users and user groups, and click Save.

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 the deleted configuration. Delete the configuration as follows when you no longer want that information saved in the Tanium Server:

1. From the Main menu, go to Administration > Configuration > LDAP/AD Sync Configurations.
2. Click Edit in the row for the LDAP server and click Delete at the top right.

Disabling an LDAP server configuration has the same effect as deleting it. See Set Status.