Considerations When Connecting Your LDAP Server

Depending on your organization's requirements, it is recommended that you make decisions and gather information about the following:

• Determine whether you want to use connection pooling with your LDAP server. With connection pooling, you can reuse an open connection to the LDAP server for subsequent operations. The connection to the LDAP server remains open even when the connection is not processing any operations (also known as pooling). This setting can improve performance by removing the processing time required to open and close a connection to the LDAP server for each operation.

  See Determining Whether to Use Connection Pooling for background information on connection pooling,

• Determine whether you need to use database passthrough execution. In MicroStrategy, a single user name and password combination is frequently used to connect to and execute jobs against a database. However, you can choose to pass to the database a user's LDAP user name and password used to log in to MicroStrategy. The database is then accessed and jobs are executed using the LDAP user name and password. This allows each user logged in to MicroStrategy to execute jobs against the database using their unique user name and password which can be given a different set of privileges than other users.

  See Determining Whether to Enable Database Passthrough Execution with LDAP for additional information on database pass-through execution,

• Determine whether you want to import LDAP user and group information into the MicroStrategy metadata. A MicroStrategy group is created for each LDAP group.

  See Determining Whether to Import LDAP Users into MicroStrategy for information on the benefits and considerations for importing LDAP user and group information into MicroStrategy.

• Determine whether you want to automatically synchronize user and group information with the LDAP server. This ensures that if there are changes in the group membership for the users you have imported into MicroStrategy, or users who are linked to existing MicroStrategy accounts, the changes in the LDAP directory are applied in MicroStrategy when users log in, or on a schedule that you determine.

  See Determining Whether to Automatically Synchronize LDAP User and Group Information for the benefits and considerations of synchronizing user and group information,

• If you choose to import LDAP user and group information into the MicroStrategy metadata, determine the following:
  • Determine whether you want to import LDAP user and group information into the MicroStrategy metadata when users log in, and whether the information is synchronized every time users log in.
  • Determine whether you want to import LDAP user and group information into the MicroStrategy metadata in batches, and whether you want the information to be synchronized according to a schedule.
  • If you want to import LDAP user and group information in batches, you must provide search filters to import the users and the groups. For example, if your organization has 1,000 users in the LDAP directory, of whom 150 need to use MicroStrategy, you must provide a search filter that imports the 150 users into the MicroStrategy metadata. See Defining LDAP Search Filters to Verify and Import Users and Groups at Login for information on defining search filters,
  • If your LDAP organizational structure includes groups contained within groups, determine how many recursive groups to import when you import a user or group into MicroStrategy.

If you choose to import two nested groups when MicroStrategy imports LDAP groups, the groups associated with each user are imported, up to two levels above the user. In this case, for User 1, the groups Domestic and Marketing would be imported. For User 3, Developers and Employees would be imported.

• If you use a single sign-on (SSO) authentication system, such as Windows authentication or integrated authentication, determine whether you want to import the LDAP user and group information for users of your single sign-on system.
• Determine whether the following additional information is imported:
  • The users' email addresses. If you have a license for MicroStrategy Distribution Services, then when you import LDAP users, you can import these email addresses as contacts associated with those users.
  • The Trusted Authenticated Request User ID for a third party user. When a third party user logs in, this Trusted Authenticated Request User ID will be used to find the linked MicroStrategy user.
  • Additional LDAP attributes to import. For example, your LDAP directory may include an attribute called accountExpires, which contains information about when the users' accounts expire. The attributes in your LDAP directory depend on the LDAP server that you use, and your LDAP configuration.

    You can create security filters based on the LDAP attributes that you import. For example, you import the LDAP attribute countryName, create a security filter based on that LDAP attribute, and then you assign that security filter to all LDAP users. Now, when a user from Brazil views a report that breaks down sales revenue by country, they only see the sales data for Brazil.

Once you have collected the above information, navigate to Workstation to set up your LDAP connection.

Setting Up LDAP SDK Connectivity

From the perspective of your LDAP server, Intelligence Server is an LDAP client that uses clear text or encrypted SSL to connect to your LDAP server through the LDAP SDK.

The LDAP SDK is a set of connectivity file libraries (DLLs) that MicroStrategy uses to communicate with the LDAP server. For the latest set of certified and supported LDAP SDK files, refer to the Readme.

Intelligence Server requires that the version of the LDAP SDK you are using supports the following:

• LDAP v. 3
• SSL connections
• 64-bit architecture on Linux platforms

  For LDAP to work properly with Intelligence Server, the 64-bit LDAP libraries must be used.

1. The behavior between Intelligence Server and the LDAP SDK varies slightly depending on the LDAP SDK used. The Readme provides an overview of these behaviors.
2. The behavior between the LDAP SDK and the LDAP server is identical, no matter which LDAP SDK is used.

MicroStrategy recommends that you use the LDAP SDK vendor that corresponds to the operating system vendor on which Intelligence Server is running in your environment. Specific recommendations are listed in the Readme, with the latest set of certified and supported LDAP SDKs, references to MicroStrategy Tech Notes with version-specific details, and SDK download location information.

High-Level Steps to Install the LDAP SDK DLLs

1. Download the LDAP SDK DLLs onto the machine where Intelligence Server is installed.
2. Install the LDAP SDK.
3. Register the location of the LDAP SDK files as follows:
   • Windows environment: Add the path of the LDAP SDK libraries as a system environment variable so that Intelligence Server can locate them.
   • Linux environment: Modify the LDAP.sh file located in the env folder of your MicroStrategy installation to point to the location of the LDAP SDK libraries. The detailed procedure is described in To Add the LDAP SDK Path to the Environment Variable in UNIX below.
4. Restart Intelligence Server.

To Add the LDAP SDK Path to the Environment Variable in UNIX

This procedure assumes you have installed an LDAP SDK. For high-level steps to install an LDAP SDK, see High-Level Steps to Install the LDAP SDK DLLs.

1. In a Linux console window, browse to HOME_PATH where HOME_PATH is the specified home directory during installation. Browse to the folder /env in this path.
2. Add Write privileges to the LDAP.sh file by typing the command chmod u+w LDAP.sh and then pressing Enter.
3. Open the LDAP.sh file in a text editor and add the library path to the MSTR_LDAP_LIBRARY_PATH environment variable. For example: MSTR_LDAP_LIBRARY_PATH='/path/LDAP/library'

   It is recommended that you store all libraries in the same path. If you have several paths, you can add all paths to the MSTR_LDAP_LIBRARY_PATH environment variable and separate them by a colon (:). For example: MSTR_LDAP_LIBRARY_PATH='/path/LDAP/library:/path/LDAP/library2'

4. Remove Write privileges from the LDAP.sh file by typing the command chmod a-w LDAP.sh and then pressing Enter.
5. Restart Intelligence Server for your changes to take effect.

Defining LDAP Search Filters to Verify and Import Users and Groups at Login

You must provide Intelligence Server with some specific parameters so it can search effectively through your LDAP directory for user information.

When users attempt to log in to MicroStrategy, the Intelligence Server authenticates users by searching the LDAP directory for the user's Distinguished Name, which is a unique way to identify users within the LDAP directory structure.

To search effectively, Intelligence Server must know where to start its search. When setting up LDAP authentication, it is recommended that you indicate a search root Distinguished Name to establish the directory location from which Intelligence Server starts all user and group searches. If this search root is not set, Intelligence Server searches the entire LDAP directory.

Additionally, you can specify search filters, which help narrow down the users and groups to search.

The following sections describe the search settings that you can configure:

• Highest Level to Start an LDAP Search: Search Root provides examples of these parameters as well as additional details of each parameter and some LDAP server-specific notes.
• Finding Users: User Search Filters provides an overview of LDAP user search filters.
• Finding Groups: Group Search Filters provides an overview of LDAP group search filters.

Highest Level to Start an LDAP Search: Search Root

The following diagram and table present several examples of possible search roots based on how users might be organized within a company and within an LDAP directory.

The following table, based on the diagram above, provides common search scenarios for users to be imported into MicroStrategy. The search root is the root to be defined in MicroStrategy for the LDAP directory.

Scenario	Search Root
Include all users and groups from Operations	Operations
Include all users and groups from Operations, Consultants, and Sales	Sales
Include all users and groups from Operations, Consultants, and Technology	Departments (with an exclusion clause in the User/Group search filter to exclude users who belong to Marketing and Administration)
Include all users and groups from Technology and Operations but not Consultants.	Departments (with an exclusion clause in the User/Group search filter to exclude users who belong to Consultants.)

For some LDAP vendors, the search root cannot be the LDAP tree's root. For example, both Microsoft Active Directory and Sun ONE require a search to begin from the domain controller RDN (dc).

Finding Users: User Search Filters

User search filters allow MicroStrategy to efficiently search an LDAP directory to authenticate or import a user at login.

Once Intelligence Server locates the user in the LDAP directory, the search returns the user's Distinguished Name, and the password entered at user login is verified against the LDAP directory. Intelligence Server uses the authentication user to access, search in, and retrieve the information from the LDAP directory.

Using the user's Distinguished Name, Intelligence Server searches for the LDAP groups that the user is a member of. You must enter the group search filter parameters separately from the user search filter parameters (see Finding Groups: Group Search Filters).

User search filters are generally in the form (&(objectclass=LDAP_USER_OBJECT_CLASS)(LDAP_LOGIN_ATTR=#LDAP_LOGIN#)) where:

• LDAP_USER_OBJECT_CLASS indicates the object class of the LDAP users. For example, you can enter (&(objectclass=person)(cn=#LDAP_LOGIN#)).
• LDAP_LOGIN_ATTR indicates which LDAP attribute to use to store LDAP logins. For example, you can enter (&(objectclass=person)(cn=#LDAP_LOGIN#)).
• #LDAP_LOGIN# can be used in this filter to represent the LDAP user login.

Depending on your LDAP server vendor and your LDAP tree structure, you may need to try different attributes within the search filter syntax above. For example, (&(objectclass=person) (uniqueID=#LDAP_LOGIN#)), where uniqueID is the LDAP attribute name your company uses for authentication.

Finding Groups: Group Search Filters

Group search filters allow MicroStrategy to efficiently search an LDAP directory for the groups to which a user belongs. These filters can be configured in the Intelligence Server Configuration Editor, under the LDAP subject.

The group search filter is generally in one of the following forms (or the following forms may be combined, using a pipe | symbol to separate the forms):

• (&(objectclass=LDAP_GROUP_OBJECT_CLASS) (LDAP_MEMBER_LOGIN_ATTR=#LDAP_LOGIN#))
• (&(objectclass=LDAP_GROUP_OBJECT_CLASS) (LDAP_MEMBER_DN_ATTR=#LDAP_DN#))
• (&(objectclass=LDAP_GROUP_OBJECT_CLASS) (gidNumber=#LDAP_GIDNUMBER#))

The group search filter forms listed above have the following placeholders:

• LDAP_GROUP_OBJECT_CLASS indicates the object class of the LDAP groups. For example, you can enter (&(objectclass=groupOfNames)(member=#LDAP_DN#)).
• LDAP_MEMBER_[LOGIN or DN]_ATTR indicates which LDAP attribute of an LDAP group is used to store LDAP logins/DNs of the LDAP users. For example, you can enter (&(objectclass=groupOfNames)(member=#LDAP_DN#)).
• #LDAP_DN# can be used in this filter to represent the distinguished name of an LDAP user.
• #LDAP_LOGIN# can be used in this filter to represent an LDAP user's login.
• #LDAP_GIDNUMBER# can be used in this filter to represent the UNIX or Linux group ID number; this corresponds to the LDAP attribute gidNumber.

You can implement specific search patterns by adding additional criteria. For example, you may have 20 different groups of users, of which only five groups will be accessing and working in MicroStrategy. You can add additional criteria to the group search filter to import only those five groups.

Determining Whether to Use Connection Pooling

With connection pooling, you can reuse an open connection to the LDAP server for subsequent operations. The connection to the LDAP server remains open even when the connection is not processing any operations (also known as pooling). This setting can improve performance by removing the processing time required to open and close a connection to the LDAP server for each operation.

If you do not use connection pooling, the connection to an LDAP server is closed after each request. If requests are sent to the LDAP server infrequently, this can help reduce the use of network resources.

Connection Pooling with Clustered LDAP Servers

You may have multiple LDAP servers which work together as a cluster of LDAP servers.

If connection pooling is disabled, when a request to open an LDAP connection is made, the LDAP server with the lightest load at the time of the request is accessed. The operation against the LDAP directory can then be completed, and in an environment without connection pooling, the connection to the LDAP server is closed. When the next request to open an LDAP connection is made, the LDAP server with the least amount of load is determined again and chosen.

If you enable connection pooling for a clustered LDAP environment, the behavior is different than described above. On the first request to open an LDAP connection, the LDAP server with the least amount of load at the time of the request is accessed. However, the connection to the LDAP server is not closed because connection pooling is enabled. Therefore, instead of determining the LDAP server with the least amount of load during the next request to open an LDAP connection, the currently open connection is reused.

Determining Whether to Enable Database Passthrough Execution with LDAP

In MicroStrategy, a single user name and password combination is frequently used to connect to and execute jobs against a database. However, you can choose to pass a user's LDAP user name and password used to log in to MicroStrategy to the database. The database is then accessed and jobs are executed using the LDAP user name and password. This allows each user logged in to MicroStrategy to execute jobs against the database using their unique user name and password, which can be given a different set of privileges than other users.

Database passthrough execution is selected for each user individually. If a user's password is changed during a session in MicroStrategy, scheduled tasks may fail to run when using database passthrough execution.

To prevent this problem, schedule password changes for a time when users are unlikely to run scheduled reports. In the case of users using database passthrough execution who regularly run scheduled reports, inform them to reschedule all reports if their passwords have been changed.

Determining Whether to Import LDAP Users into MicroStrategy

To connect your LDAP users and groups to users and groups in MicroStrategy, you can either import the LDAP users and groups into the MicroStrategy metadata or you can create a link between users and groups in the LDAP directory and in MicroStrategy. Importing a user creates a new user in MicroStrategy based on an existing user in the LDAP directory. Linking a user connects an LDAP user's information to an existing user in MicroStrategy. You can also allow LDAP users to log in to the MicroStrategy system anonymously, without an associated MicroStrategy user. The benefits and considerations of each method are described in the table below.

Connection Type	Benefits	Considerations
Import LDAP users and groups	Users and groups are created in the metadata. Users and groups can be assigned additional privileges and permissions in MicroStrategy. Users have their own inboxes and personal folders in MicroStrategy.	In environments that have many LDAP users, importing can quickly fill the metadata with these users and their related information. Users and groups may not have the correct permissions and privileges when they are initially imported into MicroStrategy.
Allow anonymous or guest users	Users can log in immediately without having to create a new MicroStrategy user.	Privileges are limited to those for the Public/Guest group and LDAP Public group. Users' personal folders and Inboxes are deleted from the system after they log out.

The options for importing users into MicroStrategy are described in detail in the following sections:

• Importing LDAP Users and Groups into MicroStrategy
• Allowing Anonymous/Guest Users with LDAP Authentication

You can modify your import settings at any time, for example, if you choose not to import users initially, but want to import them at some point in the future.

Importing LDAP Users and Groups into MicroStrategy

You can choose to import LDAP users and groups at login, in a batch process, or a combination of the two. Imported users are automatically members of MicroStrategy's LDAP Users group, and are assigned the access control list (ACL) and privileges of that group. To assign different ACLs or privileges to a user, you can move the user to another MicroStrategy user group.

When an LDAP user is imported into MicroStrategy, you can also choose to import that user's LDAP groups. If a user belongs to more than one group, all the user's groups are imported and created in the metadata. Imported LDAP groups are created within MicroStrategy's LDAP Users folder and in MicroStrategy's User Manager.

LDAP users and LDAP groups are all created within the MicroStrategy LDAP Users group at the same level. While the LDAP relationship between a user and any associated groups exists in the MicroStrategy metadata, the relationship is not visually represented in Developer.

If you want a users' groups to be shown in MicroStrategy, you must manually move them into the appropriate groups.

The relationship between an imported LDAP user or group and the MicroStrategy user or group is maintained by a link in the MicroStrategy metadata, which is in the form of a Distinguished Name. A Distinguished Name (DN) is the unique identifier of an entry (in this case a user or group) in the LDAP directory.

The MicroStrategy user's Distinguished Name is different from the DN assigned for the authentication user. The authentication user's DN is the DN of the MicroStrategy account that is used to connect to the LDAP server and search the LDAP directory. The authentication user can be anyone who has search privileges in the LDAP server, and is generally the LDAP administrator.

Removing a user from the LDAP directory does not effect the user's presence in the MicroStrategy metadata. Deleted LDAP users are not automatically deleted from the MicroStrategy metadata during synchronization. You can revoke a user's privileges in MicroStrategy, or remove the user manually.

You cannot export users or groups from MicroStrategy to an LDAP directory.

Allowing Anonymous/Guest Users with LDAP Authentication

An LDAP anonymous login is an LDAP login with an empty login and/or empty password. A successful LDAP anonymous login is authorized with the privileges and access rights of LDAP Public and Public/Guest groups. The LDAP server must be configured to allow anonymous or guest authentication requests from MicroStrategy.

Because guest users are not present in the metadata, there are certain actions these users cannot perform in MicroStrategy, even if the associated privileges and permissions are explicitly assigned. Examples include most administrative actions.

When the user is logged in as an anonymous/guest user:

• The user does not have a History List, because the user is not physically present in the metadata.
• The user cannot create objects and cannot schedule reports.
• The User Connection monitor records the LDAP user's user name.
• Intelligence Server statistics record the session information under the user name LDAP USER.

Determining Whether to Automatically Synchronize LDAP User and Group Information

In any company's security model, steps must be taken to account for a changing group of employees. Adding new users and removing ones that are no longer with the company is straightforward. Accounting for changes in a user's name or group membership can prove more complicated. To ease this process, MicroStrategy supports user name/login and group synchronization with the information contained within an LDAP directory.

If you choose to have MicroStrategy automatically synchronize LDAP users and groups, any LDAP group changes that have occurred within the LDAP server will be applied within MicroStrategy the next time an LDAP user logs in to MicroStrategy. This keeps the LDAP directory and the MicroStrategy metadata in synchronization.

By synchronizing users and groups between your LDAP server and MicroStrategy, you can update the imported LDAP users and groups in the MicroStrategy metadata with the following modifications:

• User synchronization: User details such as user name in MicroStrategy are updated with the latest definitions in the LDAP directory.
• Group synchronization: Group details such as group name in MicroStrategy are updated with the latest definitions in the LDAP directory.

When synchronizing LDAP users and groups in MicroStrategy, you should be aware of the following circumstances:

• If an LDAP user or group has been given new membership to a group that has not been imported or linked to a group in MicroStrategy and import options are turned off, the group cannot be imported into MicroStrategy and thus cannot apply its permissions in MicroStrategy.

  For example, User1 is a member of Group1 in the LDAP directory, and both have been imported into MicroStrategy. Then, in the LDAP directory, User1 is removed from Group1 and given membership to Group2. However, Group2 is not imported or linked to a MicroStrategy group. Upon synchronization, in MicroStrategy, User1 is removed from Group1, and is recognized as a member of Group2. However, any permissions for Group2 are not applied for the user until Group2 is imported or linked to a MicroStrategy group. In the interim, User1 is given the privileges and permissions of the LDAP Users group.

• When users and groups are deleted from the LDAP directory, the corresponding MicroStrategy users and groups that have been imported from the LDAP directory remain in the MicroStrategy metadata. You can revoke users' and groups' privileges in MicroStrategy and remove the users and groups manually.
• Regardless of your synchronization settings, if a user's password is modified in the LDAP directory, a user must log in to MicroStrategy with the new password. LDAP passwords are not stored in the MicroStrategy metadata. MicroStrategy uses the credentials provided by the user to search for and validate the user in the LDAP directory.

Consider a user named Joe Doe who belongs to a particular group, Sales, when he is imported into MicroStrategy. Later, he is moved to a different group, Marketing, in the LDAP directory. The LDAP user Joe Doe and LDAP groups Sales and Marketing have been imported into MicroStrategy. Finally, the user name for Joe Doe is changed to Joseph Doe, and the group name for Marketing is changed to MarketingLDAP.

The following table describes what happens with users and groups in MicroStrategy if users, groups, or both users and groups are synchronized.

Sync Users?	Sync Groups?	User Name After Synchronization	Group Name After Synchronization
No	No	Joe Doe	Marketing
No	Yes	Joe Doe	MarketingLDAP
Yes	No	Joseph Doe	Marketing
Yes	Yes	Joseph Doe	MarketingLDAP