AM 7.3.1

Key aliases and passwords

You might need to create new key aliases because you are using additional AM features, or because you are installing a new environment. In either case, consider these points:

  • First, review the list of AM features to understand which features use the AM keystore and which ones do not.

    For more information, see AM features that use keys.

  • Avoid sharing certificates between features when possible, even if this means you need to configure multiple different keystores or secret stores.

  • Make sure keystores, key aliases, and certificates are maintained on every instance; in a site environment, every instance has its own keystore files.

  • Make sure keystores and secret stores are in the same location across all instances in the site.

The following table lists the tasks related to managing key aliases in your environment:

Task Resources

Create a new key alias in an existing keystore or in a new keystore.

Create key aliases

Copy key aliases between keystores; for example, when configuring IDM’s provisioning.

Copy key aliases between keystores

Change key alias passwords.

Change key alias passwords

Change keystore passwords.

Change keystore passwords

Create key aliases

Several AM features require key aliases for signing and encryption. AM provides default key aliases for all features, but you should create new key aliases in production.

You can create key aliases in a new keystore that will be configured later as the AM keystore, or you can create key aliases in the existing AM keystore:

Create a keystore and key aliases for keystore-type secret stores

These instructions are for keystore-type secret stores. To create a new AM keystore, refer to The AM keystore instead.

  1. Obtain a new key from your certificate authority and add it to a new keystore, or generate a self-signed key in a new keystore.

    This example creates an assymetric key pair and self-signed certificate, with alias newkey in a new keystore file named keystoreA.jceks. The RSA algorithm is used to generate the key pair.

    In production environments you should use the strongest possible algorithm. 
    $ cd /path/to/openam/security/keystores/
$ keytool \
-genkeypair \
-alias newkey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=newkey' \
-keystore keystoreA.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 need to make them available within another secret store; for example, by using a file system volume secret store, as shown below:

    • Go to the directory that the filesystem volume secret store will point to.

      For example, /path/to/openam/security/secrets/mydir.

      You can use different methods to encode the content of the files. Consider creating a directory for each encoding method you plan to use.

    • Create two files, one for the keystore password, and another for the password of the keys inside the keystore.

      The files will contain the encoded passwords expected by the file system secret volume store.

      For example, if you chose Base64 encoded as the encoding, you must base64-encode the passwords, and then add them to their respective files.

      For example:

      $ echo -n bmV3c3RvcmVwYXNzd29yZA== > keystoreA_storepass
$ echo -n bmV3a2V5cGFzc3dvcmQ= > keystoreA_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 keystoreA_storepass
$ chmod 400 keystoreA_keypass

  2. Create any other keys and keystores required by your environment by repeating the steps in this procedure and/or following the steps in Create key aliases in an existing keystore.

  3. Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.

  4. Configure the keystore in a keystore-type secret store.

    See Keystore secret stores.

    To configure the file system secret store too, see File system secret volumes.

Create key aliases in an existing keystore

Perform the following steps to create new key aliases in an existing keystore. For example, the AM keystore:

  1. Change directories to the keystore location, for example, /path/to/openam/security/keystores/.

  2. Acquire a new key from your certificate authority, or generate a new self-signed key.

    When you create or import a new key, the keytool command adds the new alias to the specified keystore if it exists, or creates a new keystore if it does not exist.

    This example creates a self-signed key alias in the AM keystore, am_keystore.jceks, with a new asymmetric RSA key alias called mynewkey.

    Note than in production environments you should use the strongest algorithm you can use.

    $ cd /path/to/openam/security/keystores/
$ keytool \
-genkeypair \
-alias mynewkey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=mynewkey' \
-keystore am_keystore.jceks
Enter keystore password: Enter the password in the .keystore_storepass file.
Enter key password for <mynewkey> (RETURN if same as keystore password): Enter the password in the .keystore_keypass file.
Reenter new password: Enter the password in the .keystore_keypass file.

    Remember:

    • The contents of the password files of the AM keystore are in cleartext.

    • The contents of the password files in a file system volume secret store are not in cleartext by default. This means that you need to decode them before you can use them in the keytool command.

  3. Ensure that password files and keystores are maintained on every instance in your environment.

    Every AM instance has its own keystores and password files.

  4. (AM keystore) Restart the AM instances affected by the configuration changes to use the new key aliases.

  5. Configure the new key aliases in AM.

    For a list of features that use key aliases and links to their relevant sections, see AM features that use keys.

Create self-service key aliases

User self-service requires a key pair for encryption and a signing secret key to be available in the AM keystore before configuring any of its features. Follow the steps in this procedure to create new key aliases for the user self-service features in the AM keystore:

  1. Acquire a new key from your certificate authority, or generate new self-signed keys.

    The password of the new keys for the user self-service features must match the passwords of those keys already present in the keystore, and configured in the /path/to/openam/security/secrets/default/.am_keystore_keypass file.

    This example generates a self-signed key for encryption and a new signing secret key in the am_keystore.jceks keystore, but you could also import CA-provided keys to the keystore.

    • Create the new self-signed encryption key alias:

      $ cd /path/to/openam/security/keystores/
$ keytool \
-genkeypair \
-alias newenckey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=newenckey' \
-keystore am_keystore.jceks
Enter keystore password: Enter the password in the .am_keystore_storepass file.
Enter key password for <newenckey> (RETURN if same as keystore password): Enter the password in the .am_keystore_keypass file.
Reenter new password: Enter the password in the .am_keystore_keypass file.

    • Create the new signing secret key alias:

      $ cd /path/to/openam/security/keystores/
$ keytool \
-genseckey \
-alias newsigkey \
-keyalg HmacSHA256 \
-keysize 256 \
-storetype JCEKS \
-keystore am_keystore.jceks
Enter keystore password: Enter the password in the .am_keystore_storepass file.
Enter key password for <newsigkey> (RETURN if same as keystore password): Enter the password in the .am_keystore_keypass file.
Reenter new password: Enter the password in the .am_keystore_keypass file.

  2. Ensure that password files and keystores are maintained on every instance in your environment.

    Every AM instance has its own keystores and password files.

  3. Restart the AM instances affected by the configuration changes.

  4. Configure user self-service to use the new keys.

    For instructions, refer to Create a user self-service instance.

Copy key aliases between keystores

Some AM features require access to the key aliases used by other components of the ForgeRock Identity Platform. For example, the IDM Provisioning feature requires access to the key aliases that IDM uses to sign and encrypt data.

This section covers copying key aliases from the keystore of a ForgeRock Identity Platform component to AM’s default keystore.

  1. Use the keytool command to export the required key from the source keystore into a temporary keystore:

    $ keytool -importkeystore -srcstoretype jceks -srcalias "myKeyAlias" \
-deststoretype jceks -destalias "myKeyAlias" \
-srckeystore "/path/to/openidm/security/keystore.jceks" \
-destkeystore "/path/to/openidm/security/temp_keystore.jceks" \
-srckeypass "changeit" \
-srcstorepass "changeit" \
-destkeypass "myT3mPK3yP4ssword" \
-deststorepass "myT3mPK3yP4ssword"

    This command exports the myKeyAlias key alias, specified by the srcalias argument, to a temporary keystore file /path/to/openidm/security/temp_keystore.jceks. The store and key password is set to myT3mPK3yP4ssword. You need to use the temporary passwords when importing to the AM instance.

  2. Move the temporary keystore file created in the previous step, in this example temp_keystore.jceks, to the filesystem of the target AM server.

  3. On the target AM server, import the key alias into the AM keystore:

    $ keytool -importkeystore -srcstoretype jceks -srcalias "myKeyAlias" \
-deststoretype jceks -destalias "myKeyAlias" \
-srckeystore "/path/to/openam/security/keystores/temp_keystore.jceks" \
-destkeystore "/path/to/openam/security/keystores/am_keystore.jceks" \
-srckeypass "myT3mPK3yP4ssword" \
-srcstorepass "myT3mPK3yP4ssword" \
-destkeypass:file "/path/to/openam/security/secrets/default/.am_keystore_keypass" \
-deststorepass:file "/path/to/openam/security/secrets/default/.am_keystore_storepass"

    This command imports the key alias from the temporary temp_keystore.jceks keystore file, which was copied from the IDM instance, into the AM keystore. The command also sets the passwords to match those used by the default AM keystore.

  4. Repeat the previous steps to copy any additional key aliases from the source keystore to the destination keystore.

  5. Restart the AM instance for the key change to take effect.

    The AM instance will now be able to correctly encrypt, decrypt, sign or verify data and share it with the source ForgeRock Identity Platform component.

Change key alias passwords

Decrypting a key alias in a keystore requires a password. This password is initially specified when you generate the key, or when you import the key into a keystore, but you might need to update the password at a later time.

  1. Back up your keystore and password files.

  2. Depending on the location of the key alias whose password you are changing, perform one of the following steps:

    1. To change the password that opens the AM keystore:

      Replace the old password in the .am_keystore_keypass file with the new one:

      $ echo -n newpassword > /path/to/openam/security/secrets/default/.am_keystore_keypass

      Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command can use the password in the file, AM may not be able to use the key aliases if there are hidden, trailing, newline characters in the password file.

    2. To change the password that opens a secret store:

      Replace the old password in the secret containing it with the new one. If the secret is a file in a file system volume secret store, ensure that the new password is encoded appropriately.

      For example, for base64-encoded passwords, use the following command:

      $ echo -n bmV3a2V5cGFzc3dvcmQ= > keystoreA_keypass

    3. To change a password value used to decrypt a PEM-formatted secret:

      Encode the new password using the https://openam.example.com:8443/openam/encode.jsp page, and write the result to a file system secret or environment variable that uses the am.global.services.secret.pem.decryption secret ID:

      • File system secret

      • Environment variable

      $ echo -n AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K > am.global.services.secret.pem.decryption
      $ export AM_GLOBAL_SERVICES_SECRET_PEM_DECRYPTION=AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K

  3. Depending on the location of the secret, perform one of the following steps to update the secret’s password to match the value you configured in the previous step:

    1. To change the password of key aliases in the AM Keystore:

      Use the keytool command to change the password of each of the key aliases, for example:

      $ keytool -keypasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/am_keystore.jceks -alias mykey
Enter keystore password: Enter the password in the .am_keystore_storepass file
New key password for <mykey> Enter the password in the .am_keystore_keypass file
Re-enter new key password for <mykey> Enter the password in the .am_keystore_keypass file

      Remember to change the passwords of the configstorepwd and the dsameuserpwd aliases. Failure to do so will render AM unbootable.

      You can list the keys and password strings contained in the AM keystore using this command:

      $ keytool -list -storetype JCEKS -keystore /path/to/openam/security/keystores/am_keystore.jceks

    2. To change the password of key aliases in a secret store:

      Use the keytool command to change the password of each of the key aliases, for example:

      $ keytool -keypasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks -alias mykey
Enter keystore password: Enter the password in the keystoreA_storepass file
New key password for <mykey> Enter the password in the keystoreA_keypass file
Re-enter new key password for <mykey> Enter the password in the keystoreA_keypass file Remember

      Secrets in file system volume secret stores are, by default:

      $ `keytool -keypasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks -alias mykey
Enter keystore password: Enter the password in the keystoreA_storepass file
New key password for <mykey> Enter the password in the keystoreA_keypass file
Re-enter new key password for <mykey> Enter the password in the keystoreA_keypass file

      Secrets in file system volume secret stores are, by default, not in cleartext. You need to decode them before using them with the keytool command.

      You can list the keys and password strings contained in a secret store using this command:

      $ keytool -list -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks

    3. To change the password of a PEM-formatted secret:

      Use the openssl command to open, and then export the secret alias with a new password:

      $ openssl rsa -aes256 -in originalkey.pem -out new_password_key.pem
Enter pass phrase for originalkey.pem: Enter the original password
writing RSA key
Enter PEM pass phrase: Enter the new password
Verifying - Enter PEM pass phrase: Re-enter new password
      The algorithm you specify must match the input PEM file.

      When completed, overwrite the original PEM file with the replacement, for example:

      $ mv new_password_key.pem originalkey.pem

  4. If you also need to change the keystore password, see Change keystore passwords.

  5. Ensure that password files and keystores are maintained on every instance in your environment.

    Every AM instance has its own keystores and password files.

  6. (AM keystore) Restart the AM instances affected by the configuration changes.

Change keystore passwords

Decrypting and viewing the contents of a keystore requires a password. This password is specified by the user at the time the keystore is created, but you might need to update the password at a later time.

  1. (AM keystore) Replace the old password in the .am_keystore_storepass file with the new one:

    $ echo -n newpassword > /path/to/openam/security/secrets/default/.am_keystore_storepass

    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 use the key aliases if there are hidden trailing newline characters in the password file.

  2. (Secret stores) Replace the old password in the secret containing it with the new one.

    If the secret is a file in a file system volume secret store, ensure that the new password is encoded appropriately.

    For example, base64-encode the password, and add it to the file:

    $ echo -n bmV3c3RvcmVwYXNzd29yZA== > keystoreA_storepass

  3. Change the password of the keystore:

    • AM keystore

    • Secret stores

    $ keytool -storepasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/am_keystore.jceks
Enter keystore password: Enter the password in the .am_keystore_storepass file.
New keystore password: Enter the new password.
Re-enter new keystore password:
    $ keytool -storepasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks
Enter keystore password: Enter the password in the keystoreA_storepass file.
New keystore password: Enter the new password.
Re-enter new keystore password:

    Secrets in file system volume secret stores are, by default, not in cleartext. You need to decode them before using them with the keytool command.

  4. If you also need to change the key aliases' password, see Change keystore passwords.

  5. Ensure that password files and keystores are maintained on every instance in your environment.

    Each AM instance has its own keystores and password files.

  6. (AM keystore only) Restart the AM instance or instances affected by the configuration changes.

Copyright © 2010-2024 ForgeRock, all rights reserved.