External Authentication in Spotfire®

Introduction

Many customers want to embed Spotfire^® Web Player into a portal or other web application and secure access by passing authentication information from the portal to Spotfire.  Customers also have internal Web application security standards that require Single-Sign-On to all web applications which would include Spotfire Web Player.  Spotfire supports these scenarios via custom and external authentication.  

This article focuses on custom authentication options in the current versions of Spotfire.  Previous versions of Spotfire had other custom authentication options, and there was a different architecture in Spotfire 7.0 and earlier.  An earlier version of this document discussed those differences and is attached to this article below for historical purposes. 

The Spotfire Server is the entry point for all client connections.  Other services like Spotfire Web Player, Spotfire Automation Services and Spotfire Enterprise Runtimer for R Server (available in Spotfire 10) have become a set of scalable backend services.   Figure 1 shows how the clients all connect to the Spotfire Server in order to be serviced.

Figure 1 Spotfire Architecture - Clients Connect to Spotfire Server

Other documents including the Spotfire Server Installation Manual have detailed information about the architecture.  This document focuses on just what is important in light of custom and external authentication to the Spotfire environment.

Many customers embed Spotfire Web Player into a portal or other web application or have a corporate single-sign-on method that is used to authenticate to any internal web applications.  Prior to Spotfire 7.5, this method of authentication has usually been called "Custom Authentication" because it required custom C# coding on the Web Player.   In Spotfire 7.5 and later versions, since the Spotfire Server is handling all client requests and authentication, there is a configuration option called "External Authentication" that will handle most cases without coding.

This document walks through the various options with custom and external authentication.  

Other Resources

• Spotfire Server API for custom authentication
• Server Platform API Reference
• Extending Spotfire - overview of the different extension and customization options that the Spotfire platform provides.
• SAML2 Integration with Spotfire

Use Cases for Custom/External Authentication

Spotfire supports an almost unlimited set of possible configurations.  For the purposes of this document, we have focused on the following major use cases:

Custom Authentication in Spotfire

In this section, "External Authentication" and "Custom Authentication" will be used interchangeably.  The configuration option in Spotfire is labeled "External Authentication" in the UI Configuration Tool.  With Spotfire 7.5 and later, all authentication is done on Spotfire Server.  For some use cases, one may want to have different authentication methods supported for different user communities, e.g. internal users vs. external users.  There are some authentication methods that are allowed simultaneously; External Authentication is one of those.  One can configure External Authentication as the secondary authentication method and another method of authentication as the primary authentication method.   

Another way to support multiple authentication methods when methods are not compatible on the same Spotfire Server is to use different Sites.  Sites allow one to have different authentication methods for different Spotfire Server sites using configuration commands.

The following diagram shows the authentication flow in Spotfire 7.5 and later when a portal is used and how Spotfire Server now handles the external authentication.

Figure 2 Spotfire 7.5 and later External Authentication Flow

Upon entering credentials for authentication (1-2), the Authentication Service sets a domain cookie containing a user ticket (3), which is made available to the custom authentication mechanism on the Spotfire Server (4).  The custom authenticator (7.6 and above) (7.5 and above) on the Spotfire Server extracts the ticket, passes it to the Authentication Service (5) which translates it to the user identity and passes it back (6).  The custom authenticatorthen sets the user principal for the session using the user identity provided by the Authentication Service.   For simpler scenarios, the use of custom coding will not be required and can be supported by the Spotfire Server External Authentication configuration options.  This will be discussed in more detail later in this section.

The following diagram shows the steps and which component is handling those steps:

The configuration for External Authentication can be found in the Spotfire Server Configuration Tool or modified using the command line config-external-auth.   The Spotfire Server manual has a section called External Authentication that has more information.

If one is using External Authentication for web browser users, then typically one will need a method of authentication for users connecting via Spotfire Analyst.   Since all users now connect to Spotfire Server, it will have to handle both methods.  This screen shot shows the authentication configured for username/password using the Spotfire database and then a warning that External Authentication is also enabled.  The warning is there to make sure the user is aware that External Authentication is enabled on the External Authentication page and can be configured or disabled on that page.

Starting in Spotfire 7.8, the Spotfire Analyst users can use a Web based method of authentication if one selects the Web Authentication method.

If all one needs to do is pull out a user identity from the HTTP Attribute, Header or Cookie, then no custom code is needed.  But if one needs to pull out an encrypted token or do something more with the identity, then a Custom Authenticator or an Authentication Filter is needed.   For the simpler case, one can use the External Authentication configuration to pull out the appropriate HTTP element.   This screenshot from Spotfire Server Configuration Tool shows the type selected as (HTTP) Header and the Header to look for is REMOTE_USER.

In addition to configuring where the identity is passed in the HTTP information, one can configure some constraints that will make the connection more secure, e.g. requiring SSL, allowed hosts and allowed IPs.   The allowed IPs allow one to use regular expressions to allow blocks of IPs, e.g. 192.253.*.  Some basic transformations are allowed to extract the name using a regular expression.  Please see the Spotfire Server manual for more information.

If one needs more complex processing than just pulling out a Header, Attribute or Cookie value, then one will need to write custom code.  Since Spotfire Server is based on Tomcat, a Java web application container, any custom coding needed in Spotfire 7.5 and later will be Java code.  If custom coding is needed with Spotfire 7.5, then this is done using a Java Authentication Filter which will be shown below in the Details for Spotfire 7.5 section. 

The CustomAuthenticator added in Spotfire 7.6 simplifies the implementation and is more integrated into the Spotfire platform.  There still may be use cases where an Authentication Filter is necessary, but the Authentication Filter is not as tightly integrated into the Spotfire platform.  Since the Authentication Filter is earlier in the chain, it can be used when you need to perform a redirect or alter the HTTP response.  For Spotfire 7.6 and later, the use of the Custom Authenticator is recommended and should be used whenever possible.  

In Spotfire Server 7.6 and Later, the ability to create a Custom Authenticator is available.  The Custom Authenticator is very similar to the older custom authentication available on Spotfire Web Player.  What needs to be implemented is simpler than the Authentication Filter available for 7.5.  The CustomAuthenticator class contains an init method for initializing parameters and an authenticate method for performing authentication and returning the user principal information.  This section discusses how to configure Spotfire Server and provides a simple example of a CustomAuthenticator.

The Custom Authenticator is for more complex situations in which the out-of-the-box External Configuration settings are not enough.  In these complex situations, in order to get the authentication information from the HTTP request and pass it onto the Spotfire environment, one needs to write a Java CustomAuthenticator to process the authentication information and create a CustomAuthenticatorPrincipal for the user principal information.   

package com.tibco.spotfireps.server.security;
package com.tibco.spotfireps.server.security;

import java.util.Map;

import org.apache.logging.log4j.*; // Spotfire 7.9 and above (Log4J2) - log4j-api.jar 
//import org.apache.log4j.*; // Spotfire 7.8 and below (Log4J) - log4j.jar

import com.spotfire.server.security.AuthenticationContext;
import com.spotfire.server.security.CustomAuthenticator;
import com.spotfire.server.security.CustomAuthenticatorException;
import com.spotfire.server.security.CustomAuthenticatorPrincipal;

public class TestCustomAuthenticator implements CustomAuthenticator {

  private static final String CLASS = TestCustomAuthenticator.class.getName();
  private static final Logger s_log = LogManager.getLogger(CLASS);

  @Override
  public CustomAuthenticatorPrincipal authenticate(AuthenticationContext authContext)
       throws CustomAuthenticatorException {

    CustomAuthenticatorPrincipal authPrincipal = null;

    // get HTTP request and see if anything in the user agent
    String userName = authContext.getHeader("UserHeader");                  <- Line #1

    if (userName == null)                                                   <- Line #2
    {
      s_log.info("No UserName Specified – assume another method of authentication ");

      // Do not want to throw exception or other authentication will not be checked.
      // For example, users using Spotfire Analyst will not be able to login
      // throw new CustomAuthenticatorException("No UserName Specified - assume another method of authentication");
    }
    else
    {
      String fixedUser = new StringBuffer(userName).reverse().toString();  <- Line #2a
      s_log.info("Setting UserPrincipal - " + fixedUser);

      authPrincipal = new 
          CustomAuthenticatorPrincipal(fixedUser, "SPOTFIRE", null, null);  <- Line #3
    }
    return authPrincipal;                                                   <- Line #4
  }

  public void init(Map parameters) throws CustomAuthenticatorException {
    // TODO Auto-generated method stub
  }
}

The key lines in the code are marked:

• Line #1 - pulls out the HTTP request header value from the header marked "UserHeader".  This is the header value that is set by the SSO solution, e.g. common value for SiteMinder is SM_USER.
• Line #2 - checks to see if the value is null.  If the value is null, one can either deny access (throw an exception) or pass onto other methods of authentication (return a null principal).  If External Authentication is configured with another authentication method, then the second method will be chained to for browser users.  Spotfire Analyst users will always use the non-external authentication method.    If an exception is thrown, then most likely Spotfire Analyst users will be denied access because Spotfire Analyst will not be providing the correct header information.
  • Line #2a - processes the found user name; in this example case, just reversing the string.  This is where one would do more complex processing like calling out to an authentication service with a token to validate and get a username back.
• Line #3 - create the CustomAuthenticatorPrincipal; in this example, only the user name and domain name are set.
• Line #4 - return the created principal or null if no user name found.  The value of null will imply to Spotfire Server that another method of authentication should be checked.

As a reminder, for the simple cases, this custom coding is not required.  It is only required if one must do more processing with the value obtained.  The External Authentication configuration in Spotfire Server should handle the majority of the cases without requiring any custom coding. 

To configure Spotfire Server to use the Custom Authenticator, one sets the Type in the External Authentication to "Custom Authenticator" as seen in this screen shot:

With the External Authentication set to "Custom Authenticator," one needs to set the Class name for the CustomAuthenticator class in the text box below the type.  In this example, the Class name is set to: com.tibco.spotfireps.server.security.TestCustomAuthenticator and there are no parameters configured.

If needed, one can pass in initialization parameters that set various items, e.g. an Authentication Service URL.  After one makes the configuration changes, one needs to save the configuration changes, deploy the compiled jar file to Spotfire Server and restart Spotfire Server.  I used the Eclipse IDE and linked to the JRE from the Spotfire Server installation, the server.jar file from tomcat/webapps/spotfire/WEB-INF/lib, and servlet-api.jar from tomcat/lib directory of the TSS installation directory.  The compiled jar file needs to be copied to the tibco/tss/<version>/tomcat/custom-ext directory, and the Spotfire Server must be restarted to recognize the new jar file.  In the screen shot below, MyAuthFilter.jar has been copied to the tomcat/custom-ext directory.

After Spotfire Server is restarted, one should be able to use the updated authentication methods and test out that it recognizes the correct user values.  If there are any issues, one should look at the Spotfire Server log files in the tomcat/logs directory.  The server.log file is a good place to start.  Spotfire Server may not start correctly if it cannot find the Java class specified or there are other issues with the custom authenticator.

Advanced Topics

This section covers advanced topics that are here to provide additional information and discussion if needed. 

PostAuthenticationFilter in Spotfire Server

This section discusses the Post Authentication Filter as another extension point in the authentication and authorization of a user in Spotfire Server.  The Post Authentication Filter in Spotfire Server provides a couple of different configuration options.   The post authentication filter is provided to perform an additional check after a user's identity has been validated.   The Spotfire Server manual has a section, Post-authentication filter, describing the configuration options.  This discussion focuses on when one might need to write a Java post authentication filter.  The Post-authentication filter jar file should be placed in the <installation dir>/tomcat/custom-ext directory.

In addition to the filter mode, one can specify a Post-authentication filter class which is a Java class that can do extra manipulation, validation, etc. of the user identity that has been passed in.  This is a screen shot from the Spotfire Server configuration tool showing the Post Authentication Filter configuration:

One scenario for a Post Authentication Filter involves using external authentication to pass in additional user information that can be used to dynamically assign group membership, permissions, etc.  For example, the user identity string could contain additional information that when parsed could contain the user identity and group information which can then be used to dynamically set which groups the user is a member of.  The Post Authentication Filter can also be used to do additional validation of the user identity and reject the user if needed.

spotfire7.5_and_later_customauthentication.pdf