Skip to main content
Pentaho Documentation

MSAD security

Parent article

To use Microsoft Active Directory (MSAD) for user security, you must switch from the default Pentaho security to MSAD, then you must configure MSAD.

Switch to MS Active Directory

Perform the following steps to switch to MS Active Directory:


  1. From 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.

    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 server and to complete the set up.

  5. Click the Browse buttons to select the Pentaho System Administrator user and role to match your configuration. Click OK.

    The text box auto-populates with the selected values.
  6. For MSAD, choose Custom Configuration.

  7. For Users:

    1. Search Base by entering the path where your users are located.

    2. Search Filter by entering in the attribute that users will log in with.

  8. For Roles:

    1. For Role Attributes, enter the attribute that is used for roles/groups.

    2. For Role Search Filter, enter in the ObjectClass that defines that these are roles or groups.

    3. For Role Search Base, enter in the path where your roles or groups are located.

    4. Click Test.

  9. For Populator:

    1. For Group Role Attribute, enter in the Attribute that is used for groups.

    2. For Group Search Base, enter in the path to where your groups are located.

    3. Set the Group Search Filter to:


      You can set a Role Prefix if you need one to filter by.

  10. Click Test, then click Save.

  11. Shut down the Pentaho Server.

  12. Locate these three files and modify the settings as noted.

    1. Navigate to the pentaho-solutions/system directory, and open the file with a text editor. Find these two sections and edit them to match your Active Directory settings, then save and close the file.

    2. In the pentaho-solutions/system directory, open the pentaho.xml file with a text editor. Find this section and edit it to match your Active Directory settings, then save and close the file.

      <acl-voter> <admin-role>Administrator</admin-role> </acl-voter>
    3. Navigate to the pentaho-solutions/system/data-access directory, and open the settings.xml file with a text editor. Find these two sections and edit them to match your Active Directory settings, then save and close the file.

  13. You may be using monitoring functions on your server, such as SNMP. Whether you are using monitoring or not, you will need to perform the following configuration file changes:

    • If you are using monitoring, do the following:
      1. In a text editor, open the pentaho.jms.cfg file in the server/pentaho-server/pentaho-solutions/system/karaf/etc folder.
      2. Change the username and password to match the values previously defined in this task.
      3. Save and close the file.
    • If you are not using monitoring, do the following:
      1. In the text editor, open the org.apache.karaf.features.cfg file in the server/pentaho-server/pentaho-solutions/system/karaf/etc folder
      2. Remove the following line: pentaho-monitoring-to-snmp
      3. Save and close the file.
      4. Delete the contents of all the sub-folders in the server/pentaho-server/pentaho-solutions/system/karaf/caches/default/ folder
  14. Restart the Pentaho Server and test the MSAD functionality.


The Pentaho Server is now configured to authenticate users against your MSAD server.

Manual configuration

After you have switched Pentaho to authenticate against Active Directory, you can proceed with configuring MSAD.


MSAD allows you to uniquely specify users in two ways (Kerberos notation or Windows domain notation), in addition to the standard Distinguished Name (DN) method. If the standard DN is not working, try one of the following methods. Each of the following examples is shown in the context of the userDn property of the Spring Security DefaultSpringSecurityContextSource bean.

NoteThe examples in this section use DefaultSpringSecurityContextSource. You may need to use the same notation (Kerberos or Windows domain) in all your DN patterns.

The following code block is an example of the Kerberos notation for



The following code block is an example of the Windows domain notation for MYCOMPANY\pentahoadmin:




If more than one Active Directory instance is serving folder information, it may be necessary to enable referral, shown in the following code block. This is accomplished by modifying the DefaultSpringSecurityContextSource bean:

<bean id="contextSource" class="">
    <constructor-arg value="${contextSource.providerUrl}"/>
    <property name="userDn" value="${contextSource.userDn}"/>
    <property name="password" value="${contextSource.password}"/>
    <property name="referral" value="follow" />

Nested groups

You can pull nested groups for Pentaho within Microsoft Active Directory.

In the Populator Group Search Filter, enter the following filter for MSAD nested groups:


This filter will search down the entire tree of nested groups.

NoteThis attribute only works for Microsoft Active Directory configurations.

See also

The LDAP Properties reference article contains supplemental information for LDAP values.

Learn more

Manage users and roles in the Pentaho User Console (PUC).

Learn more