SAML SP for Java can be used when the same application is available at multiple hostnames. For example, if the same application is available at two or more addresses. This is ideal for hosted multi-tenant services.

Many SPs, One IDP

In this example configuration:

• Service Provider 1 is https://application.host1.com and
• Service Provider 2 is https://application.host2.com

To enable virtual hosting support for two Service Providers that use the same UAS as the Identity Provider:

1. Download the Ubisecure IDP metadata from the SAML 2.0 link on the Ubisecure Management home page. Save this file into the /WEB-INF/saml2/sp/metadata folder of your web application.

   Figure 1. Click SAML 2.0 to download the IDP metadata file

2. Copy the binary libraries from the installation package directory ubispservlet/webapp/WEB-INF/lib to the WEB-INF/lib directory of the web application.

   cd ubispservlet\webapp\WEB-INF\libcopy *.jar <webapp_directory>\WEB-INF\lib\

3. Configure the WEB-INF\web.xml file using the example provided ubispservlet/webapp/WEB-INF/web.xml or following the instructions in SAML SP application integration - SSO.

4. For virtual hosting ProxyFilter must not be used.
   Remove the following style of configuration if present in the web.xml file.

   <filter>
   <filter-name>ProxyFilter</filter-name>
   <filter-class>com.ubisecure.util.filter.ProxyFilter</filter-class>
   <init-param>
   <param-name>com.ubisecure.util.filter.proxy.front</param-name>
   <param-value>http://portal.example.com</param-value>
   </init-param>
   <init-param>
   <param-name>com.ubisecure.util.filter.proxy.remote-addr-name</param-name>
   <param-value>x-forwarded-for</param-value>
   </init-param>
   </filter>

   SAML SP uses Java AddressTracker component for IP address matching. If a reverse proxy is used, set the netmask parameter's x-forwarded-for setting. The client address will be retrieved from this value set by the reverse proxy.
   If a reverse proxy is used, add the following init-param to the ServiceProviderServlet of the web.xml file. The proxy must be configured to pass the required values in the headers.

   <servlet>
   	<servlet-name>ServiceProviderServlet</servlet-name>
   	<servlet-class>com.ubisecure.saml2.sp.servlet.ServiceProviderServlet</servlet-class>
   	<init-param>
   		<param-name>netmask</param-name>
   		<param-value>enabled x-forwarded-for=x-client-address</param-value>
   	</init-param>
      <load-on-startup>0</load-on-startup>
   </servlet>

5. Create a directory for each hostname:

   cd <webapp_directory>\WEB-INF\
   mkdir saml2/sp/application.host1.com
   mkdir saml2/sp/application.host2.com

6. Create the identity for Service Provider 1:

   cd <webapp_directory>\WEB-INF
   java -jar ubispservlet\tools\metadata-generator.jar Generate https://application.host1.com/webapp/spsso -o
   saml2\sp\ application.host1.com

7. Create the metadata for Service Provider 1:

   cd <webapp_directory>\WEB-INF
   java -jar ubispservlet\tools\metadata-generator.jar Metadata saml2\sp\application.host1.com -f c:\temp\sp1.xml

8. Disable the use of backchannel messages from the SP. All interactions with the SP will be via the user browser. To disable backchannel messages, set the LiteNoBackChannel compatibility flag in the SP's identity.properties file.
   
   Open identity.properties file in a text editor. Add the following line to the file:

   com.ubisecure.saml2.config.compatibilitycom.ubisecure.ubilogin.uas.saml2.compatibility = LiteNoBackChannel

9. Create the identity for Service Provider 2:

   cd <webapp_directory>\WEB-INF
   java -jar ubispservlet\tools\metadata-generator.jar Generate https://application.host2.com/webapp/spsso -o
   saml2\sp\ application.host2.com

10. Create the metadata for Service Provider 2:

    cd <webapp_directory>\WEB-INF
    java -jar ubispservlet\tools\metadata-generator.jar Metadata saml2\sp\application.host2.com -f c:\temp\sp2.xml

11. Disable the use of backchannel messages from the second SP. All interactions with the SP will be via the user browser. To disable backchannel messages, set the LiteNoBackChannel compatibility flag in the SP's identity.properties file.
    Open identity.properties file in a text editor. Add the following line to the file:

    cd <webapp_directory>\WEB-INF\saml2\sp\application.host2.com
    com.ubisecure.ubilogin.uas.saml2.compatibility = LiteNoBackChannel

12. Create an application for SP1 using Ubisecure Management and activate the application using the metadata from c:\temo\sp1.xml. Configure the application's template, methods and allowed to groups as desired. Activation is described in Associate the SP identity with a Ubisecure Web Agent section of SAML SP activation - SSO.
13. Create an application for SP2 using Ubisecure Management and activate the application using the metadata from c:\temo\sp2.xml. Configure the application's template, methods and allowed to groups as desired. Activation is described in Associate the SP identity with a Ubisecure Web Agent section of SAML SP activation - SSO.
14. The resulting file structure should be as follows. For additional hostnames, repeat the same process for each hostname:
    1. create sp subdirectory using exact hostname
    2. create the identity using the Generate command
    3. create the metadata using the Metadata command
    4. add the compatibility LiteNoBackChannel to the identity.properties file
    5. activate and configure the application using the generated metadata

[servlet and filter configuration]
<webapp_directory>\WEB-INF\web.xml          

[SAML SP binary libraries]
<webapp_directory>\WEB-INF\lib\*.jar

[SAML SP logger configuration]
<webapp_directory>\WEB-INF\classes\logback.xml

[SAML SP 1 identity]
<webapp_directory>\WEB-INF\saml2\sp\application.host1.com\identity.properties   

[SAML SP 2 identity]
<webapp_directory>\WEB-INF\saml2\sp\application.host2.com\identity.properties   

[IDP metadata]
<webapp_directory>\WEB-INF\saml2\sp\metadata\metadata.xml

Many SPs, Many IDPs

To enable virtual hosting support for two or more Service Providers that use two or more different Identity Providers, a custom discovery class must be written to determine how the IDP will be selected. Please contact Ubisecure Support for more information or refer to the SAML SP API javadoc for implementation instructions. Typically such a configuration is not required as UAS can be configured to work as an IDP proxy that already contains suitable logic for performing discovery.

If more than one IDP is used, then the metadata of each trusted IDP must be saved to the target application’s /WEB-INF/saml2/sp/<HOSTNAME>/metadata/ directory. 

[servlet and filter configuration]
<webapp_directory>\WEB-INF\web.xml          

[SAML SP binary libraries]
<webapp_directory>\WEB-INF\lib\*.jar

[SAML SP logger configuration]
<webapp_directory>\WEB-INF\classes\logback.xml

[SAML SP 1 identity]
<webapp_directory>\WEB-INF\saml2\sp\application.host1.com\identity.properties   

[SAML SP 2 identity]
<webapp_directory>\WEB-INF\saml2\sp\application.host2.com\identity.properties   

[IDP metadata files]
<webapp_directory>\WEB-INF\saml2\sp\application.host1.com\metadata\metadata.xml
<webapp_directory>\WEB-INF\saml2\sp\application.host2.com\metadata\metadata.xml

Virtual Hosting Configuration Notes

An optional default host can be specified by creating /WEB-INF/saml2/sp/identity.properties.

Any number of virtual hosts may be specified in the sub-folders /WEB-INF/saml2/sp/<NNN>/identity.properties, where <NNN> is any name. The name of the hostname for <NNN> is only a recommendation.

The identity.properties values com.ubisecure.saml2.config.id and com.ubisecure.saml2.config.url values must be unique across all identity.properties files.

Mapping a http request to a virtual host is by default done by matching javax.servlet.http.HttpServletRequest.getRequestURL() to the value found in com.ubisecure.saml2.config.url of the identity.properties file. The getRequestURL method returns the http Host: header value.

com.ubisecure.saml2.sp.event.VirtualHostEventListener may be used to implement other virtual host mapping rules.

Each virtual host may specify its own trusted metadata in /WEB-INF/saml2/sp/NNN/metadata/. In addition any metadata from /WEB-INF/saml2/sp/metadata/ is also added to each virtual host.