Managing agent certificates

When an application is integrated into the BMC Atrium Single Sign-On system, keystore and truststore are created for the HTTPS communications between the BMC Atrium Single Sign-On service and the web agent. You must recreate these keystores and truststores every time the certificate in the BMC Atrium Single Sign-On service is changed. One way of recreating the certificates is to reintegrate the application with the BMC Atrium Single Sign-On service.

In a dynamic environment where certificates are updated on a regular basis, it is difficult to reintegrate applications regularly. Alternatively, you can create certificates again manually without reintegration using the following process.

The steps for recreating certificates manually are as follows:

1. Removing existing Keystore or Truststore
2.  Creating new Keystore or Truststore
3. Creating a new Truststore
4. Encrypting Keystore or Truststore Passwords
5. Updating integration
   

To remove existing Keystore or Truststore

The existing keystore or truststore files are located in the agent configuration directory, <webserver>/atssoAgents/<webapp>. For example, with mid tier running in a Tomcat server, the files are located in: C:\Program Files\Apache Software Foundation\Tomcat 7.0\atssoAgents\arsys.

1. You can back up the keystore and truststore files to another directory as the new keystore and truststore will replace the directory and files.
2. Delete these files from the original location.

The keystore and truststore files are:

• keystore.ks — The keystore file containing agent key pair and secret key
• keystore.ks.keypass — Encrypted password for private key access
• keystore.ks.storepass — Encrypted password for keystore access
• truststore.ks — The truststore for the agent containing the BMC Atrium Single Sign-On server certificate
• truststore.ks.keypass — Encrypted password for private key access
• truststore.ks.storepass — Encrypted password for truststore access

To create new Keystore or Truststore

You must use the keytool command to create a new key pair and a new secret key for keystore or truststore.

1. Use the following keytool command for creating a new key pair.

   keytool.exe -genkey -alias agent -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -keystore keystore.ks -storepass changeit -keypass changeit -storetype jceks -dname "CN=AgentName,OU=Atrium Core,O=BMC Software,L=Austin,ST=Texas,C=US" -validity 3650 -ext KeyUsage=digitalSignature,keyEncipherment -ext ExtendedKeyUsage=serverAuth,clientAuth

   The alias specified must be agent and the keystore type must be jceks. The passwords used can have any permitted value but must be same for both storepass and keypass parameters.

   
   To prevent collision when the certificate is loaded into the BMC Atrium Single Sign-On service truststore, ensure that the Subject name of the certificate is unique (specified with the -dname parameter). To satisfy this unique value requirement, the default behavior of the BMC Atrium Single Sign-On system is to use the agent name for the CN.

2. Use the following keytool command for generating a secret key for encryption.

   keytool.exe -genseckey -alias agent.key -keyalg AES -keysize 128 -keystore keystore.ks -storepass changeit -keypass changeit -storetype jceks

   
   In this command, the alias must be agent.key, and you must save the new key in the new keystore, keystore.ks, which also contains the new agent certificate.

   Note

   The passwords for the storepass and keypass must be same as used in the command to generate the agent certificate key pair.

You can either run these commands in the agent configuration directory, or move the keystore.ks file into the agent configuration directory.

To create new Truststore

You can use the steps mentioned in the previous section to create a new truststore. Alternatively, you can also import and create a new truststore from the BMC Atrium Single Sign-On server into the new file. Use the following commands to save and import the certificate in the truststore.

1. Save the certificate in to a local file.

   Note

   For the following command to work, the BMC Atrium Single Sign-On server must be running.

   keytool.exe -printcert -rfc -sslserver <host>:<port> > sso.cer

   For this command, <host> is the name of the BMC Atrium Single Sign-On server and <port> is the HTTPS port number for the BMC Atrium Single Sign-On service. The actual filename used to store the certificate can be any valid file name. However, you must use the same file name while using the import command for the truststore.

2. Import the saved certificate to create the new truststore.

   keytool.exe -importcert -alias atsso -file sso.cer -keystore truststore.ks -storepass changeit -keypass changeit -storetype jceks

You can either run these commands in the agent configuration directory, or move the truststore.ks file into the agent configuration directory.

To encrypt Keystore or Truststore Passwords

You can use a utility to encrypt the passwords used to access the keystore and truststore. This utility is provided with the BMC Atrium Single Sign-On agent. You must use a JVM (either JDK or JRE) for running this utility. The name of this utility program is atsso-common.jar and you can locate it in the application where the agent is installed. For example, on the mid tier server, the program is located in the directory <install_directory>/midtier/WEB-INF/lib.

1. Run the following command from the command prompt to encrypt the password. You can view the encryption password as the output.

   C:\WEB-INF\lib> java -jar atsso-common.jar <to-encode>

2. Copy this encoded string into the appropriately named file for which the password is to be used. For example, copy the keystore -keypass password into a file named keystore.ks.keypass and copy the keystore -storepass password into a file named keystore.ks.storepass.
   
   To protect these new key pair and secret key, ensure that you have provided only read access permissions for the keystore, truststore, and associated password files.

3. You must also move the password files into the agent configuration directory along with the keystore.ks and truststore.ks files, if it is not the default directory.

To update integration

1. The final step is to update the information used to integrate the agent with the server. The first step in this process is to store the new agent certificate into the truststore of the BMC Atrium Single Sign-On service.
   
   The following command can be used to export the new certificate into a file so that it can be transferred to the BMC Atrium Single Sign-On server:

   keytool.exe -exportcert -alias agent -file agent.cer -rfc -keystore keystore.ks -storepass changeit1 -keypass changeit2 -storetype jceks

   The passwords that you enter in this command should be same as used for the keystore. The -alias parameter must be specified as agent. The output filename used to store the certificate can be any valid file name. However, you must use the same file name while using the import command.

2. After you have exported and transferred to the to the BMC Atrium Single Sign-On server, you must import it into the truststore for the BMC Atrium Single Sign-On server. You must copy the file to the same directory as the truststore, <install_directory>/tomcat/conf directory. The following command requires the use of the keytool program from the JVM that is configured for BMC Atrium Single Sign-On. For more information about using Keytool utility, see Using the keytool utility.
   
   

   Open a shell window in the same directory as the truststore and run the following command to import the certificate:

   keytool.exe -importcert -alias agent.alias -file agent.cer -keystore cacerts.p12 -storepass changeit -keypass changeit -storetype pkcs12 -providername JsafeJCE

   The alias specified should be unique for every agent in the BMC Atrium Single Sign-On server or you will not be able to import the certificate.

3. Once you have imported the certificate, you must restart the service.

   Note

   You must repeat this step on each node when BMC Atrium Single Sign-On is deployed in HA environment.

4. The next step is to update the agent password.
   You must log on to the BMC Atrium SSO Admin Console and specify a new password for the agent in the Agent Editor. For more information about the steps, see Managing agents.

5. After you have updated the password in the BMC Atrium Single Sign-On service, the agents bootstrap information must be updated with this new value. To simplify this process, the bootstrap configuration accepts a plain-text agent password which will be updated to an encrypted value by the agent after startup.

   1. Edit the cfg.properties located in the agent configuration directory with a text editor. Update the agent password key value pair, agentPwd with a new password. For example, the following command illustrates the password updated to the value newpassword: agentPwd=newpassword

   2. In addition to updating the password, add the following command to the file, or update the value to true if it already exists: encodePwd=true

6. Save the changes and restart the agent.

If the agent successfully connects with the BMC Atrium Single Sign-On using the new password value, then the agent will update the cfg.properties file with an encrypted value. After the web application has restarted, check the cfg.properties file to ensure this change has occurred.

Related topic

Configuring a JVM for the Tomcat Server