PingAM

Map and rotate secrets

Several AM features require secrets for signing, encryption, and mTLS authentication. For each requirement, AM has a specific secret label.

To provide AM with the correct secret, map one or more aliases from the secret stores you configure to each secret label. These mappings let you specify the active secrets, and rotate them when they expire or become compromised. You can find a list of secret labels and their default mappings in Secret label default mappings.

In previous AM releases, secret labels were referred to as secret IDs. This term is being phased out in favor of secret label but you might come across instances of secret ID in the documentation and in the UI until the terminology change is complete.

AM uses active secrets for signature generation, encryption, verification, and decryption. AM uses non-active secrets for signature verification and decryption. For example, if you map several aliases for signing OAuth 2.0 client-side tokens, new tokens are signed with the active secret, and incoming tokens are verified against both the active and the non-active secrets.

Only one secret can be active for a specific secret label mapping.

You can rotate a non-active secret to become an active secret (while the old secret remains valid). You can also retire a secret if it’s no longer considered secure.

Map secrets in keystore, HSM, or Google KMS/GSM secret stores

  1. To map secrets in a global secret store, go to Configure > Secret Stores.

    To map secrets in a realm-specific secret store, go to Realms > realm name > Secret Stores.

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

  3. On the Mappings tab, click Add Mapping.

  4. From the Secret Label drop-down list, select the secret label you want to associate with an alias.

    Find information about the different secret label mappings in Secret label 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 the active secret. AM uses active secrets for signature generation and encryption. AM uses non-active secrets for signature verification and decryption.

  6. When you have completed the mappings, click Create.

Rotate secrets in keystore and HSM secret stores

  1. To rotate secrets in a global secret store, go to Configure > Secret Stores.

    To rotate secrets in a realm-specific secret store, go to Realms > realm name > Secret Stores.

  2. Click the store that contains the secrets you want to rotate.

  3. On the Mappings tab, add a new secret alias, if necessary.

  4. Drag and drop to change the order of aliases, and set the active secret.

  5. If a secret is no longer secure, retire it by clicking the delete () icon.

  • For Google KMS and Google GSM secret stores, map only one secret to each secret label. Manage key rotation in the Google Cloud KMS key ring or Google Secret Manager.

  • Some features have a signing algorithm or encryption algorithm configuration option, and a corresponding rotatable secret for signing, encryption and verification. PingAM may enforce that the signature being verified was signed with the same algorithm specified in the configuration. Therefore, rotation between secrets with different algorithm types is not supported.

Map secrets in file system secret volumes

To map secret labels to files, follow these steps:

  1. In the directory configured as the secret store, for example, /openam/secrets, create the required files to store your secrets. Use the tables in Secret label default mappings for guidance.

    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 can 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 don’t require specific secret labels. For example, you can create a file called mykeystorepassword, and then configure it in the Store password secret label field of your keystore secret store.

    Secret labels and the filenames of file system secrets have the following constraints:

    • They can only include alphanumeric characters and periods (.).

    • They can’t start or end with a period, or have more than one period in a row.

    • Depending on the configuration of the secret store, you may be able to add the filename extension to a secret filename; for example, .txt.

    • Secret filenames can include a version suffix to support secret rotation; for example, .vversion where version is a positive integer. Learn more about configuring the version suffix in Create a file system secret volume.

  2. 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 the File Format is 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.

    Secrets must not contain trailing newline 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

Rotate and retire secrets in file system secret volumes

File system secrets can include a version suffix that lets you maintain multiple versions of a secret. With multiple secret versions, you can rotate and retire secrets, as necessary.

Define the version suffix in the file system secret volume configuration. For example, specifying a version suffix of .v lets you append .vversion to secret files, where version is any positive integer.

With a version suffix of .v AM would recognize the following secrets as valid secrets: secret.name.v1, secret.name.v2, secret.name.v3. This lets you rotate secrets with no disruption in service.

To retire a secret, make sure you have a new version of the secret, then delete that secret version from the file system.