Secrets, certificates, and keys

Encryption lets you protect sensitive data, encoding it in such a way that only authorized parties can access it.

Signing lets the receiver of data validate the sender’s identity and ensures that the data hasn’t 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 that are generated using cryptographic algorithms.

AM uses the following methods to store keys or secrets:

The AM keystore

The default AM keystore is used by certain features, and during AM startup.

You can configure the default keystore globally, so its configuration is shared by all AM instances in a deployment, or per individual server.

AM secret stores

Secret stores are repositories for cryptographic keys and credentials. You can configure them globally, or per realm.

Secret stores can be JVM system properties, key aliases stored in keystores or HSMs, or files stored in filesystems or secret volumes.

Most AM features use the secrets API (secret stores). Using the traditional AM keystore for these features isn’t supported. You can, however, define the AM keystore in a secret store and continue to use the keys inside it.

Default keystores and secret stores

During installation, AM creates a JKS and a JCEKS keystore with several self-signed certificates for demo and test purposes.

The AM keystore and the default keystore-type secret store use the JCEKS keystore. The JKS keystore isn’t used by default and can be safely deleted.

Don’t use the default keys, keystores, and secret stores in production environments.

Default JCEKS and JKS keystores

This table lists the contents of the default keystores, generated when AM starts up.

JCEKS JKS

	JCEKS	JKS
Used by default in AM?	Yes⁽¹⁾	No
Default path	`/path/to/openam/security/keystores/keystore.jceks`	`/path/to/openam/security/keystores/keystore.jks`
Where is its password stored?⁽²⁾	`/path/to/openam/security/secrets/default/.storepass`	`/path/to/openam/security/secrets/default/.storepass`
Which test aliases does it contain?	`es256test` (ECDSA key) `es384test` (ECDSA key) `es512test` (ECDSA key) `hmacsigningtest` (Symmetric HMAC key) `directenctest` (Symmetric Direct AES encryption key) `rsajwtsigningkey` (Asymmetric RSA key) `selfserviceenctest` (Asymmetric RSA key) `selfservicesigntest` (Symmetric secret signing key) `test` (Asymmetric RSA key)	`test` (Asymmetric RSA key)
Which password strings does it contain?	`configstorepwd`⁽³⁾ `dsameuserpwd`⁽⁴⁾	None
Where is the private key password file?⁽⁵⁾	`/path/to/openam/security/secrets/default/.keypass`	`/path/to/openam/security/secrets/default/.keypass`

Used by default in AM?

Yes⁽¹⁾

Default path

/path/to/openam/security/keystores/keystore.jceks

/path/to/openam/security/keystores/keystore.jks

Where is its password stored?⁽²⁾

/path/to/openam/security/secrets/default/.storepass

Which test aliases does it contain?

es256test (ECDSA key)
es384test (ECDSA key)
es512test (ECDSA key)
hmacsigningtest (Symmetric HMAC key)
directenctest (Symmetric Direct AES encryption key)
rsajwtsigningkey (Asymmetric RSA key)
selfserviceenctest (Asymmetric RSA key)
selfservicesigntest (Symmetric secret signing key)
test (Asymmetric RSA key)

test (Asymmetric RSA key)

Which password strings does it contain?

configstorepwd⁽³⁾
dsameuserpwd⁽⁴⁾

None

Where is the private key password file?⁽⁵⁾

/path/to/openam/security/secrets/default/.keypass

⁽¹⁾ New AM installations use the JCEKS keystore as the default keystore.

⁽²⁾ The password of the JCEKS and JKS keystores is a random-generated string stored in cleartext.

⁽³⁾ The value of the configstorepwd is a string. It is the password of the configuration store, which is accessed during AM startup.

⁽⁴⁾ The value of the dsameuserpwd is a string. It is the password of a reserved service account, which is accessed during AM startup.

⁽⁵⁾ The default password for all the key aliases in the JCEKS and JKS keystores is changeit, stored in cleartext.

Default secret stores

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

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

default-password-store. This filesystem-type secret store is mapped to /path/to/openam/security/secrets/encrypted

It provides 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.

These password files look similar to those of the default JCEKS keystore, but, while the password files for the JCEKS keystore 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. Therefore, if you change the passwords for the JCEKS keystore, you must also change them in the default secret store.

Configure keystores and secret stores

The default 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 needs, before you configure the AM features that use them.

Keystores and secret stores in production

Create a new keystore to use as the AM keystore. 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.
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 for keystores and secret stores. This reduces the risk of compromised keys or secrets if a malicious user is able to gain access to one of the passwords.

Keystore secret stores require at least one other secret store to provide the password of the keystore, and the password for the keys. For example, a file system volume secret store.
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:

Task	Resources
Understand AM’s secret needs Review the list of features that use keys in AM, and their possible keystore and secrets configurations.	AM features that use keys
Create and configure a new AM keystore Create and configure a new AM keystore, that will also serve as the AM bootstrap keystore. Delete the default keystores and secret stores.	The AM keystore
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. Don’t reuse passwords between keystores or secret stores. This reduces the risk of compromised keys or secrets, if a malicious user is able to gain access to one of the passwords.	Key aliases and passwords
Configure secret stores in AM Create new secret stores to map the new keys you created in previous tasks, for example, those for the OAuth 2.0 providers.	Secret stores
Make keystores and secret stores available to all AM instances	Keystores and secret stores must be available in the same location across all AM instances. This step might mean mounting a filesystem with the required files across the instances, installing cryptographic cards, and so on.
Configure key aliases and secrets in AM Change the default key aliases and secrets to the new ones you have created.	Change default key aliases Map and rotate secrets

Task

Resources

Understand AM’s secret needs

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

AM features that use keys

Create and configure a new AM keystore

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

The AM keystore

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.

Don’t reuse passwords between keystores or secret stores. This reduces the risk of compromised keys or secrets, if a malicious user is able to gain access to one of the passwords.

Key aliases and passwords

Configure secret stores in AM

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

Secret stores

Make keystores and secret stores available to all AM instances

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

This step might mean mounting a filesystem with the required files across the instances, installing cryptographic cards, and so on.

Configure key aliases and secrets in AM

Change the default key aliases and secrets to the new ones you have created.

AM 7.3.1

Secrets, certificates, and keys

Default keystores and secret stores

Default JCEKS and JKS keystores

Default secret stores

Configure keystores and secret stores