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.

Prerequisites

Before you can configure the AIP 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 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 https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html 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

Where:

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

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.

-keystore

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

During the installation process (see AIP Console package - 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: <AIP_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 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

security.saml.attribute.group=

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:

https://localhost:8081/saml/metadata

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

Troubleshooting

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:

%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