Mapping and Rotating Secrets

1. To map secrets within a global secret store:

   • Navigate to Configure > Secret Stores.

   To map secrets within a realm secret store:

   • Navigate to Realms > Realm Name > Secret Stores.

2. Select the store that contains the secrets you want to map.

3. On the Mappings tab, select Add Mapping.

4. From the Secret ID drop-down list, select the Secret ID that is to be associated to an alias.

   For information about the different secret ID mappings, see "Secret ID Default Mappings".

5. Enter any Alias and click the add () icon.

   You can add as many aliases as necessary. The first alias in the list determines which alias is the active one. Active secrets are used for signature generation and encryption, while the non-active secrets are used for signature verification and decryption.

   Tip

   When configuring mappings for a Google KMS secret store, map one secret for each secret ID, and manage key rotation in the Google Cloud KMS key ring.

6. Drag and drop to change the order of aliases, and set which alias is active.

7. If an alias is considered no longer secure, it can be retired by clicking the delete () icon.

8. Once your mappings are complete, select Create.

File system secret volumes secret stores do not allow rotating or retiring secrets through mappings like other stores do.

To map secret IDs to files, perform the following steps:

1. Change paths to the directory configured in the secret store. For example, change paths to /openam/secrets.

2. Create the required files to store your secrets using the tables in "Secret ID Default Mappings" for guidance, and leave them empty.

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

   You may also create mappings for secret store-specific secrets, such as the keystore secret store password, the keystore secret store entry password, or the HSM guice key. These mappings do not require specific secret IDs. For example, you can create a file called mykeystorepassword, and then configure it in the Store password secret ID field of your keystore secret store.

   The name of a secret ID—and therefore the file names given to file system secrets—must consist of only alphanumeric characters and periods(.). The names cannot start or end with periods, or have more than one period in a row.

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

3. Store the relevant secret value in each file.

   The format of the secret value depends on the configuration of the secret store. For example, if you have configured File Format to be Encrypted text, you must encode the secret value with AM's encryption key.

   How Do I Encode Secrets With AM's Encryption Key?

   Use the https://openam.example.com:8443/openam/encode.jsp page to encode the secret, then add the encoded value to the secret file.

   Ensure that secrets do not contain trailing new line characters. If you are using the echo command to add secrets to a file, append the -n option. For example:

   $ echo -n AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K \
   > am.global.services.oauth2.oidc.agent.idtoken.signing