So you want to use SAML to support single sign-on and secure your SAP HANA XS web application? Who doesn't? 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.
Here is how I enabled SAML authentication for my XS app. I have performed these tasks in both rev 67 and rev 70 versions of HANA. I will refer to an SSL guide posted by Erik Lemen and a SAML/XS one posted internally by Bjoern Friedmann. Let's get to work!
Pre-requisites
This guide will NOT document how to set up an Identity Provider (IDP) for SAML. 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).
Additionally you will need access to the HANA Linux environment using the Linux admin ID setup for your HANA instance. You also will a HANA user ID that has been assigned the following role to administer the SAML configuration tool: sap.hana.xs.admin.roles::SAMLAdministrator
Plan your configuration
You should be familiar with SAML concepts and may wish to read section 5.4 in the SAP HANA SPS07 Administration Guide. Before you begin, discuss your plans with the security administrator of your SAML IDP and your XS development team.
Task Overview
1. Step1: Setup SAP Crypto Library, SSL (May be optional) and Trust Store
a. Step 1a: Set up SAP Crypto Library and Trust Store Utility
b. Step 1b: Turn on SSL Encryption
c. Step 1c: Create Trust Store
d. Step 1d: Setup the trust relation with the IDP
e. Step 1e: Restart the XS Engine
2. Step 2: Configure your XS Application
a. Step 2a: Add IDP
b. Step 2b: Add Service Provider
c. Step 2c: Register your App with your IDP
d. Step 2d: Configure App
3. Step 3: Modify your XS Application Code
a. Step 3a: Using Named Users
b. Step 3b: Set Default Role for Dynamically Generated Users
c. Step 3c: Implement Logout Code
d. Step 3d: Retrieving User Information from the IDP (Optional)
Step1: Setup SAP Crypto Library, SSL (May be optional) and Trust Store
Step 1a: Set up SAP Crypto Library and Trust Store Utility
Follow the steps in Section 1 (Only) of the attached document (a modified version of this document created by Erik Lemen).
- STOP after completing section 1 of the attached instructions.
Step 1b: Turn on SSL Encryption
Important Note: This may be optional depending on your company's security policy and SAML configuration
Follow the steps in Section 2 of the attached document (a modified version of this document created by Erik Lemen), BUT FIRST see my notes below based on my findings.
Important Notes:
- DO NOT USE PINS: Don't use a pin for any of the commands – using a pin did not work for me and gave an error - I need to determine why this happened.
- If you are using HANA One on AWS, you will need to make sure you open your target port as needed
Step 1c: Create Trust Store
Type the following commands from a Linux command prompt, logged in as <sid>adm (e.g. hdbadm where your instance name is HDB):
cd /usr/sap/<INSTANCE>/SYS/global/security/lib
mkdir /usr/sap/<INSTANCE>/HDB<InstNo>/<host>/sec
./sapgenpse gen_pse -p /usr/sap/<INSTANCE>/HDB<InstNo>/<host>/sec/sapsrv.pse
Leave PIN empty (2x enter), and as "Distinguished name of PSE owner:" enter CN=<yourhostname>
Step 1d: Setup the trust relation with the IDP
Here you must gather the IDP metadata from your IDP service.
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
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".
Copy the certificate string (which is DER encoded) from the ds:X509Certificate tag. For SAP ID service this is MIICHTCCAYagAwIBAgIETKTcJjANBgkqhkiG9w0BAQUFADBTMQswCQYDVQQGEwJERTEPMA0G...
Using your favorite editor put this into a file called sapid.cer in the directory:
/usr/sap/<INSTANCE>/SYS/global/security/lib
Surround the certificate string with the tags below (there are 5 hyphens before and after the CERTIFICATE tags)
-----BEGIN CERTIFICATE-----
MIICHTCCAYagAwIBAgIETKTcJjANBgkqhkiG9w0BAQUFADBTMQswCQYDVQQGEwJERTEPMA0G...
-----END CERTIFICATE-----
Import this certificate into sapsrv.pse
./sapgenpse maintain_pk -p /usr/sap/<INSTANCE>/HDB<InstNo>/<host>/sec/sapsrv.pse -a sapid.cer
Step 1e: Restart the XS Engine
From HANA Studio, double-click on the SYSTEM you are configuring from the Systems view.
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.
Step 2: Configure your XS Application
Step 2a: Add IDP
Get your IDP Info
Similar to step 1d, you must know the URL for retrieving the metadata for your IDP. For the production SAP IDS IDP I will use the following URL: 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.
Open the URL, right-click and select "view page source". Select all text and then click copy.
Configure IDP Info
Open the URL below with a browser.
http://<host_name>:<xs_port>/sap/hana/xs/admin
Login using the SYSTEM user ID or a user ID that has the following role assigned:
sap.hana.xs.admin.roles::SAMLAdministrator
From the Identity Provider page (under the SAML Configuration menu option), click the icon in the upper-left to add a new IDP. Paste the content, that you just copied, into the metadata field, click Parse, and enter a Name for your IDP (of your choosing).
Click the check box to enable dynamic user creation. Click Save to complete the setup of your IDP in the XS configuration.
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.
Step 2b: Add Service Provider
Fill in the service provider information in the admin screen. The Name field is very important and should match the domain (host) name and URL of your XS engine, including the port number, that users will use to access your system. Use the globally accessible domain name for externally facing systems.
For example, if your XS server splash page is accessible at http://hostname:8021 then enter http://hostname:8021.
Click Save after entering your information. But do not leave the screen yet.
Step 2c: Register your App with your IDP
Copy all of the text in the Metadata text box shown on the screen.
Save this text in a local file named as you wish, but with an XML file extension (e.g. myXsAppMetadata.xml).
Note: If you wish to return user attributes back to your application you can add fields by inserting XML similar to this text below, just before the close tag </md:SPSSODescriptor>. To get the exact XML, you need the field names that are provided by your IDP. This is just an example that will allow me to access a user's profile ID, email, first name and last name.
<md:AttributeConsumingService index="1">
<md:ServiceName xml:lang="en">SAP HANA Answers</md:ServiceName>
<md:RequestedAttribute Name="user_profile_id" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true" />
<md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="false" />
<md:RequestedAttribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="false" />
<md:RequestedAttribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="false" />
</md:AttributeConsumingService>
Now you need to submit this file 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, please continue with the next steps. Of course nothing will work until they complete the necessary set up on their end.
Step 2d: Configure App
Click on the XS Applications link in the upper left menu bar. Edit the setting for your XS package(s) by highlighting each package (or just the parent package), and choosing SAML as shown below. You may need to click on the pencil icon next to the option you are editing. Select your SAML Identity Provider that you created in Step 2a and click Save.
Note: These authentication settings override the authentication settings that you may have in your .xsaccess file for your application and its individual packages.
Step 3: 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 3a: Using Named Users
Because we set the option to dynamically generate database users in Step 2a 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 = $.db.getConnection();
Each user will access the database with his/her own user ID that is automatically generated for us. Not too bad.
Step 3b: 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 3c: Implement Logout Code
To provide logout logic you must create and activate a file within your XS project with the content below. I named my file logout.xscfunc.
Logout.xscfunc
{
"library": "libxsauthenticator",
"factory": "createApp",
"method": "logout"
}
Next you have to create some javascript code shown below that can be accessed once a user clicks on a logout button or link in your application.
Logout button logic
function logout() {
$.ajax({
url: "logic/logout.xscfunc",
type: "POST",
dataType: "json",
success: function(ret) {
document.location.reload(true);
}
});
}
Step 3d: Retrieving User Information from the IDP (Optional)
User attributes that have been identified and included in your metadata XML that you sent to your IDP team in Step 2c, can be accessed from your XSJS code with the following code.
var value = $.session.samlUserInfo.<name>;
A valid example could be
var mail = $.session.samlUserInfo.mail;
Create your Own Registration Experience (Overlay)
SAML identity providers offer the ability to customize your login and registration experience using something called an overlay. I need to learn more about how this works and post a subsequent blog on the topic.
Troubleshooting
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.
Path Error when Running sapgenpse
If you receive a library path error running the sapgenpse command, you may need to run the following command.
export LD_LIBRARY_PATH=/usr/sap/HDB/SYS/global/security/lib
Further Reading
- SAP Managed Tags:
28 Comments
