AM 7.2.0

Secret stores

Secret stores are repositories for cryptographic keys and credentials. You can configure secret stores globally or per realm. Secrets in a global secret store are visible to realms, unless the realm has its own secret store with the same secrets defined.

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

AM supports the following secret store types:

A default AM installation includes a keystore-type secret store and a filesystem secret store. These are provided for testing and demonstration purposes only. In production environments, you should create your own secret stores.
Tasks to configure secret stores
Task Resources

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.

How AM resolves secrets

Most secret stores are configured globally, (at Configure > Secret Stores), or per realm (at Realms > Realm Name > Secret Stores).

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

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

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

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

If AM cannot find an alias, it logs an error. The operation being attempted (for example, signing a client-side session token) will then fail.

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 an 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.

Environment and system property secret stores

A global instance of the environment and system property secret store is configured by default.

Secrets in the environment and system property secret store are derived from the following:

  • system properties with the same key as the secret value name (for example, am.services.oauth2.stateless.token.encryption)

  • environment variables with keys that have the secret value name in upper case, and separated by underscores (for example, AM_SERVICES_OAUTH2_STATELESS_TOKEN_ENCRYPTION).

AM configures this secret store each time it starts up. Restart AM, or the container where it runs, if you add or change secret mappings.

Only the secrets format can be configured for the environment and system property secret store. Secrets in this store cannot be rotated, retired (deleted), or removed.

Configure the environment and system property secret store

  1. In the AM admin UI, go to Configure > Secret Stores > Environment and System Property Secrets Store.

  2. From the Value format drop-down list, choose one of the following:

    Secrets supported by the environment and system property secret store
    • 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.

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

    • PEM encoded certificate or key: the Privacy Enhanced Mail (PEM) formatted certificate or key. Commonly used by tools such as OpenSSL, and a large percentage of certificate authorities.

    ForgeRock recommends that you use PEM-formatted secrets.

  3. Click Save.

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.

During installation or after an upgrade from a version of AM earlier than 6.5, AM creates a number of secret stores. You can use them as an example to configure your own secret stores. For more information, see Secrets, certificates, and keys.

Create a keystore secret store

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

  1. To create a global secret store, go to Configure > Secret Stores.

    To create a realm-specific secret store, go to Realms > Realm Name > Secret Stores.

  2. Click Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, choose 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. Click Create.

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. Choose 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 left blank, the JRE default is used.

  6. In the Store password secret ID field, enter the secret ID from which AM will resolve the password to the keystore, or none if the password is blank.

    For example, storepass.

    AM resolves this secret ID using the other secret stores configured; for example, from a file system secret volume mapped to the directory where the file containing the password is stored, or from an HSM secret store.

    For more information, see 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, from a file system secret volume mapped to the directory where the file containing the password is stored, or from an HSM secret store.

    For more information, see How AM resolves secrets.

  8. Set the Key lease expiry time in minutes.

  9. Click Save.

File system secret volumes

A file system secret volume maps to a directory storing files that contain secrets—one secret per file. For a given secret value, file system secret volumes will look for a file with the same name as the secret value name, and read its contents using the configured value format.

File system secret volumes can be configured globally, or per realm.

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 Secrets, certificates, and keys.

Create a file system secret volume

  1. To configure a global file system secret volume, go to Configure > Secret Stores.

    To configure a realm file system secret volume, go to Realms > Realm Name > Secret Stores.

  2. Click Add Secret Store.

  3. Enter the Secret Store ID.

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

  5. Enter the name of the directory that contains 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. Click Create.

Configure a file system secret volume

  1. To configure a global file system secret volume, go to Configure > Secret Stores.

    To configure a realm-specific file system secret volume, go to Realms > Realm Name > Secret Stores.

  2. Choose the store you want to modify.

  3. Enter the directory name in the Directory field.

  4. 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, choose one of the following:

    Secrets supported by the file system secret volume
    • 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.

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

    • PEM encoded certificate or key: the Privacy Enhanced Mail (PEM) formatted certificate or key. Commonly used by tools such as OpenSSL, and a large percentage of certificate authorities.

    ForgeRock recommends that you use PEM-formatted secrets.

  6. Click Save.

    You can now map secret IDs to files stored in the secret store directory. See Map files in file system secret volumes.

Hardware Security Modules (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. Alternatively, create an extension that provides a Guice binding for a custom PKCS11 java.security.Provider to obtain the keystore.

Create an HSM secret store

HSM secret stores can be configured globally or per realm:

  1. To create a global HSM secret store, go to Configure > Secret Stores.

    To create a realm-specific HSM secret store, go to Realms > Realm Name > Secret Stores.

  2. Click Add Secret Store.

  3. Enter the Secret Store ID.

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

  5. Enter the Configuration File containing the 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, see How AM resolves secrets.

  8. Click Create.

Configure an HSM secret store

  1. To configure a global HSM secret store store, go to Configure > Secret Stores.

    To configure a realm-specific HSM secret store, go to Realms > Realm Name > Secret Stores.

  2. Choose 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, see How AM resolves secrets.

  6. Set the Key lease expiry time in minutes.

  7. Click Save.

Google Cloud Key Management Service (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.

    Supported signing algorithms for Google Cloud KMS secrets

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

    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.

Configure Google service account credentials

In 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.

Create 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. Click Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, choose 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.

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

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

  7. Click Create.

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

    Notes about the public key cache
    • 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 is created on each of the AM instances for each of the Google Cloud KMS secret stores. You should leave the default settings, unless you have a large number of keys in a key chain.

    • Setting a long cache timeout might be more efficient, because AM does not need to contact the Google Cloud KMS to retrieve public keys very often.

      Note, however, that AM will not detect if you have marked a key as expired in the Google Cloud KMS until the cache expires.

Use 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 Change the amAdmin password (secret store).

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 admin UI, go to Configure > Server Defaults > Advanced.

  6. 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.

Google Secret Manager (GSM) secret stores

You can configure AM to retrieve secrets from the Google Cloud Secret Manager (GSM).

Prerequisites

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

  • An instance of Secret Manager that contains the secrets you want AM to use.

    Plan ahead how you will name the secrets, and in which format they will be:

    • Each Google GSM secret store can be mapped to one type of secret. ForgeRock recommends that you use PEM-formatted secrets in GSM to make the configuration easier to maintain.

      For more information on how to create PEM secrets compatible with AM, see Import PEM-formatted keys.

    • By default, AM let all realms access all the secrets related to a GSM instance. However, you can configure lists of patterns to match the GSM secrets that a realm, or a list of realms, can access.

      For example, if you prefix the secrets for the employees realm with emp., you can configure a pattern in AM, such as emp.*, to match them for that realm.

      This is also useful to separate secrets by type, if you are not using PEM secrets.

  • A Google Cloud Compute Engine default service account, (only if AM runs in Google Cloud), or a service account.

    You can create different realm and pattern maps with the same account, if needed.

Related Google Documentation

Configure service accounts for GSM

Before configuring the Google GSM secret store, review the configuration of the Google service accounts in AM and make changes as required:

  1. Go to Configure > Global Services > Google Cloud Platform Service Accounts.

    The Service page displays a secondary configuration named default. AM is preconfigured to use a Google Cloud Compute Engine default service account.

    This default account is also configured to let all realms access all the secrets related to a GSM instance.

    If you are not using a Google Cloud Compute Engine default service account, you can delete this configuration. Alternatively, you can reconfigure it, or create a new configuration.

    Why is it useful to have several secondary configurations?

    The Google Cloud Platform Service Accounts service lets you map Google service accounts with realms. It also lets you configure patterns of secrets allowed and disallowed for a particular map of account and realms.

    For example, you can create several secondary configurations that use the same Google account, but that map different realms to different secrets.

  2. Decide whether you will reconfigure the default secondary configuration, or if you will create a new one to add a new service account.

    1. If you decided to create a new secondary configuration to add a new service account, click Add a Secondary Configuration.

      Name it, and leave the rest of the fields empty. You will configure them later.

    2. If you decided to reconfigure the default secondary configuration, click on it.

  3. On the secondary Configuration page, determine whether you need to configure the Credentials Secret ID field:

    On a Google Cloud environment, AM uses Google’s Java SDK to communicate with Google Secret Manager directly. This means that, as long as your Google Cloud environment has a Cloud Compute Engine default service account, AM will use it automatically. In this case, leave the Credentials Secret ID field blank.

    If you do not have a Cloud Compute Engine default service account or do not want to use it for this purpose, or if you are using Google GSM secret stores in a non-Google Cloud environment, you must configure AM to pick up the service account’s credentials.

    To do so, configure a file system volume secret store to provide the account’s credentials to AM.

    Next, enter the secret ID mapped to the account’s credentials in the Credentials Secret ID field.

    Map credentials to a file system secret store
    1. Log in to your Google Cloud Platform Account.

    2. Download the credentials JSON file for the Google service account that AM will use to connect to the project.

      Note that this procedure uses file system secret stores to provide the account’s secret to AM, but you can use any other suitable secret store.

    3. Ensure that the file name only contains alphanumeric characters and period (.) characters.

      For example, GSM.123.json.

      Other characters, such as hyphens (-), are not supported in the file name.

    4. Make the JSON file or its contents available across the AM environment.

      This may mean, for example, mounting the same directory across different servers, copying the file across to the same location in each server, or configuring it as a Kubernetes secret.

    5. Create a file system secret store that points to the directory containing the JSON file.

      Ensure that you configure it as follows:

      • Directory = /path/to/JSON/File

      • File Suffix = .json

      • File Format = Plain text

    6. Save your changes.

    7. In the Credentials Secret ID field, enter the name of the JSON file that contains the secret, without the extension.

      For example, for a file named GSM.123.json, you would enter GSM.123.

  4. In the Allowed Realms field, configure a list of realms allowed to use this service account.

    Enter a list of realms and subrealms, such as / /realm1 /realm2/subrealm1 /realm3, or use the wildcard (*) character to allow all realms in the deployment to use the account.

    Note that you need to press the enter key after each item on the list.

  5. In the Allowed Secret Names field, enter a list of patterns to match the GSM secrets that the configured realms can access.

    Use the wildcard (*) character to match portions of the secret names.

    For example, alpha*, or alpha*123.

    Note that you need to press the enter key after each item on the list.

  6. In the Disallowed Secret Names field, enter a list of patterns to match the GSM secrets that the configured realms cannot access, if required.

    Use the wildcard (*) character to match portions of the secret names.

    For example, development*, or secure*abc.

    Note that you need to press the enter key after each item on the list.

    For a secret to be accessed, it must match a pattern in the Allowed Secret Names field, and no patterns in the Disallowed Secret Names field.

Create a GSM secret store

GSM 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.

    Secrets mapped in a global secret store are available in every realm.

  2. Choose Add Secret Store.

  3. Enter the Secret Store ID.

  4. From the Store Type drop-down list, choose Google Secret Manager.

  5. In the Project field, enter the Google Cloud Platform project that contains the Secret Manager instance.

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

    Click Create.

  6. In the GCP Service Account ID field, enter the name of a Google Cloud Platform Service Accounts service secondary configuration.

    For example, default.

    For more information, see Configure service accounts for GSM.

  7. In the Secret Format field, enter the format of the secrets to extract from Google Secret Manager.

    Secrets supported by the GSM secret store
    • 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.

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

    • PEM encoded certificate or key: the Privacy Enhanced Mail (PEM) formatted certificate or key. Commonly used by tools such as OpenSSL, and a large percentage of certificate authorities.

    Configure a Google GSM secret store for each type of secret that you want to map.

    ForgeRock recommends that you use PEM secrets to store your secrets.

  8. In the Expiry Time field, enter the maximum time, in seconds, that AM will cache a value retrieved from Google Secret Manager.

    Setting a long cache timeout may be more efficient, since AM does not need to contact Google Secret Manager to retrieve secrets that often, but AM will not detect if you have marked a secret as expired in Google Secret Manager until the cache expires.

  9. Save your changes.

    Now you are ready to map secret IDs.

Custom secret stores

If you are creating custom components or plugins, you can implement the SecretStore interface to create a custom secret store backend.

Provide the configuration for your secret store type using one of the following subclasses:

Then, pass this class to the installSecretStoreTypes method in your plugin.

Copyright © 2010-2022 ForgeRock, all rights reserved.