How to Configure SAP HANA for SAML SSO with Tableau Server

Version 14

    Starting with version 9.1, Tableau Server supports SAML single sign-on (SSO) for SAP HANA.

     

    Note: This article describes how to configure SAP HANA for SSO using SAML. The bulk of this information is specific to SAP HANA, and Tableau can only offer limited support on this process, and cannot guarantee the accuracy of this documentation. SAP and the SAP HANA documentation are the definitive resource for how to set this up. You can verify that HANA has been configured correctly without Tableau - see "Validate your configuration" below. If this validation fails, then the HANA configuration is not correctly set up and will not work with Tableau.

     

    Requirements

    • Tableau Desktop requires an SAP HANA driver version 1.0.85 or later for HANA SSO (Kerberos).
    • Tableau Server requires an SAP HANA driver version 1.00.9 or later to use HANA SSO (SAML).
    • Kerberos is required for authentication to SAP Hana for Tableau Desktop users who will be publishing workbooks or datasources. The publisher of the datasource will connect using Kerberos, and then when publishing should select the "Viewer Credentials" option. However, Kerberos is not required for authentication to Tableau Server.

     

    Note: The HANA driver cannot encrypt SAML assertions, so we recommend that you enable encryption of SAML connections. For more information, see Customize SAP HANA Connections to Enable SAML Encryption. The publisher can also now enable SSL when creating the datasource.


    To use SAML SSO with SAP HANA, you need to complete steps 1 and 2 in this article. Step 1 is configuring Tableau Server. Step 2 is configuring SAP HANA and can be validated independently of Tableau.

     

    Step 1: Configure Tableau Server for SSO with SAP HANA

    1. Get or generate a key pair (a signed public key and a private key) to use for SAML SSO.

      You can generate the key pair using any identifying information you want. Tableau Server does not need a particular host name for SAP HANA SSO. As a best practice, you should use the fully qualified domain name. For more information, see www.geocerts.com/faq.

      You can generate the key pair in one of two ways:

      • Using OpenSSL. For example: openssl req -out CSR.csr -new -newkey rsa:2048 -nodes -keyout privateKey.key    


        This generates a certificate signing request and a private key in PEM format. Tableau Server expects the certificate in PEM format and the key in DER format. Use OpenSSL to convert the key to DER. For example:

        openssl rsa -outform DER -in privateKey.key -out privateKey.der For more information, see the OpenSSL documentation.

      • Using built-in tools that come with Windows. For more information, see the Microsoft documentation.
    2. Get the certificate signed by a trusted root authority. This can be a certificate authority such as Verisign, Thawte, Comodo, or GoDaddy, or your company's root certificate. The root certificate must be installed on HANA if it is not already present.
    3. Install the key pair in Tableau Server. For more information about how to configure Tableau Server, see Configuring SAP HANA SSO in the Tableau Server help.


    Step 2: Configure SAP HANA

     

    Confirm your SSL library and location of the trusted store

    You need to install the new certificate in the HANA trusted certificate store. The instructions for installing the certificate depend on what SSL library you are using. Confirm the library you are using and the location of the trust store, and then follow either the SapCrypto/CommonCrypto instructions or the OpenSSL instructions. You only need to do one. SapCrypto/CommonCrypto may be easier to configure, especially for self-signed certificates.

     

    To see what SSL library you are using, open HANA Studio and navigate to the configuration files in one of the following locations (note: These are listed in order of preference, with indexserver.ini overriding global.ini):

     

    The library will be openssl, sapcrypto, or commoncrypto (commoncrypto is the successor to sapcrypto and the two are equivalent for the purposes of this documentation).

    • Configuration > indexserver.ini > communication > sslcryptoprovider
      or
    • Configuration > global.ini > communication > sslcryptoprovider.

     

    To find the location of the trust store, open HANA Studio and navigate to (listed in order of preference):

    • Configuration > indexserver.ini > authentication > saplogontickettruststore
    • Configuration > indexserver.ini > communication > ssltruststore
    • Configuration > global.ini > communication > ssltruststore.

    Install certificates

     

    Note: Follow either the SAP/CommonCrypto or the OpenSSL instructions. You do not need to do both.

     

    Copy the new certificate(s) to a temporary location in the HANA file system.

     

    To install the certificate(s), do one of the following:

    • Install certificates for SapCrypto/CommonCrypto


      SapCrypto/CommonCrypto libraries store the trusted certificates in Personal Security Environment (PSE) files. The name and location of this file will be specified in the configuration parameters. For this example we are using sapsrv.pse, which is located in $SECUDIR.

      1. If the system PSE does not already exist, create one and update the indexserver.ini configuration to point to the new PSE using these commands:
        cd $DIR_EXECUTABLE
        /sapgenpse gen_pse -p $SECUDIR/sapsrv.pse
      2. Add the Tableau Server certificate chain to the PSE:
        /sapgenpse maintain_pk -p $SECUDIR/sapsrv.pse -m certificate.crt
      3. Restart HANA:
        $DIR_INSTANCE/HDB restart
    • Install certificates for OpenSSL

      OpenSSL libraries store the trusted certificates in PEM files. On HANA, this is usually in a file called trust.pem. Verify the configuration parameters for the name and location of the OpenSSL trust store.

      • If the trust store does not already exist, create one and update the indexserver.ini configuration to point to the new file:
        cd $HOME/ ssl
        touch trust pem
      • Append the Tableau Server certificate chain to the PEM file:
        ./cat certificate.crt >> trust pem         
      • If you are using a self-signed certificate, you also need to add the certificate to the system-wide root CA store in /etc/ssl/certs. You will also need to create a hash link to the file. OpenSSL will use the hash value of the certificate to look it up. Be sure to set the appropriate level of read permissions on the file:

        ./cp certificate.crt /etc/ssl/certs
        HASVAL='openssl x509 -noout -hash -in certificate.crt'

        ls /etc/ssl/certs/$HASHVAL*                    

        If there are no other certificates with the same hash value, create the sym link:

        ln -s /etc/ssl/certificate.crt $HASHVAL.0

        If there are other certificates with the same hash value, then increment the last number, for example:

        ln -s /etc/ssl/certificate.crt $HASHVAL.1

        Note: New versions of HANA support managing the certificates in the database rather than in the file system. For instructions on adding certificates in the database, consult your HANA documentation.

     

    Create an identify provider (IdP) and user mappings in SAP HANA Studio

    1. Create an IdP by importing the certificate using SAP HANA Studio. Note: This does not import the certificate into the HANA trust store, it just uses the information in the certificate to create the IdP mapping. 

      Navigate to Security > SAML Identity Providers.

      Click Import SAML identity provider from certificate file and select the certificate you created for the Tableau Server IdP.

    2. Enable SAML authentication for the user and set up external identity using the format you specified in the Tableau Server Configuration utility.

     

    The following external resources may help you configure SAP HANA for SSO with Tableau Server:

     

     

    Validate your configuration

    You can manually validate your configuration by signing an assertion with your certificate and testing it in HANA Studio.

     

    1. Sign the assertion using the XMSec command-line tool. For details, see Signing XML document using xmlsec1 command line tool.

      You can use the following assertion (copy the text and paste it into a file, and then save the file as assertion_fragment.xml).

      Note: Substitute your external id for "myuserid" in the fragment below.

      <?xml version="1.0" encoding="UTF-8" ?>
      <saml2:Assertion ID="Assertion12345789" IssueInstant="2015-07-16T04:47:49.858Z" Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        <saml2:Issuer></saml2:Issuer>
        <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
          <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
              <Transforms>
                <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
              </Transforms>
              <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
              <DigestValue />
            </Reference>
          </SignedInfo>
          <SignatureValue />
          <KeyInfo>
            <X509Data />
          </KeyInfo>
        </Signature>
        <saml2:Subject>
          <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">myuserid</saml2:NameID>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2010-01-01T00:00:00Z" NotOnOrAfter="2050-01-01T00:00:00Z"/>
      </saml2:Assertion>

      The command you use will be similar to this:

      xmlsec1 --sign --privkey-pem privkey.pem,cert.pem --output signed.xml assertion_fragment.xml

    2. Connect to HANA using HANA Studio and your normal authentication (password or Kerberos).
    3. Test the assertion either by:
      • using this command:

        CONNECT WITH SAML ASSERTION '<insert SAML assertion>'


        Don't modify the white space in the assertion. Making any changes will invalidate the hash of the document. The signature assures that the person with the certificate created the document, and that the document hasn't been tampered with.

        or

      • You can also test the assertion using the command line utility hdbsql, with the parameter -saml-assertion. However, if the user who runs the tool is configured for Kerberos login to HANA, the driver will ignore the saml assertion and instead use Kerberos and a successful login won't confirm that the HANA SAML configuration is correct. See Troubleshooting below.

     

    If logging on using either of these methods fail, then there is something wrong with the SAP HANA configuration. Consult your HANA documentation or contact SAP for further assistance

     

    Troubleshooting

    Error messages from the Hana driver can be vague. Hana doesn't give specifics on the cause of authentication failure as a security measure.

    If you have problems with authentication, you must debug it on the database side.

    Enable authentication trace logging at the debug level in SAP HANA. Enable this at the database level for all users and check the index server logs for authentication messages.

     

    You can find details about enabling trace for SAP HANA here:

    Note for newer version of Hana Studio you may have to select the "Show All Components" checkbox on the "Edit Database Trace Configuration" dialog.

    Go to indexserver -> authentication and change "System Trace Level" to debug.

     

     

    Common issues to look for:

    • Kerberos enabled in HANA

      If the logs show that the Tableau Server service (Run As) user is being logged in, make sure that Kerberos is not enabled for the Run As user in HANA. The HANA driver will try Kerberos authentication first, and if this succeeds, the SAML authentication is ignored.

    • Session cookie authentication failure

      If the logs show that the session cookie authentication failed, this could be a driver issue. If you are using HANA driver 1.0.101, downgrade to 1.0.95 to see if this resolves the problem.

    • Cannot verify signature

      If the logs show that there was a problem verifying the signature, the certificate was not installed correctly or the database may require a restart of the server to pick up the new certificates.

    • No matching SAML provider

      This can be caused by many issues:

      • The file location where the certificates were installed may be incorrect. Check the relevant configuration parameters in the .ini files. Validate that you added the certificates to that location.
      • There may also be a problem with the certificate. The EmailAddress attribute in DN is deprecated. We've found that the email address in the DN of a certificate is not handled correctly during import into HANA Studio. Try recreating your certificate without specifying an email address, or by using another attribute such as MAIL or subjectAltName.
    • External ID doesn't match

      Check the format in the user’s SAML configuration. The trace logs should show the actual assertion. Note: The external identity string is part of secure data and is not logged by Tableau Server. The Tableau Server logs will show the domain qualified username, but this is not the external identity string.

    • Assertion is not yet valid

      SAML assertions will be issued which include not-before conditions. If the time difference between Tableau Server and HANA is large, then the assertion may not yet be valid when it reaches HANA (in the case where Tableau Server is ahead of HANA). Resync the clocks.

    • Driver version errors

      If there is an error with connecting to HANA, Tableau Server will try to diagnose the cause. Some HANA driver versions (1.0.90-1.0.92) were incorrectly labeled inside the library. As a result, Tableau Server may report an error message about driver requirements. In this case, it is not the root cause of the problem. We only check this after an error occurs.

    • Prompt to sign in when viewing workbook on Tableau Server

      There may be a problem with the certificate. The EmailAddress attribute in DN is deprecated. We've found that the email address in the DN of a certificate is not handled correctly during import into HANA Studio. Try recreating your certificate without specifying an email address (when prompted by OpenSSL, leave it blank), or by using another attribute such as MAIL or subjectAltName.

    • There was no SAML assertion available for delegation.

    Tableau Server was not able to generate a SAML assertion. We have found that generally is due to issues with the key provided. Ensure the key is not password protected and is DER encoded with a .der extension

    If logging on using either of these methods fail, then there is something wrong with the SAP HANA configuration. Consult your HANA documentation or contact SAP for further assistance