Summary: this page describes how to configure the Console for SAML authentication in 1.x.

Note that the authentication mechanism has changed in ≥ 2.x, see Configure authentication and roles using Keycloak - v. 2.x.

Prerequisites

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

JDK	Ensure that you are using the following versios of JDK for both the Front End Console package and the Back End 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.
Console configured for HTTPS	The 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 Console host server in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS). See below for more information.
Console MetaData generation	Console must generate MetaData that can be sent to the IDP so that the 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 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: <console_installation>\AipConsole\data
Linux: $HOME\CAST\AipConsole\data

You can also configure the 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 Console host server in a dedicated keystore to allow encrypted communication with the 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 on the Console 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.

For example (text marked with < > should be modified for your own environment) to generate JKS keypair:

%JAVA_HOME%\keytool -genkeypair -alias <some-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>

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.
-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 in the 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, for example: Windows: <console_installation>\AipConsole\data\samlKeystore.jks Linux: $HOME\CAST\AipConsole\data\samlKeystore.jks
-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.

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 Console installation data. The configuration can be completed either during the installation of Console, or post installation:

During the installation of 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 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: Windows: <console_installation>\AipConsole\data\aipConsole.properties Linux: $HOME\CAST\AipConsole\data\aipConsole.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: security.mode=default to: security.mode=saml Then find the following section of options and fill in as indicated in the table below: # ============== # SAML security Mode # -------------- Save the aipConsole.properties file.

Step 4 - Configuration options

During the installation of 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: Windows: <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 filename	security.saml.keystore.filename=	The location of the keystore you created previously.
Keystore default alias	security.saml.keystore.default-alias=	The keystore alias you created previously.
Keystore password	security.saml.keystore.password=	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	security.saml.attribute.group=	This parameter is required. It is used to retrieve the user's groups and assign roles in the Console. Make sure that the roles assigned to the user in the IDP have equivalents in the Console Security Page.

Step 5 - Console MetaData generation

At this point, if the 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 Console MetaData and save the results as an XML file on the local machine:

https://localhost:8081/saml/metadata

This XML file describes the SSO information that the 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 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 Console UI and be correctly logged in. Your User ID will appear in the top right of the page:

Click to enlarge

Troubleshooting

I am getting a "java.io.IOException: Invalid keystore format" error when starting 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 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 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.

I'm getting a 404 error when attempting to log in - but I can log in 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: %PROGRAMDATA%\CAST\AipConsole\application-security-saml.xml
 
Linux: $HOME\ProgramData\AipConsole\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 AIP Console front-end in order for the new configuration to be taken into account.