Access Management 7.3.1

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. Once the site is up, and before opening the service to the end users, review the secret ID mappings of the new secret stores and make changes to them as you see fit.

    For example, the upgrade process may have created stores for features you are not using. Those may have mappings to secrets that do not exist, and you may want to remove them in production environments.

    For more information about the available secret IDs, see Secret ID Default Mappings.

    Reference: SAML v2.0 mappings after upgrade

    AM has always been very flexible regarding the configuration of secrets for SAML v2.0; this is why migrating the different combinations may create a high number of secret IDs 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 IDs. If this rule cannot be satisfied, the upgrade process creates new secretIDs for the provider by assigning it a secret ID 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 ID 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.