Skip to Content

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

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’./wp-content/uploads/2013/11/x509_user_329281.png
  • 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 ExplorervieIexplore.png

  • 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


certMgr.png

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:

exportIt.png

  • ‘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.ffImport.png

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

xsAppConf.pngChange 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:

useIt.png

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

To report this post you need to login first.

27 Comments

You must be Logged on to comment or reply to a post.

  1. Aleh Litasau

    Kai-Christoph, thanks for guide. Can you make guide for authentication in SAP HANA XS using sap logon tickets, please?

    p.s. it would be great as example (sap portal – sap hana xs).

    (0) 
    1. Kai-Christoph Mueller Post author

      Hi Aleh

      thank you!

      I am currently not planning to write a Post on how to configure SAP logon tickets. I neither do have an ABAP/Portal system available nor is it the preferred method of authentication.

      The documentation in the SPS07 guide also looks pretty good to me:

      http://help.sap.com/hana/SAP_HANA_Administration_Guide_en.pdf

      (chapter 5.6.5: Maintaining SSO with SAP Logon Tickets for SAP HANA XS Applications)

      Did you try this one?

      Best regards

      kc

      (0) 
          1. Aleh Litasau

            Hi, it works now.

            My problem was in domain structure. I got cookie with ticket only if I go on portal address without specifying domain.

            I reset system after many changes, so can’t say what actually helps =)

            (0) 
  2. Roberto Falk

    Hi Kai-Christoph,

    I’ve done all the steps to configure SSL and I believe it’s working, since when I go the the Trust Manager, no error is showed.

    After, I’ve created my own XS application, and, inside the XS Admin Tool, I’ve set my app to use X.509 as the authentication method.

    After that, when I try to access my xs app, no certification is asked by the bowser and the following message is showed:

    “No certificate available

    No successful authentication possible”

    How can I try to find why this is happening? I checked dev_webdisp, but the only message that gives me hints about the problem is the following:

    secussl_Create_SSL_CTX():  PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSLC.pse” not found,

    =      using PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSL.pse” as fallback

    =  secussl_Create_SSL_CTX():  PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSLA.pse” not found,

    =      using PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSL.pse” as fallback

    ******** Warning ********

    *** No SSL-client PSE “SAPSSLC.pse” available

    *** — this might limit SSL-client side connectivity

    ********

    = Success — SapCryptoLib SSL ready!

    =================================================

    I tried to include the line icm/log_level = 2 into the file sapwebdisp.pfl, but seems to me that nothing changed in the dev_webdisp log file.

    Any idea how to check what might be wrong?

    Thanks your help,

    Roberto Falk

    (0) 
    1. Aleh Litasau

      Hi Roberto,

      You don’t need SAPSSLC.pse for x.509 authentication.

      You see:

      “No certificate available

      No successful authentication possible”

      in Firefox?

      Chrome or IE better in that case.

      What CA are you using?

      Do you import CA and user certificate?

      Please, post here what you add in webdisp. configuration.

      (0) 
      1. Roberto Falk

        Hi Aleh Litasau,

        I realized that I was missing one step. Now it’s running fine.

        One additional question, now, the system is validating if the user received from the browser exists in the Hana database. But what if the user not exists? How can I get this user and do something with it? My idea is to create the user automatically. Is this possible?

        Ideally, what I want is to get the user sent by the brower and do something with it, doesn’t matter ir the user exists or not in the Hana Database.

        Thanks and regards,

        Roberto Falk

        (0) 
        1. Kai-Christoph Mueller Post author

          Hi Roberto

          in this scenario you want to make the user authenticate himself against the engine (as you configured X.509 authentication). After that you want to do something.

          This is not the way it is supposed to work.

          You will not get a session here – most likely you do not want to allow a user to create himself.

          You could either go the SAML way, as in this case the users will get created dynamically in HANA.

          Or you open a self registration page, using sqlcc technique and implement this service in a way that creates a X.509 user.

          Best regards

          kc

          (0) 
          1. Roberto Falk

            HI all,

            let me explain the idea. I’m refreshing our local sandbox here in the Labs, but I don’t want to be after this news installation the bottleneck for users requests. What I want is to create a page that everyone that wants a user, simply use it to create the user for yourself.

            The idea of validating the user, and that’s why I thought about X509, it’s because I want to keep track by using the <inumber> as username of everyone that is creqting an user.

            Do you seee a better way that I can do this?

            Thanks your help,

            Roberto Falk

            (0) 
            1. Aleh Litasau

              I think better way – create something ( script/page) which creates user with privileges  using SQL. User only provides name.

              Who unable copy his CN from certificate – doesn’t pass =)

              (0) 
                  1. Roberto Falk

                    Hi Aleh Litasau,

                    Sorry, I didn’t get your answer. If I disable the X509, when I try to access the URL, the server do not asks for the certificate, and if I enable it, the server asks for the certification, but also validates the user.

                    How can I make the url ask for the certification, but use it just to get the user, but do not validate if the users exists in the system?

                    .. another option would be, in case the user validation fails, the system lets me do something, instead of just replying as “unauthorized”.

                    Thanks your help (and patience).

                    Best regards,

                    Roberto Falk

                    (0) 
                    1. Aleh Litasau

                      Hi Roberto.

                      I mean you should create web page with form, where user input CN manually.

                      Your idea needs at least x509 developer knowledge, so if you don’t have it – just make simpler =)

                      (0) 
                      1. Roberto Falk

                        Hi Aleh,

                        yes, I’ll do it manually as you said, since I’m getting out of time.

                        But just out of curiosity, how would you do it? Using apache, is everything manual, I mean, I receive the user in the backend, and I’m responsible for authenticating the user… But on XS, this happens automatically… For me seems more a question about XS than about X509.

                        Thanks again,

                        Roberto Falk

                        (0) 
                        1. Aleh Litasau

                          Hi Roberto,

                          I would do it like this:

                          1) Create XS page with input form and one button( that execute SQL script).

                          2) User type his user_name(CN) in this form.

                          3) Click on button -> user creates.

                          (0) 
                          1. Roberto Falk

                            Hi Aleh,

                            yes, this would be the manual way, but what about the automatically way, the one the page gets automatically the user from the certificate, how would you do it?

                            Thanks and regards,

                            Roberto Falk

                            (0) 
        2. Satheesh Subramaniam

          Hi Roberto, I am running into the same issue “No certificate available. No successful authentication possible”. Which step did you miss? and what solved the issue? Thanks.

          (0) 
          1. Kai-Christoph Mueller Post author

            Hi Satheesh,

            are you sure this is the same issue? To me it more sounds like you did not import the certificate into your Browser at all (step: Import the certificate). Roberto rather wants to create users on the fly…

            best regards

            kc

            (0) 
            1. Satheesh Subramaniam

              Hi KC, appreciate the response. I have followed steps from admin help manual and ended up with the same issue as Roberto.  I copied one of his response as below for reference. The SSL works with no issues, and I can see the client certificate (I-NUMBER issued by SSO_CA) in the browser’s certificate stores, but I do not see certificate prompt and getting the following message.

              “No certificate available

              No successful authentication possible”

              ———————————————————————————————————————-

              After, I’ve created my own XS application, and, inside the XS Admin Tool, I’ve set my app to use X.509 as the authentication method.

              After that, when I try to access my xs app, no certification is asked by the bowser and the following message is showed:

              “No certificate available

              No successful authentication possible”

              How can I try to find why this is happening? I checked dev_webdisp, but the only message that gives me hints about the problem is the following:

              secussl_Create_SSL_CTX():  PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSLC.pse” not found,

              =      using PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSL.pse” as fallback

              =  secussl_Create_SSL_CTX():  PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSLA.pse” not found,

              =      using PSE “/usr/sap/SL1/HDB00/brslehana01/sec/SAPSSL.pse” as fallback

              ******** Warning ********

              *** No SSL-client PSE “SAPSSLC.pse” available

              *** — this might limit SSL-client side connectivity

              ********

              = Success — SapCryptoLib SSL ready!

              =================================================

              ———————————————————————————————————————–

              (0) 
    1. Kai-Christoph Mueller Post author

      Hi Ravi,

      you have been looking in the right chapter. This is the way you export a user certificate (mine in this case, starting with ‘D’).

      These certificates are usually created by a certification authorities and handed over to the users. If you are looking into an enterprise scenario, those certificates are most likely distributed by the company.

      Best regards

      kc

      (0) 
  3. Ann Zhang

    Dear Kai-Christoph,


    Now I can log user on with X509 certificate, but how can I log user out with X509 authentication enabled? I have tried to call sap/hana/xs/formLogin/logout.xcfunc, not it seems not work.


    Thanks,

    Ann

    (0) 

Leave a Reply