Task 10: Configure the SAML keystore in IdM

The IdM SAML key store is defined in two configuration files:

• <Tomcat>/idm-service/idm-service.war/WEB-INF/spring/applicationContext-saml.xml

  Note This file defines a set of SAML keystore variables.

• <Tomcat>/idm-service/idm-service.war/WEB-INF/spring/applicationContext.properties

  Note The variables defined in applicationContext-saml.xml are declared in this file.

In a production environment, you need to generate a new SAML keystore, and only the applicationContext.properties file needs to be updated with new SAML keystore settings.

1. Generate a SAML keystore.

   Private keys (with either self-signed or CA-signed certificates) are used to digitally sign SAML messages and encrypt their content, and in some cases for SSL/TLS Client authentication of your service provider application. SAML Extension ships with a default private key in the samlKeystore.jks file with the alias apollo, which can be used for initial testing, but for security reasons should be replaced with your own key in early development stages.

   If your IdP (for example, ADFS) does not require keys signed by a specific certification authority, you can generate your own self-signed key using the keytool Java utility, by running commands that resemble the following:

   # cd /<Tomcat>/idm-service/idm-service.war/WEB-INF/classes/security
   # keytool -genkey -keyalg RSA -alias <Choose Your Alias> -keystore samlKeystore.jks -storepass <Choose Your Password> -validity 1080 -keysize 2048

   These example commands use the following arguments:

   • keyalg: Specifies a signature algorithm.

     In generating a public/private key pair, the signature algorithm (-sigalg) is derived from the algorithm of the underlying private key:

     • If the underlying private key is of type "DSA", the -sigalg option defaults to "SHA1withDSA".
     • If the underlying private key is of type "RSA", the -sigalg option defaults to "SHA256withRSA".
     • If the underlying private key is of type "EC", the -sigalg option defaults to "SHA256withECDSA".
   • alias: Specifies an alias for this keystore file (do not use "apollo" as it already exists in the system).
   • keystore: Specifies a filename and location for this keystore file.

   • storepass: Specifies a password for the keystore file. This is the password that is used to protect the keystore file.

   • validity: Specifies a number of days that this keystore will be valid for (1080 = 3 years)
   • keysize: Specifies a number of bits for the key ("2048" means a 2048-bit RSA key will be generated)

   See the following figure for an example.

   

   Note Ensure the CN value is the host name of the Service Manager Service Portal (IdM) server. This is the first question ("What is your first and last name ?").

2. If you did not generate the SAML keystore in the <Tomcat>/idm-service/idm-service.war/WEB-INF/classes/security directory, copy the samlKeystore.jks that you generated to this directory.
3. Configure the SAML keystore in applicationContext.properties.

   1. In a text editor, open the applicationContext.properties file, which is stored in the <Tomcat>/idm-service/idm-service.war/WEB-INF/spring folder.

   2. Update the SMAL keystore file parameters:

      • idm.saml.keystore.type: keep the default value (jks).
      • idm.saml.keystore: use the value defined as -keystore samlKeystore. It is assumed that the keystore is stored in the <Tomcat>/idm-service/idm-service.war/WEB-INF/classes/security directory.
      • idm.saml.keystore.password: use the password that you specified in the previous step (-storepass <Choose Your Password>).
      • idm.saml.keystore.defaultKey.name: use the key alias that you specified: -alias <Choose Your Alias>.

      • idm.saml.keystore.defaultKey.password: use the password value that you entered at the end of the keystore creation. This password is linked to the key (alias) that you added to the keystore. It is different to the storepass value, unless you pressed Return at the end of the keystore creation process. In that case, it is the same as the keystore password (storepass).

      The following is an example configuration:

      # SAML Configuration
      idm.saml.keystore.type=jks
      idm.saml.keystore=classpath:security/samlKeystore.jks
      idm.saml.keystore.password = changeit
      idm.saml.keystore.defaultKey.name = idm
      idm.saml.keystore.defaultKey.password = changeit