PingAM 7.5.0

Configure secret stores after upgrade

AM 6.5 introduced secret stores, which are repositories of cryptographic keys, key pairs, and credentials.

  • The upgrade process does not create all the demo key aliases created during a fresh install. This includes, for example, the aliases required for the IoT service. If you want to use services that require these demo aliases, add the corresponding keys and mappings after you have upgraded.

  • Although the configuration for secret stores is available to any upgraded server in the site, the upgrade process only creates the relevant secret store files on the AM instance where you run the upgrade process.

Follow these steps to make the secret stores available to other servers in the site:

Redeploy secret stores to a site after upgrade

You can reconfigure the secret stores and their mappings after upgrade. However, we recommend that you follow the steps in this procedure to ensure all secrets are available to all the instances in the site, and later on, you make additional changes to your environment.

The upgrade process creates several secret stores, globally and by realm, depending on the features configured in AM, and depending on the version you are upgrading from:

  1. Go to Configuration > Secret Stores, and review the global secret stores created for your environment.

    Reference: Global secret stores created after upgrade
    Upgrade from AM 6 or earlier

    • default-keystore: a keystore-type secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process.

    • default-passwords-store: A filesystem secret store configured as the /path/to/openam/security/secrets/encrypted directory.

      This directory contains the secrets to open the keystore configured in the default-keystore, and its keys.

    • UpgradeGlobalSecrets: A filesystem secret store configured as the /path/to/openam/security/secrets/encrypted/encrypted_hmac_key directory.

      This directory contains the secrets used for the OAuth 2.0 server and the Persistent Cookie module.

    Upgrade from AM 6.5 or earlier

    • default-keystore: a keystore-type secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process.

    • saml2-metadata-signing-keystore: A keystore secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process.

    • default-encrypted_base64-store: A file system volume secret store that contains SAML v2.0 secrets that are base64-encrypted.

    • default-encrypted_plain-store: A file system volume secret store configured as the directory containing secrets related to the saml2-metadata-signing-keystore store.

      The directory contains the password that was configured in the Metadata signing key password field of the global SAML v2.0 Service Configurations service.

      It also contains the password files related to the default-keystore store if the default-passwords-store store does not exist.

    • Ensure that the keystores configured exist on the other servers within the site. You may need to copy the keystores across or make them available in some other way.

    • Ensure that directories configured in file system secret stores and their content exist on the other servers within the site. You may need to copy the directories across or make them available in some other way.

  2. Go to Realms > Realm Name > Secret Stores, and perform the same actions you took for the global secret stores.

    Reference: Realm-based secret stores created after upgrade

    Realm-based secret stores are created for those features that supported different keystore configurations by realm; for example, SAML v2.0, or the persistent cookie module.

    To find the realm-based secret stores, go to Realms > Realm Name > Secret Stores. The secrets themselves are stored in the /path/to/openam/security/secrets/realms/root/realm-name/secret-store-name directory.

    If you have upgraded from a version which had SAML v2.0 Service Configurations at realm level, the upgrade process creates realm-level secret stores for the Metadata signing key alias field and its key, if they were configured.

    Repeat this step for each of the realms you have configured.

  3. Deploy the new AM .war file on the rest of the AM servers.

  4. When the site is up, and before opening the service to end users, review the secret label mappings of the new secret stores and change them as required.

    For example, the upgrade process may have created secret stores for features you aren’t using. These secret stores may have mappings to secrets that don’t exist. It’s advisable to remove unused secret mappings in production environments.

    For details of the available secret labels, refer to Secret label default mappings.

    Reference: SAML v2.0 mappings after upgrade

    AM is flexible regarding the configuration of secrets for SAML v2.0. Therefore, migrating the different combinations may create a high number of secret labels in your environment.

    As a rule of thumb, AM configures providers that were using the same key aliases in the same order, to use the same secret labels. If this rule can’t be satisfied, the upgrade process creates new secret labels for the provider by assigning it a secret label identifier.

    If you have upgraded from a version which had SAML v2.0 Service Configurations, AM maps the am.services.saml2.metadata.signing.RSA secret label to the alias taken from the relevant Metadata signing key alias property of the service, either from the global service, or the realm-level services.