Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.



This mode is not enabled by default "out of the box".


Before you can configure your CAST AIP web applications to use SAML authentication, the following prerequisites must already be in place:

CAST AIP web applications deployed and functioningThe CAST AIP web applications must be deployed and functioning before you can proceed. In particular you must ensure that any roles and data authorizations are already configured.
Apache Tomcat / standalone ZIP configured for HTTPS

The Apache Tomcat host server / standalone ZIP deployments must be configured to use the HTTPS protocol. See:

FederationMetadata.xmlThis file must be provided by your IT administrators before you can proceed.
Key pair generation

A public/private key pair must be generated on the Apache Tomcat host server in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS). See below for more information.

Note: Dashboard supports the SAML Keystore file, which is generated using the SHA256 algorithm. 

Supported versions of SAML


Configuration process

Request FederationMetadata.xml

You must request the FederationMetadata.xml file from your IT administrators. When you have received the file, you should store it in a location that can be accessed from thew eb application, for example, within the Apache Tomcat installation location or within the unpacked ZIP. For example:

Code Block
Windows: D:/apache-tomcat/conf/FederationMetadata.xml
Linux: /opt/apache-tomcat/conf/FederationMetadata.xml

Key pair generation

A public/private key pair must be generated on the Apache Tomcat host server in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS). This keystore should be specific to the SAML configuration. To do so, you need to use the keytool command line utility (provided with the JRE - see for more information) on the workstation on which the web application server is running. For example:

Code Block
%JAVA_HOME%\keytool -genkeypair -alias <some-alias> -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -validity 3650 -keypass <keypass> -keystore <samlKeystore.jks> -storepass <storepass>


-aliasChoose an alias that is specific to the key pair.
-keyalg, -sigalg, -keysize, -validityChoose these options according to your own requirements (see for more information).

This configured a password that is used to protect the private key of the generated key pair. The value must be at least 6 characters.


Choose a keystore location in which to store the key pair, for example:

Code Block
Windows: D:/keystore/samlKeystore.jks
Linux: /opt/apache-tomcat/conf/samlKeystore.jks

-storepassChoose a password to protect the keystore.

Activate and configure the authentication mode in the web application

Activation and configuration of the SAML authentication mode is governed by a .properties configuration file within the web application:

Code Block
WAR 1.x

WAR ≥ 2.x

ZIP ≥ 2.x

To activate the SAML authentication mode, change the following line. For example, to change from the Default authentication security mode to SAML, do as follows. Change:

Code Block


Code Block

Save the file.

Configure SAML authentication

Find the SAML parameters section in the .properties configuration file and modify each uncommented line to match the items you have already configured. Save the .properties file when complete.

Code Block
WAR 1.x

# Parameters for saml mode
# ------------------------
# idp metadata file
# attribute name for group in saml response
# Key store path
# key store password
# Key alias
# Key password
# is Single Logout implemented in the customer IDP ?

WAR and ZIP ≥ 2.x

# or a classpath resource using "classpath:myMetadataFile.xml" for example
# NB : when using an HTTPS metadata source, you must first add the public certificate to the keystore
# Specify the filename of the keystore to use for the SAML certificates
# The file must be placed inside the security.config.folder
# Specify the default alias in the keystore for the certificate
# Specify the keystore and alias password
# The XML attribute containing the user's name
# If this attribute is missing or empty, the user ID will be used
# The XML attribute containing the user's group in the SAML response
# is Single Logout implemented in the customer IDP ?

1.x = security.saml.idp.metadata.location

2.x = security.saml.metadata.source

Location of the FederationMetadata.xml file.

1.x =

2.x = security.saml.attribute.username

2.x =

Name of the username and/or group attribute (please discuss with your IT administrators about this option).

1.x = security.saml.keystore.path

2.x = security.saml.keystore.filename

Location of the keystore you created previously.


The keystore password you created previously (corresponds to the -storepass option for keytool)

1.x = security.saml.key.alias

2.x = security.saml.keystore.default-alias

The keystore alias you created previously.

1.x = security.saml.key.password

2.x = security.saml.keystore.password

The key password you created previously (corresponds to the -keypass option for keytool).


If SAML authentication is in operation, but no Single Logout service is provided in the IdP, you can force the dashboard to handle this situation gracefully and display a message explaining what to do by setting the option to true (default):

Restart Apache Tomcat / ZIP file

Now restart your Apache Tomcat server or the web application ZIP file so that the changes you made are taken into account.

Modify application-security-saml.xml file - only required in 2.x releases

If you are using CAST Dashboards ≥ 2.0, please ensure that you modify the application-security-saml.xml file located here:

Code Block
WAR ≥ 2.x

ZIP ≥ 2.x

First you need to update the "metadataGenerator" to match the location of your Dashboard deployment. Locate the following section:

Code Block
<!-- Define basic information regarding WEBI as a Service Provider -->
<bean id="metadataGenerator" class="">
	<property name="entityId" value="https://localhost:8080/saml/metadata"/>
	<property name="extendedMetadata" ref="extendedMetadata"/>
	<property name="includeDiscoveryExtension" value="false"/>
	<property name="keyManager" ref="keyManager"/>

Change the line <property name="entityId" value="https://localhost:8080/saml/metadata"/> to match your own deployment. Some examples for the "value" parameter are given below:

Code Block
<property name="entityId" value="https://<my_server_dns_name>/saml/metadata"/>
<property name="entityId" value="https://<my_server_dns_name>/<deployed_war>/saml/metadata"/>
<property name="entityId" value="https://<my_server_dns_name><:custom_ssl_port>/<deployed_war>/saml/metadata"/>
<property name="entityId" value="https://<my_server_ip_address>/saml/metadata"/>
<property name="entityId" value="https://<my_server_ip_address>/<deployed_war>/saml/metadata"/>
<property name="entityId" value="https://<my_server_ip_address><:custom_ssl_port>/<deployed_war>/saml/metadata"/>

Next update the successRedirectHandler to configure the redirect after a successful login. Locate the following section:

Code Block
<bean id="successRedirectHandler"
	<property name="alwaysUseDefaultTargetUrl" value="true"/>
	<!-- the default landing url after login successful -->
	<property name="defaultTargetUrl" value="/engineering/index.html"/>

Change the line <property name="defaultTargetUrl" value="/engineering/index.html"/> to match your own deployment. For example:

Code Block
Engineering Dashboard: <property name="defaultTargetUrl" value="/engineering/index.html"/>
Health Dashboard: <property name="defaultTargetUrl" value="/portal/index.html"/>
Combined Health/Engineering: <property name="defaultTargetUrl" value="/welcome.html"/>

Save the file and restart your Apache Tomcat server or the web application ZIP file so that the changes you made are taken into account.

Generate spring_metadata

Now browse to the following URL to generate the spring_metadata:

Code Block
WAR file deployment:

ZIP fil deployment:

This will download a file called spring_saml_metadata.xml. Send this file to your IT administrators who will then register it in the ADFS allowing users to login to the web application.


  • Attempting to use the login button in the static/default.html page in the CAST Health Dashboard, Engineering Dashboard and the RestAPI will fail when SAML mode is configured: this button is only configured to use basic authentication. If you need to use any of the options provided in the static/default.html page (which all require a login), you must ensure that you login to the dashboard in the conventional way, and THEN access the static/default.html page in your browser.
  • ADFS are very sensitive: if badly set, authentication will fail.
  • By default, the log mechanism is not configured to provide any logging information to debug SAML authentication issues - if you have encountered issues activating SAML authentication, please enable DEBUG mode as described in Configuring the Log and Audit Trail.

Notes about Groups

  • SAML groups can also be used for authorization assignments (for example, a set of users can be assigned to a group and that group can then be authorized to view the required data instead of having to authorize individual users) and for role assignments. In SAML mode, Groups are retrieved directly from the SAML directory.
  • Nested groups are supported, both for authorization assignments and for role assignments. For instance, if user jdoe is member of groupA, which is member of groupB which is used to define an authorization or role, then jdoe will be attributed the groupB authorizations/roles.