Intro

In this Post you are going to learn how to enable X.509 client certificate authentication on your HANA system. The X.509 certificates provide a convenient and secure way for authentication.

It is possible to use this mechanism in XS applications since HANA SP6.

Prerequisites

I assume you have good understanding of authentication mechanisms and know what you are doing (at least most of the time). Other than that there are some things, which also need to be in place before going ahead:

• SSL/TLS needs to be enabled on your HANA box
  • In case you would like to get this done now, I know a good Post 😉 :
    • Outbound httpS with HANA XS (part 1) – set up your HANA box to use SSL/TLS
• OS access
  • You need to be able to copy files to and run commands on the HANA box as <sid>adm.
• You should already have a client certificate of a Certification Authority (CA)
  • I am going to show you how to look for this certificate on your machine.
  • In my example I will use SAP’s CA infrastructure

If you meet all those requirements, the setup is going to be a piece of cake.

Configuration

First of all we need to configure the server. After that we create a user who leverages the X.509 authentication. Last but not least we will configure the XS application.

How to establish trust

Get the certificate

The first thing we need to do is to get the root certificate of your CA.

Using the SAP infrastructure, it can be retrieved via

• Trust center services-> Download Area -> Root Certificates -> SSO_CA Certificate

In the following I assume the file name of this root certificate is SSO_CA.der.

Trust the certificate

In order to trust the certificate, we need to configure the trust relations for both of our trust stores (WebDispatcher [SAPSSL.pse] and XS Engine [sapsrv.pse]). Furthermore we need to enable client authentication in the Web Dispatcher profile.

This is how it can be done:

• Copy the root certificate to the server.
• Copy the attached script (X509_enablement.sh) to the same working directory.
  • Or execute the following commands on the console.
• Edit the variables at the beginning of the script according to your needs:
  • INSTANCE
  • INSTNO
  • HOST

X509_enablement.sh

#!/bin/bash
##########################################
# Configure the script
##########################################
INSTANCE='<SID>'
INSTNO='<INSTNACE_NUMBER>'
HOST='<HANA_HOSTNAME_WITHOUT_DOMAIN>'
######### example
#INSTANCE='KCR'
#INSTNO='00'
#HOST='pall00539444a'
DIR_SECURITY_LIB="/usr/sap/$INSTANCE/SYS/global/security/lib"
cp SSO_CA.der $DIR_SECURITY_LIB
##########################################
# Web Dispatcher configuration
##########################################
echo "
icm/HTTPS/verify_client = 1
" >>  /usr/sap/$INSTANCE/HDB$INSTNO/$HOST/wdisp/sapwebdisp.pfl
##########################################
# Trust relations
##########################################
echo 'ok, so now we will configure the trust relations'
$DIR_SECURITY_LIB/sapgenpse maintain_pk -p /usr/sap/$INSTANCE/HDB$INSTNO/$HOST/sec/SAPSSL.pse -a $DIR_SECURITY_LIB/SSO_CA.der
$DIR_SECURITY_LIB/sapgenpse maintain_pk -p /usr/sap/$INSTANCE/HDB$INSTNO/$HOST/sec/sapsrv.pse -a $DIR_SECURITY_LIB/SSO_CA.der
##########################################
# Restart the services
##########################################
kill -9 `pidof sapwebdisp_hdb`
kill -9 `pidof hdbxsengine`

Authenticate via X509

At this point the HANA server trusts the certificates being issued by the CA. This does not mean the end user is known to the HANA system.

So we create a user with the according authentication mechanism and make sure our XS application uses X.509.

Before finally testing our app, we need to ensure the certificate is installed in our Browser.

Create the user

There are two ways for creating a such a user.

SQL

Using a SQL interface just send the following command to the engine:

CREATE USER <YOUR_USERNAME> WITH IDENTITY  'CN=<YOUR_USERNAME>, O=SAP-AG, C=DE' ISSUER 'CN=SSO_CA, O=SAP-AG, C=DE' FOR X509;
-- in my case
CREATE USER D042399 WITH IDENTITY  'CN=D042399, O=SAP-AG, C=DE' ISSUER 'CN=SSO_CA, O=SAP-AG, C=DE' FOR X509;

Studio

Using the Studio it can be done via:

• Go to the perspective ‘Administration console’.
• Expand the <sid> node.
• Expand the ‘Security’ node.
• Right click onto the node ‘Users’ and select ‘New User’.
• Provide a user name.
• Deselect the ‘Password’ checkbox.
• Select the ‘X509’ checkbox.
• Follow the ‘configure’ link.
• In the popup
  • Click the ‘Add manually’ button.
  • Issued To:
    • ‘CN=<YOUR_USERNAME>, O=SAP-AG, C=DE’
    • in my case
      • ‘CN=D042399, O=SAP-AG, C=DE’
  • Issued By:
    • ‘CN=SSO_CA, O=SAP-AG, C=DE’
• Commit everything.

How to use the client certificate

Export the certificate

In my case the certificate is installed in Windows. Therefore Internet Explorer already has got this certificate installed. As I prefer Firefox, I am going to export it from IE and import it into Firefox.

In Windows there is a certificate export wizard, which you can start in tow ways

Internet Explorer

• Start ‘Internet Explorer’.
• Choose the menu item ‘Tools’ -> ‘Internet options’.
• Change to the tab ‘Content’ and select the button ‘Certificates’.
• In the tab ‘Personal’ select the certificate being ‘Issued By’ your CA.
• Clicking button ‘Export’ will open the ‘Certificate Export Wizard’

OR

Start->Run command (Windows button + ‘R’): certmgr.msc

• Select the node ‘Personal’ -> ‘Certificates’.
• Double click the certificate being issued by your CA
• In the popup ‘Certificate’
  • Change to the tab ‘Details’
  • Push the button ‘Copy to File…’

Certificate export wizard

Once you have opened the ‘Certificate Export wizard’, you generally follow the default screens with following modifications:

• ‘Private Key’
  • We want to export the private key.
• Export a ‘Personal Information Exchange Certificate – PKCS #12 (.PFX)’
  • Check the box: ‘Include all certificates in the certification path if possible’
  • Check the box: ‘Export all extended properties’
• Provide a password.
• And a filename (which might be a good idea to remember)

Import the certificate

So the next thing we want to do is: Import the certificate into Firefox.

• Start Firefox.
• Choose ‘Tools’->’Options’ via the menu.
• Change to the ‘Advanced’ area.
• Click the tab ‘Certificates’.
• Clicking the button ‘View Certificates’ opens Firefox’s ‘Certificate Manager’.
• Click the button ‘Import’ in the tab ‘Your Certificates’.
• Now provide the remembered file name.
• You will be asked for the transport password.

If you see a success method, you will be able to show the server a valid client certificate.

Use the XS applications authentication method

The chosen method of authentication depends on the system configuration and has to be configured in the runtime environment. To do so, we are going to leverage the XS Administrator.

Change the authentication

In order to change the authentication of your XS application open the HANA XS administrator at

https://<FQHost>:43<InstNumber>/sap/hana/xs/admin/

Activate X.509 authentication via:

• Select your XS application in the application list.
• Enable editing of the list of authentication methods by clicking the wizard stick symbol next to the list.
• Choose X509 from the list.
  • You may allow other methods as well.
• Save the changes via the button below.

Use the authentication

After changing the authentication method you can verify it’s usage by opening your application. If you see the ‘Certificate selection wizard’ everything is working as expected:

If you do not see the wizard, there may be an open session somewhere. These things will help you to get rid of it:

• Close the Browser
• Delete all the Cookies from the HANA XS hosts
• Start a private browsing tab

This XSJS code may come handy as well:

$.response.setBody(JSON.stringify({
        "username"  : $.session.getUsername()
}));

December bug

Watch out, there is the so called ‘December bug’ in SAP HANA XS SPS06 (in revisions 64 up to 69.01). Static resources being activated in December are not returned via http(s) – this particularly holds true for packages using SSO authentication (such as X.509).

Please refer to SAP Note 1950647 for details.

Conclusion

I hope this post was useful and enjoyable to you.

Enjoy your X.509 authentication and stay tuned for more

Kai-Christoph