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

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 the configuration steps 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

• 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.

• 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:

Figure 01 – server.xml

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

• 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.

• 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\

• 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

Figure 02 – securityContext.xml

• Locate (or, if they do not exist, create) the files below, and make sure the property enabled=true is configured in both:
  1. <BOE  Install  Dir>\tomcat\webapps\BOE\WEB-INF\config\custom\BILaunchpad.properties
  2. <BOE  Install  Dir>\tomcat\webapps\BOE\WEB-INF\config\custom\FioriBI.properties
• At this point BI and BILaunchpad should be inaccessible.
• Locate <BOE  Install  Dir>\tomcat\webapps\BOE\WEB-INF\web.xml and uncomment the SAML parameters:

Figure 03 – web.xml

Figure 04 – web.xml

• 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.
• 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:

Figure 05 – securityContext.xml

• 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 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):

Figure 06 – securityContext.xml

Also here:

Figure 07 – securityContext.xml

• You can finally save and close this file and replace the existing one (you have a backup, right?)
• 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

• 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.

Figure 08 – Creating new share secret in CMC

• 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:
  4. <BOE  Install  Dir>\SAP BusinessObjects Enterprise XI 4.0\win64_x64\
  5. <BOE  Install  Dir>\SAP BusinessObjects Enterprise XI 4.0\win32_x86\
• 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\

Figure 09 – Tomcat’s work directory folders

• 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.
• 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.

Figure 10 – Downloading metadata XML file

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.

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

Azure AD Configuration (Identity Provider)

From the Azure Portal:

• Click on Azure Active Directory
• Click on Enterprise applications

Figure 11 – Azure AD Enterprise Applications

• Click on All applications
• Click on New application

Figure 12 – Azure AD Applications

• Click on Non-gallery application
• Give the application a name
• Click on Add

Figure 13 – Azure AD New Application

• Click on Single sign-on
• Select SAML-based Sign-on
• Select the metadata file exported from the application
• Click on Upload

Figure 14 – Azure AD Application SSO Configuration

• Make sure user.userprincipalname is selected as the User Identifier
• Download the Certificate (Base64)
• Download the Metadata XML
• Click on Save

Figure 15 – Azure AD SSO Configuration

Resume BOE configuration

• 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 place it under <BOE  Install  Dir>\tomcat\webapps\BOE\WEB-INF\

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

Figure 16 – securityContext.xml

• 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:

Figure 17 – Azure authentication screen (this password challenge would be bypassed if the user had already authenticated to a Portal)

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

Figure 18 – Single sign on to the BILaunchpad – success!

• 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
• 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.
• 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
• 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
• 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.
• 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.
• 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.

Figure 19 – Adding a Program file via the CMC

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

Figure 20 – Configuring the Program’s parameters

• 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.
• 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.

SAML token lifecycle

Once the solution is configured, SSO works, however it will eventually stop working due to a limitation of the spring plugin.

When a user first authenticates with Azure, their tokens are given a lifetime of 1 hour (default Azure configuration). That is the “access token” lifetime.  Once the lifetime (1 hour) is reached, Azure keeps the user authenticated by using a “session token” (which happens in the background, without user interaction), and the lifetime of this token can be something like 14 days up to “until-revoke”. Newer configurations would have “until-revoke” as the default value in Azure.

Spring, however, does not seem to accept such a long lifetime for the token. By default, the oldest tokens accepted by Spring are 2-hour old ones. At this point, unless you renew your Azure token manually by logging on again, Spring will not accept the token anymore, and Business Objects will redirect the user to a 404 HTTP error page. This is a known issue, as per SAP note 2672379.

Other resources and applications (that do not depend on Spring) will continue to work with the same token with no problems.

To resolve this, one needs to expand the 2-hour limit in Spring. It can be expanded up to 24 days and no further. This is the solution recommended in the SAP note mentioned above, and it requires changing the securityContext.xml file to add a parameter (maxAuthenticationAge) and set a value (in seconds) to it.

This configuration alone, however, does not necessarily resolve the problem, and that will depend on how your Azure session token is configured. If it is configured to “until-revoked”, then this set up would probably start failing after the token becomes older than 24 days (or whatever new limit was configured for Spring).

In Azure, there are two properties that determine the token session lifetime: one for single factor authentication (i.e. password only), and one for multil factor authentication (password plus another method, such as phone tokens). The first is MaxAgeSessionSingleFactor and the latter, MaxAgeSessionMultiFactor. The several token parameters can be found here: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-configurable-token-lifetimes

These session lifetime parameters needs to be set to a value smaller than the one set for Spring, so that the Azure token is forced to renew before this interval. So if one configured Spring to have a maxAuthenticationAge of 4 days, the Azure parameters MaxAgeSessionSingleFactor  and MaxAgeSessionMultiFactor would need to be set up to 4 days at the longest. In the example below, it is set to 3 days:

This article was written by:

Francisco Almeida

DXC Oxygen BI Lead Consultant

Felipe Binotto

Microsoft Solutions Consultant