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

Summary: this page describes how to configure the AIP Console for SAML authentication.


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


Ensure that you are using the following versios of JDK for both the Front End AIP Console package and the Back End AIP Node package:

  • JDK 1.8 u161 or later

This version (or more recent versions) include support for 4096 bits RSA keys, which CAST highly recommends.

If you are using older versions of the JDK, you will need to download the Java Cryptography Extension (JCE) to enable stronger cryptographic algorithms. To enable it, download the JCE for you version of the JDK you are using and extract the content of the downloaded zip file to the lib/security folder inside your JDK installation folder.

AIP Console configured for HTTPSThe AIP Console must be configured to use the HTTPS protocol. See Changing Console and Node port numbers - activating HTTPS for more information.
Receive MetaData from Identity Provider

This MetaData information must be provided by the Identity Provider you will use before you can proceed.

Key pair generationA 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.
AIP Console MetaData generationThe AIP Console must generate MetaData that can be sent to the IDP so that the AIP Console can be added to the list of allowed Service Providers that can call the IDP.

If you are having trouble configuring SAML authentication, you can configure the AIP Console to log messages relevant to SAML in DEBUG mode which can help trace the issue. See AIP Console - Logging mechanisms.

Configuration process

Step 1 - IDP MetaData generation

You must request the IDP MetaData from the Identity Provider you will use. In general this is provided in an XML and this file must be stored in the following location:

Windows: <AIP_console_installation>\AipConsole\data
Linux: $HOME\CAST\AipConsole\data

You can also configure the AIP Console to fetch MetaData as follows:

  • via a http resource through a URL to the metadata file
  • via a classpath resource using "classpath:myMetadataFile.xml"

Step 2 - Key pair generation

A public/private key pair must be generated on the AIP Console 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 JDK - see for more information) on the AIP Console host server. For example:

%JAVA_HOME%\keytool -genkeypair -alias <some-alias> -keyalg RSA -keypass <changeit> -keystore <samlKeystore.jks> -storetype PKCS12


-aliasChoose an alias that is specific to the key pair, for example "saml".

This configures 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:

Windows: <AIP_console_installation>\AipConsole\data\samlKeystore.jks
Linux: $HOME\CAST\AipConsole\data\samlKeystore.jks

Step 3 - Activate and configure SAML authentication mode

Activation and configuration of SAML authentication mode is governed by the configuration file within the AIP Console installation data. The configuration can be completed either during the installation of the AIP Console, or post installation:

During the installation of the AIP Console

During the installation process (see AIP Console - front-end installation), you will be prompted to enter configuration information as follows. Fill in the relevant fields as indicated in the table below:

Post installation using

Post installation you can activate the SAML authentication mode and then fill in the relevant fields in the file, which is located here:

Windows: <AIP_console_installation>\AipConsole\data\
Linux: $HOME\CAST\AipConsole\data\

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:




Then find the following section of options and fill in as indicated in the table below:

# ==============
# SAML security Mode
# --------------
Save the file.

Step 4 - Configuration options

During the installation of the AIP Console

Post installation using aipConsole.propertiesDescription of option
SAML metadata sourcesecurity.saml.metadata.source=

Specify the location for the metadata source (as outlined in IDP MetaData generation), for example:

Windows: <AIP_console_installation>\AipConsole\data\MetadataFile.xml
Linux: $HOME\CAST\AipConsole\data\MetadataFile.xml
  • You can also specify:
    • a http resource by providing a full URL to the metadata file
    • a classpath resource using "classpath:myMetadataFile.xml"
Keystore filenamesecurity.saml.keystore.filename=

The location of the keystore you created previously.

Keystore default aliassecurity.saml.keystore.default-alias=

The keystore alias you created previously.

Keystore passwordsecurity.saml.keystore.password=

The keystore password you created previously.

User name attributesecurity.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.

User search filter

This parameter is required. It is used to retrieve the user's groups and assign roles in the AIP Console. Make sure that the roles assigned to the user in the IDP have equivalents in the AIP Console Security Page.

Step 5 - AIP Console MetaData generation

At this point, if the AIP Console package is running, it will need to be restarted, particularly if you are configuring SAML post-installation. Then browse to the following location to generate the AIP Console MetaData and save the results as an XML file on the local machine:


This XML file describes the SSO information that the AIP Console 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.

Step 6 - Grant a role to the user

You must assign a role to a new user before that user can log in - see Administration Center - Security - User Roles.

Step 7 - Testing SAML authentication

If SAML is enabled, you should only see a "Login" button when accessing the AIP Console

Click to enlarge

On clicking "Login", you will be redirected to the IDP login page, if you are not already logged into it (Microsoft Internet Explorer and Microsoft Edge will only have a Windows Authentication popup since they support authentication through a Windows user account):

Click to enlarge

Once you are authenticated on the IDP, you should be redirected to the AIP Console UI and be correctly logged in. Your User ID will appear in the top right of the page:

Click to enlarge


I am getting a " Invalid keystore format" error when starting the AIP Console

Make sure you use the keytool.exe from the same JDK version as the one used to run the application. Generating a keystore with JDK 1.8 or above and running the AIP COnsole with JDK 1.7 (for example) will result in this error. If this doesn't work, rename the existing keystore and create a new one as described above.

I am getting " unable to find valid certification path to requested target" after the AIP Console is started

This issue occurs when retrieving metadata from the IDP over HTTPS with a self signed certificate. To fix this, you have to retrieve the certificate from the IDP and add it to the SAML keystore created using the following command:

%JAVA_HOME%\keytool -import -file idpCertificate.crt -alias idpAlias -keystore samlKeystore.jks

You will be prompted for the keystore password and to verify information about the certificate that you want to add to the store. Once it is added, restart the application and the metadata should be obtained automatically.

  • No labels