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:
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 HTTPS||The 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 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.|
|AIP Console MetaData generation||The 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.
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:
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 https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information) on the AIP Console host server. For example:
|-alias||Choose 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:
Step 3 - Activate and configure SAML authentication mode
Activation and configuration of SAML authentication mode is governed by the aipConsole.properties 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|
|Post installation using aipConsole.properties|
Post installation you can activate the SAML authentication mode and then fill in the relevant fields in the aipConsole.properties file, which is located here:
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:Save the aipConsole.properties file.
Step 4 - Configuration options
During the installation of the AIP Console
|Post installation using aipConsole.properties||Description of option|
|SAML metadata source||security.saml.metadata.source=|
Specify the location for the metadata source (as outlined in IDP MetaData generation), for example:
The location of the keystore you created previously.
|Keystore default alias||security.saml.keystore.default-alias=|
The keystore alias you created previously.
The keystore password you created previously.
|User name attribute||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.|
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 "java.io.IOException: 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 "sun.security.provider.certpath.SunCertPathBuilderException: 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:
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.