Managing the AM Keystore

By default, AM installations provide a JCEKS keystore containing several test-only key aliases that are preconfigured in AM.

For production deployments, generate a new keystore with the key aliases you need to use.

Considerations Before You Start

Different AM features support different keystore configurations, and some features do not use the default keystore to store their key aliases. For more information, see "Features in AM That Use Keys".
Key aliases are not migrated from one keystore to another when changing the keystore configuration in AM. You must prepare the new keystore as required before configuring it.
You must restart AM if you make any changes to the keystore. Changes are, for example, adding or removing keys or changing key or keystore passwords.

Tasks:

To create a new AM keystore, see "To Replace the AM Keystore".
To modify the AM keystore configuration without changing the content of the file, see "To Modify the AM Keystore Properties".

To Replace the AM Keystore

The AM keystore provides secrets to several features of AM, as explained in "Features in AM That Use Keys", but it also but it also lets AM start up.

The AM Keystore as the Bootstrap Keystore

The AM startup process checks a file, called boot.json, that contains the settings AM requires to bootstrap. Among these settings are the path to a keystore file and the files containing the keystore and key passwords.

During the startup process, AM needs to find the following aliases inside the keystore configured in the /path/to/openam/config/boot.json file:

About the dsameuserpwd and the configstorepwd Aliases

configstorepwd

An alias for the password of the AM configuration store. The alias is password-protected, with the password specified by default in the /path/to/openam/security/secrets/default/.keypass file.

To update the value of this alias, go to Deployment > Servers > Server Name > Directory Configuration, and modify the configuration store bind password. Every time you change the bind alias, AM modifies the content of the key alias in the keystore file.

dsameuserpwd

An alias for the password of a special user required at AM startup time. The alias is password-protected, with the password specified by default in the /path/to/openam/security/secrets/default/.keypass file.

These strings cannot be recreated manually, but AM will recreate them in a new keystore after a successful start.

The key to successfully changing the AM/bootstrap keystore is to configure the new AM keystore, and restart AM while the old keystore is still accessible. The boot process will use the original keystore for booting up, write the password strings in the new keystore, and rewrite the boot.json file.

Follow the steps in this procedure to create a new AM/bootstrap keystore.

Perform the steps in this procedure to create a new keystore containing the password strings that AM needs to start up, and configure it as the new AM keystore:

Ensure that AM is running, and that you can access its console as an administrative user.
Acquire a new key from your certificate authority and add it to a new keystore, or generate a new self-signed key in a new keystore.
Create the keystore in a directory of your choosing. This directory should be the same for all the instances on the site. For example, /path/to/openam/security/keystores.
This example creates a self-signed key alias in a new keystore file, am_keystore.jceks, with a new asymmetric RSA key alias, newkey.
Note than in production environments, you should use the strongest algorithm you can.
```
$ keytool \
-genkeypair \
-alias newkey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=newkey' \
-keystore am_keystore.jceks
Enter keystore password:
Reenter new password:
Enter key password for <newkey>
(RETURN if same as keystore password):
Reenter new password:
```
Take note of the passwords you entered.
Store the keystore passwords in cleartext in a directory of your choosing.
This directory should be the same for all the instances on the site. For example, /path/to/openam/security/secrets/default.
For example:
```
$ echo -n newstorepassword > .am_keystore_storepass
$ echo -n newkeypassword > .am_keystore_keypass
```
Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command is able to use the password in the file, AM may not be able to open the keystore or the key aliases.
Make sure the password files have read-only permission for their owner. For example:
```
$ chmod 400 .am_keystore_storepass
$ chmod 400 .am_keystore_keypass
```
Configure the new keystore as the AM keystore in the site. Follow the steps in "To Modify the AM Keystore Properties".
Once AM starts, the new keystore contains the password strings that AM uses to start up. You can delete the default JCEKS keystore now. The default secret stores also use the JCEKS keystore. You can also delete them now.

To Modify the AM Keystore Properties

To modify the AM keystore configuration, perform the following steps:

In the AM console, go to Configure > Server Defaults > Security > Key Store.
Enter the keystore file name and path in the Keystore File field. For example, /path/to/openam/security/keystores/am_keystore.jceks.
Enter the Keystore Type. For example JKS, JCEKS, PKCS11, or PKCS12.
In the Keystore Password File field, enter the location of the keystore password file. For example, /path/to/openam/security/secrets/default/.am_keystore_storepass.
In the Private Key Password File field, enter the location of the private key password file. For example, /path/to/openam/security/secrets/default/.am_keystore_keypass.
Save your changes.
At this point, AM still holds the old keystore configuration in memory, and cannot use key aliases contained in the new keystore.
(Optional) If you need to change key aliases in the AM configuration, decide whether to change them before or after restarting the AM instances in the next step.
If you are using client-based sessions, ensure the signing key exists in the new keystore. You can check the configuration for client-based sessions by going to Realms > Realm Name > Authentication > Settings > Security.
To configure the rest of the features that need key aliases before or after the restart, see "Changing Default Key Aliases".
Make the new keystore files available in the same location to all the instances in the site.
This step may mean mounting a filesystem with the required files across the instances, copying the files across instances, and others.
Restart the AM instance or instances.
The new default keystore and its keys are ready to use.