Use SAML to enable SSO for your XS App on SAP HANA rev 92 or later
This blog post will give you step-by-step instructions to enable your XS app to authenticate existing users from your SAP BI, NW, BW or your non-SAP apps.
I now have the pleasure of rewriting my previous blog on this topic that consisted of 2 documents. This blog post may be a little longer due to the explanations and screenshots, but the process is simpler and much faster to implement based on the many enhancements in HANA SPS08 and SPS09.
Here is how I enabled SAML authentication for my XS app using SAP HANA rev 92. Special thanks to Markus Strehle for his many contributions to this blog.
You must be using SAP HANA rev 92 or later. This guide will NOT document how to set up an Identity Provider (IDP) for SAML or teach you how to develop an XS application. It assumes that you already have access to an IDP and have access to an administrator of the IDP. Chances are that you already have a SAML IDP set up in your company. If not, you can use the SAP BI Platform, the NetWeaver SSO product, or SAP’s own cloud-based ID Service (SAP IDS) as your IDP (see the Further Reading section for more on those products).
Fortunately you will no longer need access to the HANA Linux environment nor require the Linux admin user ID for your HANA instance. You also will no longer need to download and install crypto libraries since they are now installed with SAP HANA.
You will need a HANA user ID that has been assigned the following roles to administer the SAML configuration tool:
Plan your configuration
You should be familiar with SAML concepts and may wish to read the following sections of the SAP HANA SPS09 Administration Guide:
- 5.4 Managing Trust Relationships
- 5.5 Maintaining SAML Providers,
- 5.10 Maintaining Single Sign-On for SAP HANA XS Applications
Before you begin, discuss your plans with the security administrator of your SAML IDP and your XS development team.
- Step1: Enable SSL Encryption (May be optional or required by your IDP)
- Step 1a: Create the Certificate Request
- Step 1b: Send the Certificate Request to a Certificate Authority to be signed
- Step 1c: Confirm HTTPS and SSL are Working
- Step 2: Setup the SAML IDP and Trust Relationship
- Step 2a: Get your IDP certificate information
- Step 2b: Add Your IDP
- Step 2c: Add Service Provider
- Step 3: Configure your IDP and Application
- Step 3a: Register your App with your IDP
- Step 3b: Configure App
- Step 4: Modify your XS Application Code
- Step 4a: Using Named Users
- Step 4b: Set Default Role for Dynamically Generated Users
- Step 4c: Implement Logout Code
- Step 4d: Retrieving User Information from the IDP (Optional)
Step1: Enable SSL Encryption (May be optional or required by your IDP)
Important Note: Using SSL may be optional depending on your company’s security policy and SAML configuration.
SAP HANA uses the Extended Application Services (XS) Engine as a lightweight web application. HANA leverages SAP’s existing Web Dispatcher to act as a proxy relaying communication between front-end http requests and HANA’s back-end XS Engine.
At the time this document was written the SAP HANA hardware vendors do not deliver the HANA appliance with SSL/HTTPs enabled for the XS Engine/Web Dispatcher. These next steps will enable secure HTTP communication with the XS Engine using SAP’s Common CryptoLib libraries and an SAP CA evaluation certificate for use in development or test environments.
These steps are a supplement to the HANA security guide. If you are interested in securing HANA communication with OpenSSL please see this document. Note that OpenSSL is only supported for SQL connectivity to SAP HANA. The Web Dispatcher in SAP HANA does not support OpenSSL.
Symptoms to Resolve
The HTTP protocol should be working for communication with SAP HANA’s XS Engine when we navigate our browser to http://<host_name>:<xs_port>.
However, https protocol may or may not be working. In general (with rev 92 or later), a self-signed certificate should automatically be generated and SSL should automatically work. Note: If you delete your SAPSSLS.pse file and restart your web dispatcher the new PSE file should contain a newly generated self-signed certificate. See SAP Note 2014996 for more information regarding this new feature.
To test using https point your browser to https://<host_name>:<xs_ssl_port>. Note we use https as the protocol and use the SSL port for your XS engine. This should be 43<instance_nbr> (e.g. 4300 for HANA instance 00).
You may see a warning message from your browser, such as the following screen. You can work around this warning message by clicking “Advanced” (in Google Chrome) or “Continue to this website” (in Internet Explorer).
If you do not have an SSL certificate properly installed in your SAPSSLS.pse file you may see a different error when you go to https://<host_name>:<xs_ssl_port>.
If you receive an error you may view the details in your SAP HANA web dispatcher trace file. This file can be viewed, from the HANA Studio. Just double click on your system, select the Diagnosis Files tab and open the latest file starting with the “webdispather” prefix and “webdisp” suffix.
Important Note: If your page loaded properly but you wish to avoid the warning, you must install an evaluation or a signed certificate. If, for now, you are okay receiving the warning, you can skip ahead to Step 2 to configure your SAML authentication.
Step 1a: Create the Certificate Request
Here we will create a request for an evaluation certificate to use for our SSL encryption from a CA (certificate authority). We will use the Web Dispatcher Administration tool. These next steps should alleviate the need for a warning message when accessing our site via SSL.
Open the URL below with a browser.
Click on “PSE Management” from the navigation pane.
Keep the selection of SAPSSLS.pse and click the “Create CA Request” button.
Note: for more information regarding the various PSE files, see SAP Support Note 2009878.
Select and copy all of the text in the first text area. You will provide this information to your CA.
Step 1b: Send the Certificate Request to a Certificate Authority to be signed
This guide will generate a free evaluation certificate from SAP’s website.
Browse to http://service.sap.com/trust
Click “SSL Test Server Certificates”.
Then click the Test it Now! button that appears in the main canvas.
Paste the request text from the previous step into the Order SSL Server Test Certificate page shown here, choose the server type “PKCS#7 certificate chain”, and click the Continue button
SAP returns the signed certificate as text. Copy this text to your clipboard. You may choose to save the copied text into a local file using your favorite text editor for later reference.
Switch back to your Web Dispatcher Administration screen and paste the text into the “Import CA Response…” text area. And click “Import”
Note: If you previously closed this page, click on “PSE Management” in the navigation bar. Make sure SAPSSLS.pse is selected at the top of the screen. Then click on the “Import CA Response” button. Paste the certificate text into the text area and click import.
You should see a message stating that the CA-Response was imported into the SAPSSLS.pse and you should see certificate details in the “PSE Attributes” section of the page.
Step 1c: Confirm HTTPS and SSL are Working
If everything is working as expected, then SSL should now be enabled.
You can now call your XS Engine using the SSL port for your XS engine. This should be 43<instance_nbr> (e.g. 4300 for HANA instance 00). Type the URL into your browser.
You may see a warning if your browser does not have the root certificate for the CA in its certificate store. You can click “Advanced” (in Chrome) or “Continue to this website” (in Internet Explorer) to proceed.
If you used the SAP evaluation certificate, you can save and import the SAP Server root certificate into your browser’s trust store. Just save the certificate file from here: https://tcs.mysap.com/invoke/tc/getCert?SAPServerCA.der and then double click on the file from Windows Explorer and follow the import wizard.
If everything went well you are now looking at the XS engine screen again, but now using your evaluation certificate and SSL!
If it does not work, you can check the trace file for the web dispatcher by clicking on the “Trace” link in the navigation bar of the Web Dispatcher Administration tool as shown below. Or, as shown earlier, the trace file can also be viewed from the HANA Studio.
- If you are using HANA One on AWS, you will need to make sure you open your target (SSL) port as needed.
- As needed, from HANA Studio, you may change various web dispatcher settings in the [profile] section of the webdispatcher.ini file. A restart of the web dispatcher service is no longer required for parameter changes to take effect.
Step 2: Setup the SAML IDP and Trust Relationship
The next steps will walk you through gathering your IDP information, then adding that information to your SAP HANA configuration. This will tell HANA which IDP to trust and use when authenticating your application users.
Note for this section you will need the following roles assigned for your HANA user account.
Note: See section 5.10 [Maintaining Single Sign-On for SAP HANA XS Applications] of the SAP HANA Administration Guide for further support and reference on how to configure SAML settings for XS.
Step 2a: Get your IDP certificate information
Here you must gather the IDP metadata from your IDP service. In this example I will use the SAP’s cloud-based ID service (SAP IDS) as my SAML IDP. Again, you must choose your IDP which may be internal to your company. It may even be the SAP IDS or an IDP offered by SAP software such as the SAP BI Platform, the NetWeaver SSO product (see the Further Reading section for more on those products).
You will need the metadata URL for your IDP. For example, the metadata URL for the production SAP IDS service is: https://accounts.sap.com/saml2/metadata/accounts.sap.com
Note: Of course you should always start with a development or QA system, NOT a production system.
Once you know the appropriate metadata URL for your desired IDP, open the URL using your favorite browser. You will be copying some XML content – so right-click and select “View page source”.
Now select ALL of the text and copy it into your clipboard. You will use this content in the next step.
Step 2b: Add Your IDP
Open the URL below with a browser. This time use the https:// protocol and port number (43<instance_nbr>)
Note 1: If you will not use SSL for your site that is okay as long as your SAML IDP allows support for the HTTP protocol.
Note2 : In my screen shots below I did not use the SSL protocol and port. That is okay too, but before I copy my metadata (in a later step) I will have had to open the tool using SSL. I will point out where this occurs.
Login using the SYSTEM user ID or a user ID that has the following role assigned.
Role required: sap.hana.xs.admin.roles::SAMLAdministrator
Click on the menu icon and then click on “SAML Identity Provider”
You will then see the following screen.
Click the Plus “+” icon to add a SAML IDP.
You will see a form to enter the IDP metadata.Now paste in the content that you copied in the previous step. When you click in any of the fields in the “General Data” section, the XML content that you pasted should be reformatted and the “General Data” fields should automatically be populated as shown below.
Click to activate the checkbox for “Dynamic User Creation”
Note: Checking the box to enable dynamic user creation will automatically add a database user ID for each user as they first log in to your XS application. This is highly recommended, unless you are planning to use a single technical user ID for all users or if you will provision all HANA user IDs by some other method.
You should see a fleeting message stating that the IDP was successfully saved and then you should see the IDP listed in the “SAML Identity Provider List”.
So what just happened? Quite a bit actually.
Pressing the “Save” button added our IDP as well as established a trust relationship with the IDP. The certificate from the IDP was contained in the metadata that you pasted. This certificate was imported into the “sapsrv.pse” file.
To view the certificate and ensure it was loaded, click on “Trust Manager” from the navigation bar and select SAML. Then click on “Certificate list” you should your IDP’s certificate listed.
Note: You can also view the certificates stored in the “sapsrv.pse” from the Web Dispatcher Administration tool that we used in Step 1. This is completely optional. To see the certificate using this approach, you need the following role:
If you have this role assigned to your user account, you can go to the following URL.
Click PSE Management and select “sapsrv.pse”. If the certificate was imported properly you should see the certificate in the “Trusted Certificates” section of the screen.
Step 2c: Add Service Provider
Now from the XS Administration Tool, click the menu icon and click “SAML Service Provider”
Fill in information about your organization and name your service provider.
You should see a fleeting “success” message.
Step 3: Configure your IDP and Application
Step 3a: Register your App with your IDP
If you will use SSL for your site, and if you did not use SSL when opening the XS Admin tool, you must do so now. Point your browser to:
Click “SAML Identity Provider” from the navigation bar.
Copy all of the text in the Metadata text box shown on the screen.
Important Note: Notice that when you view this page with HTTPS in your URL the metadata uses the HTTPS protocol and port number. This is important to properly set up the IDP configuration for our XS URL (if you will be using SSL for your site).
Save this text in a local file named as you wish, but with an XML file extension (e.g. myXsAppMetadata.xml).
Note 1: If you prefer or are required to instead send an endpoint URL that provides the metadata you can use the following link, based on your host name and port. Again, use your SSL port if you will use SSL.https://<hostname>:<ssl_port>/sap/hana/xs/saml/info.xscfunc
Note 2: If you wish to return user attributes back to your application other than default attributes configured by your IDP, you must modify the XML file that you created. The SAP IDS returns the user’s email address, company, first and last names by default so that they may be accessed by your application.
But if there was a special field, let’s say “nickname”, I would have to insert XML in my XML file to request that the field be returned. I will not go into details in this blog, but this may be documented by your IDP provider.
Now you need to submit this file (or the endpoint URL) to the administrator of your IDP so that they can create an entry to recognize your Service Provider that you just configured. You may need to email the file or submit the contents via a web form. It depends on your company policy.
Note: While you wait for the activation confirmation from your IDP team, you may wish to continue with the next steps. Of course nothing will work until they complete the necessary set up on their end.
Step 3b: Configure App
Here we will configure our XS application to use SAML authentication.
Role required: sap.hana.xs.admin.roles::RuntimeConfAdministrator
From your XS Admin tool, select “XS Artifact Administration” from the navigation bar.
Select the arrow next to your package. In my case I will select the package mycorp.myapp. Youmay choose to just select a parent package depending on your application’s package layout.
After you have navigated to your package, click “Edit”.
Activate the “Force SSL” checkbox if you want to enforce SSL.
Activate the “SAML” checkbox and select your IDP from the dropdown.
Uncheck all other authentication options such as “Form based” and “Basic”.
You should see a fleeting success message such as the one above.
Note: These authentication settings override the authentication settings that you may have in your .xsaccess file for your application and its individual packages.
I am attaching actual code in the form of a delivery unit that you may wish to use to test your configuration. This sample code accesses the fields returned by SAP IDS and displays them along with providing a logout button. Just place the files in your mycorp.myapp package (minus the “.txt” extension. Also add an empty “.xsapp” file to the folder. To test this sample app, point your browser to https://<host>:<ssl_xs_port>/mycorp/myapp/saml.html
At this point, you can test your SAML authentication once you received confirmation from your IDP team that they have configured your application in the IDP system. However, please continue on to step 4 to learn more about how your XS code should work with SAML.
Step 4: Modify your XS Application Code
Package Layout and Other Development Considerations
Your XS application needs a clear security model. Will you have different levels of security for each package? Will you allow database connectivity for named user IDs or maybe just one technical user ID? Answers to these questions fall outside the scope of this blog.
However, you must consider your authorization requirements early in your development and may choose to organize your package hierarchy accordingly. For example you may want to organize your application into 3 primary packages: a public package, a user package and an admin package. Each of these packages can be granted different authentication and authorization policies.
In this blog I will provide the steps to use named users and secure the entire app (the root package of the app) with one authentication policy using SAML. We will also demonstrate how to assign a default role to new users logging into the system.
Step 4a: Using Named Users
Because we set the option to dynamically generate database users in Step 2b above, our code to get the database connection does not need to take the user ID as a parameter. See sample code below.
var conn = $.hdb.getConnection();
Each user will access the database with his/her own user ID that is automatically generated for us. Not too bad!
Step 4b: Set Default Role for Dynamically Generated Users
Double click on your system in the Systems tab of HANA Studio. Click on the Configuration tab and add the parameter defaultrole under indexserver.ini->saml. Set the value to be the name of a role that you have defined.
Now new users that login to your app will be assigned your specified role by default.
Note: I did not get it to work using the syntax of a design-time role. So I created a run-time role and assigned the design time role to it.
Step 4c: Implement Logout Code
To provide logout logic you must call the following url: /sap/hana/xs/formLogin/logout.xscfunc
You can invoke the call to the URL when a user clicks on a logout button or link in your application.
Logout button logic
<form action=”/sap/hana/xs/formLogin/logout.xscfunc” method=”post”>
<input type=”hidden” name=”X-CSRF-Token” value=””>
<input type=”hidden” name=”x-sap-origin-location” value=”/sap/hana/xs/formLogin/”>
<input type=”submit” value=”Logout”>
Step 4d: Retrieving User Information from the IDP (Optional)
SAML user attributes can be accessed from your XSJS code with the following code. Notice that there are two syntax options to choose from here.
var value = $.session.samlUserInfo[“<name>”];
var value = $.session.samlUserInfo. <name>;
A valid example could be
var response_string=$.session.samlUserInfo[“first_name”] + ” “ + $.session.samlUserInfo[“last_name”] + ” (<a href=mailto:” + $.session.samlUserInfo[“mail”] + “>” + $.session.samlUserInfo[“mail”] + “</a>). You logged on via SAML from company “ + $.session.samlUserInfo[“company”];
Create your Own Registration Experience (Overlay)
The SAP IDS SAML identity provider and other IDP’s offer the ability to customize your login and registration experience. Review your IDP documentation for details.
Assertion did not contain a valid MessageID.
If you receive the above error message when logging in to your app then your XS app is considering the response from your IDP as having timed out. You can change the timeout setting as needed by following these steps.
Double click on your system in the Systems tab of HANA Studio. Click on the Configuration tab and add the parameter assertion_timeout under indexserver.ini->saml. Set the value to be the number of seconds before a timeout takes place. The default value is 10.
Try deleting PSE and Restart the XS Engine
If you have issues that you ultimately cannot resolve, you may choose to delete the 2 PSE files that we modified and then restart the XS Engine to have them recreated in their original form. Note: New certificates being generated results in the need to reconfigure your IDP to recognize and trust your application.
From HANA Studio, double-click on your SYSTEM name from the “Systems” tab. From the landscape tab, right-click on the “xsengine” row and select “kill”.
Alternatively you can type HDB stop and then HDB start from a Linux prompt to restart the whole HANA server.
If you need to open a support ticket with SAP, you can assign your ticket to one of the following two components: HAN-DB-SEC or BC-SEC.