Setting up SAP BusinessIntelligence BI Platform SAML single sign on with Microsoft Azure AD as the Identity Provider

I have co-author this guide with Francisco Almeida, BI Lead Consultant for DXC Oxygen.
There is already a very good guide on how to set this on up, but in here we have emphasized the practical side of the setup and focused on the order they should be performed:

https://blogs.sap.com/2018/03/01/saml-integration-between-microsoft-azure-portal-and-sap-business-intelligence-platform/

There are some small differences in the order and steps, and this is because we found this approach was most likely to return the expected result as we implemented this in a real World scenario. There are also a few practical suggestions you may find useful.

This configuration has been applied to BI 4.2 SP05 and SP06. Not all screenshots were taken from the same system, so some may have been pixelated to avoid confusion.


BOE preparation configuration

1. If your deployment is already configured for HTTPS, you can skip this step; otherwise, you can contract a third-party certificate authority, or create a self-signed certificate (which will throw a warning in your browser). To go with the self-signed certificate, run the command below, which will create a keystore and alias:

keytool -genkey -alias thisAlias -keyalg RSA -keystore C:\keystore\thisKeystore -keysize 2048

Please note thisAlias and C:\keystore\thisKeystore should be changed to reflect your organisation’s naming conventions, and you will need to create a password and fill out details for like company name, state, etc.

2. Locate <BOE Install Dir>\tomcat\conf\server.xml and create a backup of the file, then edit it to enable the https connector. To do that, uncomment it and change it to look like this:

Note: thisAlias, C:\keystore\thisKeystore and thisKeystorePassword will need to match the values you used in the previous step

3. Restart tomcat and make sure you can connect to tomcat using https://myserver

Note: myserver here is the name of the host where tomcat is installed. Do not proceed if you cannot.

4. Copy all .jar files from: 

<BOE Install Dir> \SAP BusinessObjects Enterprise XI 4.0\SAMLJARS\
to:
<BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\lib\

Note: the changes below will make the BI and BILaunchpad apps inaccessible. If you are on 4.2 SP06, and want to include CMC in the SAML SSO, do not configure it now. Come back to configure CMC only after you have gone through all configuration steps and tested that it works, otherwise you may find yourself locked out of the CMC.

5. Create a backup copy of the file below, and edit the original to uncomment the apps you want to use. In the case below, we have removed the leading “<!--" and trailing “-->” from OpenDocument and BILaunchpad (this is the “fiorified” one). The line for the classic BI Launchpad was already uncommented. Save the changes but you can keep this file open as we will return to it later.

<BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\securityContext.xml

6. Locate (or, if they do not exist, create) the files below, and make sure the property saml.enabled=true is configured in both:

a. <BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\config\custom\BIlaunchpad.properties

b. <BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\config\custom\FioriBI.properties

7. At this point BI and BILaunchpad should be inaccessible.

8. Locate <BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\web.xml and uncomment the SAML parameters:




9. Launch a command line shell and navigate to <BOE Install Dir>\SAP BusinessObjects Enterprise XI 4.0\win64_x64\sapjvm\bin and execute the command below:

keytool -genkeypair -alias analias -keypass Password1 -keystore "D:\Program Files (x86)\SAP BusinessObjects\tomcat\webapps\BOE\WEB-INF\sampletestKeystore.jks" -validity 735

Define the alias (we used analias in the example above), give it a password (we used Password1) and chose a pre-existing keystore to generate it (we used the sampletestKeystore.jks). You will be asked the password of the keystore (the password for sampletestKeystore.jks is Password1) and further details.

10. Now go back to that open file <BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\securityContext.xml and update it with the keystore name, alias and password:



11. If you use BOE tomcat’s hostname to access BOE (such as https://myserver:8443/BOE/BI) you can skip this step; if you have a more sophisticated setup with a load balancer and two or more tomcat hosts, you need to declare that in the same securityContext.xml file. Comment out the generic context provider and create a new one as below (you need to replace boe.itrust.co.nz from the screenshot below with your URL and the port is defined in your tomcat’s server.xml configuration file):



Also here:



12. You can finally save and close this file and replace the existing one (you have a backup, right?)

13. Now is time to set up the trust between tomcat and the CMS. Create the file <BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\config\custom\global.properties (or change if existing) to contain the following text:

sso.enabled=true

trusted.auth.shared.secret=MySecret

trusted.auth.user.param=MyUser

trusted.auth.user.retrieval=WEB_SESSION

14. Log on to the CMC and generate a new shared secret by clicking in the “New Shared Secret” after you set the validity period and request timeout. Please note SAP recommends that the request timeout is not set to zero for security reasons.



15. Click on “Download Shared Secret” to download the file TrustedPrincipal.conf in your browser, and copy it over to the server(s) where the CMS service runs, into the following directories, so that the CMS will trust tomcat:

a. <BOE Install Dir>\SAP BusinessObjects Enterprise XI 4.0\win64_x64\

b. <BOE Install Dir>\SAP BusinessObjects Enterprise XI 4.0\win32_x86\

16. Preparation is done, now you need to stop Tomcat, and navigate to the work directory, where you should find the directories below, and delete these cached files (they will be recreated when you start tomcat again):

<BOE Install Dir>\tomcat\work\Catalina\localhost\

17. Start tomcat. Any errors in removing the comments, pointing to the keystore and password typos in the XML configuration files could cause tomcat not to rebuild the /BOE app and 404 page not found errors or even 500 ones.

18. Download the metadata XML by accessing the URL below, so the file can be sent to the Azure Specialist:

https://boe.itrust.co.nz/BOE/saml/metadata

Note: if you download the XML prior to this step, it may return a page not found error or it may download an XML with the wrong path in it – hence why this should be a late step.



If you get an error 404 page not found or similar, that means you should revisit the configuration steps, especially the on the securityContext.xml file. Open it in a browser to see that it looks right.

19. Now you need to wait for the Azure specialist to work his/her magic.

Azure AD Configuration (Identity Provider)
From the Azure Portal:

1. Click on Azure Active Directory

2. Click on Enterprise applications

 

1. Click on All applications

2. Click on New application



1. Click on Non-gallery application

2. Give the application a name

3. Click on Add



1. Click on Single sign-on

2. Select SAML-based Sign-on

3. Select the metadata file exported from the application

4. Click on Upload



1. Make sure user.userprincipalname is selected as the User Identifier

2. Download the Certificate (Base64)

3. Download the Metadata XML

4. Click on Save



Resume BOE configuration

1. The Azure specialist will download the metadata XML file and send you that file. Whatever the name of the file, you need to rename it to idp-meta-downloaded.xml and placed under <BOE Install Dir>\tomcat\webapps\BOE\WEB-INF\

This is because your securityContext.xml file expects to find it there:



2. Manually create a BOE account in CMC using the format used by Azure (usually firstname.lastname@domain.com) and try to log on to BI or BILaunchpad as normal. You should be greeted by the IdP (Azure) screen:



3. If you get the password right, this should redirect you to the BI / BILaunchpad, and automatically log you in – success!



4. We have seen some errors here where you get the Microsoft logon error or a 404 on URL /BOE/saml/metadata not found. These were caused by errors in the xml configuration file or failing to use the load balancer specific configuration mentioned above



5. We have also noticed errors when we moved on to configure other environments and tried to re-test the previous ones. This was resolved by clearing the cache of the browser. Make sure you do that every time you test SAML SSO.

6. Another possible issue you may run into is with the BILaunchpad – please remember to update the CMC > Applications > RESTful Web Services to the URL you are using, if different from a single server installation

7. If everything works, copy the changed configuration files to <BOE Install Dir>\SAP BusinessObjects Enterprise XI 4.0\warfiles\webapps\BOE\ otherwise the configuration will be lost in the next patch or service pack deployment

8. The SSO/SAML configuration may be finished, but for every account, an enterprise alias will have to be created. This can be done manually for each account, or by importing a file on CMC > Users and Groups > Manage > Import. Still, someone will need to map an S4 or BW account to the enterprise alias because they will most likely not match. If this is not your scenario, then your work is done.

9. If you need to find a way to automate the user creation and association, and you have the user’s email associated with his/her SAP account, you can develop an SDK script to use that information to automatically create an Enterprise alias and associate it with the SAP alias. We have developed a jar file (AddEntAlias) based on Business Objects’s SDK that reads an existing SAP account email property, creates and Enterprise alias, associate both accounts and renames the account to that email address, so that an SAP account like S4D~100/FALMEIDA would end up looking like francisco.almeida@itrust.co.nz, and mapped to the S4D alias automatically. This jar file can be scheduled to run after the SAP alias update.

10. If you want to use it, please read this disclaimer first. This SDK-based jar has been superficially tested with an SAP BI 4.2 SP05 system, but we cannot guarantee that it will work or that it will not cause any issues. So before using any SDK for the first time (and even if you use it all the time), make sure you have a backup of your hosts, your bootstrap files, your CMS database and your File repositories before proceeding. Also, please try this in a non-production environment before you try that in live production systems. To use it, download the file from here (password=readChomsky*), then log on to your CMC > Folders, select a location for it and click Manage > Add > Program File > click on Choose File select the file which you have just downloaded, select Java then hit OK.



11. Make sure you add the Classname to the Properties > Program Parameters of that file:



12. Now every time you want to run it, you need to use the Arguments: field (which can be changed on every scheduled job) to allow the script to log in and get its session with the CMS. So you need to specify the CMS to log the script in to, the user account you want to use to log the jar file into the system, the password, and the group that the script should run for. This group will be the only group that should be affected.

13. Each argument is separated by a space character; below is an example of how the Arguments: field could be filled out:

WIN-A2302R6200I administrator Ap@ssw0rd Everyone

This would log in to CMS WIN-A2302R6200I as the administrator and change all users because the group Everyone is specified. The following users are ignored: Administrator, Guest, users that already have an Enterprise account and SAP accounts that do not have an email associated with them. If there are 2 identical email addresses or 2 users could be created with the same ID, the script will throw an error and fail.