Introduction
Authentication mode activation
Clean up when switching to a new authentication mode
- Role clean up
- Switching away from SAML mode
Configuring authentication using local configuration
Configuring authentication using LDAP/LDAPS
- LDAP over SSL (LDAPS)
- Enabling LDAP debug mode
Configuring authentication using AD
Configuring authentication using SAML
- Supported versions of SAML
- Configuration process
Configuring SSO with CAST Console
- Prerequisites
- Configuration steps
  - Where Console and Imaging are installed on the same server
  - Where Console and Imaging are installed on separate servers

Summary: this page describes how to manage user authentication methods for CAST Imaging.

Introduction

In order to use CAST Imaging, a user must first successfully authenticate. CAST currently supports the following authentication modes:

Mode	Description
Local authentication	This mode is active by default and relies on simple username/password authentication defined in the application-security-local.xml configuration file.
LDAP	This mode is inactive by default and allows users to authenticate with an LDAP server. For example: Basic Active Directory domain controllers Other members of the Active Directory family such as ADAM / AD LDS Non-Microsoft directories such as Apache, Oracle, Novell etc. Note that the configuration of LDAP mode requires detailed knowledge of your environment's LDAP implementation - i.e. an LDAP administrator should help with this.
Active Directory	This mode is inactive by default and allows users to authenticate with a Microsoft Active Directory server.
SAML	This mode is inactive by default and allows users to authenticate via SAML. SAML authentication is available for use in ≥ 1.7.1.
SSO with CAST Console	This mode is inactive by default and allows users to access CAST Imaging using the CAST Console authentication mechanism (i.e. with a CAST Console login). Functions only for CAST Console Enterprise edition (the SSO/Keycloak service is required). SSO with CAST Console is available for use in ≥ 2.16.

CAST recommends using Standard LDAP or Active Directory because this avoids having to manually manage individual usernames and passwords via the Default authentication mode.
Only one mode can be active at a time.
For security reasons, a logged in user will be automatically disconnected after being inactive for some time:

Authentication mode activation

The authentication mode is configured in the following file. Open the file with a text editor:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties

Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .properties file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the following section of options. Change the security.mode option to the mode you require (local, ldap, ad, saml or enterprise). Save the file and then consult the appropriate section in this page for instructions about how to configure the chosen mode.

# =============================
# Authentication parameters
# -----------------------------
# Applicable authentication configuration
# -----------------------------
#  - local	->	Default. Contains a local definition of users and passwords
#  - ldap	->	Set this configuration for authentication over LDAP(S)
#  - ad	->	Set this configuration for authentication over LDAP(S) with basic Active Directory instances (simplified mode)
#  - saml -> Set this configuration for SSO authentication using SAML
#  - enterprise -> Set this configuration to create an SSO with CAST Console login system

security.mode=local

Clean up when switching to a new authentication mode

Role clean up

This step is not required when using CAST Imaging ≥ 2.5.0. When the authentication mode is changed, all roles created with the previous authentication mode will be preserved and the first person to login will be prompted to become super admin.

Whenever you switch to a new authentication mode, i.e. from one mode to another, you must run the following batch file to clean up any roles that have been assigned to users in the previous authentication mode. The batch file is located here:

Traditional Windows installer: %PROGRAMFILES%\CAST\ImagingSystem\imagingservice\switchSecurityMode.bat

Docker Installer (located in the unzipped extension folder):
Linux: server\switchSecurityMode.sh
Microsoft Windows: server\switchSecurityMode.bat

Roles are explained in more detail in Admin Center - Users panel.

Switching away from SAML mode

When switching from SAML mode back to any other mode, do not forget to reverse the changes you made to the CAST Imaging login service to force it to use the HTTPS protocol:

Update the application.properties file and set server.ssl.enabled=false
Update the nginx.conf file and change all proxy_path entries that are using HTTPS back to HTTP

You can find out more about these changes in the section CAST Imaging login service configured for HTTPS in Configuring authentication using SAML below. Finally do not forget to restart all CAST Imaging Windows services / Docker containers.

Configuring authentication using local configuration

By default, authentication using local configuration is active "out-of-the-box", with the following case sensitive usernames/passwords:

Username	Password	Role
admin	admin	ADMIN
cast	cast	USER

Roles are explained in more detail in Admin Center - Users panel.

Windows: %APPDATA%\CAST\ImagingSystem\login\security\application-security-local.xml

Docker Installer (located in the unzipped extension folder):
server\login\security\application-security-local.xml or login\security\application-security-local.xml

To edit these existing users or add new users, open the following file in a text editor:

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .xml file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

In this file, users are defined using the following format:

<user name ="[name]" password="{noop}[password]" authorities="USER" />

Please ensure that:

{noop} is left in place before the chosen password. This is required.
all new users should all use authorities="USER" - no other value is accepted.

In the examples below, a new user "james" has been added to the existing users with the password "cast". Save the file and then restart the CAST Imaging System - login service Windows Service or the login Docker container in order for the new configuration to be taken into account.

<authentication-manager>
	<authentication-provider>
		<user-service>
			<user name="cast" password="{noop}cast" authorities="USER"/>
			<user name="admin" password="{noop}admin" authorities="USER"/>
			<user name="james" password="{noop}cast" authorities="USER"/>
		</user-service>
	</authentication-provider>
</authentication-manager>

It is not possible to create a group of users in local authentication mode. If you need to leverage groups for permission management for roles and data, you should switch to LDAP/S or Active Directory mode and create your groups in the LDAP/S or Active Directory system.

Configuring authentication using LDAP/LDAPS

This mode is not enabled by default "out of the box". If you have enabled LDAP/LDAPS, open the following file in a text editor:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties

Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .properties file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the following section of options:

# -----------------------------
# Parameters for ldap mode
# -----------------------------
security.ldap.url=
security.ldap.account.dn=
security.ldap.account.password=
security.ldap.usersearch.base=
security.ldap.usersearch.filter=
security.ldap.groupsearch.base=
security.ldap.groupsearch.filter=
security.ldap.groupsearch.base.filter=
#security.ldap.url=
#security.ldap.account.dn=
#security.ldap.account.password=
#security.ldap.usersearch.base=
#security.ldap.usersearch.filter=(&(objectClass=user)(sAMAccountName={0}))
#security.ldap.groupsearch.base=
#security.ldap.groupsearch.filter=(&(objectClass=group)(member={0}))
#security.ldap.groupsearch.base.filter=(&(objectClass=group)(name={0}))
security.ldap.groupsearch.maxSearchDepth=10
# Performance fix for nested groups on AD
#security.ldap.groupsearch.filter=(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={0}))
#security.ldap.groupsearch.maxSearchDepth=1

Set the following options according to the requirements of your LDAP/LDAPS directory:

security.ldap.url must contain the URL of the directory. It can be a LDAPS URL (ldaps://server.company.com) if the directory supports a secured connection
security.ldap.account.dn and security.ldap.account.password contain the service account credentials to be used to connect to the directory, for example:
- security.ldap.account.dn=cn=user,OU=group,OU=region,DC=corp,dc=company,dc=com
- security.ldap.account.password=password
The remaining options specify the search parameters to be used on the directory, for example:
- security.ldap.usersearch.base=DC=corp,DC=company,DC=com
- security.ldap.usersearch.filter=(&(objectClass=user)(sAMAccountName={0}))
- security.ldap.groupsearch.base=OU=group,OU=in,DC=corp,DC=company,DC=com
- security.ldap.groupsearch.filter=(&(objectClass=group)(member={0}))
- security.ldap.groupsearch.base.filter=(&(objectClass=group)(sAMAccountName={0}))

Save the file and then restart the CAST Imaging System - login service Windows Service or the login Docker container in order for the new configuration to be taken into account.
Starting in release 2.0.0-beta6, an encryption tool is provided so that you can avoid passing the password for security.ldap.account.password in clear text - see Encrypting the LDAP account password.

LDAP over SSL (LDAPS)

Currently LDAP over SSL (LDAPS) is NOT supported when CAST Imaging is deployed on Docker.

If you would like to enable LDAP over SSL (LDAPS), you will need the following:

A trusted or self-signed certificate stored in a dedicated keystore to allow encrypted communication with the LDAPS server. CAST Imaging uses an embedded JDK and so the certificate should be imported into the embedded JDK's keystore, for example:

keytool -importcert -trustcacerts -file <certificate file> -keystore "C:\Program Files\Cast\ImagingSystem\jdk\lib\security\cacerts" -storepass changeit

Configure the security.ldap.url entry with the appropriate URL, typically this is ldaps://server.company.com (sometimes a port number is also required, typically this is port 636)

Enabling LDAP debug mode

If you have issues with LDAP authentication, you can enable debug log mode to help troubleshoot the issue. To do so, edit the application.properties file and locate the following section:

# -------------------------------------------------------------
#  log configuration
# -------------------------------------------------------------
logging.level.root=info
logging.level.com.castsoftware.aip.console.security.saml=debug
logging.path=C:/Program Files/CAST/ImagingSystem/logs
logging.file=${logging.path}/loginservice.log
logging.file.max-size=5MB
audit.trail.file=${logging.path}/audit-trail.log

Add the following lines to this section:

logging.level.com.castsoftware.aip.console.services.ldap=debug
logging.level.org.springframework.security.ldap=debug
logging.level.org.springframework.ldap=debug

Save the file and then restart the CAST Imaging System - login service Windows Service or the login Docker container in order for the new configuration to be taken into account.

Configuring authentication using AD

This mode is not enabled by default "out of the box". If you have enabled Active Directory, open the following file in a text editor:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties

Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .properties file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the following section of options:

# -----------------------------
# Parameters for ad mode
# -----------------------------
security.ad.url=
security.ad.domain=

Set the following options according to the requirements of your Active Directory.

security.ad.url must contain the URL of the directory. It can be a LDAPS URL (ldap://server.company.com) if the directory supports a secured connection.
security.ad.domain contains the Active Directory domain

Save the file and then restart the CAST Imaging System - login service Windows Service or the login Docker container in order for the new configuration to be taken into account.

Configuring authentication using SAML

SAML authentication is available for use in ≥ 1.7.1.

This mode is not enabled by default "out of the box". If you have enabled SAML, please follow the steps below to configure it.

When using SAML:

in CAST Imaging ≤ 2.1.0, roles are not supported. This situation has been resolved in CAST Imaging ≥ 2.2.0.
in CAST Imaging ≤ 2.1.0, all users automatically have the ADMIN role. This situation has been resolved in CAST Imaging ≥ 2.2.0.
Granting roles/permissions to groups is supported in CAST Imaging ≥ 2.9.0 (not supported in previous releases).

Prerequisites

Before you can configure CAST Imaging to use SAML authentication, the following prerequisites must already be in place:

CAST Imaging login service configured for HTTPS	The CAST Imaging login service must be configured to use the HTTPS protocol. See instructions below. CAST Imaging itself does NOT need to be configured to use the HTTPS protocol, however CAST recommends doing so in any case (see Reconfiguring the front end service to use a secure port).
FederationMetadata.xml	This file must be provided by your IT administrators before you can proceed. See instructions below.
Key pair generation	Two public/private key pairs must be generated on the CAST Imaging host machine in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS). See below for more information.

Supported versions of SAML

Version	Supported
2.0
1.1
1.0

Configuration process

CAST Imaging login service configured for HTTPS

The CAST Imaging front-end service itself does NOT need to be configured to use the HTTPS protocol, however CAST recommends doing so in any case (see Reconfiguring the front end service to use a secure port).

The CAST Imaging login service must be configured to use the HTTPS protocol. To do so:

Update application.properties file

Open the following file in a text editor:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties

Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .properties file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the following option:

# ssl must be enabled when enable saml mode
server.ssl.enabled=false

Change the line to true and save the application.properties file when complete:

# ssl must be enabled when enable saml mode
server.ssl.enabled=true

Update nginx.conf file

Open the following file in a text editor:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\nginx\nginx.conf

Docker Installer (located in the unzipped extension folder):
server\nginx\conf\nginx.conf or nginx\conf\nginx.conf

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .conf file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the following options section and change all URLs using http to https, except for proxy_pass http://127.0.0.1:8181 on Microsoft Windows)

Microsoft Windows

# Proxying the connections connections
location ^~ /imaging/login/api/ {

	limit_req zone=default burst=6 nodelay;

	proxy_pass         http://127.0.0.1:8084/;
}
location ^~ /imaging/sourcecode/api/ {
	proxy_pass         http://127.0.0.1:8084/sourcecode/api/;
}
location ^~ /imaging/api/ {
	proxy_pass         http://127.0.0.1:8084/api/;
}
location ^~ /imaging/etl/api/ {
	proxy_pass         http://127.0.0.1:8084/etl/api/;
}
location ^~ /imaging/saml/ {
	proxy_pass         http://127.0.0.1:8084/saml/;
}
location ^~ /saml/ {
	proxy_pass         http://127.0.0.1:8084/saml/;
}
location ^~ /imaging/bot/ {
	proxy_pass http://127.0.0.1:8181;
	proxy_http_version 1.1;
	proxy_redirect     off;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection 'upgrade';
	proxy_set_header Host $host;
	proxy_cache_bypass $http_upgrade;

}
location ^~ /imaging/neo4j/api/ {
	proxy_pass         http://127.0.0.1:8084/neo4j/api/;
}

Docker

# Proxying the connections
location ^~ /imaging/login/api/ {
	limit_req zone=default burst=6 nodelay;
	proxy_pass         http://localhost:8084/;
}

location ^~ /imaging/saml/ {
	proxy_pass         http://localhost:8084/saml/;
}

location ^~ /saml/ {
	proxy_pass         http://localhost:8084/saml/;
}

location ^~ /imaging/sourcecode/api/ {
	proxy_pass         http://localhost:8084/sourcecode/api/;
}

location ^~ /imaging/api/ {
	proxy_pass         http://localhost:8084/api/;
}

location ^~ /imaging/etl/api/ {
	proxy_pass         http://localhost:8084/etl/api/;
}

location ^~ /imaging/neo4j/api/ {
	proxy_pass         http://localhost:8084/neo4j/api/;
}

Save the nginx.conf file when complete.

Update application-security-saml.xml file - optional

This step is only required if you have configured the CAST Imaging front-end service to run in secure SSL mode (see Reconfiguring the front end service to use a secure port) but you are using a port other than 443. If you are using port 443, you can skip this step.

Locate the following file and edit with a text editor:

Traditional Windows installer:
%APPDATA%\CAST\ImagingSystem\login\security\application-security-saml.xml

Docker Installer (located in the unzipped extension folder):
server\login\security\application-security-saml.xml or login\security\application-security-saml.xml

First add the following section anywhere between the root <beans> tags and update the values of the serverName and serverPort entries to match the CAST Imaging host name and the custom secure SSL port number:

<bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderLB">
	<property name="scheme" value="https"/>
	<property name="serverName" value="my_server"/>
	<property name="serverPort" value="8443"/>
	<property name="includeServerPortInRequestURL" value="true"/>
	<property name="contextPath" value="${server.servlet.context-path:}"/>
</bean>

Next, locate the following section:

<!-- 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:8084/saml/metadata"/>
	<property name="extendedMetadata" ref="extendedMetadata"/>
	<property name="includeDiscoveryExtension" value="false"/>
	<property name="keyManager" ref="keyManager"/>
</bean>

And add in the line <property name="entityBaseURL" value="https://<server-name>:port"/> between the <bean> tags and update the value of the entityBaseURL entry to match the CAST Imaging host name and the custom secure SSL port number:

<!-- 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:8084/saml/metadata"/>
	<property name="extendedMetadata" ref="extendedMetadata"/>
	<property name="includeDiscoveryExtension" value="false"/>
	<property name="keyManager" ref="keyManager"/>
	<property name="entityBaseURL" value="https://my_server:8443"/>
</bean>

Save the application-security-saml.xml file when complete.

Restart the CAST Imaging login service

Restart the CAST Imaging login service to ensure that all the changes are applied correctly.

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 the following location:

%PROGRAMFILES%\ImagingSystem\login\FederationMetadata.xml

Traditional Windows installer: %PROGRAMFILES%\ImagingSystem\login\FederationMetadata.xml

Docker Installer (located in the unzipped extension folder):
server\login\FederationMetadata.xml or login\FederationMetadata.xml

Note that the file does not need to be named FederationMetadata.xml, however, the file name given to you by your IT Administrators and stored in the location above, should be EXACTLY referenced in the application.properties file on the line security.saml.idp.metadata.source.

Key pair generation

Two public/private key pairs must be generated on the CAST Imaging host server in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS):

One key is specific to SAML
One key is specific to SSL.

To do so, you need to use the keytool command line utility on the CAST Imaging host server. You can refer to https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html and specifically https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html#keytool_option_genkeypair for more information about how to use keytool with the -genkeypair command (these links refer to Oracle's Java implementation, and other JRE providers will have their own instructions, which you should use). Additional information is available in https://jenkov.com/tutorials/java-cryptography/keytool.html#generate-key-pair.

Example command lines to generate two key pair files using the JKS format:

%JAVA_HOME%\keytool -genkeypair -alias <some-unique-alias> -keyalg <RSA> -keysize <2048> -validity <365> -sigalg <SHA256withRSA> -dname "CN=<commonName>, OU=<organizationalUnitName>, O=<organizationName>, L=<localityName>, ST=<stateOrProvinceName>, C=<countryName>" -keypass <my_password> -storetype JKS -keystore <samlKeystore.jks> -storepass <storepass>

%JAVA_HOME%\keytool -genkeypair -alias <some-unique-alias> -keyalg <RSA> -keysize <2048> -validity <365> -sigalg <SHA256withRSA> -dname "CN=<commonName>, OU=<organizationalUnitName>, O=<organizationName>, L=<localityName>, ST=<stateOrProvinceName>, C=<countryName>" -keypass <my_password> -storetype JKS -keystore <sslKeystore.jks> -storepass <storepass>

Where:

-alias	Choose a name in the Java KeyStore the generated key should be identified by. Remember, an alias can only point to one key so you should generate a unique alias for each key: -alias samlKeystore -alias sslKeystore
-keyalg, -keysize, -validity	Choose these options according to your own requirements (see https://jenkov.com/tutorials/java-cryptography/keytool.html#keytool-arguments for more information).
-sigalg	The signature algorithm used to sign the key pair. CAST recommends SHA256withRSA.
-dname	The Distinguished Name from the X.500 standard. This name will be associated with the alias for this key pair in the KeyStore. The `dname` is also used as the "issuer" and "subject" fields when using a self signed certificate.
-keypass	This option configures a password that is used to protect the key pair within the KeyStore. The value must be at least 6 characters.
-storetype	The file format the KeyStore should be saved in. The default is `JKS`.
-keystore	The name of the KeyStore file to store the generated key pair in. If the file does not exist already, it will be created. CAST Imaging requires the keys to be located in the following location: <Imaging_System_installation_path>\Login\security\ For example: -keystore D:\CAST\ImagingSystem\Login\security\samlKeystore.keystore -keystore D:\CAST\ImagingSystem\Login\security\sslKeystore.keystore
-storepass	The password for the entire KeyStore file. Anyone who wants to open this KeyStore later will need this password. The `storepass` is not the same as the `keypass`. The `keypass` password only counts for a single key. You will need both the `storepass` password and the `keypass` to access any given key stored in a KeyStore. If you are adding the new key to an existing keystore defined by the `-keystore` command, then you will require the password defined at the time the existing keystore was created. If this is a new keystore, this command creates a new password for the new keystore, which you should retain.

Note that since you will be storing both keys in the same keystore, you should use the same -keypass and -storepass passwords during each key pair creation. These passwords are required in later steps.

Configure SAML authentication

Open the following file in a text editor:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties
 
Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Microsoft Windows traditional installer

The file is located in the protected %APPDATA% location, therefore you must open the .properties file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the following section of options and modify each uncommented line to match the items you have already configured. Save the application.properties file when complete.

# ==============
# Parameters for saml mode
# --------------
# Specify the location for the metadata source
# By default, it uses a file on the filesystem and must be given an absolute path
# You can specify a Http resource by providing a full url to a metadata file
# 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
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=
# Specify the default alias in the keystore for the certificate
security.saml.keystore.default-alias=
# Specify the keystore and alias password
security.saml.keystore.password=
# 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=
# -------------------------------------------------------------
# ssl configuration, ssl is required when enable the saml mode
# -------------------------------------------------------------
# The format used for the keystore. It could be set to JKS in case it is a JKS file
server.ssl.key-store-type=
# The path to the keystore containing the certificate
server.ssl.key-store=
# The password used to generate the certificate
server.ssl.key-store-password=
# The alias mapped to the certificate
server.ssl.key-alias=

security.saml.idp.metadata.source	Full path to the FederationMetadata.xml file that has been provided to you by your IT Administrators. You may need to escape the path: security.saml.metadata.source=D:\\CAST\\ImagingSystem\\Login\\FederationMetadata.xml Note that the file name must exactly match the name of the file given to you by you IT Administrators. E.g. if they have given you a file called Federation-Metadata.xml, you must specify this name exactly.
security.saml.keystore.filename	The file name of the SAML certificate file you created previously when generating the SAML public/private key pair (with the -keystore command). For example: security.saml.keystore.filename=samlKeystore.keystore
security.saml.key.default-alias	The keystore SAML key alias you created previously when generating the SAML public/private key pair (with the -alias command). For example: security.saml.key.default-alias=samlKeystore
security.saml.keystore.password	The SAML keystore password you entered previously when prompted while generating the SAML public/private key pair.
security.saml.attribute.username	The user's name to be displayed in the UI. This parameter is optional, by default we'll retrieve the user's ID as it is given from the IDP, but by setting this parameter, you can then display a user's full name instead of its login ID.
security.saml.attribute.group	This parameter is required. It is used to retrieve the user's groups - its exact format will depend on the SAML setup and should be confirmed by the ADFS admin. It should match with the name passed in the SAML response
server.ssl.key-store-type	Enter the type of SSL keystore you have used to generate the SSL public/private key pair. If you do not explicitly set this when generating the SSL public/private key pair (i.e. explicitly using the -storetype command), then it will default to JKS which is what you should enter: server.ssl.key-store-type=JKS
server.ssl.key-store	Full path to the SSL certificate file you created previously when generating the SSL public/private key pair (with the -keystore command). You may need to escape the path: server.ssl.key-store=D:\\CAST\\ImagingSystem\\Login\\security\\sslKeystore.keystore CAST highly recommends placing the Java keystore in a location outside of system folders because this may prevent CAST from accessing the required files. CAST recommends a folder at the root of the system drive ensuring that file permissions are adequate.
server.ssl.key-store-password	The SSL keystore password you entered previously when prompted while generating the SSL public/private key pair.
server.ssl.key-alias	The SSL key alias you created previously when generating the SSL public/private key pair (with the -alias command). For example: server.ssl.key-alias=sslKeystore

CAST recommends also adding the following option to provide debug level logging when attempting to setup SAML authentication:

logging.level.com.castsoftware.aip.console.security.saml=debug

Once the SAML configuration is complete, you may wish to change this to "info" or remove it completely.

Update application-security-saml.xml file

Locate the following file and edit with a text editor:

Traditional Windows installer:
%APPDATA%\CAST\ImagingSystem\login\security\application-security-saml.xml

Docker Installer (located in the unzipped extension folder):
server\login\security\application-security-saml.xml or login\security\application-security-saml.xml

Locate the following two sections where "https://localhost" are mentioned:

<!-- 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:8084/saml/metadata"/>
	<property name="extendedMetadata" ref="extendedMetadata"/>
	<property name="includeDiscoveryExtension" value="false"/>
	<property name="keyManager" ref="keyManager"/>
</bean>

and:

<bean id="successRedirectHandler"
	class="com.castsoftware.aip.console.security.saml.SamlAuthenticationSuccessHandler">
	<property name="defaultTargetUrl"
		value="https://localhost/"/>
</bean>

Change "https://localhost" to the host name of the current server (for example "my_server", as shown below). Save the application-security-saml.xml file when complete.

<!-- Define basic information regarding WEBI as a Service Provider -->
<bean id="metadataGenerator" class="org.springframework.security.saml.metadata.MetadataGenerator">
	<property name="entityId" value="https://my_server:8084/saml/metadata"/>
	<property name="extendedMetadata" ref="extendedMetadata"/>
	<property name="includeDiscoveryExtension" value="false"/>
	<property name="keyManager" ref="keyManager"/>
</bean>

and:

<bean id="successRedirectHandler"
	class="com.castsoftware.aip.console.security.saml.SamlAuthenticationSuccessHandler">
	<property name="defaultTargetUrl"
		value="https://my_server/"/>
</bean>

Restart all CAST Imaging services

Restart the Windows services / Docker containers in the following order for the new configuration to be taken into account:

Microsoft Windows traditional installer	Docker
CAST Imaging System - imaging-ETL	etl
CAST Imaging System - login service	login
CAST Imaging System - imaging-service	server
CAST Imaging System - Frontend service	nginx
CAST Imaging System - sourcecode service	sourcecode
CAST Imaging System - Neo4j Graph Database	neo4j

CAST Imaging metadata generation

Browse to the following URL (assuming CAST Imaging is installed on the local machine) to generate the metadata:

https://localhost/saml/metadata

This XML file describes the SSO information that the CAST Imaging needs and will provide to the IDP when a user requests a login. Send this file to the person in charge of the IDP so that it can be added to the list of allowed Service Providers that can call this IDP.

Troubleshooting

If you face issues configuring SAML authentication, you may wish to try the following changes:

Allow metadata with an invalid signature or signed by a not-trusted credential to be accepted

Open the following file in a text editor:

Windows: %APPDATA%\CAST\ImagingSystem\login\security\application-security-saml.xml

Docker Installer (located in the unzipped extension folder):
server\login\security\application-security-saml.xml or login\security\application-security-saml.xml

Change the following from this:

<property name="metadataRequireSignature" value="true"/>

to this:

<property name="metadataRequireSignature" value="false"/>

Save the file and then restart the CAST Imaging System - login service Windows Service or the login Docker container in order for the new configuration to be taken into account.

404 error when attempting to log in - but login functions correctly in "incognito" or "private" browser mode

If you are facing a 404 error when attempting to login, but you can successfully log in using "incognito" or "private" browser mode, ensure that the maxAuthenticationAge attribute matches the session timeout value in IDP. Open the following file in a text editor:

Windows: %APPDATA%\CAST\ImagingSystem\login\security\application-security-saml.xml

Docker Installer (located in the unzipped extension folder):
server\login\security\application-security-saml.xml or login\security\application-security-saml.xml

Locate the following line:

<bean id="webSSOProfilerConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl"/>

Modify this line as follows where value="xxx" matches the value (in seconds) defined for session timeout in your IDP:

<bean id="webSSOProfilerConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
	<property name="maxAuthenticationAge" value="xxx"/>
</bean>

Save the file and then restart the CAST Imaging System - login service Windows Service or the login Docker container in order for the new configuration to be taken into account.

Bad gateway 502

If you encounter a "bad gateway 502" error when attempting to fetch the metadata using the URL https://localhost/saml/metadata you may need to modify the nginx.conf file and change all instances of 127.0.0.1 to the server host name (except for proxy_pass http://127.0.0.1:8181 on Microsoft Windows):

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\nginx\nginx.conf

Docker Installer (located in the unzipped extension folder):
server\nginx\conf\nginx.conf or nginx\conf\nginx.conf

For example:

Microsoft Windows

# Proxying the connections connections
location ^~ /imaging/login/api/ {

	limit_req zone=default burst=6 nodelay;

	proxy_pass         https://my_server_hostname:8084/;
}
location ^~ /imaging/sourcecode/api/ {
	proxy_pass         https://my_server_hostname:8084/sourcecode/api/;
}
location ^~ /imaging/api/ {
	proxy_pass         https://my_server_hostname:8084/api/;
}
location ^~ /imaging/etl/api/ {
	proxy_pass         https://my_server_hostname:8084/etl/api/;
}
location ^~ /imaging/saml/ {
	proxy_pass         https://my_server_hostname:8084/saml/;
}
location ^~ /saml/ {
	proxy_pass         https://my_server_hostname:8084/saml/;
}
location ^~ /imaging/bot/ {
	proxy_pass http://127.0.0.1:8181;
	proxy_http_version 1.1;
	proxy_redirect     off;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection 'upgrade';
	proxy_set_header Host $host;
	proxy_cache_bypass $http_upgrade;

}
location ^~ /imaging/neo4j/api/ {
	proxy_pass         https://my_server_hostname:8084/neo4j/api/;
}

Configuring SSO with CAST Console

This option creates an SSO (Single Sign On) between CAST Console and CAST Imaging, therefore when logged into the CAST Console, a user can click through to CAST Imaging and no login prompt will be shown, i.e. users are logged into CAST Imaging with with their CAST Console login credentials. In effect, setting this option replaces the CAST Imaging login system with the CAST Console login system.

Prerequisites

Component	Release	Description
CAST Imaging	≥ 2.16.0-funcrel	-
CAST Console Enterprise edition	≥ 2.8.0-funcrel	Not supported with CAST Console Standalone edition - Keycloak is required.

Configuration steps

Where Console and Imaging are installed on the same server

The only configuration that is required is to modify the following file depending on your environment:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties

Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Find the following line:

security.mode=local

Change the line to:

security.mode=enterprise

Save the file and then restart the CAST imaging "login" Windows Service or the "server" container.

Where Console and Imaging are installed on separate servers

In addition to the configuration explained above to change security.mode to "enterprise", you must ALSO make the following additional changes:

Update application.properties to specify where Console is installed

Modify the following file depending on your environment:

Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\login\application.properties

Docker Installer (located in the unzipped extension folder):
server\login\application.properties or login\application.properties

Find the following line which directs CAST Imaging to look for Console on the "localhost":

spring.config.import=optional:configserver:http://localhost:8088/config

Change "localhost" to match the IP address or hostname of the server on which CAST Console is installed:

spring.config.import=optional:configserver:http://<console_ip_address_hostname>:8088/config

Save the file and then restart the CAST imaging "login" Windows Service or the "server" container.

Open port 8084 inbound on CAST Imaging server

The CAST Console SSO/Keycloak service requires access to port 8084 on the CAST Imaging server, therefore please ensure that this port is accepting inbound TCP packets from the CAST Console server.

Create a redirect in Keycloak

To ensure that Keycloak is authorised to redirect to the CAST Imaging server, connect to Keycloak from any machine on the local network:

http://<console_ip_address_hostname>:8086

Click the Administration Console option:

The default login credentials are admin/admin unless these have been modified as part of the deployment process:

Now click the Clients option and then click aip-console-client:

Click to enlarge

Now add a new redirect:

You should add a redirect as follows: http://<imaging_ip_address_hostname>:8084/*

Ensure you save the changes:

Configure authentication

Introduction

Authentication mode activation

Clean up when switching to a new authentication mode

Role clean up

Switching away from SAML mode

Configuring authentication using local configuration

Configuring authentication using LDAP/LDAPS

LDAP over SSL (LDAPS)

Enabling LDAP debug mode

Configuring authentication using AD

Configuring authentication using SAML

Supported versions of SAML

Configuration process

CAST Imaging login service configured for HTTPS

Update application.properties file

Update nginx.conf file

Update application-security-saml.xml file - optional

Restart the CAST Imaging login service

Request FederationMetadata.xml

Key pair generation

Configure SAML authentication

Update application-security-saml.xml file

Restart all CAST Imaging services

CAST Imaging metadata generation

Troubleshooting

Allow metadata with an invalid signature or signed by a not-trusted credential to be accepted

404 error when attempting to log in - but login functions correctly in "incognito" or "private" browser mode

Bad gateway 502

Configuring SSO with CAST Console

Prerequisites

Configuration steps

Where Console and Imaging are installed on the same server

Where Console and Imaging are installed on separate servers

Update application.properties to specify where Console is installed

Open port 8084 inbound on CAST Imaging server

Create a redirect in Keycloak