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.
Before you can configure the 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 Console package and the Back End 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.
|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.
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 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:
|-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 |
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 |
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:
The password for the entire KeyStore file. Anyone who wants to open this KeyStore later will need this password. The
If you are adding the new key to an existing keystore defined by the
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|
|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 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 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:
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
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:
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:
Locate the following line:
Modify this line as follows where
value="xxx" matches the value (in seconds) defined for session timeout in your IDP:
Save the file and then restart the AIP Console front-end in order for the new configuration to be taken into account.