Skip to end of metadata
Go to start of metadata

*** UPDATE ***

 

 

Please visit our new troubleshooting tool called the decision trees. We've tried to automate the troubleshooting of SSO issues in an easy to use concise way. Please leave feedback to tell us if this works for you and what we can improve.!!

 

https://decisiontreesdc846d4a4.us2.hana.ondemand.com/dtp/viewer/#/tree/188/actions/2021

 

 


Typographical Conventions

Type Style

Description

 

Example Text

Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options.

Cross-references to other documentation.

 

Example text

Emphasized words or phrases in body text, graphic titles, and table titles.

 
 

Example text

File and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools.

 

Example text

User entry texts. These are words or characters that you enter in the system exactly as they appear in the documentation.

 

<Example text>

Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system.

 

EXAMPLE TEXT

Keys on the keyboard, for example, F2 or ENTER.

 

Icons

Icon

Description

Note

SAP Knowledge Base Article

Recommendation

Go to Common Errors on this topic

1  Business Scenario

The objective of this document is to provide step-by-step instructions on how to configure Single Sign-On (SSO) using Security Assertion Markup Language (SAML) between SAP BusinessObjects BI Platform 4.1 (BI Platform) and SAP HANA Database 1.0 (HANA).  

2  Prerequisites

This guide is geared towards HANA Database Administrators or SAP BusinessObjects BI Platform Administrators.

This guide will assume there is basic knowledge of:

      • SAP HANA Configuration Files such as indexserver.ini and global.ini
      • SAP HANA Studio
      • SAP BusinessObjects BI Platform Central Management Console

3  Background Information

3.1  Single Sign-On

Single Sign-On (SSO) allows a user to log on once and gain access to multiple systems and services without being asked to produce credentials again. 

Security Assertion Markup Language (SAML) Kerberos is one of many ways for realizing SSO (other examples are Kerberos, SAP Logon Ticket or X.509 certificates). 

Depending on how SSO has been setup, it could permit the user logon to just a front end application or it can enable SSO all the way down to the database in what’s known as SSO to database

(SSO2DB).

Example
An example of SSO that is relevant to many office workers day-to-day is the use of Microsoft Outlook and the absence of a login and password to access your email and address book. When a user logs into a workstation, they enter a username and password. Shortly afterwards the desktop appears. If you start Outlook, you are not prompted for the login and password you just entered. The mechanisms of this are described in detail later in this document.

3.2       Definitions

There will be several references to specific HANA and BI Platform systems in the guide and also in the screenshots. The following systems are used:

      • SAP HANA Database Server

-      Hostname: LSLES11SP3x64

-      Instance: 00

-      System ID (SID): SL1

-      Revision: 102.4

-      Operating System: SUSE Linux 11.3

-      Web Dispatcher: Internal

-      Crypto Provider: CommonCrypto

 

      • SAP BusinessObjects BI Platform

-      Hostname: BIPW08R2-0

-      Version: 4.1 SP 7 Patch 1

-      Operating System: Windows Server 2008 R2

-      Web Application Server: Apache Tomcat for BI 4 (residing on the same system)

 

This guide will reference the placeholders identified in the following table:

Placeholder

Description

<HANA System>

Hostname of the SAP HANA Database system

<HANA Instance>

Instance number of the SAP HANA Database system

<WDisp Port>

Web Dispatcher port number

<BI System>

Hostname of the SAP BusinessObjects BI Platform system.

<Web Application Server>

Hostname of the Web Application Server hosting the BI Platform system.

<Web Application Server Port>

Port number of the Web Application Server hosting the BI Platform system.

4  Prerequisites

4.1  Network Requirements

Hostname resolution must be possible between the HANA system and the BI Platform System (ping <BI System> and ping <HANA System> )

4.2  Software Requirements

SAP HANA Platform 1.0 (this document was created based on SPS10)

SAP BusinessObjects BI Platform 4.0 and higher.

4.3 SSL

SSL is strongly recommended, but in this guide, SSL is not configured.

4.4 Time Syncronization

The HANA system and the BI System must have syncronized clocks. To achieve this, you can use an NTP server to synchroize the times.

 

5  Step-By-Step Configuration

5.1  Overview

To setup SAML authentication, a trust must be established between the HANA and BI Platform System. At a high level, the steps include:

    1. Generate a certificate from BI Platform
    2. Import the certificate into the HANA Trust Store

After that trust has been estabilished, the last step is to setup the security on the HANA system:

    1. Import the certificate into the HANA Security
    2. Configure a SAML user with an external identity user
    3. Test the connection
5.2  Generate a Certificate from BI Platform

Generating a HANA certificate is performed through the BI Platform Central Management Console (CMC).

1. Open a browser and go to http://< Web Application Server >:< Web Application Server Port >/BOE/CMC

          Example:

2. Go to CMC Home > Applications > HANA Authentication

3. Select the icon to create a new connection

4. Input the HANA details:

HANA Hostname

Hostname of the SAP HANA Database system

HANA Port

SQL Port for the HANA indexserver. HANA Studio > Administration

Unique Identifier Provider ID:

Unique Name of the certificate

Service Provider Name:

Configuration setting (default is SpID).

This should match the parameter
indexserver.ini > [authentication] > saml_service_provider_name


Service Provider Name mismatch?

 

 

Example:


 The text “After the certificate is generated, copy it to your HANA deployment’s “trust.pem” file” is not applicable in this case because CommonCrypto is used. A trust.pem is used for OpenSSL.

5. Select Generate and copy the entire certificate into the clipboard.

6. Select OK to save the connection

7. Create a new certificate file by pasting the certificate into a text editor.

8. Save the file as a .cer extension.


 Example:

9. This section is now complete

5.3  Import the Certificate into the HANA Trust Store

To find out which trust store is used by HANA, check the configuration setting global.ini > [communication] > ssltruststore. 

By default, the value is sapsrv.pse. This means the sapsrv.pse is located in the $SECUDIR/sapsrv.pse

There are three methods of importing the certificate into the trust store:

  1. On the HANA O/S directly using sapgenpse commands.  
  2. Using the internal Web Dispatcher Administration console.
  3. In the XS Trust Manager (http://<HANA System>:<WDisp Port>/sap/hana/xs/admin/#TrustManager

 

The following steps will be performed using the Web Dispatcher Adminstration console

1. Access the Web Dispatcher Administration page by going to this location:

http://<HANA System>:<WDisp Port>/sap/hana/xs/wdisp/admin/public/default.html

2. Login with a HANA user (In this case, the SYSTEM user)

Example:


  403 Forbidden Error?

3. Select PSE Management on the left hand side

4. From the Manage PSE drop down menu, select sapsrv.pse


  5. Select Import Certificate from the Trusted Certificates

6. Copy the certificate text from the certificate generated from the BI Platform CMC. Make sure to include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----

7. Select Import

8. The certificate should appear in the Trusted Certificates section

9. Restart the HANA system for these changes to take effect

10. This section is now complete.

5.4  Import Certificate into HANA Security

The next step is to import the same certificate into HANA Security. This step is needed to create the SAML Identity Provider (IdP).

1. Open HANA Studio and Login to the HANA System using the SYSTEM user (or an equivalent user)

2. Expand Security Folder and select Security

3. Select the SAML Identity Providers tab and select the Import button

4. Locate the certificate file that was created earlier

5. Fill in the Identity Provider Name. This can be any name and does not have to match the CN name. The Entity ID is optional as well.

6. This section is now complete.

5.5  Create a HANA user with SAML

The certificate has been generated and imported into the trust store and also into HANA Security. The next step is to assign a HANA user to a BI Platform user.

1. Open HANA Studio and Login to the HANA System using the SYSTEM user (or an equivalent user)

2. Expand the Security folder and right click Users and select New User

3. Specify a username and a password.

4. Select the check box SAML and select Configure.

5. Select Add and there should be the SAML Identity Provider in the list.

6. Add an External Identity.

        • The External Identity is the username from the BI Platform system
        • This name is case sensitive and leading or trailing space are valid characters

      Important: both names (the BI user name and the HANA SAML EXTERNAL_IDENTITY) must be exactly the same - no trailing or leading space - no deviation in upper and lower  case

In this example, Administrator is used.

7. This section is now complete

5.6  Validation

The next section outlines the steps to validate that the SSO is working.

1. Open a browser and go to http://< Web Application Server >:< Web Application Server Port >/BOE/CMC

2. Go to CMC Home > Applications > HANA Authentication

3. Open the existing connection that was created earlier

4. Specify the username to test. 

This user must match the External Identity user that was configured earlier.
In this example, Administrator is used.

5. If SSO is configured correctly, the message “Connection Successful” will be shown.

Connection Failed error?

 

The next test will validate the BI Platform client tools.

1. Start Information Design Tool (IDT)

2. In the Repository Resources section on the left bottom corner, Select the plus icon   and select Insert Session.

3. When prompted to login to BI Platform. Input the username that was specified as the SAML External Identity

4. Right click connections and select Insert Relational Connection

5. Specify a Resource Name

6. Expand SAP > SAP HANA Database 1.0 > JDBC Drivers

7. Select Use Single Sign On from the Authentication Mode drop down. This will grey out the username and password

8. Specify the hostname of the HANA system and the instance number

9. Select Test connection. If the test is successful, the following popup will appear



  Test Failed error

10. This section is complete.

 

6  Multitenant Database Containers

6.1  Overview

SAP HANA supports multiple isolated databases in a single SAP HANA system. These are referred to as

multitenant database containers (MDC)

In terms of configuration, the main differences between the configuration of a multi-container system and a single-container system will be:

1) Each tenant will need a BI Platform certificate created

2) When creating the connection in IDT, the “Multi-Server” section must be used.

6.2  Multitenant Database Container Steps (key differences)

1. Determine the SQL Port for the master indexserver server for the tenant in Studio > Landscape > Services

2. Create a certificate from BI Platform > CMC > HANA Authentication for the tenant. Make sure to use the SQL port in step 1.

3. Repeat the next steps from the single container system configuration.

      1. Import the certificate into the HANA Trust Store
      2. Import the certificate into HANA Security
      3. Create a HANA user with the SAML Validation
      4. Validation

        Use the Multi Server section and specify the HANA hostname and Tenant Port.

        Example:

4. This section is now complete.

7  Appendix

7.1  Tracing and Troubleshooting
7.1.1  Debug Tracing

Debug tracing can be enabled to get more information on potential errors. Use this if there is an error not mentioned in this guide.

To enable debug tracing, follow the steps:

1. Open HANA Studio and Login using the SYSTEM user

2. Open SQL Editor and execute the command:

ALTER SYSTEM ALTER CONFIGURATION ('indexserver.ini', 'SYSTEM') set ('trace', 'authentication') = 'debug' with reconfigure;

3. Reproduce the error and disable the trace by running the command:

ALTER SYSTEM ALTER CONFIGURATION ('indexserver.ini', 'SYSTEM') UNSET ('trace', 'authentication');

4. Go to the Administration tab in HANA Studio and select Diagnosis Files.

5. There should be an updated indexserver trace file. For example:

6. Open the indexserver trace file and search for the line:

ALTER SYSTEM ALTER CONFIGURATION ('indexserver.ini', 'SYSTEM') set ('trace', 'authentication') = 'debug' with reconfigure

This is where the trace analysis should begin.

 

7.2  Common Errors
7.2.1   SAML Service Provider Name mismatch

During the step of creating a HANA certificate from the CMC. The value for Service Provider Name is not the same.

Does not match:

Solution: These two Service Provider names need to match. Change the saml_service_provider_name to match the certificate.


For example:

7.2.2  Error 403 – Forbidden error

After logging into the Web Dispatcher Administration console, a 403 Forbidden error appears.

For example:

Solution: Grant the role sap.hana.xs.wdisp.admin::WebDispatcherAdmin role to the user trying to login.

 

7.2.3  Test Connection fails in the CMC

When testing the HANA Authentication connection in the CMC > Applications > HANA Authorization, an error occurs.

Connection Failed: The test of the HANA SSO ticket used to log onto the HANA DB has failed due to: [10]: authentication failed. (FWM 02133)

Solution:

      • Make sure the case sensitivity is correct for the “External Identity” and the BI Platform user.
      • After importing the certificate from SAP Web Dispatcher, the HANA system is restarted.
      • Ensure that the Service Provider Name matches the saml_service_provider_name.  See Service Provider Name Common Errors

 

The connection test may fail if there is a certificate collection with the purpose of SAML. To validate if this is the case, enable the authentication tracing mentioned in 7.1.1  Debug Tracing.


In the traces, the following will appear

 

0000-00-00 00:00:00.048768 i Authentication SAMLAuthenticator.cpp(00404) : Unable to verify XML signature"

 

But the following will NOT appear: 

 

i Authentication   SAMLAuthenticator.cpp(00691) : No in-memory PSE store for SAML - fallback to system trust store"

 

When you execute the following query, there is a record returned:


SELECT * FROM PSES WHERE PURPOSE='SAML'

Solution:
Review note: 2374226 - SAP HANA DB: SAML Logon from BI Platform to SAP HANA Database is not working

 

 

 

Connection Failed: The test of the HANA SSO ticket used to log onto the HANA DB has failed due to: SAP DBTech JDBC: Cannot connect to jdbc:sap://LSLES11SP3x64:30011/ [Cannot connect to host LSLES11SP3x64:30011 [Connection refused: connect], -813.].. (FWM 02133)

Solution: The BI Platform system cannot reach the HANA system. Make sure to check the following:

      • Check if the firewall is blocking the connectity between BI Platform and SAP HANA System.
      • Make sure the HANA port is the correct port. This is especially important when configuring SAML with a mult-tenant HANA system.

7.2.4  IDT Test Connection fails

Selecting Test Connection in IDT fails with error:

Fail to create an instance of Job : Cannot cast class java.util.ArrayList to class java.lang.String

Solution: The connection test has failed. Most likely, this error appears when the CMC connection test also fails. Click here to go to that section.

7.3  References and Notes

 

 

 

 

 

 

 

 

 

 

 

  • No labels

16 Comments

  1. Great overview! Have a question though. Is SSL required for SAML SSO? It's not listed as a prerequisite?

    1. Hi,

      Thank you for your question.

      Great recommendation. I will add this into the prerequisites. SSL is very strongly recommended in any SSO configuration.

      Cheers,
      Jimmy

       

       

  2. Former Member

    Hi Jimmy,

    We have SAML configured as mentioned in your blog in our landscape with both BOBJ and HANA On premise. Currently we are evaluating to move HANA to SAP cloud platform  with HANA DB as service and leave BOBJ on premise landscape. Can you please advise if above mentioned SAML configuration works between BOBJ(Intranet Zone) and HANA (Internet Zone) ?

    Thank you

    Ravi

    1. Hi Ravi,

      This should work as long as the network is set up so that the two systems can communicate.

      Cheers,
      Jimmy 

  3. Former Member

    Hi Jimmy,

    I was told this setup will not work if both systems are not on same network by SAP support. is that true statement?

    Thank you

    1. Private Message me your incident number I'll have a look. 

  4. Former Member

    163901/2017 , I m unable to find a way to private message you..

    1. Hi Ravi,

      I've taken a look at the incident and the statement may have been misinterpreted. I think what the engineer was stating was that if the BOBJ system cannot "talk" to the HCP system, then the authentication will not work.

      I have moved your incident to a team that specializes in cross system authentication questions. They should be able to assist you further and then get you to development if need be.

      Cheers,
      Jimmy

  5. Former Member

    Make sure the 'Disable ODBC/JDBC access' is UNCHECKED  when creating the SAML user or the test connection will not work!

     

    d14.png

    1. Great Catch. I didn't even realize I had that checked off.

      I'll update the picture.

  6. Hi,

    Great instructions, thank you!  

    This is the first document around this process that I have found that indicates a version perquisite of HANA SPS10 and I would like to confirm that this is a "hard requirement".  None of the other posts or OSS Notes that I have found on this subject mention this.  Before we invest time in this process ( we are on HANA 1.00.097) I am hoping that you can confirm.

    Thanks again for the detailed documentation.

    Rgds,

    Mel

    1. Hi Mel,

      I need to reword that section. That isn't so much a prerequisite, but just the version that this document is based on.

      Version 2 is in the works using the in-memory trust store so stay tuned.

      In the mean time, I'll update this document.

  7. sapsrv.pse → Default all tenant databases use the same trust store as the system database for SAML-based user authentication


    5.4 Import Certificate into HANA Security → For HANA MDC, it will be done in tenant DB level? right?


    1. Hi Nina,

      Yes this would be created on the tenants. 

      This wiki guide is a bit old. I think it's time to get it updated for 2.0! I'll work with some of my colleagues and get a new version out on this topic.

      Best Regards,

      Jimmy

  8. Hi Jimmy,

    I find the latest one:

    Note 2593701 - HOW-TO In-Memory Trust Store and HANA DB SSO SAML and BI Platform 4.2 / Analysis for Office 4.2

    Regards,

    Ning

    1. yes, I created that white paper. I just haven't had the time to convert it into this wiki page.