SAML is a specification that provides a means to exchange authentication and authorization of the \u201cprincipal\u201d (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.<\/p>\n\n\n\n
Getting started<\/p>\n\n\n\n
*Note<\/b>: Steps 2-4 should not be needed in Pentaho+ 6.1, where custom. properties already has correct dependendencies<\/p>\n\n\n\n
1. Obtain the SAML Plugin Karaf Assembly (pentaho-saml-sample.kar file), logout.jsp, and applicationContext-spring-security-saml.xml<\/p>\n\n\n\n
2. Shutdown the Pentaho Plus BA Server<\/p>\n\n\n\n
3. Open $PENTAHO_HOME\/server\/biserver-ee\/pentaho-solutions\/system\/karaf\/etc\/custom.properties a. Add a specific version to the line containing \u201corg.springframework.security.context, \\\u201d by changing it to: org.springframework.security.context; version\\=”2.0.8.RELEASE”, \\<\/p>\n\n\n\n
b. Directly below that line, add a new line containing another required dependency:<\/p>\n\n\n\n
org.springframework.security.ui; version\\=\"2.0.8.RELEASE\", \\<\/pre>\n\n\n\n4. Start the Pentaho+ BA Server<\/p>\n\n\n\n
5. Wait for the server to report it has started in $PENTAHO_HOME\/server\/biserver-ee\/tomcat\/logs\/catalina.log<\/p>\n\n\n\n
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<\/p>\n\n\n\n
$PENTAHO_HOME\/server\/biserver-ee\/system\/karaf\/etc\/pentaho.saml.cfg<\/pre>\n\n\n\nconfiguration file will be created<\/p>\n\n\n\n
7. Shutdown the BA Server<\/p>\n\n\n\n
8. Copy logout.jsp into the $PENTAHO_HOME\/server\/biserver-ee\/tomcat\/webapps\/pentaho\/ folder<\/p>\n\n\n\n
9. Copy applicationContext-spring-security-saml.xml into the $PENTAHO_HOME\/server\/biserver-ee\/pentaho-solutions\/system\/ folder<\/p>\n\n\n\n
1.2 Create a SAML Assertion Signing (and Encryption) Certificate and Keystore<\/h3>\n\n\n\n
1. Create a $PENTAHO_HOME\/server\/biserver-ee\/saml\/ folder<\/p>\n\n\n\n
2. Open a terminal or command prompt, and make the newly created folder your working directory:<\/p>\n\n\n\n
<\/i>cd $PENTAHO_HOME\/server\/biserver-ee\/saml<\/pre>\n\n\n\n3. 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).<\/p>\n\n\n\n
$PENTAHO_JAVA_HOME\/bin\/keytool -genkey -alias saml -keystore $PENTAHO_HOME\/server\/biserver-ee\/saml\/saml.keystore.jks -storepass changeit <\/b>-keyalg RSA \u2013keypass changeit <\/b><\/pre>\n\n\n\nNotes:<\/h4>\n\n\n\n
\n
- When prompted, fill out any information relevant to your organization<\/li>\n\n\n\n
- If you\u2019re IdP only supports SHA1 signing, add \u201c-sigalg SHA1WithRSA\u201d as an argument<\/li>\n\n\n\n
- Use a password other than \u201cchangeit\u201d for \u2013storepass and \u2013keypass arguments<\/li>\n\n\n\n
- The keystore password (-storepass) and key password (-keypass) do not need to be the same<\/li>\n<\/ul>\n\n\n\n
1.3 Prepare the Pentaho+ Service Provider Metadata XML File<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
1. you do not already have an SP metadata file, copy the text below into a unix formatted file called pentaho-sp.xml:<\/p>\n\n\n\n
\n
- \n
\n
\n \n<\/colgroup>\n \n \n <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n<md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" ID=\"pentaho\" entityID=\"pentaho\">\n\n<md:SPSSODescriptor AuthnRequestsSigned=\"true\" WantAssertionsSigned=\"false\"\n\nprotocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\n\n<md:KeyDescriptor use=\"signing\">\n\n<ds:KeyInfo xmlns:ds=\"http:\/\/www.w3.org\/2000\/09\/xmldsig#\">\n\n<ds:X509Data>\n\n<ds:X509Certificate><!-- REPLACE COMMENT WITH BASE64 SIGNING CERTIFICATE --><\/ds:X509Certificate>\n\n<\/ds:X509Data>\n\n<\/ds:KeyInfo>\n\n<\/md:KeyDescriptor>\n\n<md:KeyDescriptor use=\"encryption\">\n\n<ds:KeyInfo xmlns:ds=\"http:\/\/www.w3.org\/2000\/09\/xmldsig#\">\n\n<ds:X509Data>\n\n<ds:X509Certificate><!-- REPLACE COMMENT WITH BASE64 ENCRYPTION CERTIFICATE --><\/ds:X509Certificate>\n\n<\/ds:X509Data>\n\n<\/ds:KeyInfo>\n\n<\/md:KeyDescriptor>\n\n<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress<\/md:NameIDFormat>\n\n<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient<\/md:NameIDFormat>\n\n<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent<\/md:NameIDFormat>\n\n<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified<\/md:NameIDFormat>\n\n<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName<\/md:NameIDFormat>\n\n<!-- MODIFY LOCATION ATTRIBUTES WITH PROTOCOL, DOMAIN, and PORT -->\n\n<md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"\n\nLocation=\"https:\/\/localhost:8443<\/b>\/pentaho\/saml\/SingleLogout\"\/>\n\n<md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"\n\nLocation=\"https:\/\/localhost:8443<\/b>\/pentaho\/saml\/SingleLogout\"\/>\n\n<md:AssertionConsumerService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"\n\nLocation=\"https:\/\/localhost:8443<\/b>\/pentaho\/saml\/SSO\" index=\"0\" isDefault=\"true\"\/>\n\n<md:AssertionConsumerService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact\"\n\nLocation=\"https:\/\/localhost:8443<\/b>\/pentaho\/saml\/SSO\" index=\"1\"\/>\n\n<\/md:SPSSODescriptor>\n\n<\/md:EntityDescriptor><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/dd>\n<\/dl>\n\n\n\n2.Move or copy your SP metadata file (pentaho-sp.xml if using a file from step 1) to<\/p>\n\n\n\n
$PENTAHO_HOME\/server\/biserver-ee\/saml\/pentaho-sp.xml<\/pre>\n\n\n\n3. Locate the XML tag entries for \u201c<md:SingleLogoutService>\u201d and \u201c<md:AssertionConsumerService>,\u201d and replace the values of the \u201cLocation\u201d attribute (bolded in blue above) with the appropriate protocol (http\/https), domain name, and port that the BA Server is running on.<\/p>\n\n\n\n
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:<\/p>\n\n\n\n
$PENTAHO_JAVA_HOME\/bin\/keytool -exportcert -keystore $PENTAHO_HOME\/server\/biserver-ee\/saml\/saml.keystore.jks -storepass changeit <\/b>-alias saml -rfc<\/pre>\n\n\n\n5. The command in the previous step should print out the certificate data, which looks like:<\/p>\n\n\n\n
-----BEGIN CERTIFICATE---- <\/b>\n\nCERTIFICATE\n\nDATA\n\nPAYLOAD\n\n-----END CERTIFICATE----- <\/b><\/pre>\n\n\n\nCopy the content of the certificate data payload (not the begin or end line) into the appropriate \u201c<ds:X509Certificate>\u201d entry tag. The \u201cuse\u201d attribute of the parent \u201c<md:KeyDescriptior>\u201d tag defines if you\u2019re dealing with the signing or encryption certificate. The same certificate data can be used in both spots.<\/p>\n\n\n\n
2. Setup a Pentaho+ Application\/Party Trust\/Client in the IdP(OKTA) and Obtain the IdP Metadata XML<\/h3>\n\n\n\n
OKTA configuration<\/h4>\n\n\n\n
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\u2019ll have to export the signing certificate that will be imported during configuration.<\/p>\n\n\n\n
Export the Signing Certificate<\/h4>\n\n\n\n
Execute the following command to place the signing public key in a cer file:<\/p>\n\n\n\n
$PENTAHO_JAVA_HOME\/bin\/keytool -exportcert -keystore $PENTAHO_HOME\/server\/biserver-ee\/saml\/saml.keystore.jks -storepass changeit <\/b>-alias saml \u2013rfc > $PENTAHO_HOME\/server\/biserver-ee\/saml\/saml.signing.cert.cer<\/pre>\n\n\n\n1. Sign into an Okta account with Administrative privileges<\/p>\n\n\n\n
2. Enter the \u201cAdmin\u201d section of the site<\/p>\n\n\n\n
3. Click the \u201cAdd Applications\u201d shortcut<\/p>\n\n\n\n
4. Click the \u201cCreate New App\u201d button<\/p>\n\n\n\n
5. Fill in the \u201cApp name\u201d field with \u201cpentaho\u201d<\/p>\n\n\n\n
6. Optionally add a logo, and leave the visibility settings unchanged<\/p>\n\n\n\n
7. Click \u201cNext\u201d<\/p>\n\n\n\n
8. Fill in the basic settings form as follows:<\/p>\n\n\n\n
Field <\/b><\/td> Value <\/b><\/td><\/tr> Single sign on URL<\/td> http:\/\/localhost:8080<\/b>\/pentaho\/saml\/SSO<\/td><\/tr> Recipient URL and Destination URL checkbox<\/td> Checkbox selected<\/td><\/tr> Audience URI<\/td> pentaho<\/td><\/tr> Default Relay State<\/td> <empty><\/td><\/tr> Name ID format<\/td> EmailAddress<\/td><\/tr> Application Username<\/td> Okta username<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n 9. Update the blue portion <\/b>in the URL above to match the domain and port of the BA Server<\/p>\n\n\n\n
10. Click on \u201cShow advanced settings,\u201d and fill in these values:<\/p>\n\n\n\n
Field <\/b><\/td> Value <\/b><\/td><\/tr> Response<\/td> signed<\/td><\/tr> Assertion Signature<\/td> signed<\/td><\/tr> Signature algorithm<\/td> RSA- SHA256<\/td><\/tr> Digest algorithm<\/td> SHA256<\/td><\/tr> Assertion encryption<\/td> unencrypted<\/td><\/tr> Enable Single Logout<\/td> Checkbox: checked<\/td><\/tr> Single Logout URL<\/td> http:\/\/localhost:8080<\/b>\/pentaho\/saml\/SingleLogout<\/td><\/tr> SP Issuer<\/td> pentaho<\/td><\/tr> Signature Certificate<\/td> \n Upload the certificate exported above, which should be located at:<\/p>\n
$PENTAHO_HOME\/server\/biserver-ee\/saml\/signing.cer <\/b><\/p>\n<\/td><\/tr>
Authentication Context<\/td> PasswordProtectedTransport<\/td><\/tr> Honor Force Auth.<\/td> Yes<\/td><\/tr> Saml Issuer ID<\/td> okta\/${org.externalKey}<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n 11. Update the blue portion <\/b>of the Single Logout URL above to match the domain and port of the BA Server<\/p>\n\n\n\n
12. Click \u201cNext\u201d<\/p>\n\n\n\n
13. Check the radio button \u201cI’m an Okta customer adding an internal app\u201d<\/p>\n\n\n\n
14. Enable the checkbox \u201cThis is an internal app that we have created\u201d<\/p>\n\n\n\n
15. Click \u201cFinish\u201d<\/p>\n\n\n\n
You should be redirected to the \u201cSign On\u201d page of the newly created \u201cpentaho\u201d application. If not, you can get there by following these steps:<\/strong><\/p>\n\n\n\n
i. In the top menu bar, select Applications > Applications<\/p>\n\n\n\n
ii. Select \u201cpentaho\u201d<\/p>\n\n\n\n
iii. Click \u201cSign On\u201d<\/p>\n\n\n\n
16. Click the \u201cIdentity Provider metadata\u201d hyperlink, and download the resulting file as $PENTAHO_HOME\/server\/biserver-ee\/saml\/okta-idp.xml<\/p>\n\n\n\n
3. Configure the pentaho.saml.cfg File<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
1. Shut down the BA Server if it is running<\/p>\n\n\n\n
2. Open the \/pentaho6\/server\/biserver-ee\/pentaho-solutions\/system\/karaf\/etc\/pentaho.saml.cfg file for editing.<\/p>\n\n\n\n
3.1 Setting IdP Properties<\/h3>\n\n\n\n
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 \u201c#\u201d sign at the front of the line.<\/p>\n\n\n\n
1. Comment the entries for saml.idp.metadata.url and saml.idp.metadata.classpath if they are uncommented<\/p>\n\n\n\n
2. Uncomment the entry for saml.idp.metadata.filesystem if it is commented<\/p>\n\n\n\n
3. Change the value (after the equal sign) to the path of your IdP metadata XML file:<\/p>\n\n\n\n
saml.idp.metadata.filesystem=\/pentaho6\/server\/biserver-ee\/saml\/saml-idp.xml<\/pre>\n\n\n\nYou 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.<\/p>\n\n\n\n
1. Open $PENTAHO_HOME\/server\/biserver-ee\/saml\/saml-idp.xml<\/p>\n\n\n\n
2. Locate the \u201c<EntityDescriptor>\u201d tag, and copy the value of the \u201centityId\u201d attribute:<\/p>\n\n\n\n
<EntityDescriptor ID=\u201d\u2026\u201d entityID=\u201dhttp:\/\/the-idp-url <\/b>\u201c xmlns=<\/p>\n\n\n\n
3. In pentaho.saml.cfg, set the value of the saml.idp.url property to the copied value<\/p>\n\n\n\n
saml.idp.url=http:\/\/the-idp-url<\/pre>\n\n\n\n3.2 Setting SP Properties<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
1. Comment out the entries (prefix the line with \u201c#\u201d) for saml.sp.metadata.url and saml.sp.metadata.classpath if they\u2019re uncommented<\/p>\n\n\n\n
2. Uncomment the line for saml.sp.metadata.filesystem if it is commented<\/p>\n\n\n\n
3. Change the value of the saml.sp.metadata.filesystem to:<\/p>\n\n\n\n
saml.sp.metdata.filesystem=\/pentaho6\/server\/biserver-ee\/saml\/pentaho-sp.xml<\/pre>\n\n\n\nThe other property that is configurable for the Service Provider is saml.sp.metadata.entityId. It has a case sensitive value that defaults to \u201cpentaho\u201d. 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.<\/p>\n\n\n\n
3.3 Setting the Keystore Properties<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
1. Comment the saml.keystore.url and saml.keystore.classpath properties with \u201c#\u201d if they are uncommented<\/p>\n\n\n\n
2. Uncomment saml.keystore.filesystem if it is commented with \u201c#\u201d<\/p>\n\n\n\n
3. Change the value of saml.keystore.filesystem to:<\/p>\n\n\n\n
saml.keystore.filesystem=\/pentaho6\/server\/biserver-ee\/saml\/saml.keystore.jks<\/pre>\n\n\n\n4. 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 \u201csaml,\u201d which would be configured as:<\/p>\n\n\n\n
saml.keystore.default.key=saml<\/pre>\n\n\n\n5. Locate and set the keystore password with the saml.keystore.password property. This should match the password used as the \u2013storepass argument when you obtained a SAML signing certificate in the \u201cCreate a SAML Assertion Signing (and Encryption) Certificate and Keystore\u201d section of this document.<\/p>\n\n\n\n
saml.keystore.password=changeit <\/b><\/pre>\n\n\n\n6. If any of your certificate private key passwords include the colon \u201c:\u201d character, change the saml.username.password.delimiter.char property to a valid delimiter character not included in any of the key passwords.<\/p>\n\n\n\n
7. Provide a comma separated list of username<delimeter>password to allow the Pentaho Plus SAML plugin to read private keys in the saml.keystore.private.username.passwords property:<\/p>\n\n\n\n
saml.keystore.private.username.passwords=saml:changeit,saml2:changeit<\/pre>\n\n\n\n3.4 Enable the SAML Plugin<\/h3>\n\n\n\n
1. Shut down the BA Server if it is running<\/p>\n\n\n\n
2. Open $PENTAHO_HOME\/server\/biserver-ee\/pentaho-solutions\/system\/pentaho-spring-beans.xml for editing<\/p>\n\n\n\n
3. Locate the line containing \u201c<import resource=”applicationContext-spring-security-jdbc.xml” \/>\u201d and add the following line below it:<\/p>\n\n\n\n
<import resource=\"applicationContext-spring-security-saml.xml\" \/><\/pre>\n\n\n\n4. Save and close the file<\/p>\n\n\n\n
5. Open $PENTAHO_HOME\/server\/biserver-ee\/pentaho-solutions\/system\/security.properties for editing<\/p>\n\n\n\n
6. Change the provider on the first line to \u201csaml\u201d. Once completed, the line will read:<\/p>\n\n\n\n
provider=saml<\/pre>\n\n\n\n7. Save and close the file<\/p>\n\n\n\n
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\u2019s Name ID provided by SAML will appear in the top right hand corner of the page.<\/p>\n\n\n\n
Note<\/b>: 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.<\/p>\n\n\n\n
Summary<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
Reference:<\/h4>\n\n\n\n
Pentaho+<\/h4>\n\n\n\n
\u2022 Source Code: \/Samples for Extending Pentaho\/Reference Implementations\/Security\/SAML 2.0<\/p>\n\n\n\n
\u2022 Resources: \/Samples for Extending Pentaho\/<\/p>\n\n\n\n
OKTA<\/h4>\n\n\n\n
Setup SAML application in OKTA<\/p>\n\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
SAML is a specification that provides a means to exchange authentication, and authorization of the \u201cprincipal\u201d <\/p>\n","protected":false},"author":23,"featured_media":1134,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[424],"tags":[433,434,435,436,437],"class_list":["post-206","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-pentaho","tag-okta","tag-pentaho-authentication","tag-saml-2-0","tag-saml-and-pentaho","tag-single-sign-on"],"acf":[],"_links":{"self":[{"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/posts\/206","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/users\/23"}],"replies":[{"embeddable":true,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/comments?post=206"}],"version-history":[{"count":3,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/posts\/206\/revisions"}],"predecessor-version":[{"id":11462,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/posts\/206\/revisions\/11462"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/media\/1134"}],"wp:attachment":[{"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/media?parent=206"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/categories?post=206"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tenthplanet.in\/blogs\/wp-json\/wp\/v2\/tags?post=206"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}