The AM keystore

AM provides a JCEKS keystore by default, containing several test-only key aliases. For production deployments, you should create a new keystore with your own key aliases.

Before you start, note the following points about the AM keystore:

Different AM features support different keystore configurations. Some features don’t use the default keystore to store their key aliases. For more information, see AM features that use keys.
Key aliases aren’t migrated from one keystore to another. You must prepare a new keystore before you configure it, then migrate the required key aliases manually.
If you make any changes to the keystore, such as adding or removing keys or changing key or keystore passwords, you must restart AM.
All passwords for Java keystores (keystore passwords, entry passwords, and key passwords) can contain only ASCII characters. Using non-ASCII characters in these passwords results in errors.

Replace the AM keystore

The AM keystore provides the secrets required by several features, but it also lets AM start up.

About the bootstrap keystore

The AM startup process checks a file (/path/to/openam/config/boot.json), for the bootstrap settings. These settings include the path to a keystore file, and the files containing the keystore and key passwords. For example:

{
  "instance" : "http://am.example.com:8080/am",
  "dsameUser" : "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org",
  "keystores" : {
    "default" : {
      "keyStorePasswordFile" : "/path/to/am/security/secrets/default/.storepass",
      "keyPasswordFile" : "/path/to/am/security/secrets/default/.keypass",
      "keyStoreType" : "JCEKS",
      "keyStoreFile" : "/path/to/am/security/keystores/keystore.jceks"
    }
  },
  "configStoreList" : [ {
    "baseDN" : "dc=openam,dc=forgerock,dc=org",
    "dirManagerDN" : "cn=Directory Manager",
    "ldapHost" : "am.example.com",
    "ldapPort" : 50636,
    "ldapProtocol" : "ldaps"
  } ]
}

The dsameUser is an internal account that AM uses to connect to the configuration store. AM generates the password for this account on startup and you can’t read or change it.

AM looks for the configuration store password (configstorepwd) in the default keystore specified in the boot.json file. The alias is password-protected with the password specified in the /path/to/openam/security/secrets/default/.keypass file.

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

You can’t create this string manually. AM recreates it in a new keystore after a successful start.

To change the bootstrap keystore, configure a new AM keystore and restart AM while the old keystore is still available. The startup process does the following:

Boots up using the original keystore
Writes the password string in the new keystore
Rewrites the boot.json file.

Follow these steps to create a new keystore with the password strings AM needs to start up, and configure it as the default AM keystore:

Ensure that AM is running, and that you can access the AM admin UI as an administrative user.
Create a new keystore in any writable directory. This directory must be the same for all AM instances in the site, for example, /path/to/openam/security/keystores.
Obtain a new key from your certificate authority and add it to the new keystore, or generate a new self-signed key in the new keystore.

This example creates a self-signed key alias in a new keystore file, am_keystore.jceks, with a new asymmetric RSA key alias, newkey.

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 writable directory.

This directory should be the same for all AM instances in 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 might not be able to open the keystore or the key aliases.
Make sure that 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 Change AM keystore properties.

When AM starts successfully, 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.

Change AM keystore properties

In the AM admin UI, 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.
Click Save Changes.

At this point, AM still holds the old keystore configuration in memory, and cannot use key aliases contained in the new keystore.
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-side sessions, ensure the signing key exists in the new keystore. You can check the configuration for client-side 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 Change 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.

PingAM 7.5.0

The AM keystore

Replace the AM keystore

Change AM keystore properties