Skip to main content
Pentaho Documentation

Set Up SAML for the Pentaho 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. 

These instructions are provided for reference purposes only, to walk you through an example SAML set up. If you want to extend your SAML set up further, please work with with your Customer Success Manager.

The following diagram is 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 Pentaho Server):

Pentaho Server and SAML Workflow

Before You Begin

Before you can configure SAML for the Pentaho Server, you will need to complete these tasks:

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 7.0 Installation Make sure that you have at least Pentaho 7.0 installed and configured.

Getting the Pentaho Server Ready for SAML 

After you have finished installing your IdP, have gathered the required information, and confirmed that you are using at least Pentaho 7.0; you are ready to set up the Pentaho Server to use SAML. When it is set up, 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 set up process:

  • Download and Unpack SAML files
  • Edit SAML Config File

Step 1: Download and Unpack SAML Files

Download and unpack the SAML files and place them in the correct directories.

  1. Contact Pentaho Support for instructions on how to build the sample.kar file.
  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.
    • You should see this statement in the log file:
Creating configuration from pentaho.saml.cfg
  1. Stop the Pentaho 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 2: Edit SAML Config File

Edit the pentaho.saml.cfg file with three keys.

  1. Open the pentaho.saml.cfg with any text editor and make the following changes:
    • 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.

The following code block is an example of these keys:

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 Pentaho Server SAML Sample

Also perform the following steps after you have prepared the Pentaho Server to work with the SAML sample:

  1. Verify that the Pentaho Server is stopped.
  2. Locate the pentaho-solutions/system directory and open the pentaho-spring-beans.xml file with any text editor.
  3. Place the following 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 Pentaho Server.

Deactivate the Pentaho Server SAML Sample

Perform the following steps to deactivate the SAML sample:

  1. Stop the Pentaho Server.
  2. Locate the pentaho-solutions/system directory and open the pentaho-spring-beans.xml file with any text editor.
  3. Find and remove the following 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 Pentaho Server.