This article is an example of how to configure a standard Tomcat 8 installation to connect with a SAML Idp server. 


Note: in this example, we are using a convenient "serverless" SAML simulation tool: "fujifish Samling". 

Of course, you need to adapt the configuration to your own real SAML Idp server. 


Download and install Apache CXF Fediz library 

Download from Apache website: https://cxf.apache.org/fediz-downloads.html

For installing: 

- unzip the Fediz zip file 

- create a dedicated folder under tomcat/lib, for example tomcat/lib/fediz

- copy all jar files from apache-fediz-1.5.1/plugins/tomcat/lib/*.jar to tomcat/lib/fediz


In some environments, you may also need to add these two files into the tomcat/lib/fediz directory :

    stax2-api-3.1.4.jar https://mvnrepository.com/artifact/org.codehaus.woodstox/stax2-api/3.1.4

    woodstox-core-5.0.3.jar https://mvnrepository.com/artifact/com.fasterxml.woodstox/woodstox-core/5.0.3



Configure Tomcat


Note: the file tomcat-users.xml is ignored when using a SAML authentication mechanism. 


In the file tomcat/conf/catalina.properties

Add the Fediz jar files to common.loader: "${catalina.home}/lib/fediz/*.jar"


Create the file tomcat/conf/Catalina/localhost/analytics.xml

File content: 

<?xml version="1.0" encoding="UTF-8"?>
<Context>
<Valve className="org.apache.cxf.fediz.tomcat.FederationAuthenticator" configFile="conf/fediz_config.xml" />
</Context>


Create the file tomcat/conf/fediz_config.xml

This is the file where you define your SAML Idp server information. 

In this example we use the fujifish tool for simulating a SAML server.

Adjust it to your SAML server. 

- make sure you install and reference your SAML server's certificate in certificateStores/trustManager/keyStore.

- make sure you set the correct data in the "protocol" section for your SAML server

- make sure that roleURI reflects the name of the property that your SAML server will use to communicate the user's roles after authentication is done. roleDelimiter is the character used when there are several roles.

- make sure you communicate the logout URL to the users, currently Analytics may not use your SAML's url by default


Sample file content:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FedizConfig>
<contextConfig name="/analytics">
<audienceUris>
<audienceItem>http://localhost:8080/analytics</audienceItem>
</audienceUris>
<certificateStores>
<trustManager>
<!-- not that certificate is in file directly, not imported in keystore, as this is also supported by fediz -->
<keyStore file="D:\apps\tomcat\conf\samling.cert" type="PEM" />
</trustManager>
</certificateStores>
<trustedIssuers>
<issuer certificateValidation="PeerTrust" />
</trustedIssuers>
<protocol xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="samlProtocolType" version="2.0">
<disableDeflateEncoding>true</disableDeflateEncoding>
<doNotEnforceKnownIssuer>true</doNotEnforceKnownIssuer>
<issuer>https://fujifish.github.io/samling/samling.html</issuer>
<roleURI>groups</roleURI>
<roleDelimiter>,</roleDelimiter>
</protocol>
<!-- <logoutURL>/sem_check2</logoutURL> -->
</contextConfig>
</FedizConfig>


Access Analytics and authenticate with your SAML

When browsing to http://localhost:8080/analytics/stambia, Tomcat will forward your browser to the SAML authentication page. 

In this example, the fujifish samling authentication page is a "test" page so it does not really look like an authentication form. 

Note that we set the user's roles like this: groups=analyticsConnect,analyticsSessionAdmin




Once the auth form is submitted, the SAML server takes the browser back to Tomcat and Analytics is loaded with the appropriate permissions: