Pentaho secure single sign-on via Okta for both web and mobile access using SAML 2.0

Introduction

SAML is a specification that provides a means to exchange authentication and authorization of the “principal” (user) between an Identity Provider (IdP) and a Service Provider (SP). Once the plugin is installed, the Pentaho BA Server will become a SAML Service Provider, relying on the assertion to provide authentication, or both authentication and authorization for role assignment depending on the Identity Provider being used.

Getting started

1.Configuring the Pentaho BA Server for SAML Authentication

1.1 Installing the SAML Plugin and Required Files in Pentaho

*Note: Steps 2-4 should not be needed in Pentaho 6.1, where custom. properties already has correct dependendencies

1. Obtain the SAML Plugin Karaf Assembly (pentaho-saml-sample.kar file), logout.jsp, and applicationContext-spring-security-saml.xml

• a. Check “Additional resources” section for the location from where you can download logout.jsp and applicationContext-spring-security-saml.xml
• b. Check “Additional resources” section for the github location from where you can get the pentaho-saml-sample source code ( to build the .kar file )

2. Shutdown the Pentaho BA Server

3. Open $PENTAHO_HOME/server/biserver-ee/pentaho-solutions/system/karaf/etc/custom.properties a. Add a specific version to the line containing “org.springframework.security.context, \” by changing it to: org.springframework.security.context; version\=”2.0.8.RELEASE”, \

b. Directly below that line, add a new line containing another required dependency:

org.springframework.security.ui; version\="2.0.8.RELEASE", \

4. Start the Pentaho BA Server

5. Wait for the server to report it has started in $PENTAHO_HOME/server/biserver-ee/tomcat/logs/catalina.log

6. Place the pentaho-saml-sample.kar file in the $PENTAHO_HOME/server/biserver-ee/system/karaf/deploy/ folder. Once the plugin is installed, the

$PENTAHO_HOME/server/biserver-ee/system/karaf/etc/pentaho.saml.cfg

configuration file will be created

7. Shutdown the BA Server

8. Copy logout.jsp into the $PENTAHO_HOME/server/biserver-ee/tomcat/webapps/pentaho/ folder

9. Copy applicationContext-spring-security-saml.xml into the $PENTAHO_HOME/server/biserver-ee/pentaho-solutions/system/ folder

1.2 Create a SAML Assertion Signing (and Encryption) Certificate and Keystore

1. Create a $PENTAHO_HOME/server/biserver-ee/saml/ folder

2. Open a terminal or command prompt, and make the newly created folder your working directory:

 cd $PENTAHO_HOME/server/biserver-ee/saml

3. Run the keytool command to generate a self-signed certificate. You may also obtain a signed certificate from a certificate authority if you wish. Ensure that the certificate uses a hash algorithm supported by your IdP (most likely SHA1 or SHA256).

$PENTAHO_JAVA_HOME/bin/keytool -genkey -alias saml -keystore $PENTAHO_HOME/server/biserver-ee/saml/saml.keystore.jks -storepass changeit -keyalg RSA –keypass changeit 

Notes:

• When prompted, fill out any information relevant to your organization
• If you’re IdP only supports SHA1 signing, add “-sigalg SHA1WithRSA” as an argument
• Use a password other than “changeit” for –storepass and –keypass arguments
• The keystore password (-storepass) and key password (-keypass) do not need to be the same

1.3 Prepare the Pentaho Service Provider Metadata XML File

Having the Service Provider metadata file can simplify the process of obtaining the required Identity Provider metadata from the different IdP services. This section describes how to modify a template SP metadata file to match your BA Server installation.

1. you do not already have an SP metadata file, copy the text below into a unix formatted file called pentaho-sp.xml:

<?xml version="1.0" encoding="UTF-8"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="pentaho" entityID="pentaho"> <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate><!-- REPLACE COMMENT WITH BASE64 SIGNING CERTIFICATE --></ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:KeyDescriptor use="encryption"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate><!-- REPLACE COMMENT WITH BASE64 ENCRYPTION CERTIFICATE --></ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName</md:NameIDFormat> <!-- MODIFY LOCATION ATTRIBUTES WITH PROTOCOL, DOMAIN, and PORT --> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8443/pentaho/saml/SingleLogout"/> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8443/pentaho/saml/SingleLogout"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8443/pentaho/saml/SSO" index="0" isDefault="true"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://localhost:8443/pentaho/saml/SSO" index="1"/> </md:SPSSODescriptor> </md:EntityDescriptor>

2.Move or copy your SP metadata file (pentaho-sp.xml if using a file from step 1) to

$PENTAHO_HOME/server/biserver-ee/saml/pentaho-sp.xml

3. Locate the XML tag entries for “<md:SingleLogoutService>” and “<md:AssertionConsumerService>,” and replace the values of the “Location” attribute (bolded in blue above) with the appropriate protocol (http/https), domain name, and port that the BA Server is running on.

4. Export the contents of your saml signing (and additional encryption certificate if you generated one) certificate to a base64 representation using the following keytool command:

$PENTAHO_JAVA_HOME/bin/keytool -exportcert -keystore $PENTAHO_HOME/server/biserver-ee/saml/saml.keystore.jks -storepass changeit -alias saml -rfc

5. The command in the previous step should print out the certificate data, which looks like:

-----BEGIN CERTIFICATE---- 

CERTIFICATE

DATA

PAYLOAD

-----END CERTIFICATE----- 

Copy the content of the certificate data payload (not the begin or end line) into the appropriate “<ds:X509Certificate>” entry tag. The “use” attribute of the parent “<md:KeyDescriptior>” tag defines if you’re dealing with the signing or encryption certificate. The same certificate data can be used in both spots.

2. Setup a Pentaho Application/Party Trust/Client in the IdP(OKTA) and Obtain the IdP Metadata XML

OKTA configuration

Some IdPs have a feature to upload the SP Metadata XML file to configure your service provider. However, Okta does not currently have this feature, so you’ll have to export the signing certificate that will be imported during configuration.

Export the Signing Certificate

Execute the following command to place the signing public key in a cer file:

$PENTAHO_JAVA_HOME/bin/keytool -exportcert -keystore $PENTAHO_HOME/server/biserver-ee/saml/saml.keystore.jks -storepass changeit -alias saml –rfc > $PENTAHO_HOME/server/biserver-ee/saml/saml.signing.cert.cer

1. Sign into an Okta account with Administrative privileges

2. Enter the “Admin” section of the site

3. Click the “Add Applications” shortcut

4. Click the “Create New App” button

5. Fill in the “App name” field with “pentaho”

6. Optionally add a logo, and leave the visibility settings unchanged

7. Click “Next”

8. Fill in the basic settings form as follows:

9. Update the blue portion in the URL above to match the domain and port of the BA Server

10. Click on “Show advanced settings,” and fill in these values:

11. Update the blue portion of the Single Logout URL above to match the domain and port of the BA Server

12. Click “Next”

13. Check the radio button “I’m an Okta customer adding an internal app”

14. Enable the checkbox “This is an internal app that we have created”

15. Click “Finish”

You should be redirected to the “Sign On” page of the newly created “pentaho” application. If not, you can get there by following these steps:

i. In the top menu bar, select Applications > Applications

ii. Select “pentaho”

iii. Click “Sign On”

16. Click the “Identity Provider metadata” hyperlink, and download the resulting file as $PENTAHO_HOME/server/biserver-ee/saml/okta-idp.xml

3. Configure the pentaho.saml.cfg File

At this point, there is a saml folder with an IdP metadata xml file, the Pentaho SP metadata xml file, and a saml keystore with the signing certificate (and possibly separate encryption certificate). When editing the pentaho.saml.cfg file, please note that absolute paths (no variables) must be listed in the file.

1. Shut down the BA Server if it is running

2. Open the /pentaho6/server/biserver-ee/pentaho-solutions/system/karaf/etc/pentaho.saml.cfg file for editing.

3.1 Setting IdP Properties

There are three ways to identify the IdP metadata XML file. It can be specified to be read from a URL, a filesystem path, or from a jar on the classpath (saml.idp.metadata.url, saml.idp.metadata.filesystem, and saml.idp.metadata.classpath(respectively). Only one method should be enabled at any time, and the non-used properties should be commented out with a number “#” sign at the front of the line.

1. Comment the entries for saml.idp.metadata.url and saml.idp.metadata.classpath if they are uncommented

2. Uncomment the entry for saml.idp.metadata.filesystem if it is commented

3. Change the value (after the equal sign) to the path of your IdP metadata XML file:

 saml.idp.metadata.filesystem=/pentaho6/server/biserver-ee/saml/saml-idp.xml

You will also need to set the saml.idp.url property, which is used to select the proper EntityDescriptor from the referenced saml-idp.xml file.

1. Open $PENTAHO_HOME/server/biserver-ee/saml/saml-idp.xml

2. Locate the “<EntityDescriptor>” tag, and copy the value of the “entityId” attribute:

<EntityDescriptor ID=”…” entityID=”http://the-idp-url “ xmlns=

3. In pentaho.saml.cfg, set the value of the saml.idp.url property to the copied value

 saml.idp.url=http://the-idp-url

3.2 Setting SP Properties

Similar to the IdP settings, there are three ways to specify the Service Provider document. Choose from URL, filesystem, or classpath using the saml.sp.metadata.url, saml.sp.metadata.filesystem, or saml.sp.metadata.classpath properties. This example will use the filesystem, since earlier instructions directed you to save the pentaho-sp.xml file.

1. Comment out the entries (prefix the line with “#”) for saml.sp.metadata.url and saml.sp.metadata.classpath if they’re uncommented

2. Uncomment the line for saml.sp.metadata.filesystem if it is commented

3. Change the value of the saml.sp.metadata.filesystem to:

saml.sp.metdata.filesystem=/pentaho6/server/biserver-ee/saml/pentaho-sp.xml

The other property that is configurable for the Service Provider is saml.sp.metadata.entityId. It has a case sensitive value that defaults to “pentaho”. Editing this value is not recommended. The value has to match the entityId in the SP metadata XML file and the party trust configured in the IdP.

3.3 Setting the Keystore Properties

All of the certificates needed for signing, encryption, and communication with SAML servers need to be in a single keystore file. Similar to IdP and SP configuration, the keystore can be specified with a URL, filesystem path, or classpath entry using the saml.keystore.url, saml.keystore.filesystem, or saml.keystore.classpath properties.

1. Comment the saml.keystore.url and saml.keystore.classpath properties with “#” if they are uncommented

2. Uncomment saml.keystore.filesystem if it is commented with “#”

3. Change the value of saml.keystore.filesystem to:

 saml.keystore.filesystem=/pentaho6/server/biserver-ee/saml/saml.keystore.jks

4. Locate the saml.keystore.default.key property, and change it to match the alias of your saml signing certificate. The path setup before referenced a self-signed certificate aliased as “saml,” which would be configured as:

saml.keystore.default.key=saml

5. Locate and set the keystore password with the saml.keystore.password property. This should match the password used as the –storepass argument when you obtained a SAML signing certificate in the “Create a SAML Assertion Signing (and Encryption) Certificate and Keystore” section of this document.

saml.keystore.password=changeit 

6. If any of your certificate private key passwords include the colon “:” character, change the saml.username.password.delimiter.char property to a valid delimiter character not included in any of the key passwords.

7. Provide a comma separated list of username<delimeter>password to allow the Pentaho SAML plugin to read private keys in the saml.keystore.private.username.passwords property:

saml.keystore.private.username.passwords=saml:changeit,saml2:changeit

3.4 Enable the SAML Plugin

1. Shut down the BA Server if it is running

2. Open $PENTAHO_HOME/server/biserver-ee/pentaho-solutions/system/pentaho-spring-beans.xml for editing

3. Locate the line containing “<import resource=”applicationContext-spring-security-jdbc.xml” />” and add the following line below it:

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

4. Save and close the file

5. Open $PENTAHO_HOME/server/biserver-ee/pentaho-solutions/system/security.properties for editing

6. Change the provider on the first line to “saml”. Once completed, the line will read:

 provider=saml

7. Save and close the file

8. Start the BA Server and attempt to authenticate. The system should redirect to the Single Sign On page (if not already logged in), and upon successful credential authentication, the user’s Name ID provided by SAML will appear in the top right hand corner of the page.

Note: If you wish to disable the SAML plugin, simply shut down the BA Server, then comment out the line added to pentaho-spring-beans.xml and change the provider in security.properties to its previous value.

Summary

On-Demand Identity Management for All Your Web Applications. Okta is an on-demand identity and access management service that enables enterprises to accelerate the secure adoption of their web applications, both in the cloud and behind the firewall.

Reference:

Pentaho

https://github.com/pentaho/pentaho-engineering-samples

• Source Code: /Samples for Extending Pentaho/Reference Implementations/Security/SAML 2.0

• Resources: /Samples for Extending Pentaho/

OKTA

Setup SAML application in OKTA

https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta