Configuring Secret Stores

Secret stores are repositories for cryptographic keys and credentials. You can configure them globally, which ensures that all realms inherit your secret store settings. You can also configure secret stores by realm, which allows you to set different secret store settings for each realm.

Since secrets must be shared by all the servers in the site, a good practice is to keep them all under the same directory or mount point, for example, /path/to/openam/security/secrets.

AM provides a keystore and a filesystem secret store by default in new installations, but we recommend that you create your own secret stores in production environments.

AM supports the following secret store types:

  • Environment and System Properties

    AM supports configuring secrets derived from JVM system properties.

  • Keystore

    AM supports a number of different keystore formats, including JCEKS, JKS, PKCS11, and PKCS12.

  • File System Secret Volumes

    AM supports secrets that are stored as files in defined folders. For example, in a cloud deployment you could mount a secret volume that AM can access.

  • Hardware Security Modules (HSM)

    AM supports retrieval of secrets from hardware security modules, either locally or over the network.

  • Google Cloud Key Management Service (KMS)

    AM supports retrieving secrets from the Google Cloud Platform KMS.

Tasks to Configure Secret Stores
TaskResources

Understand How AM Resolves Secrets

Secrets are first resolved at the realm level, and then globally.

Configure Secret Stores

Configure as many secret stores as your environment needs.

Map Secret IDs to Secrets

A number of AM features require the use of secrets for signing and encryption. For each requirement, AM has a secret ID.

You can create active aliases in keystore and HSM secret stores.


Understanding How AM Resolves Secrets

Most secret stores are configured at the global level, by going to Configure > Secret Stores, or at the realm level, by going to Realms > Realm Name > Secret Stores.

Secrets derived from environmental or system properties are configured globally, in a special, persistent secret store.

When resolving secrets, AM will search secret stores in the following order:

  1. Any secret store configured for the realm, regardless of their type.

  2. Any secret store configured globally, regardless of their type.

If AM cannot find the alias, it will log an error and the operation it was trying to do (for example, signing a client-based session token) will fail.

Caution

Map each secret ID once across the secret stores configured for the realm, or globally. For example, in a realm with two secret stores configured (a keystore secret store and a HSM secret store) the am.services.oauth2.jwt.authenticity.signing secret ID is mapped only in the keystore secret store and not in the HSM secret store.

The Environment and System Property Secrets Store

There is a global instance of the Environment and System Property Secrets Store configured at all times. You can access the Environment and System Property Secrets Store globally.

Secrets within the environment and system property secrets store are derived from system properties with the same key as the secret value name (for example, am.services.oauth2.stateless.token.encryption), or as environment variables with keys that have the secret value name in upper case, and with all period characters replaced with underscores (for example, AM_SERVICES_OAUTH2_STATELESS_TOKEN_ENCRYPTION).

AM configures this secret store on startup. Restart AM or the container where it runs to use the new secret mappings.

The only configuration settings that apply for the environment and system property secrets store is the format of the secrets. Secrets that come from this store cannot be rotated, retired (deleted), or removed.

To Configure the Environment and System Property Secrets Store

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. Go to Configure > Secret Stores > Environment and System Property Secrets Store.

  3. From the Value format drop-down list, select one of the following:

    • Plain Text: the secret is provided in UTF-8 encoded text.

    • Base64 encoded: the secret is provided in Base64 encoded binary values.

    • Encrypted text: the plain text secrets are encrypted using AM's encryption key, found at Deployment > Servers > Security > Encryption.

    • Encrypted Base64 encoded: the Base64 encoded binary values are encrypted using AM's encryption key.

    • Encrypted HMAC key: the Base64 encoded binary representation of the HMAC key is encrypted using AM's encryption key.

    • BASE64_HMAC_KEY: the Base64 encoded binary representation of the HMAC key.

  4. Save your changes.

Keystore Secret Stores

A keystore secret store is a secret store that maps to a keystore file, for example, a JKS, JCEKS, PKCS11, or PKCS12 file.

Tip

During installation or after an upgrade from a version of AM earlier than 6.5, AM deploys a number of secret stores. You can use them as an example to configure your own secret stores. For more information, see About the Default Secret Stores.

To Create a Keystore Secret Store

Keystore secret stores can be configured at a global or realm level:

  1. To create on a global level:

    • Go to Configure > Secret Stores.

    To create on a realm level:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, select Keystore.

  5. Enter the keystore file to use.

    This file must be available to all AM instances, for example, by storing it on a shared filesystem, or by copying and maintaining the file across instances.

  6. Select Create.

To Configure a Keystore Secret Store

  1. To configure a global keystore:

    • Go to Configure > Secret Stores.

    To configure a realm keystore:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select the store you want to modify.

  3. Enter the keystore file name in the File field.

  4. Enter the Keystore Type, for example JKS, JCEKS, PKCS11, or PKCS12.

    The specified keystore type must be supported by, and configured in, the local Java runtime environment.

  5. Set the Provider name. If blank, the JRE default will be used.

  6. In the Store password secret ID field, enter the secret ID from which AM will resolve the password that opens the keystore file, or none if the password is blank. For example, storepass.

    AM resolves this secret ID using the other secret stores configured. For example, a file system secret volume secret store mapped to the directory where the file containing the password is stored, or an HSM secret store. For more information about how AM resolves secrets, see "Understanding How AM Resolves Secrets".

  7. In the Entry password secret ID field, enter the secret ID from which AM will resolve the password to the keys stored in the keystore, or none if the password is blank. For example, entrypass.

    AM resolves this secret ID using the other secret stores configured. For example, a file system secret volume secret store mapped to the directory where the file containing the password is stored, or an HSM secret store. For more information about how AM resolves secrets, see "Understanding How AM Resolves Secrets".

  8. Set the Key lease expiry time in minutes.

  9. Save your changes.

File System Secret Volumes Secret Stores

File System Secret Volumes maps to a directory storing files that contain secrets - one secret per file. For a given secret value, file system secret volumes stores will look for a file with the same name as the secret value name, and read its contents using the configured value format. They can be configured at a global and realm level.

Tip

During installation or after an upgrade from a version of AM earlier than 6.5, AM deploys a number of secret stores. You can use them as an example to configure your own secret stores. For more information, see About the Default Secret Stores.

To Create a File System Secret Volume Store

  1. To create on a global level:

    • Go to Configure > Secret Stores.

    To create on a realm level:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, select File System Secret Volumes.

  5. Enter the name of the directory containing the secret files.

    This directory must be available to all AM instances, for example, by converting it to a shared filesystem, or by creating and maintaining it and its files across instances.

  6. Select Create.

To Configure a File System Secret Volume Store

  1. To configure a global file system secret volume store:

    • Go to Configure > Secret Stores.

    To configure a realm file system secret volume store:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select the store you want to modify.

  3. Enter the directory name in the Directory field.

  4. (Optional) Enter a suffix to add to the name of each secret in the File suffix field. For example, .txt.

  5. From the Value format drop-down list, select one of the following:

    • Plain Text: the secret is provided in UTF-8 encoded text.

    • Base64 encoded: the secret is provided in base64-encoded binary values.

    • Encrypted text: the plain text secrets are encrypted using AM's encryption key, found at Deployment > Servers > Security > Encryption.

    • Encrypted Base64 encoded: the base64-encoded binary values are encrypted using AM's encryption key.

    • Encrypted HMAC key: the base64-encoded binary representation of the HMAC key is encrypted using AM's encryption key.

    • Base64 encoded HMAC key: the base64-encoded binary representation of the HMAC key.

    • Encrypted with Google KMS: the secrets are encrypted with a secret stored in the Google Cloud KMS, then base64-encoded.

      See "Using Google Cloud KMS Secrets to Decrypt AM Secrets".

    • Google KMS-encrypted HMAC key: the HMAC key is encrypted with a secret stored in the Google Cloud KMS, then base64-encoded.

      See "Using Google Cloud KMS Secrets to Decrypt AM Secrets".

  6. Save your changes.

    You can now map secret IDs to files stored in the secret store directory. See "To Map Files in File System Secret Volumes Secret Stores".

HSM Secret Stores

An HSM Secret Store maps to a hardware security module. To configure an HSM Secret Store, you need a secret ID that can provide the PIN or password for the HSM, or an extension can be created that provides a Guice binding for a custom PKCS11 java.security.Provider to obtain the keystore.

To Create an HSM Secret Store

HSM Secret Stores can be configured at a global and realm level:

  1. To create on a global level:

    • Go to Configure > Secret Stores.

    To create on a realm level:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, select HSM.

  5. Enter the Configuration File containing initialization configuration for the HSM.

  6. In the Provider Guice Key Name field, enter the name of a Guice key that can be used to obtain an initialized provider from which the HSM keystore can be obtained.

  7. In the HSM PIN/password secret ID field, enter the secret ID from which HSM's PIN or password can be obtained.

    AM resolves this secret ID using the other secret stores configured. For example, a file system secret volume secret store mapped to the directory where the file containing the password is stored, or a keystore secret store. For more information about how AM resolves secrets, see "Understanding How AM Resolves Secrets".

  8. Select Create.

To Configure an HSM Secret Store

  1. To configure a global HSM secret store store:

    • Go to Configure > Secret Stores.

    To configure a realm HSM secret store:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select the store you want to modify.

  3. In the Configuration File field, enter the name of the file containing initialization configuration for the HSM.

  4. In the Provider Guice Key Name field, enter the name of a Guice key that can be used to obtain an initialized provider from which the HSM keystore can be obtained.

  5. In the HSM PIN/password secret ID field, enter the secret ID from which HSM's PIN or password can be obtained.

    AM resolves this secret ID using the other secret stores configured. For example, a file system secret volume secret store mapped to the directory where the file containing the password is stored, or a keystore secret store. For more information about how AM resolves secrets, see "Understanding How AM Resolves Secrets".

  6. Set the Key lease expiry time in minutes.

  7. Save your changes.

Google KMS Secret Stores

You can configure AM to retrieve secrets from the Google Cloud KMS. Support includes:

  • Mapping Google Cloud KMS secrets to secret IDs used for signing and verification purposes. Using Google Cloud KMS secrets as mappings for encryption and decryption secret IDs is not supported.

    For example, mapping a Google Cloud KMS secret to the am.services.oauth2.oidc.signing.RSA secret ID is supported because it is a secret ID used for signing OAuth 2.0 tokens. Mapping a Google Cloud KMS secret to the am.services.oauth2.oidc.decryption.RSA1.5 secret ID is not supported because it is used for decrypting OpenID Connect parameters.

    SHA256WithRSA (RS256)
    SHA512WithRSA (RS512)
    SHA256WithRSAAndMGF1 (PS256)
    SHA512WithRSAAndMGF1 (PS512)
    SHA256WithECDSA (ES256)
    SHA384WithECDSA (ES384)

    Caution

    Signing tokens with Google Cloud KMS secrets is not a fast operation. For every signature request, AM makes an API call to the Google Cloud KMS to perform the signature operation.

    Test the time it would take in your environment to sign tokens under stress conditions to determine if the delay is acceptable. We recommend that you use Google Cloud KMS secrets in environments with a low volume of signatures and high volume of verifications, since AM performs the verification locally.

  • Using a Google Cloud KMS secret to decrypt secrets loaded using other secret stores, or to decrypt the hashed password of the amAdmin user.

Prerequisites

You need a Google Cloud Platform account that has a project. The project must have:

  • A key ring containing the secrets that AM will use. It can be configured in any Google Cloud location.

  • A service account that AM will use to connect to the project.

Refer to the Google Key Management Service documentation and Google's Getting Started with Authentication for more information.


Configuring the Google Service Account Credentials

On a Google Cloud environment, AM uses Google's Java SDK to communicate with the Google Cloud KMS directly. This means that, as long as your Google Cloud environment has a default service account, AM will use it automatically.

If you do not have a default service account or do not want to use it for this purpose, or if you are using Google Cloud KMS secret stores in a non-Google Cloud environment, you must configure the path to the credentials in an environment variable so that AM can use them:

  1. Log in to your Google Cloud Platform Account.

  2. Download the credentials file for the Google service account that AM will use to connect to the project, and store it in the server where AM runs.

  3. Set up the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of the credentials. Ensure that the variable is available to the container where AM runs.

    For example, add the environment variable to the setenv.sh file of your Apache Tomcat installation: 

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/Tomcat/Google-service-account-credentials-for-AM.json"

  4. Restart the container where AM runs.

  5. Perform the steps in this procedure on each of the servers where AM runs.

Creating KMS Secret Stores

Google KMS secret stores can be configured at a global or realm level:

  1. To create on a global level:

    • Go to Configure > Secret Stores.

    To create on a realm level:

    • Go to Realms > Realm Name > Secret Stores.

  2. Select Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, select Google KMS.

  5. In the Project field, enter the Google Cloud Platform project that contains the key ring with the secrets.

    At the time of this writing, you can find your projects by logging in to your Google Cloud Platform dashboard.

  6. Configure the following fields related to the key ring.

    At the time of this writing, you can find the required information by logging in to the Google Cloud Platform dashboard, choosing your project, and then going to > Security > Cryptographic Keys.

    1. In the Location field, enter the location of the key ring.

    2. In the Key Ring field, enter the name of the key ring containing the secrets that AM should use.

  7. Select Create.

    The page of the new secret store appears.

  8. (Optional) Configure the size of the public key cache and its duration as required in your environment.

    When AM signs data with a secret stored in the Google Cloud KMS, it makes an API call to the Google Cloud KMS to perform the signature operation.

    When AM needs to verify a signature, it retrieves the public key from the Google Cloud KMS and verifies the signature locally. The cache prevents AM from retrieving the public key every time, and therefore, speeds the verification process.

    The cache lives in AM's heap and it is created on each of the AM instances for each of the Google Cloud KMS secret stores. We recommend that you leave the default settings unless you have a large number of keys in a key chain.

    Setting a long cache timeout may be more efficient, since AM does not need to contact the Google Cloud KMS to retrieve public keys that often, but note that AM will not detect if you have marked a key as expired in the Google Cloud KMS until the cache expires.

Using Google Cloud KMS Secrets to Decrypt AM Secrets

You can use a Google Cloud KMS secret to decrypt secrets stored in AM secret stores as they are read from the filesystem, environment variables, or system properties.

You can also use the same secret to decrypt the hashed password of the amAdmin user. See "Changing the amAdmin Password (Secret Stores)".

Important

You can only configure one Google Cloud KMS secret for decrypting secrets in the AM site.

This procedure assumes that the encrypted secrets will be stored in a filesystem, and therefore, configured in AM in a file system volume secret store:

  1. Check if you already have a Google Cloud KMS secret for decrypting.

    Go to Configure > Server Defaults >Advanced, and check if the org.forgerock.openam.secrets.googlekms.decryptionkey advanced server property is configured.

    If it is, you do not need to create another key.

    If the property is not configured, log in to your Google Cloud dashboard and create a secret of one of the following types in the key ring of your choosing:

    • Symmetric encrypt/decrypt

    • Asymmetric decrypt

  2. Use the secret you identified or created in the previous step to encrypt the secrets that AM will use.

    You can use the gcloud tool included in Google Cloud's SDK to encrypt the secrets. The tool creates a binary file with the encrypted secret, but AM does not support secrets in binary format. To work around this, base64-encode the encrypted secret. For example: 

    gcloud kms encrypt \
--plaintext-file=./secret.txt \
--ciphertext-file=- \
--project=my_project_ID \
--location=my_location \
--keyring=my_keyring_for_AM \
--key=my_key_for_decrypting_secrets_in_AM | base64 > secret.enc

  3. Rename the files containing the secrets so that they map to the required secret IDs. Use the tables in "Secret ID Default Mappings" for guidance.

    For example, to create a mapping for the Web and Java agents' OAuth 2.0 provider, rename the file containing the relevant secret to a file called am.global.services.oauth2.oidc.agent.idtoken.signing.

    Depending on the configuration of the secret store, you may be able to add a suffix to the file name, such as .enc.

  4. Share the encrypted secrets with the AM servers. This may mean, for example, copying the encrypted files to the same directory in every AM server, or mounting a directory in every AM server that is shared across the instances.

  5. In the AM console, go to Configure > Server Defaults > Advanced.

  6. (Optional) If unset, set the org.forgerock.openam.secrets.googlekms.decryptionkey advanced server property to the fully qualified resource ID of the Google Cloud KMS secret that you used in the previous step. For example: 

    projects/my_project_ID/locations/my_location/keyRings/my_keyring_for_AM/cryptoKeys/my_key_for_decrypting_secrets_in_AM

    For information about how to find the key ID, see Object Hierarchy in the Google Cloud KMS documentation.

  7. Configure the file system volume secret store that points to the directory containing the encrypted secrets. See "To Configure a File System Secret Volume Store".

Read a different version of :