Page tree
Skip to end of metadata
Go to start of metadata

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

Notes
Local authenticationThis mode is active by default and relies on simple username/password authentication defined in the application-security-local.xml configuration file.
  • 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.
  • SAML authentication is available for use in ≥ 1.7.1.
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 DirectoryThis 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.


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, ldapad, saml). 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

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:

UsernamePasswordRole
adminadminADMIN
castcastUSER

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 formats:

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

Please ensure that:

  • {noop} is left in place before the chosen password. This is required.
  • all new users should all use authorities="" - there is no need to add a value.
1.6.x - 1.9.x
<user name ="[name]" password="{noop}[password]" authorities="USER" />
<user name ="[name]" password="{noop}[password]" authorities="ADMIN" />

Please ensure that:

  • {noop} is left in place before the chosen password. This is required.
  • all NEW users use the authorities="USER" attribute. This is required.

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. 

≥ 1.10.0


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


<authentication-manager>
	<authentication-provider>
		<user-service>
			<user name="cast" password="{noop}cast" authorities="USER" />
			<user name="admin" password="{noop}admin" authorities="ADMIN" />
			<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 (ldap://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.

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 not currently supported in any release.

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.xmlThis file must be provided by your IT administrators before you can proceed. See instructions below.
Key pair generationA public/private key pair 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. See instructions below.

Supported versions of SAML

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

Configuration process

CAST Imaging login service configured for HTTPS

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

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.

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

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 (provided with the JDK - see https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information) on the CAST Imaging host server. Example command lines to generate two key pair files using the JKS format:

%JAVA_HOME%\keytool -genkeypair -keystore <path_to_saml_keystore_file> -alias <some_unique_alias> [-keyalg RSA] [-validity 10000]
%JAVA_HOME%\keytool -genkeypair -keystore <path_to_ssl_keystore_file> -alias <some_unique_alias> [-keyalg RSA] [-validity 10000]

Where:

-genkeypairThe keytool command to generate a public key and associated private key. See https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html#keytool_option_genkeypair. Note that in older implementations of Java, this command was known as -genkey and can still be used.
-keystore

The keystore files must be placed 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
-alias

Choose an alias that is specific to each key pair (each alias must be unique), for example:

-alias samlKeystore
-alias sslKeystore
[-keyalg]Specifies an RSA type key pair with a -keysize of 2048. If you omit this command, a DSA key pair will be created with a -keysize of 2048.
[-validity]Specifies a key pair that is valid for 10000 days. If you omit this command a key pair that is valid for 90 days will be created.
Note that you will be prompted for -keypass and -storepass passwords during each key pair creation. CAST recommends using the same password if possible and note them down - you will require them 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. You may need to escape the path:

security.saml.metadata.source=D:\\CAST\\ImagingSystem\\Login\\FederationMetadata.xml

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.
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
server.ssl.key-store-passwordThe 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 installerDocker
CAST Imaging System - imaging-ETLetl
CAST Imaging System - login servicelogin

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 change which will 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.

  • No labels