User security

You can choose from two different user security options: Pentaho Security or advanced security providers (such as LDAP, Single Sign-On, or Microsoft Active Directory).

For the Pentaho User Console (PUC), your predefined users and roles can be used if you are already using a security provider such as Lightweight Directory Access Protocol (LDAP), Microsoft Active Directory (MSAD), or Single Sign-On (SSO). Pentaho Data Integration (PDI) can also be configured to use your implementation of these providers or Kerberos to authenticate users and authorize data access.

These articles guide you through the process of configuring third-party security frameworks for the Pentaho Server.

Note: If you are evaluating Pentaho or have a production environment with fewer than a hundred users, you may decide to use Pentaho default security. See the Install Pentaho Data Integration and Analytics document for details.

Before you can implement advanced security, you must have installed and configured the Pentaho Server. You should have administrative-level knowledge of the security provider you want to use, details about your user community, and a plan for the user roles to be used in PDI. You should also know how to use the command line to issue commands for Microsoft Windows or Linux.

PUC can be used to perform most security tasks pertaining to the console. For some cases with PDI, you will need a text editor to modify text files. Some of these security tasks also require that you work on the actual machine where the Pentaho Server is installed.

All of the tasks that use the Administration page in PUC require that you log on to the User Console with the Pentaho administrator user name and password.

For information on the two different user security options you can choose from, see the following sections:

• Pentaho Server security

• Advanced security providers

Pentaho Server security

Pentaho Security is a quick way to configure security. It works well without a security provider. It also works well for communities under 100 users.

The Pentaho User Console (PUC) lets you define security by users and roles. The Pentaho Server controls which users and roles can access web resources and repository content.

Hiding user folders in PUC and PDI

One way you can centralize and secure content created by users is to hide individual users' Home folders in the Pentaho User Console (PUC) or in the PDI client. For example, if your organization implements multi-tenancy, you may want to prevent individual users from viewing their Home folders for security reasons.

You can configure your server to hide the Home folders by default for both PUC and PDI. When you create new users in your system, their Home folders will be hidden. If a user needs to create, edit, or save content, you can provide the Write permission in a folder that is visible to that user. Those users can then view the folder and access the content. You can add the Write permission in PUC and in the PDI client.

These tasks assume you are a Pentaho Administrator.

Perform the following steps to edit the system.properties file so that when you create new users, their Home folders will be hidden by default.

1. Stop the Pentaho Server.

   See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server.

2. Navigate to /Pentaho/server/pentaho-server/pentaho-solutions/system and open system.properties in a text editor.

3. Locate the hideUserHomeFolderOnCreate property. By default, this property is set to false.

4. Change the setting to true:

   hideUserHomeFolderOnCreate=true

5. Save and close system.properties.

6. Start the Pentaho Server.

   See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server.

Now when you add a new user in either PUC or the PDI client, that user's Home folder is hidden by default.

Next steps:

• To override this setting for a specific user, see Override the hidden Home folder for a user.

• To stop hiding Home folders by default when you create new users, see Stop hiding the Home folder for new users.

• If a user with a hidden Home folder needs to create, edit, or save content, grant Write permission using PUC or the PDI client.

Override the hidden Home folder for a user

Follow these steps to override the hidden Home folder for a specific user.

1. Log in to PUC with your Pentaho Administrator credentials.

2. Go to Browse Files.

3. Select the user’s Home folder.

4. In the Properties dialog box, clear Hidden.

The user's Home folder is now visible.

Stop hiding the Home folder for new users

Follow these steps to stop creating users with their Home folders hidden by default.

1. Stop the Pentaho Server.

2. Navigate to /Pentaho/server/pentaho-server/pentaho-solutions/system and open system.properties in a text editor.

3. Locate the hideUserHomeFolderOnCreate property.

4. Change the setting to false:

   hideUserHomeFolderOnCreate=false

5. Save and close system.properties.

6. Start the Pentaho Server.

When you add a new user in either PUC or the PDI client, that user's Home folder is now visible.

See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server.

Assign the Write permission to a user folder in PUC

In PUC you can assign Write permission in a public folder to a user whose Home folder is hidden. When this permission is granted, the user can save and edit content they create using PUC.

1. Log in to PUC with your Pentaho Administrator credentials.

2. Select the Public folder, and then select or create the folder you want the user to access.

3. Assign Write permission:

   1. Click Properties > Share and clear Inherits folder permissions.

   2. Click Add and select the user.

   3. Select Write for the user.

   4. Click OK to save your changes.

The user can now save content in the assigned folder.

Assign the Write permission to a user folder in the PDI client

In the PDI client you can assign the Write permission in a public folder to a user whose Home folder is hidden. When this permission is granted, the user can save and edit content they create using the PDI client.

1. Start the PDI client.

   See the Pentaho Data Integration document for instructions on starting the PDI client.

2. Connect to a Pentaho Repository with your Pentaho Administrator credentials.

3. Open the Repository Explorer: Tools > Repository > Explore.

4. On the Browse tab, select the Public folder, and then select or create the folder you want the user to access.

5. Select the folder and grant Write permission:

   1. On the Access Control panel, clear Inherit access control from parent.

   2. Click the Plus sign to add a user.

   3. Select the user and move them to Selected. Click OK.

   4. Select the user in User/Role and select Write.

   5. Click Apply, then click OK.

6. Close the Repository Explorer.

The user can now save content in the assigned folder.

Restrict or share files and folders

Access to files or folders can be refined using the Pentaho User Console. Each file or folder can either use the default permissions or you can tailor them for specific users and roles.

Prior to performing this task, determine whether you will use the default Pentaho roles or create custom users and roles. You must also have successfully set up your security back end.

1. Log in to the User Console using the administrator role.

2. From Browse Files, choose the folder you want to set permissions on from the Folders pane.

   If you want to set permissions on a specific file in that folder, highlight the file in the Files pane.

3. Click Properties in the Actions pane.

   The Properties window appears.

4. On the Share tab, select the Role that you want to set permissions for. Then clear Inherits folder permissions.

   Permissions for [Role] becomes available.

5. Select permissions for that role, then click OK.

The permissions are set for that file or folder and are associated with the selected role.

For additional security in multi-tenancy organizations, you can hide individual users' Home folders. See Hiding user folders in PUC and PDI.

Pass authentication credentials in URL parameters

This section is currently a placeholder. Add the approved guidance for passing credentials in URL parameters.

Remove Pentaho Server security

You can remove Pentaho Server security by enabling anonymous access or by modifying data source management.

Enable anonymous access

You can bypass built-in security on the Pentaho Server by giving all permissions to anonymous users. An "anonymousUser" is any user, either existing or newly created, that you specify as an all-permissions, no-login user, and to whom you grant the Anonymous role.

This procedure grants full Pentaho Server access to the Anonymous role. It also removes the login requirement.

All of the files you will be using are located in /pentaho/server/pentaho-server/pentaho-solutions/system. Before you begin, stop the Pentaho Server.

Modify application security

Perform the following steps to modify application security:

1. Open applicationContext-spring-security.xml in a text editor.

2. Make sure a default anonymous role is defined. Match your bean definition and property value to the following example:

   <bean id="anonymousProcessingFilter" class="org.springframework.security.web.authentication.AnonymousAuthenticationFilter">
     <constructor-arg value="foobar" />
     <constructor-arg value="anonymousUser" />
     <constructor-arg>
       <list>
         <bean class="org.springframework.security.core.authority.SimpleGrantedAuthority">
           <constructor-arg value="Anonymous" />
         </bean>
       </list>
     </constructor-arg>
   </bean>

   Note: These next steps permit PDI client tools to publish to the Pentaho Server without a user name and password.

3. Find these two beans in the same file:

   • filterInvocationInterceptor

   • filterInvocationInterceptorForWS

4. Locate the securityMetadataSource property in the beans and match the contents to the following example:

   <bean id="filterInvocationInterceptor" class="org.springframework.security.web.access.intercept.FilterSecurityInterceptor">
     <property name="authenticationManager" ref="authenticationManager" />
     <property name="accessDecisionManager" ref="httpRequestAccessDecisionManager" />
     <property name="securityMetadataSource">
       <sec:filter-security-metadata-source request-matcher="ciRegex" use-expressions="false">
         <!-- all patterns have Anonymous role access -->
         <sec:intercept-url pattern="\A/.*\Z" access="Anonymous,Authenticated" />
       </sec:filter-security-metadata-source>
     </property>
   </bean>

5. Save and close applicationContext-spring-security.xml.

Modify Pentaho configuration

Perform the following steps to modify the Pentaho configuration:

1. Open pentaho.xml in a text editor.

2. Find the anonymous-authentication section under pentaho-system, and define the anonymous user and role as shown in the following example:

   <pentaho-system>
   <!-- omitted -->
     <anonymous-authentication>
       <anonymous-user>anonymousUser</anonymous-user>
       <anonymous-role>Anonymous</anonymous-role>
     </anonymous-authentication>
   <!-- omitted -->
   </pentaho-system>

3. Save and close pentaho.xml.

Modify repository properties

Perform the following steps to modify the repository properties:

1. Open repository-spring.properties in a text editor.

2. Find singleTenantAdminAuthorityName and replace the value with Anonymous.

3. Find singleTenantAdminUserName and replace the value with your anonymous user name.

4. Save and close the file.

Map the appropriate role

Perform the following steps to map roles:

1. Find all references to the bean id="Mondrian-UserRoleMapper". Make sure the only active mapper is the one shown in the following example:

   <bean id="Mondrian-UserRoleMapper" name="Mondrian-SampleUserSession-UserRoleMapper" class="org.pentaho.platform.plugin.action.mondrian.mapper.MondrianUserSessionUserRoleListMapper" scope="singleton">
     <property name="sessionProperty" value="MondrianUserRoles" />
   </bean>

2. If you changed pentahoObjects.spring.xml, save and close the file.

You have now worked around Pentaho Server security. If you use the relational metadata database model, refer to Remove Security from Metadata Domain Repository for the next steps.

Remove security from data source management

This procedure changes your data source management so that an anonymous user can access it. These steps are necessary to completely remove security from the Pentaho Server. However, this procedure does not remove all security. If you need to remove all security, enable anonymous access as described above.

Perform the following steps to completely remove security from the Pentaho Server:

1. Stop the Pentaho Server (if needed).

2. Open /pentaho/server/pentaho-server/pentaho-solutions/system/data-access/settings.xml in a text editor.

   1. Find <data-access-roles>Administrator</data-access-roles> and change Administrator to Anonymous.

   2. Find <data-access-view-roles>Authenticated,Administrator</data-access-view-roles> and change Authenticated,Administrator to Anonymous.

   3. Find <data-access-view-users>suzy</data-access-view-users> and change suzy to anonymousUser.

   4. Find <data-access-datasource-solution-storage>admin</data-access-datasource-solution-storage> and change admin to anonymousUser.

3. Save and close the file.

4. Restart the Pentaho Server.

Advanced security providers

Use these options when the default Pentaho security provider is not enough.

This section consolidates configuration guidance for common advanced providers and related hardening tasks.

Spring (authentication providers) security

Spring security is a cascading security implementation that moves down through a list of authentication providers. If the first provider fails to authenticate, then the application looks to the next provider in the list to authenticate. If you are using multiple AuthenticationProviders at the same time, you must add each security provider to the applicationContext.spring.security.xml file. You must also add provider name values to the activeUserDetailsService beans in the pentahoObjects.spring.xml file. We recommend that you make a backup of these files before altering them.

ApplicationContext

Perform the following steps to add security providers to the ApplicationContext:

1. Stop the Pentaho Server and the solution repository.

2. Navigate to the /pentaho-solutions/system directory and open the applicationContext-­spring-security.xml file with any text editor.

3. Locate the following authenticationManager bean tags:

   <bean id="authenticationManager" class="org.springframework.security.authentication.ProviderManager">
       <constructor-arg>
         <util:list>
         </util:list>
       <constructor-arg>
   </bean>

4. Add your AuthenticationProvider information below the list tag. The example below adds the jackrabbitprovider:

   <pen:bean class="org.springframework.security.authentication.AuthenticationProvider">
       <pen:attributes>
       <pen:attr key="providerName" value="jackrabbit"/>
       </pen:attributes>
   </pen:bean>

5. Then, add providerName information right beneath the jackrabbit information. LDAP is used in this example. You can add as many providers as needed:

   <pen:bean class="org.springframework.security.authentication.AuthenticationProvider">
       <pen:attributes>
       <pen:attr key="providerName" value="ldap"/>
       </pen:attributes>
   </pen:bean>

6. After you are finished adding AuthenticationProvider information, save and close the file.

The following code block is a more complete example of the authenticationManager portion of the applicationContext-­spring-security.xml file:

<!-- ======================== AUTHENTICATION ======================= -->
<bean id="authenticationManager" class="org.springframework.security.authentication.ProviderManager">
    <constructor-arg>
      <util:list>
        <pen:bean class="org.springframework.security.authentication.AuthenticationProvider">
            <pen:attributes>
              <pen:attr key="providerName" value="jackrabbit"/>
            </pen:attributes>
        </pen:bean>
        <pen:bean class="org.springframework.security.authentication.AuthenticationProvider">
            <pen:attributes>
              <pen:attr key="providerName" value="ldap"/>
            </pen:attributes>
        </pen:bean>
      </util:list>
    </constructor-arg>
    <property name="authenticationEventPublisher">
      <ref bean="defaultAuthenticationEventPublisher" />
    </property>
</bean>

Add the Jackrabbit provider

The Jackrabbit provider is required in the activeUserDetailsService bean, even if you configure another provider. Perform the following steps to add the Jackrabbit provider to the activeUserDetailsService bean:

1. Navigate to the /pentaho-solutions/system directory and open the pentahoObjects.spring.xml file with any text editor.

2. Locate the activeUserDetailsService bean tag:

   <!-- Reference to a bean in one of the applicationContext-pentaho-security-*.xml; selected by configured provider-->
     <pen:bean id="activeUserDetailsService" class="org.springframework.security.core.userdetails.UserDetailsService">
        <pen:attributes>
           <pen:attr key="providerName" value="${security.provider}"/>
        </pen:attributes>
     </pen:bean>

3. Replace ${security.provider} with the jackrabbit provider value. For example:

   <pen:attr key="providerName" value="jackrabbit"/>

Add another provider

Perform the following steps to add more provider names:

1. Duplicate the activeUserDetailsService bean shown in Substep 2 of the Add the Jackrabbit Provider section.

2. Rename the bean ID, for example: bean id="activeUserDetailsService2"

3. Replace the jackrabbit value with the new provider value. For example:

   <pen:attr key="providerName" value="ldap"/>

4. Locate the following UserDetailsService bean tags:

   <!-- A composite bean composed of the activeUserDetailsService and systemUserDetailsService -->
     <bean id="UserDetailsService" class="org.pentaho.platform.plugin.services.security.userrole.ChainedUserDetailsService">
       <constructor-arg>
           <list>
             <ref bean="activeUserDetailsService"/>
             <ref bean="systemUserDetailsService"/>
           </list>
       </constructor-arg>
     </bean>

5. Add your bean ID to the list element. For example:

   <!-- A composite bean composed of the activeUserDetailsService and systemUserDetailsService -->
     <bean id="UserDetailsService" class="org.pentaho.platform.plugin.services.security.userrole.ChainedUserDetailsService">
        <constructor-arg>
            <list>
               <ref bean="activeUserDetailsService"/>
               <ref bean="activeUserDetailsService2"/>
               <ref bean="systemUserDetailsService"/>
            </list>
        </constructor-arg>
    </bean>

6. Restart the Pentaho Server and solution repository.

Configure authentication

To configure Web resource authentication to correspond with your user roles in the Pentaho Server, perform the following instructions.

1. Ensure that the Pentaho Server is not currently running; if it is, run the stop-pentaho script.

2. Open a Terminal or Command Prompt window and navigate to the .../pentaho-solutions/system/ directory.

3. Edit the applicationContext-spring-security.xml file with a text editor.

4. Find and examine the following property: <property name="objectDefinitionSource">

5. Modify the regex patterns to include your roles.

   The objectDefinitionSource property associates URL patterns with roles. RoleVoter specifies that if any role on the right hand side of the equals sign is granted to the user, the user may view any page that matches that URL pattern. The default roles in this file are not required. You can replace, delete, or change them in any way that suits you.

You should now have coarse-grained permissions established for user roles.

Authentication provider examples

Provider Name	Short Description	Application Context for AuthenticationProvider
Jackrabbit	Default Pentaho security.	applicationContext-spring-security-jackrabbit.xml
LDAP	LDAP security	applicationContext-spring-security-ldap.xml
JDBC	JDBC security allows you to use your own security tables	applicationContext-spring-security-jdbc.xml
Memory	In memory authentication	applicationContext-spring-security-memory.xml

JDBC security

You must have existing security tables in a relational database in order to proceed with this task.

Switch to JDBC security

Follow the instructions below to switch from Pentaho default security to JDBC security, which will allow you to use your own security tables.

If you want to use encrypted passwords for JDBC security as explained in the Install Pentaho Data Integration and Analytics document, use the encrypted password for all password values.

If you are using the Pentaho Server and choose to switch to a JDBC security shared object, you will no longer be able to use the role and user administration settings in the Administration portion of the User Console.

1. Stop the Pentaho Server.

2. Open /pentaho-solutions/system/security.properties with a text editor.

3. Change the value of the provide property to jdbc.

4. Set up the connection to the database that holds the users and authorities:

   1. Open the /pentaho-solutions/system/applicationContext-spring-security-jdbc.properties file with a text editor. Find the following two lines and change the jdbcDriver and URL to the appropriate values.

      datasource.driver.classname=org.hsqldb.jdbcDriver

      datasource.url=jdbc:hsqldb:hsql://localhost:9002/userdb

   2. Change the user name and password by editing the following two items:

      \datasource.username=sa, datasource.password=

   3. Set the validation.query by editing its row. Examples of different validation queries are shown in the file.

      datasource.validation.query=SELECT 1 FROM INFORMATION_SCHEMA.SYSTEM_USERS

   4. Set the wait timeout, max pool, and max idle by editing the following three items to change the defaults.

      datasource.pool.max.wait=-1, datasource.pool.max.active=8, datasource.max.idle=4

   5. Save the file and close the editor.

5. If needed, modify the user queries that pull information about users and authorities:

   1. Open /pentaho-solutions/system/applicationContext-spring-security-jdbc.xml with a text editor.

   2. Find the following line and change the SQL query returning the user and roles for which the user is a member to the appropriate statement:

      <value>
          <[SELECT username, authority FROM GRANTED_AUTHORITIES WHERE username = ? ORDER BY authority]>
      </value>

   3. Find the following line and change the SQL query that determines the user, password, and whether they can log in to the appropriate statement:

      <value>
          <[SELECT username, password, enabled FROM USERS WHERE username = ? ORDER BY username]>
      </value>

6. If needed, modify the following role queries that pull information about users and authorities.

   1. Open the /pentaho-solutions/system/applicationContext-pentaho-security-jdbc.xml file with a text editor.

   2. Find the following line and change the SQL query showing the roles for security on objects to the appropriate statement:

      <value>
          <[SELECT distinct(authority) as authority FROM AUTHORITIES ORDER BY authority]>
      </value>

   3. Find the following line and change the SQL query that returns all users in a specific role to the appropriate statement:

      <value>
          <[SELECT distinct(username) as username FROM GRANTED_AUTHORITIES where authority = ? ORDER BY username]>
      </value>

   4. Find the following line and change the SQL query that returns all users by order to the appropriate statement:

      <value>
          <[SELECT distinct(username) as username FROM USERS ORDER BY username]>
      </value>

   5. Save the file and close the editor.

7. Update the default Pentaho admin user on the system to map to your JDBC admin user:

   1. Open the /pentaho-solutions/system/repository.spring.properties file with a text editor.

   2. Find the following lines and change the default value from <admin> to map to your <admin username> in your JDBC system:

      singleTenantAdminUserName=<Admin User>

   3. Save the file and close the editor.

8. To fully map the JDBC's admin role to other configuration files, specify the name of the administrator role for your JDBC authentication database in the applicationContext-pentaho-security-jdbc.xml file.

   1. Open the /pentaho-solutions/system/applicationContext-pentaho-security-jdbc.xml file with a text editor.

   2. Find the following lines and change the entry key to the key assigned to the administrator role in your JDBC authentication database:

      <!-- map ldap role to pentaho security role -->
      <util:map id="jdbcRoleMap">
         <entry key="Admin" value="Administrator"/>
      </util:map>

   3. Save and close the file.

9. Start the Pentaho Server.

   The server is configured to authenticate users against the specified database.

Manual LDAP/JDBC hybrid configuration

You might need to create a hybrid between an LDAP security solution and a JDBC security table for role definitions. This is common in situations where LDAP roles can't be redefined for Pentaho Server use. These instructions help you switch the Pentaho Server's authentication back-end from the Pentaho data access object to an LDAP/JDBC hybrid.

Before you begin configuring LDAP and JDBC for the Pentaho Server, you will need to verify a couple of things.

Task	Description
Verify Successful Default Pentaho Security Deployment	Make sure your Pentaho Server has been successfully deployed using default Pentaho Security (Jackrabbit authentication).
Configure Pentaho for LDAP Authentication	Verify that your Pentaho system is configured for LDAP authentication.
Verify Database with User Roles	Verify that you have a database populated with your user roles.

After you finish the prerequisite tasks above, there are a few things that you need to do in order set up a hybrid LDAP/JDBC configuration successfully. The table structure described here is for example purposes.

These sections will guide you through the remaining steps of this process:

• Step 1: Create user/authorities database tables

• Step 2: Set up inserts for tables

• Step 3: Update JDBC security queries

• Step 4: Enable JDBC authorization beans

• Step 5: Verify LDAP/JDBC configuration

Step 1: Create user/authorities database tables

You will need to create a few database tables in order to get LDAP and JDBC to work together.

1. Create a table called USERS and populate it with the following values:

   Column Name	Column Type	Column Description
   username	VARCHAR(50)	The User name.
   password	VARCHAR(50)	This column value is not considered in a hybrid LDAP/JDBC solution.
   enables	VARCHAR(100)	Set to true if user is enables; false if not enabled.

2. Create a table called AUTHORITIES and populate it with the following values:

   Column Name	Column Type	Column Description
   authority	VARCHAR(50)	The Pentaho role, such as Administrator, Report Author, etc.

3. Create a table called GRANTED_AUTHORITIES and populate it with the following values:

   Column Name	Column Type	Column Description
   username	VARCHAR(50)	The User name.
   authority	VARCHAR(5)	Associated Pentaho role.

Step 2: Update user and role values for tables

Next, you will need to perform a series of updates for the tables you just created. Users will be authenticated using their Active Directory password.

Note: Some syntax examples are provided here for you to customize with your own values.

1. Update usernames and passwords in the USERS table as shown:

   INSERT INTO USERS VALUES('username','Password1','1',NULL)

2. Update roles in the AUTHORITIES table as shown:

   INSERT INTO AUTHORITIES VALUES('DBPentAdmins','Super User')
   INSERT INTO AUTHORITIES VALUES('DBPentHR','HR Users')
   INSERT INTO AUTHORITIES VALUES('DBPentFinance','Finance Users')
   INSERT INTO AUTHORITIES VALUES('DBPentUsers','User has not logged in')

3. Update users with their associated roles in the GRANTED_AUTHORITIES table as shown:

   INSERT INTO GRANTED_AUTHORITIES VALUES('admin','DBPentAdmins')
   INSERT INTO GRANTED_AUTHORITIES VALUES('admin','DBPentUsers')
   INSERT INTO GRANTED_AUTHORITIES VALUES('tiffany','DBPentUsers')
   INSERT INTO GRANTED_AUTHORITIES VALUES('tiffany','DBPentFinance')
   INSERT INTO GRANTED_AUTHORITIES VALUES('pat','DBPentUsers')
   INSERT INTO GRANTED_AUTHORITIES VALUES('pat','DBPentHR')

Step 3: Update JDBC security queries

You might have different names for your created tables than are provided in these examples. If so, after you have updated your user and role values in your tables, you need to update a couple of queries and other items to match your system names.

1. Locate the /pentaho-server/pentaho-solutions/system directory and update these two files with the noted information.

   1. applicationContext-pentaho-security-jdbc.xml

   2. applicationContext-spring-security-jdbc.xml

2. Update the query, as well as field names such as username, password, and enabled that are expected by spring framework security. Be sure to use an alias if you are using different field names.

   SELECT userid as username, 'password' as password, 'enabled' as enabled FROM USERS_ROLES WHERE userid= ? ORDER BY userid

3. Stop the Pentaho Server.

4. Copy your respective database JDBC driver to the tomcat/lib directory.

   See the JDBC drivers reference in the Try Pentaho Data Integration and Analytics document for information on supported drivers.

Step 4: Enable JDBC Authorization beans

Last, you will need to enable some JDBC Authorization beans.

Update security properties file

Perform the following steps to update the security.properties file:

1. Stop the Pentaho Server.

2. Locate the pentaho-server/pentaho-solutions/system directory.

3. Open the security.properties file with any text editor.

   1. Locate the LDAP property bean and add the role provider as shown here:

      provider=ldap
      role.provider=jdbc

4. Save and close the file.

Update spring security-jdbc properties file

Perform the following steps to update the applicationContext-spring-security-jdbc.properties file:

1. Open the applicationContext-spring-security-jdbc.properties file.

2. Add or update this database information with your system values.

   Database Setting	Description
   datasource.driver.classname	Fully-qualified Java class name of the JDBC driver you are using.
   datasource.url	Connection URL to be passed to your JDBC driver to establish a connection.
   datasource.username	Connection username to be passed to our JDBC driver to establish a connection
   datasource.password	Connection password to be passed to our JDBC driver to establish a connection
   datasource.validation.query	SQL query that is used to validate connections from this pool before returning them to the caller. This query must be a SELECT statement that returns at least one row.
   datasource.pool.max.wait	Maximum number of milliseconds that the pool will wait when there are no available connections. For a connection to be returned before throwing an exception, or <= 0, to wait indefinitely. Default is -1.
   datasource.pool.max.active	Maximum number of active connections that can be allocated from this pool at the same time, or negative for no limit. Default value is 8.
   datasource.max.idle	Maximum number of connections that can remain idle in the pool, without extra ones being destroyed, or negative for no limit. Default value is 8.
   datasource.min.idle	Minimum number of active connections that can remain idle in the pool, without extra ones being created when the evictor runs, or 0 to create none. Default value is 0.

3. Save and close the file.

Update the pentaho-security-jdbc file

Perform the following steps to update the applicationContext-pentaho-security-jdbc.xml file:

1. Open the applicationContext-pentaho-security-jdbc.xml file.

2. Change the entry key to show your admin role for your database.

From:	<util:map id="jdbcRoleMap"> <entry key="Admin" value="Administrator"/> </util:map>
To:	<util:map id="jdbcRoleMap"> <entry key="DBPentAdmins" value="Administrator"/> </util:map>

1. Save and close the file.

Update the pentahoObjects spring file

Perform the following steps to update the pentahoObjects.spring.xml file:

1. Open the pentahoObjects.spring.xml file.

2. Change these beans as shown, then save and close the file.

From:	<pen:bean id="activeUserRoleListService" class="org.pentaho.platform.api.engine.IUserRoleListService"> <pen:attributes> <pen:attr key="providerName" value="${security.provider}"/> </pen:attributes> </pen:bean>
To:	<pen:bean id="activeUserRoleListService" class="org.pentaho.platform.api.engine.IUserRoleListService"> <pen:attributes> <pen:attr key="providerName" value="jdbc"/> </pen:attributes> </pen:bean>

Update spring security-ldap file

Perform the following steps to update the applicationContext-spring-security-ldap.xml file:

1. Open the applicationContext-spring-security-ldap.xml file.

2. Remove the bean for org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator and replace it with this one:

   <bean id="populator" class="org.springframework.security.ldap.authentication.UserDetailsServiceLdapAuthoritiesPopulator">
   <constructor-arg ref="jdbcUserDetailsService" />
   </bean>

3. Save and close the file.

Update the repository spring properties file

Perform the following steps to update the repository.spring.properties file:

1. Open the repository.spring.properties file.

2. Locate the value for the singleTenantAdminUserName and make sure that it points to the correct admin user for your system.

3. Restart the Pentaho Server.

Step 5: Verify LDAP/JDBC Configuration

Pentaho should now be successfully configured with hybrid authentication. Users are authenticated through LDAP, and the roles are authorized through JDBC. You can verify this by logging into PUC as an admin and checking in the Users & Roles tab in the Administration perspective.

SAML security

Security Assertion Markup Language (SAML) is a web­based authentication mechanism that relies on the browser as an agent to broker the authentication flow. There are numerous third-party Identity Providers (IdP) available, such as OpenSSO, OKTA, and SSOCircle.com.

The following diagram is a high-level sketch of a SAML identification structure containing a third-party Identity Provider (IdP), an End-User Browser (the Pentaho User Console), and a Service Provider (the Pentaho Server):

See the guidelines for SAML on the Support Portal for help in setting up an example instance of SAML security. If you want to extend your SAML set up further, please work with with your Customer Success Manager or contact Support.

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

   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.

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
      [email protected]
      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 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:

   <bean id="ldapAuthenticationProvider" class="org.pentaho.platform.plugin.services.security.userrole.ldap.DefaultLdapAuthenticationProvider">
     <constructor-arg>
       <ref bean="cachingAuthenticator" />
     </constructor-arg>
     <constructor-arg>
       <ref bean="cachingPopulator" />
     </constructor-arg>
     <constructor-arg>
       <ref bean="ldapRoleMapper" />
     </constructor-arg>
   </bean>

3. Verify the following constructor entries are commented out in the applicationContext-spring-security-ldap.xml file:

   <bean id="cachingAuthenticator" class="org.pentaho.platform.plugin.services.security.userrole.ldap.PentahoCachingLdapAuthenticator">
   	<constructor-arg ref="authenticator" />
   	<property name="cacheRegionName" value="ldapAuthenticatorCache" />
   	<property name="passwordHashMethod" value="SHA-256" />
   </bean>
   
   <bean id="cachingPopulator" class="org.pentaho.platform.plugin.services.security.userrole.ldap.PentahoCachingLdapAuthoritiesPopulator">
   	<constructor-arg ref="populator" />
   	<property name="cacheRegionName" value="ldapPopulatorCache" />
   </bean>

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:

   <cache 
   name="ldapPopulatorCache" 
   maxEntriesLocalHeap="2000" 
   eternal="false" 
   overflowToDisk="false" 
   timeToIdleSeconds="300" 
   timeToLiveSeconds="600" 
   diskPersistent="false"/>
   
   <cache 
   name="ldapAuthenticatorCache" 
   maxEntriesLocalHeap="2000" 
   eternal="false" 
   overflowToDisk="false" 
   timeToIdleSeconds="300" 
   timeToLiveSeconds="600" 
   diskPersistent="false"/>

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.

Chain LDAP servers

You can chain multiple LDAP servers together for authentication and authorization of your users.

You may want to implement chained servers if you:

• Have one or more LDAP Servers for your organization

• Need a failover LDAP server

• Have multiple domains within an LDAP Server

To chain your LDAP servers, you must configure your setup by editing existing files, creating configuration files, and then finalize the process. This process requires the following steps:

• Step 1: Configure the authentication manager

• Step 2: Configure the your users and roles

• Step 3: Create a spring security application context file

• Step 4: Create Pentaho security application context file

• Step 5: Create a properties file for the ldapProvider

• Step 6: Apply your new files

• Step 7: Complete the configuration process

Before you begin, you must stop the server if it is running before proceeding. You must also use the same providerName in all the configuration files below.

Step 1: Configure the authentication manager

Perform the following steps to configure the authentication manager:

1. Navigate to the server/pentaho-server/pentaho-solutions/system/ directory.

2. Open the applicationContext-spring-security.xml file in any text editor.

3. Locate the authenticationManager bean tags and add the following AuthenticationProvider code in the list tag, replacing ldapProviderName with your providerName:

   <pen:bean class="org.springframework.security.authentication.AuthenticationProvider">
   	<pen:attributes>
   		<pen:attr key="providerName" value="<ldapProviderName>"/>
   	</pen:attributes>
   </pen:bean>

   After adding the above bean, your authentication manager code will look like the following example code where ldapProviderName is replaced with with your providerName:

   <bean id="authenticationManager" class="org.springframework.security.authentication.ProviderManager">
   	<constructor-arg>
   		<util:list>
   			<pen:bean class="org.springframework.security.authentication.AuthenticationProvider"/>
   			<ref bean="anonymousAuthenticationProvider"/>
   			<pen:bean class="org.springframework.security.authentication.AuthenticationProvider">
   				<pen:attributes>
   					<pen:attr key="providerName" value="<ldapProviderName>"/>
   				</pen:attributes>
   			</pen:bean>
   		</util:list>
   	</constructor-arg>
   	<property name="authenticationEventPublisher" ref="defaultAuthenticationEventPublisher"/>
   </bean>

4. Save and close the file.

Step 2: Configure the your users and roles

Perform the following steps to configure the your users and roles.

1. Navigate to the server/pentaho-server/pentaho-solutions/system directory.

2. Open the pentahoObjects.spring.xml file in any text editor.

3. Locate the activeUserRoleListService definition beans tag and add the following UserRoleListService beans beneath the activeUserRoleListService ending tag, replacing ldapProviderName with your providerName as shown in the following example:

   <pen:bean id="<ldapProviderName>_activeUserRoleListService" class="org.pentaho.platform.api.engine.IUserRoleListService">
   	<pen:attributes>
   		<pen:attr key="providerName" value="<ldapProviderName>"/>
   		</pen:attributes>
   </pen:bean>

4. Locate the IUserRoleListService definition beans tag and add the newly added bean ID after the list tag with ref bean attribute.

5. Add the following property after the constructor tag:

   <property name="strategy">
   	<value type="org.pentaho.platform.plugin.services.security.userrole.CompositeUserRoleListService.STRATEGY">ADDITIVE</value>
   </property>

   After adding the above reference bean and property, your IUserRoleListService code will look like the following example code where ldapProviderName is replaced with with your providerName:

   <!-- A composite bean composed of the activeUserRoleListService and systemUserRoleListService -->
   <bean id="IUserRoleListService" class="org.pentaho.platform.plugin.services.security.userrole.CompositeUserRoleListService">
   	<constructor-arg>
   		<list>
   			<ref bean="<ldapProviderName>_activeUserRoleListService"/>
   			<ref bean="activeUserRoleListService"/>
   			<ref bean="systemUserRoleListService"/>
   		</list>
   	</constructor-arg>
   	<property name="strategy">
   		<value type="org.pentaho.platform.plugin.services.security.userrole.CompositeUserRoleListService.STRATEGY">ADDITIVE</value>
   	</property>
   	<pen:publish as-type="INTERFACES">
   		<pen:attributes>
   			<pen:attr key="priority" value="50"/>
   		</pen:attributes>
   	</pen:publish>
   </bean>

6. Locate the activeUserDetailsService bean tags and add the following ldapProviderName_activeUserDetailsService after the activeUserDetailsService end tag, replacing ldapProviderName with your providerName:

   <pen:bean id="<ldapProviderName>_activeUserDetailsService" class="org.springframework.security.core.userdetails.UserDetailsService">
                 <pen:attributes>
                          <pen:attr key="providerName" value="<ldapProviderName>"/>
                  </pen:attributes>
   </pen:bean>

7. Locate the UserDetailsService definition beans tag and add the newly added bean ID after the list tag with reference bean attribute.

   After adding the above reference bean, your UserDetailsService code will look like the following example code where ldapProviderName is replaced with with your providerName

   <!-- A composite bean composed of the activeUserDetailsService and systemUserDetailsService -->
   <bean id="UserDetailsService" class="org.pentaho.platform.plugin.services.security.userrole.ChainedUserDetailsService">
   	<constructor-arg>
   		<list>
   			<ref bean="<ldapProviderName>_activeUserDetailsService"/>
   			<ref bean="activeUserDetailsService"/>
   			<ref bean="systemUserDetailsService"/>
   		</list>
   	</constructor-arg>
   </bean>

8. Save and close the file.

Step 3: Create a spring security application context file

Perform the following steps to create a spring security application context file:

1. Create a LDAP Spring security applicationContext file using the following example code, replacing all occurrences of ldapProviderName with your providerName:

   <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:pen="http://www.pentaho.com/schema/pentaho-system" xmlns:util="http://www.springframework.org/schema/util" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd
   	http://www.pentaho.com/schema/pentaho-system http://www.pentaho.com/schema/pentaho-system.xsd
   	http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-4.3.xsd" default-lazy-init="true">
   	<bean id="<ldapProviderName>_ldapAuthenticationProvider" class="org.pentaho.platform.plugin.services.security.userrole.ldap.DefaultLdapAuthenticationProvider">
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_authenticator"/>
   		</constructor-arg>
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_populator"/>
   		</constructor-arg>
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_ldapRoleMapper"/>
   		</constructor-arg>
   	</bean>
   	<!-- Interceptor which changes the thread context classloader to the class' current classloader.-->
   	<bean id="<ldapProviderName>_classloaderSwitcherInterceptor" class="org.pentaho.platform.plugin.services.security.userrole.ClassloaderSwitcherInterceptor">
    </bean>
   	<bean id="<ldapProviderName>_ldapAuthenticationProviderProxy" class="org.springframework.aop.framework.ProxyFactoryBean">
   		<property name="proxyInterfaces" value="org.springframework.security.authentication.AuthenticationProvider"/>
   		<property name="target" ref="<ldapProviderName>_ldapAuthenticationProvider"/>
   		<property name="interceptorNames">
   			<list>
   				<value><ldapProviderName>_classloaderSwitcherInterceptor</value>
   				</list>
   			</property>
   			<pen:publish as-type="org.springframework.security.authentication.AuthenticationProvider">
   				<pen:attributes>
   					<pen:attr key="providerName" value="<ldapProviderName>"/>
   				</pen:attributes>
   			</pen:publish>
   		</bean>
   	<bean id="<ldapProviderName>_authenticator" class="org.springframework.security.ldap.authentication.BindAuthenticator">
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_contextSource"/>
   		</constructor-arg>
   		<property name="userSearch">
   			<ref bean="<ldapProviderName>_userSearch"/>
   		</property>
   	</bean>
   <!-- Uncomment below and update ldapAuthenticationProvider to enable local caching of LDAP credentials; reduces LDAP traffic when running numerous spoon/pan/kitchen jobs against a repository. -->
   <!--
   <bean id="cachingAuthenticator"
    class="org.pentaho.platform.plugin.services.security.userrole.ldap.PentahoCachingLdapAuthenticator">
    <constructor-arg ref="authenticator" />
    <property name="cacheRegionName" value="ldapAuthenticatorCache" />
    <property name="passwordHashMethod" value="SHA-256" />
   </bean>
   -->
   	<bean id="<ldapProviderName>_contextSource" class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
   		<constructor-arg value="${<ldapProviderName>.contextSource.providerUrl}"/>
   		<property name="userDn" value="${<ldapProviderName>.contextSource.userDn}"/>
   		<property name="password" value="${<ldapProviderName>.contextSource.password}"/>
   	</bean>
   	<!-- be sure to escape ampersands -->
   	<bean id="<ldapProviderName>_userSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
   		<constructor-arg index="0" value="${<ldapProviderName>.userSearch.searchBase}"/>
   		<constructor-arg index="1" value="${<ldapProviderName>.userSearch.searchFilter}"/>
   		<constructor-arg index="2">
   			<ref bean="<ldapProviderName>_contextSource"/>
   		</constructor-arg>
   	</bean>
   	<!-- be sure to escape ampersands -->
   	<bean id="<ldapProviderName>_populator" class="org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator">
   		<constructor-arg index="0">
   			<ref bean="<ldapProviderName>_contextSource"/>
   		</constructor-arg>
   		<constructor-arg index="1" value="${<ldapProviderName>.populator.groupSearchBase}"/>
   		<property name="groupRoleAttribute" value="${<ldapProviderName>.populator.groupRoleAttribute}"/>
   		<!-- {0} will be replaced with user DN; {1} will be replaced with username -->
   		<property name="groupSearchFilter" value="${<ldapProviderName>.populator.groupSearchFilter}"/>
   		<property name="rolePrefix" value="${<ldapProviderName>.populator.rolePrefix}"/>
   		<property name="convertToUpperCase" value="${<ldapProviderName>.populator.convertToUpperCase}"/>
   		<property name="searchSubtree" value="${<ldapProviderName>.populator.searchSubtree}"/>
   		<property name="defaultRole" ref="defaultRole"/>
   	</bean>
   <!-- Uncomment below and update ldapAuthenticationProvider to enable local caching of LDAP credentials; reduces LDAP
   traffic when running numerous spoon/pan/kitchen jobs against a repository. -->
   <!--
    <bean id="cachingPopulator"
    class="org.pentaho.platform.plugin.services.security.userrole.ldap.PentahoCachingLdapAuthoritiesPopulator">
    <constructor-arg ref="populator" />
    <property name="cacheRegionName" value="ldapPopulatorCache" />
    </bean> -->
   	<bean id="<ldapProviderName>_ldapUserDetailsService0" class="org.pentaho.platform.plugin.services.security.userrole.ldap.DefaultLdapUserDetailsService">
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_userSearch"/>
   		</constructor-arg>
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_populator"/>
   		</constructor-arg>
   		<constructor-arg ref="tenantedUserNameUtils"/>
   	</bean>
   	<bean id="<ldapProviderName>_ldapUserDetailsServiceProxy" class="org.springframework.aop.framework.ProxyFactoryBean">
   		<property name="proxyInterfaces" value="org.springframework.security.core.userdetails.UserDetailsService"/>
   		<property name="target" ref="<ldapProviderName>_ldapUserDetailsService0"/>
   		<property name="interceptorNames">
   			<list>
   				<value><ldapProviderName>_classloaderSwitcherInterceptor</value>
   			</list>
   			</property>
   	</bean>
   		<!-- map LDAP role to pentaho security role -->
   		<util:map id="<ldapProviderName>_ldapRoleMap">
   			<entry key="${<ldapProviderName>.adminRole}" value="Administrator"/>
   		</util:map>
   	<bean id="<ldapProviderName>_ldapRoleMapper" class="org.pentaho.platform.engine.security.DefaultLdapRoleMapper">
   		<constructor-arg>
   			<ref bean="<ldapProviderName>_ldapRoleMap"/>
   		</constructor-arg>
   		<constructor-arg value="${<ldapProviderName>.allAuthoritiesSearch.roleAttribute}"/>
   	</bean>
   	<bean id="<ldapProviderName>_ldapUserDetailsService" class="org.pentaho.platform.engine.security.DefaultRoleUserDetailsServiceDecorator">
   		<property name="userDetailsService" ref="<ldapProviderName>_ldapUserDetailsServiceProxy"/>
   		<property name="defaultRole" ref="defaultRole"/>
   		<property name="roleMapper" ref="<ldapProviderName>_ldapRoleMapper"/>
   		<pen:publish as-type="INTERFACES">
   			<pen:attributes>
   				<pen:attr key="providerName" value="<ldapProviderName>"/>
   			</pen:attributes>
   		</pen:publish>
   	</bean>
   	<bean class="org.pentaho.platform.config.SolutionPropertiesFileConfiguration">
   		<constructor-arg value="<ldapProviderName>"/>
   		<constructor-arg value="applicationContext-security-<ldapProviderName>.properties"/>
   		<pen:publish as-type="INTERFACES"/>
   	</bean>
   </beans>

2. Save the filename as applicationContext-spring-security-<ldapProviderName>.xml where ldapProviderName is your providerName in the /pentaho-solutions/system directory.

Step 4: Create Pentaho security application context file

Perform the following steps to create a Pentaho security application context file:

1. Copy the following example code into a file, replacing all the occurrences of ldapProviderName with your providerName:

   <?xml version="1.0" encoding="UTF-8"?>
   <!--+
   	| Application context containing LDAP UserRoleListService
   	| implementation.
   	+-->
   <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   
          xmlns:pen="http://www.pentaho.com/schema/pentaho-system"
          xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd http://www.pentaho.com/schema/pentaho-system http://www.pentaho.com/schema/pentaho-system.xsd" default-lazy-init="true">
   
     <!-- be sure to escape ampersands -->
     <bean id="ldapProviderName_allUsernamesSearch"
           class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.GenericLdapSearch">
       <constructor-arg index="0" ref="ldapProviderName_contextSource" />
       <constructor-arg index="1">
         <bean
             class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.LdapSearchParamsFactoryImpl">
           <constructor-arg index="0" value="${ldapProviderName.allUsernamesSearch.searchBase}" />
           <constructor-arg index="1" value="${ldapProviderName.allUsernamesSearch.searchFilter}" />
         </bean>
       </constructor-arg>
       <constructor-arg index="2">
         <bean
             class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.SearchResultToAttrValueList">
           <constructor-arg index="0" value="${ldapProviderName.allUsernamesSearch.usernameAttribute}" />
         </bean>
       </constructor-arg>
     </bean>
   
     <!-- be sure to escape ampersands -->
     <bean id="ldapProviderName_allAuthoritiesSearch"
           class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.GenericLdapSearch">
       <constructor-arg index="0" ref="ldapProviderName_contextSource" />
       <constructor-arg index="1">
         <bean
             class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.LdapSearchParamsFactoryImpl">
           <constructor-arg index="0" value="${ldapProviderName.allAuthoritiesSearch.searchBase}" />
           <constructor-arg index="1"
                            value="${ldapProviderName.allAuthoritiesSearch.searchFilter}" />
         </bean>
       </constructor-arg>
       <constructor-arg index="2">
         <bean
             class="org.apache.commons.collections.functors.ChainedTransformer">
           <constructor-arg index="0">
             <list>
               <bean
                   class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.SearchResultToAttrValueList">
                 <constructor-arg index="0" value="${ldapProviderName.allAuthoritiesSearch.roleAttribute}" />
               </bean>
               <bean
                   class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.StringToGrantedAuthority">
                 <property name="rolePrefix" value="${ldapProviderName.populator.rolePrefix}" />
                 <property name="convertToUpperCase" value="${ldapProviderName.populator.convertToUpperCase}" />
               </bean>
             </list>
           </constructor-arg>
         </bean>
       </constructor-arg>
     </bean>
   
     <!-- not currently used -->
     <bean id="ldapProviderName_usernamesInRoleSearch"
           class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.NoOpLdapSearch">
     </bean>
   
     <bean id="ldapProviderName_ldapUserRoleListService"
           class="org.pentaho.platform.plugin.services.security.userrole.ldap.DefaultLdapUserRoleListService">
       <constructor-arg index="0" >
         <bean class="org.pentaho.platform.engine.security.DefaultUsernameComparator" />
       </constructor-arg>
       <constructor-arg index="1" >
         <bean class="org.pentaho.platform.engine.security.DefaultRoleComparator" />
       </constructor-arg>
       <constructor-arg index="2">
         <ref bean="ldapProviderName_ldapRoleMapper" />
       </constructor-arg>
       <property name="allAuthoritiesSearch">
         <ref bean="ldapProviderName_allAuthoritiesSearch" />
       </property>
       <property name="allUsernamesSearch">
         <ref bean="ldapProviderName_allUsernamesSearch" />
       </property>
       <property name="userDetailsService">
       	<pen:bean class="org.springframework.security.core.userdetails.UserDetailsService"/>
       </property>
       <property name="usernamesInRoleSearch">
         <ref bean="ldapProviderName_usernamesInRoleSearch" />
       </property>
       <property name="roleNameUtils" >
         <ref bean="tenantedRoleNameUtils" />
       </property>
       <property name="userNameUtils">
         <ref bean="tenantedUserNameUtils" />
       </property>
       <property name="systemRoles" >
         <ref bean="singleTenantSystemAuthorities" />
       </property>
       <property name="extraRoles" ref="extraRoles" />
       <pen:publish as-type="INTERFACES">
         <pen:attributes>
           <pen:attr key="providerName" value="ldapProviderName"/>
         </pen:attributes>
       </pen:publish>    
     </bean>
   </beans>

2. Save the file as applicationContext-pentaho-security-<ldapProviderName>.xml in the pentaho-solutions/system directory where ldapProviderName is your providerName.

Step 5: Create a properties file for the ldapProvider

Perform the following steps to create an ldapProvider properties file:

1. Copy the following example code into any text editor and save it in the server/pentaho-server/pentaho-solutions/system directory as the applicationContext-security-<ldapProviderName>.properties file where ldapProviderName is your providerName.

   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
   [email protected]
   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. Modify any variables that pertain to your environment.

3. Save and close the file.

Step 6: Apply your new files

Perform the following steps to apply the newly created files:

1. Navigate to the server/pentaho-server/pentaho-solutions/system directory.

2. Open the pentaho-spring-beans.xml file with any text editor.

3. Search for the <import resource="applicationContext-pentaho-security-ldap.xml" /> element and add the following lines after it:

   <import resource="applicationContext-spring-security-ldapProviderName.xml" />  
   <import resource="applicationContext-pentaho-security-<ldapProviderName>.xml" />

4. Save and close the file.

Step 7: Complete the configuration process

Perform the following step to complete the configuration process:

1. Delete the server/pentaho-server/pentaho-solutions/system/jackrabbit/repository directory.

2. Delete the server/pentaho-server/pentaho-solutions/system/karaf/caches directory.

3. Restart the server.

   CAUTION:

   Do not delete the repository.xml file in the server/pentaho-server/pentaho-solutions/system/jackrabbit directory.

If you want to configure another LDAP configuration, repeat all the steps using a different providerName.

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

   <bean id="populator" class="org.pentaho.platform.plugin.services.security.userrole.ldap.NestedLdapAuthoritiesPopulator">

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).

   <bean id="allAuthoritiesSearch" class="org.pentaho.platform.plugin.services​.security.userrole.ldap.search.GenericLdapSearch">
       <!-- omitted -->
       <constructor-arg index="2">
           <bean class="org.apache.commons.collections.functors.ChainedTransformer">
               <constructor-arg index="0">
                   <list>
                       <bean class="org.pentaho.platform.plugin.services.security.​userrole.ldap.transform.SearchResultToAttrValueList">
                           <!-- omitted -->
                       </bean>
                       <bean class="org.pentaho.platform.plugin.services.security.userrole.​ldap.transform.ExtraRoles">
                           <property name="extraRoles">
                               <set>
                                   <value>example_role</value>
                               </set>
                           </property>
                       </bean>
                       <bean class="org.pentaho.platform.plugin.services.security.​userrole.ldap.transform.StringToGrantedAuthority">
                           <!-- omitted -->
                       </bean>
                   </list>
               </constructor-arg>
           </bean>
       </constructor-arg>
   </bean>

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

MSAD security

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

Notes:

• The LDAP properties reference article contains supplemental information for LDAP values.

• See the Pentaho Business Analytics document for information on managing users and roles in the Pentaho User Console (PUC).

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.

      CN=Users,DC=MyDomain,DC=com

   2. For Search Filter, enter the attribute that users log in with.

      (sAMAccountName={0})

8. For Roles:

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

      CN

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

      (objectClass=group)

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

      OU=groups,DC=MyDOmain,DC=com

9. For Populator:

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

      CN

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

      OU=groups,DC=MyDOmain,DC=com

   3. Set the Group Search Filter for the attribute to use:

      (member={0})

      Note: The 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:

      populator.groupSearchFilter=(member:1.2.840.113556.1.4.1941:={0})

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.

See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server.

Manual configuration

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

Binding

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.

Note: The 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 [email protected]:

File: applicationContext-security-ldap.properties

contextSource.providerUrl=ldap\://mycompany\:389
[email protected]
contextSource.password=omitte

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

File: applicationContext-security-ldap.properties

contextSource.providerUrl=ldap\://mycompany\:389
contextSource.userDn=MYCOMPANY\pentahoadmin
contextSource.password=omitted

Referrals

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="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
    <constructor-arg value="${contextSource.providerUrl}"/>
    <property name="userDn" value="${contextSource.userDn}"/>
    <property name="password" value="${contextSource.password}"/>
    <property name="referral" value="follow" />
</bean>

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:

populator.groupSearchFilter=(member:1.2.840.113556.1.4.1941:={0})

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

Note: This attribute only works for Microsoft Active Directory configurations.

AES security

As a default security, Kettle obfuscation is applied to your passwords. You can increase password security by changing it to use an Advanced Encryption Standard (AES) implementation that can be applied to all passwords, including those in database connections, transformation steps, and job entries.

You can choose from two types of AES security implementations: Electronic Code Book (ECB) and Cipher Block Chaining (CBC). See https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation to learn more about these AES implementations.

Note: If you switch password security methods, all existing passwords will also use the new method. You may also have to update passwords and re-save Pentaho Data Integration (PDI) transformations (KTRs) and jobs (KJBs) to enforce any AES implementation changes.

Create an AES key file

You need to establish an encryption key for any AES implementation you might use.

Perform the following steps to specify your encryption key by creating a key text file to contain it:

1. Create a text file that contains a key phrase, such as !@ExampleKey#123.

   Leading and trailing white spaces are ignored. The encryption key in the key file must be 16 bytes in length, !@ExampleKey#123 or 1234567891234567 for example.

2. Save and close the file.

   Note: Safeguard the key file. If the key file becomes corrupted or lost, passwords cannot be decrypted.

You must specify the path to your key file in the kettle.properties file.

Specify AES variables in the properties file

Perform the following steps to set AES-specific variables in the kettle.properties file for the PDI client (Spoon), the Pentaho Server, and any clusters.

1. Open the kettle.properties file for the PDI client (Spoon). By default, the kettle.properties file is in the user’s home directory.

2. Add the following variables and values.

Variable	Description	Value
KETTLE_PASSWORD_ENCODER_PLUGIN (Required)	Indicates the type of plugin used.	Use AES for either the ECB or CBC encryption implementation. Specifying AES defaults to the ECB encryption implementation. Note: If you are changing the plugin type from AES to AES2, you must reset your connection passwords and save the updated transformations (KTRs) and jobs (KJBs).
KETTLE_AES_KEY_FILE (Required)	Indicates the path to the key file.	Specify the path to the key file. Relative paths are resolved against the Kettle working directory, not the location of the kettle.properties file. c:/securearea/keyfile.txt for example.
KETTLE_AES_KETTLE_PASSWORD_HANDLING (Optional)	Maintain backwards compatibility by setting this variable to Decode.	Use DECODE. If this variable is not set, Kettle encoded passwords are not decoded. If this variable is set to anything other than DECODE, a runtime exception will be thrown with a message similar to the following example: A Kettle encoded password was used: 'Encrypted 2be98afc86aa79f8da510a171da9fa6d4'

1. Save and close the kettle.properties file.

2. Stop and restart the PDI client (Spoon).

3. Repeat this process for other kettle.properties files on the Pentaho Server and cluster nodes.

You must specify the AES implementation used by updating the kettle-password-encoder-plugins.xml file.

Configure Pentaho for AES encryption

You must configure Pentaho Data Integration (PDI) and Tomcat for AES encryption, and specify which AES implementation to use.

Perform the following steps to configure PDI or Tomcat:

1. Navigate to the kettle-password-encoder-plugins.xml file in one of the following directories and open it with any text editor:

   • PDI: data-integration/classes

   • Tomcat: server/pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes

2. Add or uncomment the following code depending on which AES implementation (ECB or CBC) you want to use:

   • For ECB:

     <password-encoder-plugin id="AES2">
          <description>AES Password Encoder</description>
          <classname>org.pentaho.support.encryption.AESTwoWayPasswordEncoder</classname>
          <default-encoder>true</default-encoder>
          <mode>ECB</mode>
     </password-encoder-plugin>

   • For CBC:

     <password-encoder-plugin id="AES2">
          <description>AES Password Encoder</description>
          <classname>org.pentaho.support.encryption.AESTwoWayPasswordEncoder</classname>
          <default-encoder>true</default-encoder>
          <mode>CBC</mode>
     </password-encoder-plugin>

   Note: You can only have one default-encoder set to true at a time within the kettle-password-encoder-plugins.xml file. ECB is used as the default implementation if the <mode> element is not specified.

3. Save and close the file.

4. Repeat this process for the other kettle-password-encoder-plugins.xml file.

You can verify AES encryption is working with either a batch file command or through the PDI client.

Use a batch file command to verify encryption

Perform the following steps if you want to use the Encr.bat command to make sure your encryption implementation is working as expected:

1. Open a terminal window to a command line.

2. Navigate to one of the following directories:

   • PDI: data-integration

   • Tomcat: server/pentaho-server

3. Run one of the following commands depending on the type of encoder you set:

   • AES2: encr.bat -aes2 password

   • AES: encr.bat -aes password

   • Kettle: encr.bat -kettle password

   • Default: encr.bat password

For AES2 encryption, the first character of the encrypted password represents the encryption implementation used. The first character is a 1 for the ECB encryption implementation (AES2 1RGySKmVU6JWiijkti3Vd8w== for example). The first character is a 2 for the CBC encryption implementation (AES2 2UP+e9xqhL0bkSGWgHokk6xpdhAkO1X8OBxNeGu4qdGI= for example).

Use the PDI client to verify encryption

Perform the following steps if you want to use the PDI client to make sure your encryption implementation is working as expected:

1. Start the PDI client (Spoon).

2. Create a blank transformation.

3. Add a database connection that requires a password.

   See the Install Pentaho Data Integration and Analytics document for instructions on defining a database connection.

4. Save, then close the transformation.

5. Use a text editor to open the transformation you just saved, then search for the name of the connection you created.

6. Examine the password.

   If the password is preceded by the letters AES, or AES2, the encryption was applied correctly.

7. Close the transformation.

OIDC / OAuth 2.0

Prerequisites

The security provider must have users, roles, and passwords correctly established by the Administrator prior to implementation.

The newly integrated OAuth authentication mechanism utilizes OIDC-based authorization_code authentication, while the security provider will handle the authorization.

Users have the flexibility to configure multiple OAuth providers.

To enable OAuth functionality with Pentaho login, make the following changes:

1. Enable OAuth & specify Security Provider

2. Update OIDC Configuration

Enable OAuth & Specify Security Provider

For this Step you will be updating <PENTAHO_HOME>/pentaho-server/pentaho-solutions/system/security.properties.

OAuth is disabled by default with enable-oauth-authentication=false. Administrators can enable it by setting this flag to true: enable-oauth-authentication=true.

Next, you will need to establish the security provider.

Specify Security Provider

Jackrabbit and LDAP serve as security providers while OAuth functions solely as an authentication mechanism in Pentaho Server. Please contact support to understand why these choices were made.

In order to specify the security provider, you must first decide the approach for managing user-role mappings.

1. If you expect to manage user roles in Pentaho, then set provider=jackrabbit. You will then have to assign roles to users in Pentaho User Console. See <link> for details.

2. If you expect to manager user roles in LDAP, then <waiting for input from Sathish and Vamsi to complete this>.

Update OIDC Configuration

For this step, you will be updating <PENTAHO_HOME>/pentaho-server/pentaho-solutions/system/applicationContext-spring-security-oauth.properties

applicationContext-spring-security-oauth.properties is the central configuration file for OAuth2/OIDC authentication in Pentaho 11.0. It serves as the primary interface for administrators to:

• Enable/disable OAuth authentication

• Configure multiple Identity Providers simultaneously

• Set up client registrations for different IdPs (Keycloak, Okta, Azure, etc.)

Core Identity Properties:

1. registration-id - Unique identifier for the IdP configuration.

2. client-name - Display name for the IdP

3. client-id/client-secret - OAuth2 client credentials from the IdP

4. position - Display order on the login page

5. user-name-attribute-name - used for mapping with username created by administrator in Pentaho jackrabbit/LDAP.

6. authorization-grant-type - Auth flow type. By default, authorization_code is the OAuth2 flow type.

7. scope - Requested permissions (typically openid,profile,email). Scopes ensure IDP access token has necessary data

The registration-id value must match the prefix used for all related properties.

For e.g., keycloak.registration-id=keycloak,

Then ALL related properties for that IdP must use the keycloak. prefix:

keycloak.registration-id=keycloak keycloak.client-name=keycloak keycloak.client-id=your-client-id keycloak.client-secret=your-client-secret keycloak.scope=openid,profile,email keycloak.redirect-uri=http://... keycloak.token-uri=http://...

OIDC Endpoints:

1. token-uri - IdP's token endpoint

2. authorization-uri - IdP's authorization endpoint

3. jwk-set-uri - IdP's public keys for token validation

4. user-info-uri - IdP's user information endpoint

5. redirect-uri - Callback URL after IdP authentication

6. end-session-endpoint - Logout endpoint for IdP

7. post-logout-redirect-uri - Redirection uri after IDP session is logged out

Once the above steps are completed and you restart Pentaho Server, the login screen should show options to login via the IdP(s) you have configured above. For example, if Azure Entra, Keycloak, and Okta are all configured you will see the following:

OR (if you have the new experience configured):

Server-Side Request Forgery prevention

Malicious actors can use Server-Side Request Forgery (SSRF) for URL spoofing to map the internal network of the Pentaho Server and then perform possible network attacks. To prevent SSRF attempts against the Pentaho Server and its plugins, you must enable SSRF protection and create an allowed list of alternate fully qualified server URLs to be recognized by the application. Using this allowed list, the server only accepts HTTP requests from compatible host headers. Unlisted URLs are not acknowledged as valid by the server and the system responds with a 403 Forbidden status code.

Preventing Server-Side Request Forgery

Perform the following steps to prevent SSRF attempts.

1. Stop the Pentaho Server if it is currently running.

2. Navigate to the pentaho\server\pentaho-server\pentaho-solutions\system directory.

3. Open the system.properties file with any text editor.

4. Locate the ssrf-protection-enabled element, which is set to false by default, and then set its value to true:

   **ssrf-protection-enabled=**true

5. Save and close the system.properties file.

6. Open the server.properties file using the text editor.

7. Locate the alternative-fully-qualified-server-urls element and then enter a comma-separated list of all the alternative fully qualified URLs containing the complete and exact location through which the servers can be reached in your environment:

   alternative-fully-qualified-server-urls=<fully qualified URL>,<fully qualified URL>,<fully qualified URL>

8. Save and close the server.properties file.

9. Start the Pentaho Server.

The Pentaho Server is now configured to only allow fully qualified and alternate fully qualified server URLs to be recognized.

SSL Security

This section contains instructions and guidance for enhancing the security of the Pentaho Server and User Console on an application server level via Secure Sockets Layer (SSL). SSL provides verification of server identity and encryption of data between clients and the Pentaho Server.

Configure SSL (HTTPS) in the Pentaho User Console and Pentaho Server

By default, the Pentaho Server and User Console are configured to communicate over HTTP. To switch to HTTPS, follow the instructions below that apply to your scenario.

Enable SSL in the Pentaho Server with a certificate authority

If you already have an SSL certificate through a certificate authority such as Thawte or Verisign, you need to configure your application server to use the certificate. It can then be used by the Pentaho Server. Apache provides documentation for configuring Tomcat for CA-signed certificates at https://tomcat.apache.org/. Just follow those procedures, and skip the sections below that deal with self-signed SSL certificates.

After the application server is configured to use your certificate, you must modify the base URL tokens for both the Pentaho Server and the User Console. Make sure you follow the directions for changing the Pentaho Server Base URL. Without executing those changes, your server will not work over HTTPS.

Enable SSL in the Pentaho Server with a self-signed certificate

This process explains how to enable SSL in the Pentaho Server with a self-signed certificate. These steps do not show how to generate a self-signed certificate, or how to configure Tomcat to use it. For more information on SSL certificates in Tomcat, consult the Tomcat documentation. This procedure assumes that an SSL certificate is generated and Tomcat is configured to use it.

The following instructions explain how to complete the trust relationship between the Pentaho Server (when it is configured for SSL) and the User Console:

1. Change to the home directory of the user account that starts the Pentaho Server and User Console processes or services:

   cd ~

   If you installed the default settings for Pentaho, this directory will be: /home/pentaho/

2. Execute the following command, changing the storepass (pass in the example) and keypass (pass2 in the example) accordingly:

   keytool -export -alias tomcat -file tomcat.cer -storepass pass -keypass pass2 -keystore .keystore

3. Change to the $PENTAHO_JAVA_HOME/jre/lib/security/ directory:

   cd $PENTAHO_JAVA_HOME/jre/lib/security/

   The PENTAHO_JAVA_HOME variable was established during your production installation procedure. If you are on Windows, environment variables are surrounded by percent signs, as in: cd %PENTAHO_JAVA_HOME%\jre\lib\security\. If you get an error about this path not being valid, then use JAVA_HOME instead of PENTAHO_JAVA_HOME.

4. Execute the following command, changing the alias (tomcat in the example), the file path to the certificate (the current user's home directory in the example), and the storepass (pass in the example) accordingly:

   keytool -import -alias tomcat -file ~/tomcat.cer -keystore cacerts -storepass pass

   Note: If the path to your certificate involves spaces, you must either escape the spaces (on Linux or Unix), or put double quotes around the path (on Windows) in order for the command to work properly.

5. Execute the following command and make note of the MD5 sum for the Tomcat entry:

   keytool -list -keystore cacerts

6. Change back to the home directory of the user account that starts the Pentaho Server and User Console, and run this command:

   keytool -list -keystore .keystore

7. Compare the Tomcat entry's MD5 sum to the one you generated previously and ensure that they match. If these sums do not match, you've made a mistake someplace in the certificate trust process. Go through the steps again and ensure that you're working with the right user accounts and directories.

The Pentaho Server is now configured to allow access via SSL.

Change the Pentaho Server fully qualified URL

If you switch from HTTP to HTTPS, you must also change the Pentaho Server's tokenized fully qualified URL value to accommodate for the new port number.

Perform the following steps to change the fully qualified URL.

1. Stop the Pentaho Server if it is currently running.

2. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory.

3. Open the server.properties file with any text editor.

4. Locate the following element and modify the port number to match your SSL-enabled port number:

   fully-qualified-server-url=http://localhost:8080/pentaho/

5. Save and close the file.

6. Start the Pentaho Server and make sure that it is available through HTTPS on the specified port.

The Pentaho Server is now configured to allow access via SSL to communicate on an SSL-aware port.

Use the Apache web server (HTTPd) for socket handling

Tomcat's socket handling abilities are not quite as robust as Apache HTTPd's socket handling, especially when it comes to system error handling. Tomcat performs all its socket handling through the Java VM. Since Java is designed to be cross-platform, it lacks some system-specific optimizations, such as socket optimization. In situations where the Pentaho Server is hit with a large number of dropped connections, invalid packets, or invalid requests from invalid IP addresses, HTTPd would do a much better job of dropping these error conditions than Tomcat. Therefore, you can improve Pentaho Server security by fronting Tomcat with HTTPd. A side-effect of this configuration is increased performance when delivering static content from the Pentaho Server.

Perform the following steps to configure the Apache HTTPd Web server to handle delivery of static content and facilitation of socket connections:

1. Install Apache 2.2.x, with SSL support, through your operating system's preferred installation method.

   For most people, this will be through a package manager. It's also perfectly valid to download and install the reference implementation from http://www.apache.org. It is possible to use Apache 1.3, but you will have to modify the instructions on your own from this point onward.

2. If the Apache server has started as a consequence of installing, stop the Apache server or service.

3. Retrieve or create your SSL keys.

   If you do not know how to generate self-signed certificates, refer to the OpenSSL documentation. Most production environments have SSL certificates issued by a certificate authority such as Thawte or Verisign.

4. Check to see if you already have the Tomcat Connector installed on your system.

   You can generally accomplish this by searching your filesystem for mod_jk, though you can also search your http.conf file for mod_jk. If it is present, then you only need to be concerned with the Apache HTTPd configuration details and can skip this step. If it is not there, then the Tomcat Connector module needs to be installed. If you are using Linux or BSD, use your package manager or the Ports system to install mod_jk. For all other platforms, visit the http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/, then click on the directory for your operating system. The module will be either an SO file (for Linux, BSD, OS X, and Solaris) or DLL file (for Windows). Save it to your Apache modules directory, which is generally C:\Program Files\Apache Group\Apache2\modules\ on Windows, and /usr/lib/apache2/modules/ on Unix-like operating systems, though this can vary depending on your Apache configuration.

5. Edit your httpd.conf file with a text editor and add the following text to the end of the file, modifying the paths and filenames as instructed in the comments:

   Note: Some operating systems use modular HTTPd configuration files and have unique methods of including each separate piece into one central file. Ensure that you are not accidentally interfering with an auto-generated mod_jk configuration before you continue. In many cases, some of the configuration example below will have to be cut out (such as the LoadModule statement). In some cases (such as with Ubuntu Linux), httpd.conf may be completely empty, in which case you should still be able to add the below lines to it. Replace example.com with your hostname or domain name.

   # Load mod_jk module
   # Update this path to match your mod_jk location; Windows users should change the .so to .dll
   LoadModule    jk_module  /usr/lib/apache/modules/mod_jk.so
   # Where to find workers.properties
   # Update this path to match your conf directory location
   JkWorkersFile /etc/httpd/conf/workers.properties
   # Should mod_jk send SSL information to Tomcat (default is On)
   JkExtractSSL On
   # What is the indicator for SSL (default is HTTPS)
   JkHTTPSIndicator HTTPS
   # What is the indicator for SSL session (default is SSL_SESSION_ID)
   JkSESSIONIndicator SSL_SESSION_ID
   # What is the indicator for client SSL cipher suit (default is SSL_CIPHER)
   JkCIPHERIndicator SSL_CIPHER
   # What is the indicator for the client SSL certificated (default is SSL_CLIENT_CERT)
   JkCERTSIndicator SSL_CLIENT_CERT
   # Where to put jk shared memory
   # Update this path to match your local state directory or logs directory
   JkShmFile     /var/log/httpd/mod_jk.shm
   # Where to put jk logs
   # Update this path to match your logs directory location (put mod_jk.log next to access_log)
   JkLogFile     /var/log/httpd/mod_jk.log
   # Set the jk log level [debug/error/info]
   JkLogLevel    info
   # Select the timestamp log format
   JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
   # Send everything for context /examples to worker named worker1 (ajp13)
   # JkOptions indicates to send SSK KEY SIZE
   JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
   # JkRequestLogFormat
   JkRequestLogFormat "%w %V %T"
   # Mount your applications
   JkMount /pentaho/* tomcat_pentaho
   # Add shared memory.
   # This directive is present with 1.2.10 and
   # later versions of mod_jk, and is needed for
   # for load balancing to work properly
   JkShmFile logs/jk.shm
   <VirtualHost example.com
   ServerName example.com
   JkMount /pentaho default
   JkMount /pentaho/* default
   JkMount /sw-style default
   JkMount /sw-style/* default
   JkMount /pentaho-style default
   JkMount /pentaho-style/* default
   </VirtualHost>

6. In your Apache configuration, ensure that SSL is enabled by uncommenting or adding and modifying the following lines:

   LoadModule ssl_module modules/mod_ssl.so
   Include conf/extra/httpd-ssl.conf

7. Save and close the file, then edit /conf/extra/httpd-ssl.conf and properly define the locations for your SSL certificate and key:

   SSLCertificateFile "conf/ssl/mycert.cert"
   SSLCertificateKeyFile "conf/ssl/mycert.key"

8. Ensure that your SSL engine options contain these entries:

   SSLOptions +StdEnvVars +ExportCertData

9. Add these lines to the end of the VirtualHost section:

   JkMount /pentaho default
   JkMount /pentaho/* default
   JkMount /sw-style default
   JkMount /sw-style/* default
   JkMount /pentaho-style default
   JkMount /pentaho-style/* default

10. Save and close the file, then create a workers.properties file in your Apache conf directory.

    If it already exists, merge it with the example configuration in the next step.

11. Copy the following text into the new workers.properties file, changing the location of Tomcat and Java, and the port numbers and IP addresses to match your configuration:

    workers.tomcat_home=/home/pentaho/pentaho/server/pentaho-server/tomcat/
    workers.java_home=/home/pentaho/pentaho/java/
    worker.list=tomcat_pentaho
    worker.tomcat_pentaho.type=ajp13

Apache HTTPd is now configured to securely and efficiently handle static content for Tomcat. You should now start Tomcat and HTTPd, then navigate to your domain name or hostname and verify that you can access the PentahoWeb application.

Change the administrator role

The default administrator role in the Pentaho Server is Admin. If you need to give this privilege level to a different role name, follow these instructions:

Note: Role names are case sensitive, so take special care when typing in the new role name.

1. Open the /pentaho/server/pentaho-server/pentaho-solutions/system/pentaho.xml file with a text editor.

2. Find the <acl-voter> element, and replace its <admin-role> property with the new administrator role.

   For example, as NewAdmin is used in this sample procedure:

   <admin-role>NewAdmin</admin-role>

3. Find the <acl-publisher> element, and appropriately replace all instances of Admin in the properties inside of the <default-acls> and <overrides> elements as shown in the following example:

   <acl-entry role="NewAdmin" acl="ADMIN_ALL" />

4. Save the file, then open applicationContext-spring-security.xml.

5. Find the filterInvocationInterceptor bean, and modify its objectDefinitionSource property accordingly.

   You may need to consult the Spring Security documentation to complete this step:

   <property name="objectDefinitionSource">
       <value>
           <[
           CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
           ...
           \A/admin.*\Z=NewAdmin
           ...
           ]>
       </value>
   </property>

You have successfully changed the administrator role.

SSO security

This section contains instructions for configuring the Pentaho Server to work with the Central Authentication Service (CAS) single sign-on (SSO) framework.

You can integrate Pentaho with Central Authentication Service (CAS). You must have a CAS server installed and running before you continue.

Perform the following steps to integrate Pentaho with CAS.

1. Stop the Pentaho Server

2. Download the following files and copy them to the pentaho-server/tomcat/webapps/pentaho/WEB-INF/lib directory.

   • https://repo1.maven.org/maven2/org/jasig/cas/cas-client-core/3.1.10/cas-client-core-3.1.10.jar

   • https://repo1.maven.org/maven2/org/springframework/security/spring-security-cas-client/3.0.8.RELEASE/spring-security-cas-client-3.0.8.RELEASE.jar

3. Navigate to the pentaho-server/pentaho-solutions/system directory and open the pentaho-spring-beans.xml file with any text editor.

   1. Add the <import resource="applicationContext-spring-security-cas.xml"/> to the list of imports after all the other applicationContext*.xml files.

   2. Save and close the file.

4. Navigate to the pentaho-server/pentaho-solutions/system directory and open the applicationContext-spring-security-cas.xml file with any text editor. Update the file using the following steps:

   Note: You must use the publicly available IP address for all URLs in this file.

   1. If you are using Pentaho with SSL, then update the references for https://localhost:8443/cas to your working CAS server URL.

      The CAS Server must use SSL. Contact your CAS Administrator if you need to add SSL security to your CAS instance.

   2. Locate the bean containing the ID for casAuthenticationProvider.

      <bean id="casAuthenticationProvider"
      class="org.springframework.security.providers.cas.CasAuthenticationProvider">
      <property name="userDetailsService">
       <ref bean="userDetailsService" />
      </property>

   3. Change the bean ID based on your configuration to the applicable one as shown below.

      casAuthenticationProvider.jdbcUserDetailsService

      casAuthenticationProvider.ldapUserDetailsService

   4. Save and close the file.

5. Navigate to the pentaho-server/tomcat/webapps/pentaho/WEB-INF directory and open the web.xml file.

   1. Add the following lines to their applicable sections in the file:

      <servlet>
        <servlet-name>casFailed</servlet-name>
        <jsp-file>/jsp/casFailed.jsp</jsp-file>
      </servlet>

      <servlet-mapping>
        <servlet-name>casFailed</servlet-name>
        <url-pattern>/public/casFailed</url-pattern>
      </servlet-mapping>casAuthenticationProvider.hibernateUserDetailsService

      <listener>
          <listener-class>org.jasig.cas.client.session.SingleSignOutHttpSessionListener</listener-class>  
      </listener>

   2. Save and close the file.

      Note: The casFailed entries are CAS login flow dependent and must be defined and configured by the CAS Administrator on the CAS server. These entries cover cases such as what happens when the user enters the wrong password or similar issues authenticating. The action taken depends on the CAS login flow definition.

6. Start the Pentaho Server.

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

Configure session timeout

Connection timeout issues when using CAS with the Pentaho Server can result in the inability to login or re-load data in the web client page until you refresh the page. To avoid problems with the session timing out, perform the following steps to configure the session timeout:

1. Stop the Pentaho Server.

2. Navigate to the pentaho-server/tomcat/webapps/pentaho/WEB-INF directory and open the web.xml file with any text editor.

   1. Find the session-config property and edit the session-timeout value (the default value is 120 minutes) to increase the period to a value that is greater than the setting used for your CAS server session timeout value:

      <session-config>
        <tracking-mode>COOKIE</tracking-mode>
        <session-timeout>120</session-timeout>
      </session-config>

   2. Locate the Pentaho Web Context Filter and add the following init-param:

      <init-param>
        <param-name>ssoEnabled</param-name>
        <param-value>true</param-value>
      </init-param>

   3. Save and close the file.

3. Activate the session timeout dialog box:

   1. Navigate to the pentaho-server/pentaho-solutions/system directory and open the applicationContext-spring-security-cas.xml file then locate the httpSessionPentahoSessionContextIntegrationFilter bean id.

   2. Find the ssoEnabled property and set the value from true to false.

   3. Save and close the file.

4. Restart the Pentaho Server.