Skip to main content

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at


Hitachi Vantara Lumada and 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. Select Custom Configuration.

  7. For Users:

    1. For Search Base, enter the path where your users are located.

    2. For Search Filter, enter the attribute that users 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.

  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 for the attribute to use:

      NoteThe following example works only for Microsoft Active Directory configurations.
      You can search down the entire tree to pull only MSAD nested groups by entering the following filter:
  10. Click Test.

    The LDAP Populator Test dialog box opens.
  11. Enter the LDAP/MSAD User Name and User DN, then click OK.

    You can see the groups and roles that the user is a member of in Microsoft Active Directory.
  12. Click Close to close the results window, and then click Save.

  13. Stop the Pentaho Server.

  14. Delete the server/pentaho-server/pentaho-solutions/system/karaf/caches folder.

  15. Restart the Pentaho Server.


The Pentaho Server is now configured to authenticate users against your MSAD server. You can log in to the User Console using your Active Directory credentials.

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