Skip to main content
Pentaho Documentation

Set Up SAML for BA Server

SAML is mostly used as a web-­based authentication mechanism. It relies on the browser being used as an agent that brokers the authentication flow. There are numerous 3rd-party Identity Providers (IdP) available, such as OpenSSO, OKTA, SSOCircle.com, etc. 

Shown here is a  a high-­level sketch of a SAML identification structure, containing a 3rd-party Identity Provider (IdP), an End-User Browser (the Pentaho User Console), and a Service Provider (the BA Server).   

SAMLDiag.png

Before You Begin

Before you begin configuring SAML for the BA Server, you'll need to do a few things.

Task Description
Get a 3rd-party Authentication Provider Register with a 3rd-party authentication provider, such as OpenSSO, OKTA, Salesforce.com, etc. 
Gather Information Make sure that you have the following information on hand:
  • URL for the location of your 3rd-party authentication provider 
  • Absolute path for the IdP metadata xml file
  • Absolute path for Pentaho SP metadata xml file
Verify Pentaho 6.0 Installation Make sure that you have Pentaho Business Analytics 6.0 installed and configured.

Getting the BA Server Ready for SAML 

After you have finished installing your IdP, have gathered the required information, and confirmed that you are using Pentaho 6.0, you are ready to set up the BA Server to use SAML. 

When you are finished, you will also be able to logout either locally only or globally. Global logout ends the session on the current IdP, the current SP, and any other SP sessions that are connected to the chosen IdP.

The default role of Authenticated is assigned to any SAML-authenticated user, unless you specify otherwise.

These sections will guide you through the entire process:

  • Edit the Karaf Properties File
  • Download and Unpack SAML files
  • Edit SAML Config File

Step 1: Edit the Karaf Properties File

The first thing you'll need to do is add a couple of properties to the Karaf file.

  1. Locate the pentaho-­solutions/system/karaf/etc directory and open the custom.properties file with any text editor.
  2. Find the entry for security.context and replace as shown here:

Remove Old Entry

org.springframework.security.context, \

Add New Entry

org.springframework.security.context; version\="2.0.8.RELEASE", \
  1. Next, add this entry directly below that one: 
org.springframework.security.ui; version\="2.0.8.RELEASE", \
  1. Save and close the file.
  2. Start the BA Server.

Step 2: Download and Unpack SAML Files

Next, you'll need to download and unpack the SAML files and place them in the correct directories.

  1. Contact Pentaho Support to get the SAML sample files.
  2. Make sure that you have these four items in your SAML file package:
    • pentaho-saml-sample.kar
    • applicationContext-spring-security-saml.xml
    • logout.html
  3. Place the .kar file into the pentaho-solutions/system/karaf/deploy directory, then check the log file.
    1. You should see this in the log file.
Creating configuration from pentaho.saml.cfg
  1. Stop the BA Server.
  2. Place the applicationContext-­spring­‐security­‐saml.xml file into the pentaho-­solutions/system directory.
  3. Place the logout.html file into the tomcat/webapps/pentaho directory.

Step 3: Edit SAML Config File

Now you'll need to edit the pentaho.saml.cfg file with these three keys.

  1. Open the pentaho.saml.cfg with any text editor.
    • Find the saml.idp.url value and enter the URL for your 3rd-party IdP.
    • Find the saml.idp.metadata.filesystem and enter the absolute path to your IdP metadata.xml file.
    • Find the saml.sp.metadata.filesystem and enter the absolute path to your Pentaho SP metadata.xml file.
  2. Save and close the file.

Here is an example that you can use:

saml.idp.url=http://idp.[3rd-party IdP].com
saml.idp.metadata.filesystem=/users/admin/saml/idp/[3rd-party IdP] e-idp-metadata.xml
saml.sp.metadata.filesystem=/users/admin/saml/sp/pentaho- sp-metadata.xml

Activate the BA Server SAML Sample

There are a few things that you have to do after you have prepared the BA Server to work with the SAML sample.

  1. Verify that the BA Server is stopped.
  2. Locate the pentaho-solutions/system directory and open the pentaho-spring-beans.xml file with any text editor.
  3. Place this bean just above the pentahoObjects.spring.xml bean.
<import resource="applicationContext-spring-security-saml.xml" />
  1. Save and close the file.
  2. Open the security.properties file with any text editor. 
  3. Change the provider value at the top from jackrabbit to saml.
  4. Save and close the file.
  5. Start the BA Server.

Deactivate the BA Server SAML Sample

These directions show you how to deactivate the SAML sample.

  1. Stop the BA Server.
  2. Locate the pentaho-solutions/system directory and open the pentaho-spring-beans.xml file with any text editor.
  3. Find and remove this bean: 
<import resource="applicationContext-spring-security-saml.xml" />
  1. Save and close the file.
  2. Open the security.properties file with any text editor. 
  3. Change the provider value at the top from saml to any other provider.
  4. Save and close the file.
  5. Start the BA Server.