The following blog entry can serve to guide you through configuration and troubleshooting problems that may occur while configuring single sign on (SSO) via SAML on HANA Cloud Platform (HCP). It will describe the basic steps which need to be conducted when setting up this kind of configuration, including a lot of screenshots and comments. Additionally it points out all problems that arose in our activities.
Some information on the application we are running:
- SAP Innovation Management 1.0.2
- JavaScript/XS-Application running on XS-Engine
- Hosted on Hana Cloud Platform (HCP) – HANA DB Rev. 80
Target:
- SP-initiated SSO with ADFS (Active Directory Federation Services - rollup pack 3) – not IDP-initiated! (not supported in HCP rev. 80)
More detailed information on versions...
Requirements to configure this type of scenario:
- HANA HCP access (to access HCP dashboard)
- HANA DB access (+ resp. rights/priviledges)
- HANA Studio with HANA Cloud Platform Tools
- latest NEO command line tool
- ADFS metadata file (xml) (IDP metadata)
- IDP certificate
- HCP metadata file to hand over to IDP
- You may have a temporary AD user in order to test SSO yourself
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Important note:
In advance I wanted to mention the following SAP-help page, which is related to JAVA-Applications only (not usable for XS-Applications) “ID Federation with the Corporate Identity Provider” – following this configuration guide for XS-Applications won’t achieve anything:
https://help.hana.ondemand.com/help/frameset.htm?dc618538d97610148155d97dcd123c24.html
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
In the following I try to describe each step that I walked through while setting up the SSO environment:
Short overview/table of contents:
- Get identity provider metadata
- Upload certificate into HCP XS-Engine
- Trust configuration to IDP in HANA Cloud Platform (HCP)
- Create HTTP-Destinations for XS-Applications
- Configure SSO/SLO endpoints
- Change authentication method of your application
- Adjust users and enable SAML
- Configure Trust on the Identity Provider Side (IDP)
Troubleshooting - Debugging logon tries to your application
References
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1. Get identity provider metadata
As we target SSO via SAML with AD users, the following data was given (original URL was changed):
https://customerurl*.url.com/federationmetadata/2007-06/federationmetadata.xml
This xml sheet basically describes everything related to federated logon configuration for this specific IDP. It provides us URLs and the certificate we need to upload in the next step.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2. Upload certificate into HCP XS-Engine
In this step you need:
- Certificate file of your IDP OR federation metadata file with certificate data
- Latest NEO-Command line tool
Certificate of your IDP
As you may only have a metadata file of your IDP. You need to extract the corresponding certificate data out of this file and create a certificate yourself. In our case we extracted the certificate data from a xml federation metadata file from our IDP’s active directory.
We basically just copied the string that was standing in between <X509Certificate> brackets and put it into a *.txt file which was then saved as *.PEM/*.DER certificate.
Latest NEO-Command line tool
This task needs to be done in revision 80 via neo command line tool. Therefore you need to download the tool onto your local machine (in HAN SPS09 you would use the web interface in your XS-Admin section).
Access: https://tools.hana.ondemand.com/
Extract the neo tool to a folder of your choice.
You now have your neo tool extracted and your certificate file in some folder on your machine. We are now moving over to the upload procedure itself...
Upload procedure
As you won’t be able to upload the certificate via web interface in HCP XS-Admin (in HANA HCP SPS09 this will be possible) nor access OS-level, you need to upload the corresponding certificate via the following commands, using the neo-command line tool, which is described in the following. Moreover it doesn’t make any difference if you grant yourself the following roles – you be able to access the tab “SAML Provider” either:
Open a new command line session in windows (windows key + r -> “CMD” -> enter), navigate to your neo tools folder (“cd your_neo_tool_path\tools”) and paste all commands you need to execute. The documentation for the neo-command line tool can be found here:
https://help.hana.ondemand.com/help/frameset.htm?46acebcd81384c9881f8ae7c5f3e3cac.html
Upload certificate
Command template
neo upload-hanaxs-certificates --host hana.ondemand.com --account myacc --application myapp --user mymail@example.com --location C:\Certificates\myCert.pem
Command to use
neo upload-hanaxs-certificates --host hana.ondemand.com --account ACCOUNT -a ACCOUNT --user USERNAME --localpath C:\Certificates
You get your Account ID (ACCOUNT) in the welcome screen of your HCP dashboard:
The result should look like this:
Restart the SAP HANA XS service as well as the indexserver so the upload comes into effect. This is done using the restart-hana console command.
neo restart-hana --service-name xsengine --id myhanaid --account myaccount --host hana.ondemand.com --user mymail@example.com
Restart XSENGINE
neo restart-hana --service-name xsengine --id xs --account ACCOUNT --host hana.ondemand.com --user USERNAME
Restart INDEXSERVER
neo restart-hana --service-name indexserver --id xs --account ACCOUNT --host hana.ondemand.com --user USERNAME
After both services restart, list the certificate(s) you uploaded. List the available HANA XS certificates to check if the certificates were uploaded successfully.This is done using the list-hanaxs-certificates command.
Command template
neo list-hanaxs-certificates --host hana.ondemand.com --account myaccount --application myapp --user mymail@example.com --contained-strng John Doe
Command to use
neo list-hanaxs-certificates --host hana.ondemand.com --account ACCOUNT -a ACCOUNT --user USERNAME
This is how your result should look like (in this case only one certificate has been uploaded) - for sure you certificate data will differ from what is shown here:
Other neo-commands that may be helpful in this context:
Get system status (DB-information, versions)
Command template
neo status --account <account_name> --application <application_name> --host <landscape_host> --user <e-mail_or_user>
neo status --host hana.ondemand.com -a ACCOUNT --application ACCOUNT --user USERNAME
Stop a service running on your HCP
Command template
neo stop --host hana.ondemand.com --account myacc --application myapp --user mymail@example.com --synchronous
neo stop --host hana.ondemand.com --account ACCOUNT --application ACCOUNT --user USERNAME –synchronous
Delete an existing certificate
Command template
neo delete-hanaxs-certificates --host hana.ondemand.com --account myacc --application myapp --user mymail@example.com --contained-string John Doe
Command to use
neo delete-hanaxs-certificates --host hana.ondemand.com --account ACCOUNT -a ACCOUNT --user USERNAME --contained-string STRINGIDENTIFIER
Reconcile Certificates
Command template
neo reconcile-hanaxs-certificates --host <landscape_host> --account <account_name> -a <application_name> --user <e-mail_or_user>
Command to use
neo reconcile-hanaxs-certificates --host hana.ondemand.com --account ACCOUNT -a ACCOUNT --user USERNAME
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
3. Upload certificate into HCP XS-Engine
To create a SAML Provider in HANA you may follow this help page:
http://help.sap.de/saphelp_hanaone/helpdata/en/20/d4cca075191014824eeda2cbba6445/content.htm
(You get certificate related data from your IDP (Identity provider) or you may extract from a federation xml-file)
In you SQL-console you need to fire the following SQL-command to create a SAML provider:
CREATE SAML PROVIDER PROVIDERNAME WITH
SUBJECT 'SUBJECT CONTENT OF YOUR CERTIFICATE'
ISSUER 'ISSUER CONTENT OF YOUR CERTIFICATE'
ENABLEUSER CREATION;
This command will create the following entry - first navigate to the screens shown below:
- Your HANA HCP System à Security
2. new entry should have been created in the following screen (Security à SAML Identity Providers):
You may not face the problem occurred in our case at all, nevertheless it’s worth reading through it!
Problems occurred:
As in our case the imported certificate, provided by the IDP/business partner, was a very “complex” certificate, we could not manage it finding the correct string value for “Issued To” and “Issued By”. This was mainly due to an incorrect parsing algorithm on HCP-side. Just as a side note, the “Issued To” string had a length of 213 characters, “Issued By” a length of 95 characters – this may be quite unusual as well to use such a certificate for this purpose. Because of this fact we were running numerous times into the following error:
How could we finally manage it?
Finally we set up a test environment with HANA SPS09, configuring all trust relationships to our IDP/SAML configuration as we did in the productive environment.
Through debugging and SAML tracing we could then identify the exact string values that were necessary to use as “Issued To” and “Issued By”.
Additionally, as the certificate provided by the IDP was very complex, we uploaded two more certificates, as you can see below. In total we now had three certificates uploaded to XS-Engine. Reading the certificates from top till down you can recognize that a separate certificate of the issuer “CN=Symantec Class 3…” of our IDP’s certificate has been uploaded. This in turn has another issuer “CN=VeriSign Class 3…” which was then additionally uploaded as the third certificate.
You can access this data as well with the following SQL-command:
SELECT * FROM SYS.SAML_PROVIDERS
Having created your SAML-Provider no restart of neither XS-Engine nor indexserver is required.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
4. Create HTTP-Destinations for XS-Applications
The following information has been extracted from https://help.hana.ondemand.com/help/frameset.htm?2a71022f17ee454586d753008f61885b.html“SAML 2.0 Configuration”:
insert into _SYS_XS.HTTP_DESTINATIONS values('sap.hana.xs.samlProviders', '<uppercase idp name>', '<idp description>', '<idp host>', <idp port>, '<path prefix>', <use proxy>, '<proxy host>', <proxy port>, 0, <use SSL>, <timeout>, '', '');
Parameter | Description and Values |
<uppercase idp name> | Create a short name for this IdP in uppercase. |
<idp description> | A free-text description. |
<idp host> | The IdP host. |
<idp port> | The IdP port. |
<path prefix> | A path prefix to be used for all endpoint URLs. |
<use proxy> | Values:
|
<proxy host> | The proxy host. Empty string if none. |
<proxy port> | The proxy port. |
<use SSL> | Defines if the communication will be over HTTP(S). Values:
|
<timeout> | The timeout in milliseconds. If the value is -1, then the timeout is infinite. |
In our case I created the HTTP-Destination using the following parameters (no proxy in use, SSL use: yes, ADFS related configuration): - original parameters were changed
Parameter | Description and Values |
<uppercase idp name> | 'IDP-NAME' |
<idp description> | 'FREETEXT' |
<idp host> | ‚adfs.IDPNAME.com‘ |
<idp port> | 443 |
<path prefix> | ‘’ |
<use proxy> | 0 |
<proxy host> | ‘’ |
<proxy port> | ‘’ |
<use SSL> | 1 |
<timeout> | -1 |
insert into _SYS_XS.HTTP_DESTINATIONS values('sap.hana.xs.samlProviders', 'IDP-NAME', 'FREETEXT', 'IDP-HOSTNAME', 443, '', 0, '', 0, 0, 1, -1, '', '');
To browse the configuration you can review it via the following SQL-command:
SELECT * FROM "_SYS_XS"."HTTP_DESTINATIONS"
----------------------------------------------------------------------------------------
5. Configure SSO/SLO endpoints
Following the SAML 2.0 Configuration you need to configure endpoints using the following SQL-statements:
Configuration | SQL Statement | Example |
SSO Redirect binding | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('<uppercase idp name>', 0, 0, 'sap.hana.xs.samlProviders', '<uppercase idp name>', '<SSO redirect endpoint URL>'); | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('NOVO1', 0, 0, 'sap.hana.xs.samlProviders', 'NOVO1', '/saml2/idp/sso/novo'); |
SSO POST binding | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('<uppercase idp name>', 0, 1, 'sap.hana.xs.samlProviders', '<uppercase idp name>', '<SSO POST endpoint URL>); | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('NOVO1', 0, 1, 'sap.hana.xs.samlProviders', 'NOVO1', '/saml2/idp/sso/novo'); |
SLO Redirect binding | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('<uppercase idp name>', 1, 0, 'sap.hana.xs.samlProviders', '<uppercase idp name>', '<SLO redirect endpoint URL>'); | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('NOVO1', 1, 0, 'sap.hana.xs.samlProviders', 'NOVO1', '/saml2/idp/slo/novo'); |
SLO POST binding | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('<uppercase idp name>', 1, 1, 'sap.hana.xs.samlProviders', '<uppercase idp name>', '<SLO POST endpoint URL>'); | insert into _SYS_XS.SAML_PROVIDER_CONFIG values('NOVO1', 1, 1, 'sap.hana.xs.samlProviders', 'NOVO1', '/saml2/idp/slo/novo'); |
Note You need to configure all four endpoints, executing all four statements.
These SQL-Commands have I executed in HANA Studio SQL console:
<uppercase idp name> = SAML-Provider that you created in step 3 of this guide
insert into _SYS_XS.SAML_PROVIDER_CONFIG values('SAML PROVIDER NAME', 0, 0, 'sap.hana.xs.samlProviders', 'DESTINATION NAME', '/adfs/ls');
insert into _SYS_XS.SAML_PROVIDER_CONFIG values('SAML PROVIDER NAME', 0, 1, 'sap.hana.xs.samlProviders', 'DESTINATION NAME', '/adfs/ls ');
insert into _SYS_XS.SAML_PROVIDER_CONFIG values('SAML PROVIDER NAME', 1, 0, 'sap.hana.xs.samlProviders', 'DESTINATION NAME', '/adfs/ls ');
insert into _SYS_XS.SAML_PROVIDER_CONFIG values('SAML PROVIDER NAME', 1, 1, 'sap.hana.xs.samlProviders', 'DESTINATION NAME', '/adfs/ls ');
Executing these statements you will generate the corresponding entries for single sign on and single log out. However HCP SPS08 does not support single log out. Therefore SLO entries are somehow obsolete, but need to be generated as well.
Problems occurred:
In one of our tests, having not been aware of IDP-initiated logon would not work, we defined the following URL as an SSO endpoint (1st and 2nd SQL-statement above - SSO POST binding & Redirect binding):
/adfs/ls/idpinitiatedsignon.aspx?logintoRP=ACCOUNTNAME.hana.ondemand.com
(ACCOUNTNAME = as described in step 8 of this guide)
Using this configuration we ran into the following error “No RelayState found in request”:
This was due to HCP SPS08 version which does not support IDP-initiated logon.
If you want to alter entries in this section, you may use the following SQL-Command:
This table has the following column-names:
SAML_PROVIDER, PROFILE_TYPE, BINDING_TYPE, DESTINATION_PACKAGE, DESTINATION_NAME, PATH
UPDATE _SYS_XS.SAML_PROVIDER_CONFIG SET COLUMN-NAME = '' WHERE COLUMN-NAME = '';
You may access this data via the following SQL-command:
SELECT * FROM _SYS_XS.SAML_PROVIDER_CONFIG
----------------------------------------------------------------------------------------
6. Change authentication method of your application
Now you need to access your application specific authentication settings in XS-Engine Administration web interface. Navigate from your HCP dashboard to XS-Administration page. Navigate to the application’s package that you want to enable SAML for. You should now be able to select the SAML Identity Provider that you created in step 3.
----------------------------------------------------------------------------------------
7. Adjust users and enable SAML
In order to enable SSO you need to set SAML as the basic authentication method for every user:
You can specify these settings as well using the following SQL-commands:
- 1. ALTERUSER USERNAME ENABLE SAML;
- 2. ALTERUSER USERNAME ADDIDENTITY 'EXTERNAL IDENTITY' FOR SAML PROVIDER FIRMENICH;
If you use the same usernames in the application as in your AD, your External Identity will be for sure the same as your username. For the existing 200 users we have in the system currently, I simply created an excel sheets in order to somehow automate and facilitate creating these SQL-statements (application usernames + AD usernames are the same in our scenario!)
----------------------------------------------------------------------------------------
8. Configure Trust on the Identity Provider Side (IDP)
Download the SAP HANA service provider metadata from the following URL:
https://ACCOUNTNAME.hana.ondemand.com/sap/hana/xs/saml/info.xscfunc
ACCOUNTNAME: Your HCP’s account name (typically XS + Account ID)
- e.g. Account ID = p7823ksd à ACCOUNTNAME = xsp7823ksd
Import the SAP HANA service provider metadata in the identity provider. See the identity provider vendor’s documentation for more information.
Important note:
On AD-side configuration for the service provider needs to be done the following way
As in rev. 80 only SHA-1 is supported, you need to make sure having configured this setting:
Furthermore you need to specify a transformation to Name ID (id format unspecified):
In your case it may not be “UPN” as the incoming claim type, but another one. This depends on your ADFS version and rollup pack. It may even be necessary to setup a custom rule for this. How such a rule can be setup
The SAML-message which is created based upon this configuration must have the following assertion:
<NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">AD-USERNAME</NameID>
This kind of assertion is incorrect and won’t work:
<NameID>AD-USERNAME</NameID>
----------------------------------------------------------------------------------------
9. Test accessing your application via SSO!
Troubleshooting - Debugging logon tries to your application
You may use the trace functionality in order to get higher transparency when it comes to troubleshooting. Besides using a SAML-tracer in Firefox, we activated DEBUG traces every now and then (Open Administration of your system in HANA Studio -> Trace Configuration -> Database Trace -> Configuration):
We made use of the following traces:
| Trace level |
Indexserver |
|
Authentication | DEBUG |
XS-Engine |
|
Authentication | DEBUG |
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
References
https://help.hana.ondemand.com/
https://help.hana.ondemand.com/help/frameset.htm?2a71022f17ee454586d753008f61885b.html
http://scn.sap.com/docs/DOC-50418
https://help.sap.com/hana/SAP_HANA_Administration_Guide_en.pdf
https://help.hana.ondemand.com/help/frameset.htm?e6b196abbb5710148c8ec6a698441b1e.html
https://help.hana.ondemand.com/help/frameset.htm?46acebcd81384c9881f8ae7c5f3e3cac.html