Configuring Secrets, Certificates, and Keys

Encryption makes it possible to protect sensitive data, encoding it in such a way that only authorized parties can access it.

Signing allows the receiver of a piece of data to validate the sender's identity and ensures that the data has not been tampered with.

AM depends on signing and encryption to protect network communication and to keep data confidential and unalterable. In turn, signing and encryption depend on keys or secrets, which are generated using cryptographic algorithms.

AM uses the following methods to store keys or secrets:

  • The AM keystore. Used by some features, it can be configured globally so its configuration is shared by any AM instance in a deployment, or individually per server.

    AM also uses this keystore to start up.

    During installation, AM deploys a JCEKS and a JKS keystore with several self-signed key aliases, for demo and test purposes only.

  • AM secret stores. Introduced in 6.5, secret stores are repositories for cryptographic keys and credentials. They can be configured globally, so the configuration is shared by any instance in the site, or by realm.

    Note

    AM is migrating features from using the AM keystore to use secret stores.

    AM supports configuring JVM system properties, key aliases stored in keystores or HSM, or files stored in filesystems or secret volumes, as secrets.

About the Default Keystores and Secret Stores

During installation, AM deploys a JKS and a JCEKS keystore with several self-signed key aliases for demo and test purposes only.

Both the AM keystore and the default secret stores use the default JCEKS keystore. The JKS keystore is not used by default, and can be safely deleted.

Do not use the default keys, keystores, and secret stores in production environments.

 JCEKSJKS
Used by default in AM? Yes [a] No
In which path is it? /path/to/openam/security/keystores/keystore.jceks/path/to/openam/security/keystores/keystore.jks
Where is its password stored? [b] /path/to/openam/security/secrets/default/.storepass /path/to/openam/security/secrets/default/.storepass
Which test aliases does it contain?

es256test [c]

es384test [c]

es512test [c]

hmacsigningtest [d]

directenctest [e]

rsajwtsigningkey [f]

selfserviceenctest [f]

selfservicesigntest [g]

test [f]

test [f]
Which password strings does it contain?

configstorepwd [h]

dsameuserpwd [i]

None

Where is the private key password file? [j] /path/to/openam/security/secrets/default/.keypass /path/to/openam/security/secrets/default/.keypass

[a] New AM installations use the JCEKS keystore as the default keystore.

[b] The password of the JCEKS and JKS keystores is a random-generated string stored in cleartext.

[c] ECDSA key.

[d] Symmetric HMAC key.

[e] Symmetric Direct AES encryption key.

[f] Asymmetric RSA key.

[g] Symmetric secret signing key.

[h] The value of the configstorepwd is a string. It is the password of the configuration store, which is accessed during AM startup.

[i] The value of the dsameuserpwd is a string. It is the password of a reserved service account, which is accessed during AM startup.

[j] The password for all the key aliases in the JCEKS and JKS keystores is changeit, stored in cleartext.

  • default-keystore. This keystore-type secret store is mapped to the default JCEKS keystore.

    It also contains ID mappings for several of the AM features that use keys.

    For more information about the mappings, see "Secret ID Default Mappings".

  • default-password-store. This filesystem-type secret store is mapped to /path/to/openam/security/secrets/encrypted and it is used to provide the passwords to open the default-keystore secret store:

    • The storepass file contains the encrypted password of the keystore.

    • The entrypass file contains the encrypted password of the keys inside the keystore.

    Note

    This password configuration is very similar to the one for the default JCEKS keystore. However, the files are different. While the password files for the JCEKS are in cleartext, the password files for the default secret store are encrypted with AM's encryption key.

    Take into account that the keystore file is the same, which means that if you change the passwords for the JCEKS keystore, you must change them in the default secret store as well.


Tasks to Configure Keystores and Secret Stores

The provided keystores and secret stores are sufficient for testing and demonstrating AM features.

For production and pre-production environments, configure the keystores and secret stores that your environment will use before configuring the AM features that use them.

High-Level Steps to Configure Keystores and Secret Stores in Production Environments

  1. Create a new keystore to configure as the AM keystore, and delete the default keystores and the default secret stores.

    AM will use the new keystore to start up.

    Configure different keys for different features, when possible.

  2. Create separate secret stores for each AM feature you are using. For example, create one for SAML v2.0 secrets, and a different one for OAuth 2.0 secrets.

    Use different passwords among keystores or secret stores. This will reduce the amount of compromised keys or secrets if a malicious user is able to leverage one of the passwords.

    Keystore secret stores need, at least, another secret store to provide the password of the keystore, and the password for the keys. For example, a file system volume secret store.

  3. Configure AM features to use your custom key aliases and secrets.

The following table guides you through the tasks you need to perform to configure the keys and secrets AM requires:

TaskResources

Understand AM's Secret Needs

Review the list of features that use keys in AM, and their possible keystore and secrets configurations.

Create a new AM Keystore and Configure It

Create and configure a new AM keystore, which will also serve as the AM bootstrap keystore, and delete the default keystores and secret stores.

Create Secrets as Needed

Create as many keystores, key aliases, and/or secrets as required in your environment based on the information you learned when you reviewed the list on the first task. You will configure them in AM in the next steps.

Keys and secrets protect the credentials, tokens, and other sensitive information that your environment needs to send and receive. Therefore, ensure that keys and secrets are protected and only shared when required. This may result in configuring multiple keystores and/or secret stores for different features.

Do not reuse passwords among keystores or secret stores. This will reduce the amount of compromised keys or secrets if a malicious user is able to leverage one of the passwords.

Configure Secret Stores in AM

Create new secret stores to map the relevant new keys you created in previous tasks, for example, those for the OAuth 2.0 providers.

Make Available the Keystores and Secret Stores to All AM Instances

Keystores and secret stores must be available in the same location across of all of the instances.

This step may mean mounting a filesystem with the required files across the instances, installing cryptographic cards, and others, if not done already.

Configure Key Aliases and Secrets in AM

Change the pre-configured key aliases and secrets with those created in the previous tasks.

Read a different version of :