Edition: Futurama Website

Module: SAML2LoadBalancer, extra component of Futurama HTML

User: System administrator


- License file

- User name and password for Futurama downloads

- Windows 2008 R2 server or higher (for client Windows 7 or higher)

- .NET Framework 4.6.2 with to be installed

- Internet Information Server 7.5 or higher




Describes the SAML2 Load Balancer component that enables the use of the SAML2 Identityprovider in combination with a load balancer. When you use Futurama Website in combination with a SAML2 Identity provider and a load balancer, problems arise with the SingleLogout functionality. This component enables a scenario where the combination of Futurama Website, SAML2 and a load balancer is used.

The problem occurs with the session affinity of the load balancer. This makes sure that a subsequent request to a Futurama server is handled by the the same server as the original request. A SAML2 SingleLogout Request doesn’t come from the user itself and its browser, but is issued by the SAML2 IdentityProvider. Therefore this subsequent request can be routed by the load balancer to a different server. That server then tries to remove the Futurama session, but it cannot find the session. This module solves that situation by adding a component. At the start of a new SAML2 session, the user and the URL of the server that it is logged into is stored. When a logout request is received, it is passed to the correct server by this component.


Visit the Futurama website to download the SAML2LoadBalancer code:

  • Go to
  • Go to the download section of the Support menu
  • Log in with user name and password
  • Click the most recent Futurama release
  • Extract the zip-file 


Release folder

Use the release code from the folder 'SAML2LoadBalancer'.

Installation initial version

If this is the first installation of the SAML2LoadBalancer code follow the steps in this paragraph. If you already have a working application and are intended to upgrade this to a new Futurama version consult the next paragraph 'Upgrading existing version'. Important is that the SAML2LoadBalancer only is used in the situation of a loadbalanced situation. In a loadbalanced situation a Serverfarm is configured in IIS. See this for explanation of the Application request Routing within IIS. In the next steps you will see that the address of the ServerFarm has to be changed to the SAML2LoadBalancer directory.

To do the first install of the SAML2LoadBalancer code follow the next steps:

  • Create at the Windows webserver a new folder in which the code from the release folder can be installed
  • Copy the code from the release folder to this new folder
  • Copy the license file to this new folder
  • Rename the default.config to web.config (see the description in chapter 'Configuration' for the way the web.config can be configured)
  • Within IIS already a ServerFarm address exists. Change the physical path of this ServerFarm to the directory where in the previous steps the SAML2LoadBalancer code is installed

Upgrading existing version

If you already have installed the SAML2Loadbalancer code, and want to upgrade this to a new version follow the steps in this paragraph. If this is the first installation follow the steps in the preceding paragraph 'Installation initial version'. Follow the next steps to upgrade an existing version of the SAML2Loadbalancer:

  • Open the folder at the Windows webserver where you have installed the SAML2Loadbalancer code
  • Copy the code from the release folder to this folder.



After installing the SAML2Loadbalancer code the configuration can be done. See below for this configuration.

Configuration File

In the release folder we provided a default.config. In the Installation steps mentioned above this default.config is renamed to web.config. In this configuration section the sections within this configuration file are explained.

configSections and futuramaSettings

Within the section 'configSections' you find a sectionGroup named futuramaSettings. This sectionGroup futuramaSettings is also a separate section in the config under the configSections section. Each section name within the sectionGroup futuramaSettings is also contained within the futuramaSettings section. Below a brief explanation of these futuramaSettings sections.

Configuration Log

It is possible to log errors, warnings, information messages and developers messages with Futurama. In the chapter 'Configuration Log' you can find information how to configure the configuration file to log this information.

Configuration address SAML2Loadbalancer

In the installation you have changed the physical address of the ServerFarm to the location of the SAML2LoadBalancer installation. Futurama has to communicate at the background with this SAML2Loadbalancer. In order to let these two sources communicate with each other let the ServerFarm listen to an extra address. This must be an internal address (for example localhost) as this is only internal communication.  Next, this extra address must be configured in the identityprovider section of the web.config of your website application. See Configuration – IdentityProvider, the SAML2LoadBalancerURL property.

Logging out

It is important to distinguish two different logout situations: local logout and remote logout.

Local logout

In the local logout situation the logout is triggered from the Futurama session. The user browses through your Futurama application and decides to logout. After pressing the logout button in your Futurama application the next steps are followed:

  • the Futurama instance communicates with the IDP for a logout request (enable the logging in the configuration file of the Futurama instance to see this logout request) ;
  • With this logout request to the IDP the ARRcookie is sent (due to session affinity)
  • The IDP respondes to this request with a logout response to SAML/SingleLogoutService.aspx. This logout response is sent via a QUERY_STRING (SAMLResponse=…)
  • The response has to be sent directly to the Futurama Farm. Due to the ARR cookie the Futurama Farm can match the response with the Futurama instance the logout request was sent from

Remote logout

In the remote logout situation the logout is triggered from the IDP. The user is logged in in several applications and wants to logout from one of these applications. After the logout the user is redirected to the IDP from where a logout request is sent to all the applications (for example your Futurama application) the user is logged in. After logging out from the IDP the next steps are followed:

  • the IDP does a logout request to SAML/SingleLogoutService.aspx;
  • this request has to be sent to the SAML2Loadbalancer. As the logout is initiated from the IDP, this request can not be routed directly to the loadbalancer as direct routing could imply that the request is sent to another Futurama instance as the Futurama instance the session of the user is started. So, the request first has to be sent to the SAML2Loadbalancer. This SAML2Loadbalancer will route the logout request to the right Futurama instance

So it is important that a local logout is routed to the loadbalancer and a remote logout is routed to the SAML2Loadbalancer. See the next paragraph for the configuration of this routing.

Loadbalancer configuration

In the configuration of the loadbalanced environment an URL Rewrite rule is defined in order to redirect incoming requests to the ServerFarm. This will create the loadbalancing of your sessions. It is important to add an extra rewrite rule in order to use the single log out functionality. When a user is logged in (in your application and another single sign on application) and wants to logout from one of these application he must confirm to log out in all these applications. After confirming, a single logout request is sent to the Futurama application. This is done to the page /SAML/SingleLogoutService.aspx. See the installation of your Futurama HTML code. Within this installation you will find the subfolder SAML and the SingleLogoutService.aspx file. Now it is important that this request is not loadbalanced. See the previous paragraph: a local logout has to be loadbalanced.

This can be done by adding an extra URL Rewrite rule. Make sure this rule is first executed before the existing URL Rewrite rule. Second configure this new rule by:

  • Requested URL: matches the Pattern
  • Using: Regular expressions
  • Pattern: SAML/SingleLogoutService.aspx
  • Ignore case: checked 
  • Conditions: same conditions as the existing URL Rewrite rule plus adding a QUERY_STRING condition (Input={QUERY_STRING}, Type=Does not match the pattern, Pattern=SAMLResponse)
  • Action type: None
  • Stop processing of subsequent rules: checked


The installation and configuration can be tested. See below how to test. If you encounter problems, check the chapter 'Troubleshooting'.

Test in browser

To test whether the SAML2Loadbalancer is installed properly follow the next steps:

  • Log on to the server where the SAML2Loadbalancer is installed;
  • In the SAML2LoadbalancerURL property (see this page) the internal address of the SAML2Loadbalancer is configured. Add saml/sessions to this address (so for example http://internaladdress/saml/sessions) to check whether a json file can be downloaded. 


If you encounter problems with the installation of the SAML2Loadbalancer check the section below.

Logging information

In the web.config the log section is configured. First step in troubleshooting is checking the information in the different log files. Make sure that the log information is actually created. If you don't see any log information consult the chapter 'Configuration Log' for the settings to get this information.

Related Topics

- Application Request Routing: Load balancing with IIS module

- Configuration - Identity Provider: Configuring SAML2 Identity provider


If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2016-12-09