> For the complete documentation index, see [llms.txt](https://docs.pentaho.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pentaho.com/pdia-admin/9.3-administer/secure-the-pentaho-system/user-security/advanced-security-providers/ldap-security.md). # LDAP security To use Lightweight Directory Access Protocol (LDAP) for user security, you must switch from the default Pentaho security to LDAP, then you must configure LDAP. ## Switch to LDAP To connect to your LDAP server, you must import the certificate into the JRE's truststore/keystore used by the Pentaho Server (`java/lib/security/cacerts`). 1. From the User Console **Home** menu, click **Administration**, then select **Authentication** from the left. The **Authentication** interface appears. **Local - Use basic Pentaho Authentication** is selected by default. 2. Select the **External - Use LDAP / Active Directory server** option. ![User console authentication set to external](/files/TCQSXfwUzBUUYfprSt1a) The **LDAP Server Connection** fields populate with a default URL, user name, and password. 3. Change the **Server URL**, **User Name**, and **Password** as needed. 4. Click **Test Server Connection** to verify the connection to your LDAP server and to complete the set up. 5. Click the node to select the **Pentaho System Administrator** user and role to match your LDAP configuration, then click **OK**. **Note:** The Admin user is required for all system-related operations, including the creation of user folders. The Administrator Role is required for mapping a third-party admin role to the Pentaho admin role (Administrator). 6. Select your **LDAP Provider** from the drop-down menu. 7. Configure the LDAP connection as explained in [LDAP properties](broken://pages/FWW39FknmbQAhqnMFMMx). 8. Stop the Pentaho Server. See the **Install Pentaho Data Integration and Analytics** document for instructions on starting and stopping the Pentaho Server. 9. Delete the `server/pentaho-server/pentaho-solutions/system/karaf/caches` folder. 10. Restart the Pentaho Server and test the LDAP functionality. See the **Install Pentaho Data Integration and Analytics** document for instructions on starting and stopping the Pentaho Server. The Pentaho Server is now configured to authenticate users against your LDAP directory server. ## Manual configuration You must have a working LDAP server with an established configuration before continuing. Follow the instructions below to manually switch from Pentaho default security to LDAP security. 1. Stop the Pentaho Server. 2. Edit the `security.properties` file located in the `server/pentaho-server/pentaho-solutions/system` folder. 1. Change **provider=jackrabbit** to **provider=ldap** 2. Save and close the file. 3. Edit the `server/pentaho-server/pentaho-solutions/system/applicationContext-security-ldap.properties` file. 1. Modify the settings to match your LDAP configuration. ``` userSearch.searchBase=OU\=YourDomainCustomerCareUsers,DC\=YourDomainCustomerCare,DC\=com allAuthoritiesSearch.roleAttribute=cn allAuthoritiesSearch.searchBase=OU\=YourDomainCustomerCareGroups,DC\=YourDomainCustomerCare,DC\=com userSearch.searchFilter=(sAMAccountName\={0}) allUsernamesSearch.searchFilter=objectClass\=Person allAuthoritiesSearch.searchFilter= (objectClass\=group) providerType=ldapCustomConfiguration contextSource.userDn=youradminUser@YourDomaincustomercare.com populator.rolePrefix= allUsernamesSearch.searchBase=OU\=YourDomainCustomerCareUsers,DC\=YourDomainCustomerCare,DC\=com adminUser=CN\=YourAdminUserDN,OU\=OrlandoFL,OU\=NAMER,OU\=Support,OU\=YourDomainCustomerCareUsers,DC\=YourDomainCustomerCare,DC\=com adminRole=CN\=YourAdminRole,OU\=YourDomainCustomerCareGroups,DC\=YourDomainCustomerCare,DC\=com populator.groupSearchBase=OU\=YourDomainCustomerCareGroups,DC\=YourDomainCustomerCare,DC\=com populator.convertToUpperCase=false populator.searchSubtree=false allUsernamesSearch.usernameAttribute=sAMAccountName populator.groupRoleAttribute=cn contextSource.providerUrl=ldap\://10.100.7.17\:389 contextSource.password=******** populator.groupSearchFilter=(member\={0}) ``` 2. Save and close the file. 4. Edit the `server/pentaho-server/pentaho-solutions/system/repository.spring.properties` file. 1. Replace *admin* in the following line: `singleTenanatAdminUserName=admin` with the value of the **adminUser’s***sAMAccountName* as defined in the `applicationContext-security-ldap.properties` file. 2. Save and close the file. 5. Delete the following directory: `server/pentaho-server/pentaho-solutions/system/jackrabbit/repository` **CAUTION:** Do not delete the `repository.xml` file, which is also located in the following directory: `server/pentaho-server/pentaho-solutions/system/jackrabbit` 6. Delete the `server/pentaho-server/pentaho-solutions/system/karaf/caches` folder. 7. Restart the Pentaho Server and test the LDAP functionality. The Pentaho Server is now configured to authenticate users against your directory server. The [LDAP properties](broken://pages/FWW39FknmbQAhqnMFMMx) reference article contains supplemental information for LDAP values. ### Configure LDAP security caching If you are using Lightweight Directory Access Protocol (LDAP) security for your Pentaho environment, the Pentaho Data Integration and Analytics products actively communicate with your LDAP server. Configuring Pentaho to cache access to your LDAP server could improve access speed for this active communication. To configure Pentaho to cache LDAP security communication, you must update Pentaho spring security to initialize caching, associate the spring security caching with LDAP, then configure the properties of the cache. Perform the following steps to configure Pentaho for LDAP security caching. 1. Open the `pentaho-server/pentaho-solutions/system/applicationContext-spring-security-ldap.xml` file with a text editor. 2. Change `authenticator` to `cachingAuthenticator` and `populator` to `cachingPopulator` in the `ldapAuthenticationProvider` bean entry to initialize caching, as shown in the following example: ```xml ``` 3. Verify the following `constructor` entries are commented out in the `applicationContext-spring-security-ldap.xml` file: ```xml ``` 4. Uncomment the `constructor` entries or add them if they do not appear in the `applicationContext-spring-security-ldap.xml` file to associate the spring security caching with LDAP. 5. Save and close the `applicationContext-spring-security-ldap.xml` file. 6. Open the `pentaho-server/tomcat/webapp/WEB-INF/classes/ehcache.xml` file with a text editor. 7. Verify the following `cache` entries are commented out in the `pentaho-server/tomcat/webapp/WEB-INF/classes/ehcache.xml` file: ```xml ``` 8. Uncomment the `cache` entries or add them if they do not appear in the `pentaho-server/tomcat/webapp/WEB-INF/classes/ehcache.xml` file to configure the properties of the cache. 9. Save and close the `applicationContext-spring-security-ldap.xml` file. Your LDAP server connection to Pentaho Data Integration and Analytics is now cached. ### Use nested roles It is possible to nest user roles such that one role includes all of the users of another role. Doing this external to the core LDAP structure prevents recursive directory queries to find all parents of a given child role. Follow the directions below to modify the Pentaho Server to support nested roles for LDAP and MSAD authentication types. 1. Stop the Pentaho Server or service. ``` sh /usr/local/pentaho/server/pentaho-server/stop-pentaho.sh ``` 2. Open the `/pentaho/server/pentaho-server/pentaho-solutions/system/applicationContext-spring-security-ldap.xml` file with a text editor. 3. In the `populator` bean definition, replace **DefaultLdapAuthoritiesPopulator** with: **NestedLdapAuthoritiesPopulator** ```xml ``` 4. Save the file, then edit `/pentaho/server/pentaho-server/pentaho-solutions/system/applicationContext-pentaho-security-ldap.xml`. This and the next step are only necessary if the roles that serve as "parents" to nested roles cannot be returned by a traditional all authorities search. 5. Add an `extraRoles` bean to the list of transformers in the `ChainedTransformers` bean, and set properties for each parent role (represented by **example\_role** below). ```xml example_role ``` 6. Save the file, close your text editor, and start the Pentaho Server. ``` sh /usr/local/pentaho/server/pentaho-server/start-pentaho.sh ``` The Pentaho Server can now handle nested roles with LDAP or Active Directory authentication. ### LDAP properties You can configure LDAP values by editing the `/pentaho-solutions/system/applicationContext-security-ldap.properties` file in your Pentaho Server folder. #### Connection information (context) These entries define connections involving LDAP users (typically administrators) that can execute folder searches. | LDAP Property | Purpose | Example | | ------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | **context.Source.providerUrl** | LDAP connection URL | `contextSource.providerUrl=ldap://holly:389/DC=Valyant,DC=local` | | **contextSource.userDn** | Distinguished name of a user with read access to directory | `contextSource.userDn=CN= Administrator, CN=Users,DC=Valyant,DC=local` | | **contextSource.password** | Password for the specified user | `contextSource.password=secret` | #### Users These options control how the LDAP server is searched for user names that are entered in the Pentaho login dialog box. **Note:** The `{0}` token will be replaced by the user name from the login dialog box. **Note:** The example above defines `DC=Valyant,DC=local` in **contextSource.providerURL**. Given that definition, you would not need to repeat that in **userSearch.searchBase** below because it will be appended automatically to the defined value here. | LDAP Property | Purpose | Example | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | **userSearch.searchBase** | Base (by user name) for user searches | `userSearch.searchBase=CN=Users` | | **userSearch.searchFilter** | Filter (by user name) for user searches. The attribute you specify here must contain the value that you want your users to log into Pentaho with. Active Directory user names are represented by **sAMAccountName**; full names are represented by **displayName**. | `userSearch.searchFilter=(sAMAccountName={0})` | #### Populator The populator matches fully distinguished user names from **userSearch** to distinguished role names for roles those users belong to. **Note:** The `{0}` token will be replaced with the user DN found during a user search; the `{1}` token is replaced with the user name entered in the login screen. | LDAP Property | Purpose | Example | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | **populator.convertToUpperCase** | Indicates whether or not retrieved role names are converted to uppercase | `populator.convertToUpperCase=false` | | **populator.groupRoleAttribute** | The attribute to get role names from | `populator.groupRoleAttribute=cn` | | **populator.groupSearchBase** | Base (by user DN or user name) for role searches. | `populator.groupSearchBase=ou= Pentaho` | | **populator.groupSearchFilter** | The special nested group filter for Active Directory is shown in the example; this will not work with non-MSAD directory servers. | `populator.groupSearchFilter= (memberof:1.2.840.113556.1.4.1941: =({0}))` | | **populator.rolePrefix** | A prefix to add to the beginning of the role name found in the group role attribute; the value can be an empty string. | `populator.rolePrefix=` | | **populator.searchSubtree** | Indicates whether or not the search must include the current object and all children. If set to `false`, the search must include the current object only. | `populator.searchSubtree=true` | #### All authorities search These entries populate the Pentaho Server Access Control List (ACL) roles. These should be similar or identical to the populator entries. | LDAP Property | Purpose | Example | | -------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **allAuthoritiesSearch.roleAttribute** | The attribute used for role values | `allAuthoritiesSearch.roleAttribute=cn` | | **allAuthoritiesSearch.searchBase** | Base for "all roles" searches | `allAuthoritiesSearch.searchBase=ou= Pentaho` | | **allAuthoritiesSearch.searchFilter** | Filter for "all roles" searches. Active Directory requires that the**objectClass** value be set to group. | `allAuthoritiesSearch.searchFilter= (objectClass=group)` | #### All user name search These entries populate the Pentaho Server ACL users. | LDAP Property | Purpose | Example | | ----------------------------------------- | ---------------------------------- | ------------------------------------------------------- | | **allUsernamesSearch.username Attribute** | The attribute used for user values | `allUsernamesSearch.username Attribute= sAMAccountName` | | **allUsernamesSearch.searchBase** | Base for "all users" searches | `allUsernamesSearch.searchBase= CN=users` | | **allUsernamesSearch.searchFilter** | Filter for "all users" searches | `allUsernamesSearch.searchFilter= objectClass=person` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pentaho.com/pdia-admin/9.3-administer/secure-the-pentaho-system/user-security/advanced-security-providers/ldap-security.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.