Introduction

The new SAP HANA Multitenant Database Containers (MDC) feature, which was introduced last week in the Free Developer Edition of the SAP HANA Cloud Platform not only gives you a development experience much closer to a productive HANA instance, it also allows for much more freedom in configuring your HANA than the old HANA trial instances based on shared databases.

In the old HANA trial offering, the servers were preconfigured to use SAML authentication with the SAP Identity Provider for your HANA XS applications, and there was no option to change that. With the new MDC trial systems, you now have a choice between form-based authentication and SAML support using an identity provider of your choice (including On-Premise IDPs).

When configuring your XS application to use SAML, the authentication is handled by an Identity Provider Service (IDP) instead of adding user management in the HANA system. The IDP will authenticate the user either by username and password, or by certificate. This allows for single sign-on (SSO) scenarios and thus improves largely the user experience.

To make this scenario possible, a trust relationship between your HANA database and the IDP needs to be set up, meaning that you need to register your HANA instance, the Service Provider in the IDP and vice versa.

Once this is done you can configure the applications running on your HANA instance to use SAML authentication: if you open the UI for such an XS application in your browser, the request is redirected to the IDP, which will take care of the user authentication. Once the user’s identity is verified, the IDP sends the request back to the HANA application – including the information about the user. The application can then perform the authorization check based on the verified information about who was sending the request and decide if the user is allowed to perform the requested operation.

Note: the described procedure is specifically tailored to be used with HANA SPS10 (tested with revision 102.3, which is currently being used for the HANA MDC trial systems). There are a few places which look and feel like a workaround (feel free to apply the duck test to this statement). This will become easier in the future, and hopefully once SPS11 becomes available I will be able to replace these steps with a something simpler.

But now, without further ado, let’s jump right into the nitty gritty belly of the beast…

What You Need

There are a few things you need before we start:

• A Web browser (I was using Google Chrome).
• A tenant database on a SAP HANA Multitenant Database Containers system. You can get one following the instructions in the blog by Ekaterina Mitova.
• A SAP HANA Studio (Eclipse + SAP HANA Tools): follow the instructions on the SAP HANA Tools site.
• The SAP HANA Cloud Platform Tools plugin for the HANA Studio.
• A tool to generate the certificate for your Service Provider with. I will use OpenSSL in this blog. (If you are using a Mac or Linux system, chances are that it is already installed.)
• A tenant in an IDP Service with privileges to register service providers and manage users. I will use a tenant from an SAP test IDP in this blog.

Preparing Your HANA Tenant Database

After you have created the Trial instance following Ekaterina’s blog, you need to assign some privileges to an administration user in the HANA system. To keep it simple for this blog, we are using the SYSTEM user for that – something you should not do in a productive system!

In the database overview of the SAP HANA Cloud Platform Cockpit click on the SAP HANA Cockpit link:

In the SAP HANA Cockpit UI click on Manage Roles and Users:

In the security management UI select the SYSTEM user from the user list and assign these roles:

• sap.hana.security.base.roles::HANACertificateAdmin
• sap.hana.security.base.roles::HANACertificateView
• sap.hana.security.cockpit.roles::DisplayCertificateStore
• sap.hana.xs.lm.roles::Developer
• sap.hana.ide.roles::Developer
• sap.hana.xs.admin.roles::SAMLAdministrator
• sap.hana.xs.admin.roles::RuntimeConfAdministrator

Note: in case you want to create a new user for administration of certificates, you also need to grant the system privilege CERTIFICATION ADMIN. The SYSTEM user already has this by default.

Creating a Hello World Application

Let’s first create the HANA XS application we want to protect with SAML authentication in this blog. This is pretty easy using the SAP HANA Web-based Development Workbench.

• Click on the SAP HANA Web-based Development Workbench link in the SAP HANA Cloud Platform Cockpit. A new UI opens.
• In this new UI, click on Editor
• Create a new sub-package within the public package
• In the context menu for the new sub-package, select Create Application
• Select Template “HANA XS Hello World” and click on Create

You should now see something like this:

Testing the Hello World Application

Click on the activate and run button:

Now the Hello World application will start in a new browser tab.

Click on the Call Backend” button: you should now see the message “Hello World from User SYSTEM”

Since you were already logged on to the HANA instance with the SYSTEM user in this browser, the new browser tab was opened with the same identity. Try opening the application by copying the URL into a private browsing window or another browser. You should be prompted with the normal HANA logon screen.

Note down the application URL. We’ll want to use it later when we test the SAML authentication.

Creating Your Service Provider Certificate

The Service Provider certificate is the “passport” with which your HANA instance will authenticate itself to the IDP. For productive purposes you will want to get an official certificate, signed by a trusted certification authority. For this trial scenario we will just create a self-signed certificate ourselves.

Create the certificate with OpenSSL

OpenSSL is a command tool, and once it is installed you can create a self-signed certificate by calling the tool in a command shell like this (all in one line):

openssl req -x509 -sha256 -newkey rsa:2048 -keyout certificate.key -out certificate.crt -days 1024 -nodes   -subj ‘/CN=trust.no.one’

Note: I didn’t check if the example domain name I used ‘trust.no.one’ is actually registered by anyone. You can use your domain instead.

This command will produce two files:

• certificate.key: the private key. Never share this with anyone for a productive use-case!
• certificate.crt: the public certificate for your service provider

Register the Certificate in Your HANA Instance

Connect to the Tenant DB via HANA Studio (add cloud system). Unfortunately, the SQL editor in the SAP HANA Web-based Development Workbench (aka Web IDE) does not seem to work for some of the multiline statements we are about to use.

Create a PSE Container

In an SQL editor execute the following command:

CREATE PSE TrustMe;

Assign the PSE Store For SAML Use

Execute this statement:

SET PSE TrustMe PURPOSE SAML;

Register the Service Provider Certificate

For the following statement use the values from the certificate.crt (replace the part between the Begin/End Certificate tags) and from the certificate.key file from (the part between the Begin/End Private RSA Key tags). You should end up with something like this:

ALTER PSE TrustMe SET OWN CERTIFICATE ‘—–BEGIN CERTIFICATE—–

MIIDKTCCAhGgAwIBAgIJAL0Qouc1TloGMA0GCSqGSIb3DQEBCwUAMBcxFTATBgNV

BAMTDHRydXN0Lm5vLm9uZTAeFw0xNjAxMjExNjExMDVaFw0xODExMTAxNjExMDVa

MBcxFTATBgNVBAMTDHRydXN0Lm5vLm9uZTCCASIwDQYJKoZIhvcNAQEBBQADggEP

ADCCAQoCggEBAMNu3KJ8f1N2jFhorBvBU9jcjG/0xV+T54iVlN+qwGFc6YbCZbr/

sFx97c3wM+qdUvXncyRYeLMpTzbg/muogmIVV07qyxd/S8vsseHlQthcQinCoz81

H99ivtKRpQ/swHwanPuDtoQCcTppMtqaxhhOjEhV4jI3iMjNeOfFoRhzNSz7IvRg

5xG/uYicmpFBYo6ySPrbtnRn5nUo9OMlXFQSW7L562oDmomWjmysvdkV1ghBN2LI

wVSNp07pJt0TM33SIOJZQqY2eB6YYKjLQx+t7EMySfHSZdBZ9e3M0LTlaYR1O/Vp

LLaOuuM1DSBznw5Z8T/1KThvpT0rBTEx+kkCAwEAAaN4MHYwHQYDVR0OBBYEFJdw

DpH7f8vnPVrWvmBWqpVlq3quMEcGA1UdIwRAMD6AFJdwDpH7f8vnPVrWvmBWqpVl

q3quoRukGTAXMRUwEwYDVQQDEwx0cnVzdC5uby5vbmWCCQC9EKLnNU5aBjAMBgNV

HRMEBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBTIS7CgRAmLTSukBOfMg0oi0Sj

B2ztF1aHb6XPn/kBRnmdXpdn86dyrAXpOYOVToWCxATKjx4cAXO7Cb9aOAhSJRfh

XXEB6dXnXESnyvuet4oyorPKqTmq7jEE30Mfnw7MqrgEM/dCy+IHIeK9SzETUUsA

+FkwtEppKYF6f3X5SeO4dxU9xZOxrinAWANESbE8r48PtaeL8oslRXqLHbVhZEW9

r0TXS3tWOyW17wKTIQt9DVZ1LaSGpU5rXCUyQR/RJ/fsYNEl2SMOMUIsMeFH3tZq

HfMqQUVFBYHpWCraMTxOUTS5PHdUoxW070Ygn3d1gLjN3EZONNo8CEhek/sC

—–END CERTIFICATE—–

—–BEGIN RSA PRIVATE KEY—–

MIIEpAIBAAKCAQEAw27conx/U3aMWGisG8FT2NyMb/TFX5PniJWU36rAYVzphsJl

uv+wXH3tzfAz6p1S9edzJFh4sylPNuD+a6iCYhVXTurLF39Ly+yx4eVC2FxCKcKj

PzUf32K+0pGlD+zAfBqc+4O2hAJxOmky2prGGE6MSFXiMjeIyM1458WhGHM1LPsi

9GDnEb+5iJyakUFijrJI+tu2dGfmdSj04yVcVBJbsvnragOaiZaObKy92RXWCEE3

YsjBVI2nTukm3RMzfdIg4llCpjZ4HphgqMtDH63sQzJJ8dJl0Fn17czQtOVphHU7

9Wksto664zUNIHOfDlnxP/UpOG+lPSsFMTH6SQIDAQABAoIBAQCm0IY7m5EDKPl6

rT3bIxXy0a5+Eaw3fQPwrd05XYKAmNIsWNqE16MuD79gPVvTMx6RD1JU/79nDiez

bDE+q8M+/YBcuEVKdTm5gvwDGbIJBBbllmHJngrqnlrLWc5O3YMfa4f7l92+qGcF

uK3TsrDMJp/PTp+YxZZX8Cr3itWLC6v41f7P8JH/QvDWVRdo01oNH3x6xwdcywak

IvDSyMFjX5UVR/uHyaYyd9ox96Tw3YbJwru4XOOhObePUe7k522ShzywY+/OESuu

y6xIe8vVJLcPEChQGmjCuDRE2UsEJ/AM3iT3VVoyHy/vUaiWnyF99wmsHE0/jT8p

2hsQtxwBAoGBAPabIyhBdgoQSa5GGaoMlPAs6B6eduFuBxbzXlFJonLVKO0e6pZI

/hkyeO1rlFWjNy2WhyN8ss9cFz0VX8x/0tj6TgUJRJ674aSpUq+kgYiZbgwPuCOk

Udxhu56/z8pkcpjBNbUTkT9EuQzLavKIpj2L7P/EhhSLuDJ6jMvHW+DpAoGBAMrg

sar4aEOk+nIqoewnHupHmyZqN3Y0QjmXF3r9lFHV5PHu9ZK+6vjDgrCJhDr+cr/q

OU+wJ8r9JH640y/BOXWdbsSysQWVWoLOEwbLd8iKwAfL6MDVyoXk3dP7BOo1fVJh

B6/vLWy5WObKlq9EfvqJeH7gXEZkgkulV4+/KnJhAoGAHeRgNpj4ve+Lftxwb/Rm

eVZ4LH342wqDQXzuidvrHRBJjbSZqu3eHx/HGMBZkqfeIGCGsP6Eji4Tgwv8OMWl

wTdWDbY54yPTDiqYI0JFkVFHzZ56K5fXdGdEXtHRVi8m1O1WnURp7sldxPdDV3LI

89zqNXaU6hilkzjXqDvaH0ECgYEAwmCL+VotU3pS9mWAZGmLBj57GVA1OUySkuj/

dzhUDiBYTbB8mw/Ow29W3Nu01G0L9nJsXLxTM/pcKAnfVWbVLaocAduPHeFeKetV

cXIqnvrJR+8HXxK3CpggLUTZDakYHICYw+jt5bijw+QggWaoHlTuHOnLnyoXaHDP

NwuamKECgYApD7C/UcHVC9W6yCORHmmwkerAPacXnKIPiXWOQzkLG7zKoDzsE3yi

BqmpA2hvAbFFXUBe86vj1HW8jQIa//TXYSYHks1wFEWcGVczWoETt9025FEr0qTy

ncJkQXo9N3yXgRQMui+7gPAfZa1jp151ATOzf9pnWfHJ74pLh5MvPQ==

—–END RSA PRIVATE KEY—–‘

You have now created a PSE store containing the “own” certificate with which your HANA instance will be registered in the IDP service.

Complete the Service Provider Settings

There are still a few properties of the metadata for your Service Provider which need to be set. This is done in the XS Admin Tool of your tenant DB. You can open this tool by appending “/sap/hana/xs/admin/#samlsp” to the Url of your HANA instance.

Service Provider Information

In the Service Provider Information tab, you should set your Organisation Name, Organisation Display Name and Organisation URL. To change the values, click on the Edit button in the lower right corner and click on Save once you’re done.

Service Provider Configuration

Not much to do here. Just set the Default Role to “PUBLIC”.

Making the IDP Trust Your HANA

In this step you will export the certificate of your HANA instance and register it as a Service Provider in the IDP.

Export HANA SAML Metadata

Now go to the Metadata tab of the SAML Service Provider UI in the XS Admin Tool. Select the complete XML content of the text field and copy and paste it to a local text file. Save that file with the ending xml.

Register Your Service Provider Metadata in the IDP

My development team has a tenant in an SAP test instance of the SAP Cloud Identity Service, so I will use that to demonstrate the process in this blog. This should work similarly with other IDP service offerings.

1. Log on to the SAP Cloud Identity Administration Console
2. Go to Applications
3. Click on + Add
4. Enter a new name and click on Save
5. Click on SAML 2.0 Configuration
6. In the Define from Metadata section click on the Browse… button
7. Select the xml metadata file for your Service Provider, which you created in the previous step
8. Click on Save

You have now set up the IDP to trust your HANA instance.

Making Your HANA Trust the IDP

We still need to set up the trust relation in the other direction, because right now your HANA system doesn’t know anything about the IDP.

Export the IDP Metadata

Again, I’m using the SAP Cloud Identity Service to demonstrate this.

1. Log on to the SAP Cloud Identity Administration Console
2. Go to Tenant Settings -> SAML 2.0 Configuration
3. Click on Download Metadata File at the very bottom of the window. This will create a metadata.xml file containing the IDP metadata to your local disc
4. At the bottom of the screen (please scroll down to the end) you will find the Signing Certificate. Copy the cryptic string from the Insert as Text field and paste it to a local text file.

Import the IDP Metadata Into HANA

Now this is a bit tricky, because for part of the information you will still use the “old” XS Admin Tool and other parts are handled now via SQL statements.

Create the HTTP Destinations

This is the part where you can still use the XS Admin Tool. There is probably a way to do all this by manually storing this information in the appropriate database tables in the HANA system, but this would require deeper knowledge of the internal table layout and semantics, so it’s easier to do it like this:

1. Go to the XS Admin Tool in your tenant database (appending “/sap/hana/xs/admin/#samlsp” to the URL of your HANA instance)
2. Go to SAML Identity Provider and click on +
3. Open the metadata.xml file you downloaded from the IDP in a text editor and copy and paste it to the Metadata input area
4. Click Save

Now the metadata is displayed in the General Data and Destination fields, but because of the new certificate handling introduced in HANA with SPS10 nothing was really stored. We now need a trick to get the General Data and Destination data actually stored in the appropriate HANA tables:

1. Delete all the text in the Identity Provider Metadata input field
2. Click on Save again (there will likely be an error displayed at this point, but don’t mind that)

Verify that the destination was stored in HANA by going to the Catalog view (in the SAP HANA Web-based Development Workbench or SAP HANA Studio) and check the _SYS_XS.HTTP_DESTINATIONS table:

Add the Certificate

Because the XS Admin Tool cannot store the actual certificate anymore (the storage was moved from the file system to the database, and the tool wasn’t updated for this), we now have to store the certificate with a SQL statement.

Use the certificate string you got from the step where you exported the metadata from the IDP and embed it in a ‘CREATE CERTIFICATE’ statement. Make sure to have the BEGIN/END CERTIFICATE tags surrounding your string with the exact amount of dashes. Line brakes should not matter here.

I found that I had to execute this statement in the HANA Studio as the Web-based Development Workbench gave me an error.

CREATE CERTIFICATE FROM ‘—–BEGIN CERTIFICATE—–MIIDIjCCAgqgAwIBAQIGAUjG8PFJMA0GCSqGSIb3DQEBBQUAMFAxCzAJBgNVBAYTAkRFMQ8wDQYDVQQKEwZTQVAtU0UxMDAuBgNVBAMTJ2hjcHBlcnNpc3RlbmNlLmFjY291bnRzNDAwLm9uZGVtYW5kLmNvbTAeFw0xNDA5MzAxNDIyMzJaFw0yNDA5MzAxNDIyMzJaMFAxCzAJBgNVBAYTAkRFMQ8wDQYDVQQKEwZTQVAtU0UxMDAuBgNVBAMTJ2hjcHBlcnNpc3RlbmNlLmFjY291bnRzNDAwLm9uZGVtYW5kLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJC+1IF9tNTNyF8m7OEaEDUtjBs6Yjmrjk96jjSrKGFusrXwEWL9+qMqTt0gSo9ITAQzziVQa+8e81vFgtKI0ieMgRC6byXWeL/2BkIU4tkBwU986JdyPfPZFBkr3WM5gLpGgXyt87w+n5cZfNG6W7bn3U7aQdH5B8HZTo539v4TbDAWvMbZjGNPt3aan+96ybyX96+4VwrumJeLhl2SpRSp2p0VoSCHMNBqLzRcnB7bj5skeYrK9qC3oFFfzrbVxOitUBwuVZ5RHb28sfhlL3+QgFJiL8TYUa2NOP/+oa79JvWhCtVEAv+FMPFf7c42pSK+YIlsKpGnVcDyNe0zPWUCAwEAAYICAAAwDQYJKoZIhvcNAQEFBQADggEBAGKC5C2JxUS6vKMzKwXJcr9WGOyXhTwTHZRYZc+gnrPTN2gYBdCnZaTCKwEKvf+boU9SKY2/awaKeMS0z0G/HY7ck4du5OQmCIBnudbjD2rvfTWW0hAoB+U5YfqhnzPEbp+HzbvY7ydCg56gO6oRcoyQEJ69KSzNK2UGo20UC2YE+GY6DCV6n4SdyooYmnJjKdKy11NFzsVav6GdVtaaazbhy3XNWuVPjIGB+VwDAeTOon4xbUw6zPnn1duQ5cFRFXXX0T6gmpfkJIDtKWrRw2M/sl9N/fAjkqRgFEahAV67ebOyO0iQRIZwqfyMGy5lMgGA2+tWfb/pGQvKXhO+UnE=
—–END CERTIFICATE—–‘;

Now check the content of the SYS.CERTIFICATES view and look for the CERTIFICATE_ID of the IDP certificate you just created. You need this ID for the next step.

With this CERTIFICATE_ID you can now add the IDP certificate to the PSE used for the SAML authentication:

ALTER PSE TrustMe ADD CERTIFICATE 154178;

Check the view SYS.PSE_CERTIFICATES, it should now have two entries, one with CERTIFICATE_USAGE OWN and one with TRUST

You have now fully configured the trust relationship between your HANA instance and the IDP for the sake of SAML authentication!

Setting Up the Application For SAML Authentication

What is still left to do is to configure the Hello World application to use SAML authentication instead of basic authentication.

1. Again, go to the XS Admin Tool in your tenant database (appending /sap/hana/xs/admin/#” to the URL of your HANA instance)
2. Select XS Artifact Administration
3. Navigate to the package where you created your Hello World application
4. Click on Edit
5. In Authentication Methods tick the SAML checkbox and select the IDP configuration created in step 2
6. Untick all other checkboxes
7. Click Save

The configuration should now look like this:

Testing the Application

The User ID of my user in the IDP is “P000001”, as we can see in the user administration UI of the SAP Cloud Identity tenant:

We expect this ID to show up in the Hello World application once we log using the SAML authentication.

Remember the application URL from when we first tested it? Paste it in a private browsing window or even another browser (we want to avoid any caching problems).

Instead of the logon screen of your HANA system you should now see the logon screen of your IDP (assuming that you have not set up single sign-on, in which case you would be either directly redirected to the application, or asked by the browser to use a certificate for authentication).

Once you log in, the application UI is displayed. When you now click on the Call Backend button, instead of the SYSTEM user the user ID of the user from the Identity Provider should be displayed.

Note: if you did not tick the Dynamic User Creation checkbox in step 2 you need to create the user in the HANA instance manually, otherwise you will see an error message that the user does not exist.

Closing Thoughts

I hope this blog is of help to anyone who wants to try such a scenario. The next step would be to try and add single sign-on.

Admittedly, the process to set up SAML authentication is not the smoothest. Especially the need to use the HANA Studio for multiline statements and the disjoint of the XS Admin Tool with the new certificate storage make it a bit of an adventure to configure this. I am certain that these points will be addressed in one of the next HANA versions.

I’d also like to give a big shout-out to my team-mate, architect and HANA whisperer Eduard Bartsch who guided me through some of the most tricky parts of this procedure.