Page tree

Versions Compared

Key

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

...

Expand

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

Prerequisites

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 backend identity provider. See below for more information.

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

Supported versions of SAML

VersionSupported
2.0(tick)
1.1(error)
1.0(error)

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 the web application, for example, within the Apache Tomcat installation location or within the unpacked ZIP. For example:

Code Block
languagetext
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)backend identity provider. 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 (see for example https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information about how to use this tool (this link refers to Oracle's Java implementation, and other JRE providers will have their own instructions, which you should use)) on the workstation on which the web application server is running. For example:

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

Where:

-aliasChoose an alias that is specific to the key pair.
-keyalg, -sigalg, -keysize, -validityChoose these options according to your own requirements requirements (see  for example https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information ).about how to use this tool (this link refers to Oracle's Java implementation, and other JRE providers will have their own instructions, which you should use))
-keypass

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.

-keystore

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

Code Block
languagetext
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
languagetext
WAR 1.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties

ZIP ≥ 2.x
<unpacked_zip>\configurations\application.properties

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
languagetext
security.mode=default

to:

Code Block
languagetext
security.mode=saml

Save the security.properties 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
languagetext
WAR 1.x

# Parameters for saml mode
# ------------------------
# idp metadata file
security.saml.idp.metadata.location=file:/opt/apache-tomcat/conf/FederationMetadata.xml
# attribute name for group in saml response
security.saml.idp.metadata.group.attribute.name=http://schemas.xmlsoap.org/claims/Group
# Key store path
security.saml.keystore.path=file:/opt/apache-tomcat/conf/myKeystore.jks
# key store password
security.saml.keystore.password=changeit
# Key alias
security.saml.key.alias=somealias
# Key password
security.saml.key.password=changeit
# is Single Logout implemented in the customer IDP ?
security.saml.single.logout=true

WAR and ZIP ≥ 2.x

## SPRING SECURITY SAML CONFIG
# or a classpath resource using "classpath:myMetadataFile.xml" for example
security.saml.idp.metadata.source=/opt/apache-tomcat/conf/FederationMetadata.xml
# NB : when using an HTTPS metadata source, you must first add the public certificate to the keystore
security.saml.metadata.source=
# Specify the filename of the keystore to use for the SAML certificates
# The file must be placed inside the security.config.folder
security.saml.keystore.filename=sample.keystore
# Specify the default alias in the keystore for the certificate
security.saml.keystore.default-alias=somealias
# Specify the keystore and alias password
security.saml.keystore.password=changeit
# The XML attribute containing the user's name
# If this attribute is missing or empty, the user ID will be used
security.saml.attribute.username=
# The XML attribute containing the user's group in the SAML response
security.saml.attribute.group=
# is Single Logout implemented in the customer IDP ?
security.saml.single.logout=true


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

2.x = security.saml.metadata.source

Location of the FederationMetadata.xml file
For example: 

Windows: D:/apache-tomcat/conf/FederationMetadata.xml

Linux: /opt/apache-tomcat/conf/FederationMetadata.xml

1.x = security.saml.idp.metadata.group.attribute.name

2.x = security.saml.attribute.username

2.x = security.saml.attribute.group

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.

security.saml.keystore.password

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).

security.saml.single.logout

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
languagetext
WAR ≥ 2.x
CATALINA_HOME\webapps\<deployed_war>\WEB-INF\classes\security

ZIP ≥ 2.x
<unpacked_zip>\configurations\security

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="org.springframework.security.saml.metadata.MetadataGenerator">
	<property name="entityId" value="https://localhost:8080/saml/metadata"/>
	<property name="extendedMetadata" ref="extendedMetadata"/>
	<property name="includeDiscoveryExtension" value="false"/>
	<property name="keyManager" ref="keyManager"/>
</bean>

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"
	class="org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler">
	<property name="alwaysUseDefaultTargetUrl" value="true"/>
	<!-- the default landing url after login successful -->
	<property name="defaultTargetUrl" value="/engineering/index.html"/>
</bean>

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
languagetext
WAR file deployment:
https://tomcat/<deployed_war>/saml/metadata

ZIP fil deployment:
https://localhost/saml/metadata

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.

Tips

  • 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.

...