SAML2 Integration with Spotfire® (an example with Shibboleth)

Introduction

This document describes how Spotfire^® can use SAML2 protocol. It describes all tools provided to use external authentication protocols including SAML. This document has been udpated to work with Spotfire 10.10 and support the additional required security for the AJP Connector.

SAML stands for (Security Assertion Markup Language) is a security standard used for authentication agains Identity Providers (IdP). for more information please refer to this page: https://en.wikipedia.org/s/article/Security_Assertion_Markup_Language

Basically all this is possible thanks to the following components:

In our context, we have installed the SP Shibboleth (https://shibboleth.net/products/service-provider.html) along with apache http://www.apachelounge.com/. Also note that we are performing a Windows Installation.

The following sections describe this installation.

Apache Installation

In this section we will presume both Spotfire Server and Shibboleth SP have been respectively installed on C:\opt\shibboleth-sp (SHIB_DIR) and C:\tibco\tss\<version> (SPOT_DIR).

Go to the apache download web site http://www.apachelounge.com/. The Apache versions available from this web site are known to work with the modules that come with the Windows version of Shibboleth.

Be sure that you have installed the latest C++ Redistributable Visual Studio 2015 or 2017 : vc_redist_x64/86.exe. then downloand the Apache http and extract in C:\Apache24 (APACHE_DIR). You will need at least the 2.4.42 version in order to support the secret= settings.

Edit the file c:/Apache24/conf/httpd.conf

# least PidFile.
#
# Ensure the following line is set correctly
ServerRoot "c:/Apache24"

#Locate or uncomment the line below. If not you need to manually add them.
#When manually adding a module you should ensure it really download with your apache distribution
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule proxy_http_module modules/mod_proxy_http.so


#add the following lines for reverse proxy with the Spotfire Server
ProxyPreserveHost On
#Spotfire Server
# AJP secret attribute is supported in Apache 2.4.42 and above is required for AJP
# make sure to replace "mysecret" with something more secure
# the "mysecret" must match the secret attribute in the Spotfire Server AJP Connector
ProxyPass / ajp://localhost:9009/ secret=mysecret
ProxyPassReverse / ajp://localhost:9009/ secret=mysecret
ProxyIOBufferSize 65536

#You have noticed that we use mod_ajp instead of mod_proxy. The reason for that is apache is somme #cases cannot transmit parameters to Tomcat (Spotfire Server)


#For Shibboleth configuration, add the below lines

#Shibboleth configuration 
Include C:/opt/shibboleth-sp/etc/shibboleth/apache24.config 
UseCanonicalName On 

<Location /Shibboleth.sso>
	SetHandler shib 
</Location>

<Location "/" >
	AuthType shibboleth
	ShibRequestSetting requireSession 1
	Require valid-user
	ShibUseHeaders On
</Location>

Optional: If single logout support is needed, then one needs to trap the logout from the Spotfire Server and have that trigger the SP (Shibbleth) to post the logout to the IdP. While Spotfire does call a logout page behind the scenes, the best thing to trap is the call to the login page. Adding the following Location directive to the httpd.conf can help with the SLO scenario:

<Location /spotfire/login.html>
    Redirect permanent "https:/<machine>/Shibboleth.sso/Logout"
</location>

## for Spotfire 10 and above another logout may occur
## when logout using menu in Analytics->User->Log out
<Location /spotfire/wp/LoggedOut.aspx>
    Redirect permanent "https://<your domain here>/Shibboleth.sso/Logout"
</Location>

As always, make sure to test this scenario and others within your environment to make sure it works as expected.

Setting up apache with SSO

There are two options: either use a self-signed certificate or import an authority provided certificate.

In both cases, you need to setup the Windows environment variable OPENSSL_CONF to point to the openssl.cnf files location. C:\Apache24\conf

To create a self signed certificate:

From a command line tool. Change directory to c:/apache24/bin

openssl req -new -out server.csr

openssl rsa -in privkey.pem -out server.key

openssl x509 -in server.csr -out server.cert -req -signkey server.key -days 365

Copy the server.cert and the server.key files in the folder c:/apache24/conf/ssl

Edit the c:/apache24/conf/httpd.conf file again and make the following changes

LoadModule ssl_module modules/mod_ssl.so

LoadModule socache_shmcb_module modules/mod_socache_shmcb.so

Include conf/extra/httpd-ssl.conf

Then open the file conf/extra/httpd-ssl.conf to add the following chnages.

#
# When we also provide SSL we have to listen to the 
# standard HTTP port (see above) and to the HTTPS port
#
Listen 443

...
#we can ignore this part of the file

<VirtualHost _default_:443>

#   General setup for the virtual host
DocumentRoot "c:/Apache24/htdocs"
ServerName spotfiredemo:443
ServerAdmin admin@local
ErrorLog "c:/Apache24/logs/error.log"
TransferLog "c:/Apache24/logs/access.log"

#   SSL Engine Switch:
#   Enable/Disable SSL for this virtual host.
SSLEngine on
SSLCertificateFile "c:/Apache24/conf/ssl/server.cert"
SSLCertificateKeyFile "c:/Apache24/conf/ssl/server.key"

At this point, we are almost done with Apache.

Use an existing certificate:

To download an existing certificate instead of a self signed please have a look at this https://www.sslshopper.com/move-or-copy-an-ssl-certificate-from-a-windows-server-to-an-apache-server.html. Basically, what you need is to export your certificate from your Windows machine.

Then copy the .pfx file to the server or another computer that has OpenSSL installed.

Run this OpenSSL command to create a text file with the contents of the .pfx file:

 openssl pkcs12 -in mydomain.pfx -out mydomain.txt -nodes

Open the mydomain.txt file that the command created in a text editor. Copy each certificate/private key to its own text file including the "-----BEGIN RSA PRIVATE KEY-----"and "-----BEGIN CERTIFICATE-----

Then replace the self-signed certificates from Apache by the new ones in the httpd-ssl.conf file. Depending on implementation, the certificates may also be used with Shibboleth for encrypting and decrypting the IdP communication.

Installing Shibboleth SP

Download and install Shibboleth SP from here http://shibboleth.net/downloads/service-provider/latest/ The currently used version is the shibboleth-sp-2.6.0.0-win64.msi http://shibboleth.net/downloads/service-provider/latest/win64/shibboleth-sp-2.6.0.0-win64.msi

Run the provided .msi while keeping as much as possible the default options.

At the end of the installation, you need the following. Edit the file C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml and ensure to choose a unique entityID for your SP (Shibboleth). The entityID will be shared with the IdP to uniquely identity your SP.

 <ApplicationDefaults entityID="https://spotfiredemo/shibboleth""
                         REMOTE_USER="eppn persistent-id targeted-id" attributePrefix="AJP_">

        ......

            <!--
            Configures SSO for a default IdP. To allow for >1 IdP, remove
            entityID property and adjust discoveryURL to point to discovery service.
            (Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
            You can also override entityID on /Login query string, or in RequestMap/htaccess.
            -->
            <SSO entityID="https://spotfiredemo/idp/shibboleth""
                 discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">;
              SAML2 SAML1
            </SSO>

            ....
    </ApplicationDefaults>

Also notice the attributePrefix="AJP_" The attributePrefix is critical. The mod_ajp will not pass through any attributes that do not have the prefix set to "AJP_".

In the SSO section, the entityID is the entityID from the IdP which is likely the external SAML Provider. The entityID can usually be found in the metadata.xml file.

If one is using the certificate for Apache as also a signing certificate for the IdP and SP communication, then one may need to add or modify the following lines in the shibboleth2.xml file. Make sure to use the correct names for the server.cert and server.key files. In this example, the server.cert and server.key files were copied from the Apache location to the C:\opt\shibboleth-sp\etc\shibboleth directory such that no file names were needed in the certificate attributes.

	<CredentialResolver type="File" use="signing"
		key="server.key" certificate="server.cert"/>
	<CredentialResolver type="File" use="encryption"
		key="server.key" certificate="server.cert"/>

And finally you should the metadata file profvided by your IdP. This metadata can be generated and provided by the IdP administrator.

Below is an example provided by the testshib online free IdP that uses URL for the metadata file.

<!-- Loads and trusts a metadata file that describes only the Testshib IdP and how to communicate with it. -->
        <MetadataProvider type="XML" uri="http://www.testshib.org/metadata/testshib-providers.xml""
             backingFilePath="testshib-two-idp-metadata.xml" reloadInterval="180000" />

The metadata information may also be provided as a file instead of a URL in which case the MetadataProvider tag would look like this:

<!-- Loads and trusts a local metadata file that describes only the Testshib IdP and how to communicate with it. -->
        <MetadataProvider type="XML" validate="true" path="c:/opt/myIPD_Metadata.xml>"/>

When the metadata is provided as a static file instead of a URL, any changes to the metadata on the IdP will require the file to be updated.

The next file to change is the attribute-map.xml. Attribute id is the attribute name that will be sent to Spotfire by shibboleth.

<!-- Fourth, the SAML 2.0 NameID Format: -->
    <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" id="persistent-id">
        <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
    </Attribute>
	
	
	<!-- Fourth, the SAML 2.0 NameID Format: -->
    <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" id="NameID">
        <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
    </Attribute>

We should ensure that at least one attribute is the same as the one returned by the SAML response. This value can be verified in shibboleth log files transaction and shibd. Your attribute values may be different than the ones listed here. The metadata file provided by the IdP should have the attribute mapping information that can be used to fill in the attribute-map.xml file correctly.

Configure Spotfire Server

In this step we assume that Spotfire Server will be protected by Shibboleth. remember this setting in Apache httpd.conf:

<Location />
    AuthType shibboleth
    ShibRequestSetting requireSession 1 
    Require valid-user
    ShibUseHeaders On
</Location>

Then we will have to change the server.xml located here C:\tibco\tss\<version>\tomcat\conf.

NOTE: The additional security attributes - allowedRequestAttributesPattern, address, secretRequired and secret - are required to provide additional security for the AJP connector. The secret attrbiute needs to match the secret provided in the httpd.conf file for the AJP proxy commands. Make sure to modify the address attribute as needed to match the address of the Apache HTTPD server. In this example, everything is installed on the same server so localhost - 127.0.0.1 - is used.

If Analyst is connecting via the AJP connector, then one should modify the maxHttpHeaderSize for the AJP Connector, e.g. set to 116384. An error may occur when saving analysis files if this value is too small.

<Service name="Spotfire">

  <!-- we should   different port for thick clients or setup an https on port 8433
		See below
  -->
    <Connector port="8080"
               maxHttpHeaderSize="16384"
               connectionTimeout="30000"
               enableLookups="false"
               URIEncoding="UTF-8"
               disableUploadTimeout="true"
               server="Spotfire Server"
               compression="on"
               compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,image/svg+xml,application/xml,application/octet-stream"               
               acceptorThreadCount="2"
               keepAliveTimeout="30000"
               maxKeepAliveRequests="-1"
               maxThreads="2000" />

<!-- Add a new AJP Port for Apache mod_ajp	
	-->
     <Connector port="9009" 
		enableLookups="false" 
		redirectPort="8443" 
		protocol="AJP/1.3" 
		packetSize="65536" 
		tomcatAuthentication="false"
				
		maxHttpHeaderSize="16384"
		connectionTimeout="30000"
		URIEncoding="UTF-8"
		disableUploadTimeout="true"
		server="Spotfire Server"
		compression="on"
		compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,image/svg+xml,application/xml,application/octet-stream"               
		acceptorThreadCount="2"
		keepAliveTimeout="30000"
		maxKeepAliveRequests="-1"
		maxThreads="2000"

		allowedRequestAttributesPattern=".*"
		address="127.0.0.1"
		secretRequired="true"
		secret="mysecret"
	/>

In the server.xml, if one only wants users to connect via the IdP, then the other client facing connectors should be commented out (in this example the 8080 connector). See below for information on how to have the Spotfire Analyst support connecting via the SAML2 protocol.

Note: If Spotfire Server and the Node Manager (Web Player) are installed on the same machine, one needs to modify the AJP port to be above 8099 as Web Player can use ports 8000-8099. If change the AJP port in server.xml, make sure to modify the AJP proxy lines in httpd.conf.

Finally we should change the Server configuration. Note the regular expression at the bottom of the next picture:

The reason for adding this expression .*\!(.*) is that the IdP returns the full path of the user e.g name="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"!NameID

Another useful Name Filter Expression is (.*)\@.* which will select the username from an email address, e.g. a value of myuser@mydomain.com will pass myuser to Spotfire Server.

One also needs to be mindful of the Post Authentication Filter setting. The Post Authentication Filter can either Block or Auto-create users not in Spotfire. Depending on how the Web SSO names are presented to Spotfire and the User Directory that Spotfire is using, the users may need to be auto created. Please see the Spotfire Server documentation - Post Authentication Filter for more information.

This document is still under development, so please contact me if you see anything I have forgotten or you need to better understand.

Spotfire Analyst Configurations

For Spotfire Analyst, one has several options when setting up the SAML (Web SSO) integration:

Spotfire Analyst with Web Authentication

Starting with Spotfire version 7.8, one can use SAML (Web SSO) for Analysts and iOS devices. The above procedure will then need to be adapted as follows.

- First : change the Apache/Shibboleth configuration to only intercept and authenticate requests to /spotfire/sf_security_check_external_auth (requests to all other paths should simply be let through). The following changes to the Apache httpd.conf configuration file should be made:

<VirtualHost *:80>
    #   General setup for the virtual host
    DocumentRoot "C:/Apache24/htdocs"
    ServerName WIN-399J5DLK4EL
    <Location /Shibboleth.sso>
        SetHandler shib
    </Location>
    <Location /spotfire/sf_security_check_external_auth>
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        Require valid-user 
        ShibUseHeaders On
    </location>
</VirtualHost>

In another implementation in which HTTPS was used for all connections, the above did not work since there was only the 443 connection for both Spotfire Analyst and browser users. The Shibboleth.sso section had to have all the authentication information and the Location is changed from '/' to /spotfire/sf_security_check_external_auth. The following changes httpd.conf worked in this other scenario (replacing the existing Location directives for Shibbleth and the root path ('/'):

<Location /Shibboleth.sso>
	SetHandler shib 
	AuthType shibboleth
	ShibRequestSetting requireSession 1 
	Require valid-user
	ShibUseHeaders On
</Location>

<Location /spotfire/sf_security_check_external_auth>
	AuthType shibboleth
	ShibRequestSetting requireSession 1 
	Require valid-user
	ShibUseHeaders On
</Location>

- Second: External Authentication should be used as primary authentication method for the Spotfire Server (User directory can be Database or LDAP):

And the "declared authentication method" (now part of the External Authentication configuration) should be set to "Web Authentication" as seen in this screen shot:

When users open the Spotfire Analyst, a web browser will open in which users can type in their Web SSO credentials and get logged in via the same method which they would use in a browser.

Spotfire Analyst Proxied Through Apache

In this case, Spotfire Analyst users will not use Web Authentication but will authenticate directly to Spotfire Server using the default method. This option is useful in scenarios where one can only expose the standard HTTPS port (443) and Spotfire Server and Apache are installed on the same machine. This allows Apache to use 443 and all users, web and analyst, to connect on the same port.

To ignore the Spotfire Analyst when it connects to Apache, the Apache httpd.conf file is modified to ignore the SSO authentication when the HTTP user agent is Analyst. The following is the updated Location section of the Apache httpd.conf file:

<Location / >
	<If "%{HTTP_USER_AGENT} !~ m#Spotfire.Dxp.ClientType/Professional#">
		AuthType shibboleth
		ShibRequestSetting requireSession 1 
		Require valid-user
		ShibUseHeaders On
	</If>
</Location>

An "If" block is added around the Shibboleth section such that when a browser connects this code is run but when Analyst connects it is ignored and the traffic is just passed through to Spotfire Server. Spotfire Analyst sets the HTTP User Agent header to a string that contains the string that is looked for: Spotfire.Dxp.ClientType/Professional.

Setting Spotfire Server Public Address

If one does configure Spotfire Analyst or Spotfire Mobile connections to Spotfire Server, then the Public Address for Spotfire Server might need to change. The Public Address is used when generating URLs to Spotfire Server like when sharing Spotfire Library items with others. When Apache Server is a proxy for Spotfire Server, the default public address URL for Spotfire Server may be incorrect which may cause issues with connectivity from the Spotfire Mobile applications especially.

The Public address URL should be set to the Apache Server URL which one uses in the browser to connect to Spotfire. The Public Address can be configured from the command-line using the config set-public-address command and via the Configuration Tool GUI:

After changing the Public Address, make sure to save the configuration to the database and restart all Spotfire Server(s) in order for the new public address to be used.

Common Responses to IdP Questions

When integrating with an IdP, the IdP will need information about how the SP (Shibboleth) is configured in order to integrate the systems. The following are the common answers when using Shibboleth as the SP (note the exact answers may change with your environment but this can be useful to give a head start):

The IdP (to receive SAML requests from the SP)
A service Provider aka SP (to send the SAML request to the IdP and and pases the information received from the IdP to Spotfire Server)
And of course your application (Spotfire Server) will authentication the user with information provided by the SP. Note that this can be done in a more avanced way. (See External Authentication in Spotfire Server)

Connect Spotfire Analyst directly to Spotfire Server allowing Analyst users to authenticate using the default authentication. With this option, a client facing port in the Spotfire Server server.xml file would need to be kept open. With Apache and Spotfire Server on the same machine, different ports will have to be used which means one could run into issues with ports that can be exposed, e.g. standard HTTP/HTTPS ports vs. non-standard ports. (See option #3.)
Configure Spotfire Analyst with Web Authentication (See next section): This requires changes to the Apache configuration and the Spotfire Server configuration.
Have Spotfire Analyst users connect through Apache with all requests from Analyst proxied through to Spotfire Server (See later section - Spotfire Analyst Proxied Through Apache). This option requires a modification to the Apache httpd.conf file and allows one to expose Spotfire Server on a single port to both web and analyst users and gets around any issues with different and non-standard ports.

What is entityID? This is the entityID attribute value from the shibboleth2.xml file in <ApplicationDefaults entityID=?<this value>?.....> One should make sure that this is a unique value.
What is ACS (Assertion Consumer Service) endpoint? https://<machine>/Shibboleth.sso/SAML2/POST
What is SLO (Single Logout) endpoint? https://<machine>/Shibboleth.sso/SLO/POST
What binding do you prefer for ACS? POST
What binding do you prefer for SLO? POST

Sign In