---
title: Map and rotate secrets
description: Several AM features require secrets for signing and encryption. For each requirement, AM has a specific secret ID.
component: pingam
version: 7.4
page_id: pingam:security:secret-mapping
canonical_url: https://docs.pingidentity.com/pingam/8.1/security/secret-mapping.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Security", "Setup & Configuration"]
page_aliases: ["security-guide:secret-mapping.adoc"]
superseded_by: https://docs.pingidentity.com/pingam/8.1/security/secret-mapping.html
section_ids:
  create-mappings: Map secrets in keystore, HSM, or Google KMS/GSM secret stores
  creating-mappings-FS: Map files in file system secret volumes
  secret-id-mappings: Secret ID default mappings
  general-default-secret-IDs: General
  oauth2-default-secret-IDs: OAuth 2.0 and OpenID Connect as provider
  oidc-social-registration-secret-IDs: OAuth 2.0 and OpenID Connect as client/relying party of the Social Identity Provider service
  agents-default-secret-IDs: Web agents and Java agents
  authentication-default-secret-IDs: Authentication
  saml2-default-secret-IDs: SAML 2.0
  iot-default-secret-IDs: IoT
  attestation-secret-IDs: Attestation certificates
---

# Map and rotate secrets

Several AM features require secrets for signing and encryption. For each requirement, AM has a specific *secret ID*.

To provide AM with the correct secret, map one or more aliases from the secret stores you configure to each of the secret IDs. These mappings let you specify the active secrets, and rotate them when they expire or become compromised. For a list of secret IDs and their default mappings, see [Secret ID default mappings](#secret-id-mappings).

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 ID drop-down list, choose the secret ID that you want to associate with an alias.

   For information about the different secret ID mappings, [Secret ID default mappings](#secret-id-mappings).

5. Enter any Alias and click the add ([icon: plus, set=fa]) icon.

   You can add as many aliases as necessary. The first alias in the list determines the active secret. Active secrets are used for signature generation and encryption. Non-active secrets are used for signature verification and decryption.

   |   |                                                                                                                                                                                                            |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | When you configure mappings for a Google KMS or a Google GSM secret store, map only *one* secret for each secret ID and manage key rotation in the Google Cloud KMS key ring, or in Google Secret Manager. |

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

7. If a secret is considered no longer secure, retire it by clicking the delete ([icon: times, set=fa]) icon.

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

## Map files in file system secret volumes

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

To map secret IDs 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 ID default mappings](#secret-id-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 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 include 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`. |

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 you have configured File Format to be `Encrypted text`, you must encode the secret value with AM's encryption key.

   > **Collapse: 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:```bash
   $ echo -n AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K > am.global.services.oauth2.oidc.agent.idtoken.signing
   ``` |

## Secret ID default mappings

The following groups contain the secret IDs used by the AM features, and their default mappings, if any. Expand the categories for additional information about where or how the mappings are used.

### General

> **Collapse: Secret ID for PEM decryption password**
>
> The following table shows the secret ID in which you can store the password used to decrypt password-encrypted PEM files.
>
> Encode the password using the `https://openam.example.com:8443/openam/encode.jsp` page.
>
> | Secret ID                                  | Default alias | Algorithms                |
> | ------------------------------------------ | ------------- | ------------------------- |
> | `am.global.services.secret.pem.decryption` |               | Encode using `encode.jsp` |

> **Collapse: Secret ID mappings for encrypting client-side sessions**
>
> The following table shows the secret ID mapping to use when encrypting [client-side](../am-sessions/client-based-sessions.html) sessions:
>
> | Secret ID                                           | Default alias | Algorithms |
> | --------------------------------------------------- | ------------- | ---------- |
> | `am.global.services.session.clientbased.encryption` | `test`        | RS256      |
>
> To use AES-based encryption algorithms, configure the secret in the Encryption Symmetric AES Key field in Configure > Global Services > Sessions > Advanced.

> **Collapse: Secret ID mappings for signing client-side sessions**
>
> The following table shows the secret ID mapping to use when signing [client-side](../am-sessions/client-based-sessions.html) sessions:
>
> | Secret ID                                        | Default alias      | Algorithms              |
> | ------------------------------------------------ | ------------------ | ----------------------- |
> | `am.global.services.session.clientbased.signing` | `rsajwtsigningkey` | RS256 ES256 ES384 ES512 |
>
> To use HMAC-based signing algorithms, configure the secret in the Signing HMAC Shared Secret field in Configure > Global Services > Sessions > Advanced.

### OAuth 2.0 and OpenID Connect as provider

> **Collapse: Secret ID mappings for JWT authenticity signing**
>
> The following table shows the secret ID mapping used to sign several OAuth 2.0 and OpenID Connect-related JWTs:
>
> | Secret ID                                     | Default alias     | Algorithms        |
> | --------------------------------------------- | ----------------- | ----------------- |
> | `am.services.oauth2.jwt.authenticity.signing` | `hmacsigningtest` | HS256 HS384 HS512 |
>
> |   |                                                                                                                                                                                                                                                                                                          |
> | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
> |   | This key is used to sign the following tokens and requests:- OpenID Connect tokens for web and Java agents.
>
> - OpenID Connect tokens that are signed with an HMAC algorithm.
>
> - Macaroon access and refresh tokens.
>
> - Consent requests to remote consent agents that are signed with an HMAC algorithm. |

> **Collapse: Secret ID mappings for encrypting client-side OAuth 2.0 tokens**
>
> This table shows the secret ID mapping used to encrypt [client-side](../am-oauth2/stateless-stateful-tokens.html#client-side-tokens) access tokens:
>
> | Secret ID                                       | Default alias   | Algorithms    |
> | ----------------------------------------------- | --------------- | ------------- |
> | `am.services.oauth2.stateless.token.encryption` | `directenctest` | A128CBC-HS256 |

> **Collapse: Secret ID mappings for signing client-side OAuth 2.0 tokens**
>
> This table shows the secret ID mappings used to sign [client-side](../am-oauth2/stateless-stateful-tokens.html#client-side-tokens) access tokens:
>
> | Secret ID                                    | Default alias      | Algorithms                          |
> | -------------------------------------------- | ------------------ | ----------------------------------- |
> | `am.services.oauth2.stateless.signing.ES256` | `es256test`        | ES256                               |
> | `am.services.oauth2.stateless.signing.ES384` | `es384test`        | ES384                               |
> | `am.services.oauth2.stateless.signing.ES512` | `es512test`        | ES512                               |
> | `am.services.oauth2.stateless.signing.HMAC`  | `hmacsigningtest`  | HS256 HS384 HS512                   |
> | `am.services.oauth2.stateless.signing.RSA`   | `rsajwtsigningkey` | PS256 PS384 PS512 RS256 RS384 RS512 |

> **Collapse: Secret ID mappings for signing remote consent requests**
>
> The following table shows the secret ID mappings used to sign remote consent requests:
>
> | Secret ID                                                     | Default alias      | Algorithms(1)                       |
> | ------------------------------------------------------------- | ------------------ | ----------------------------------- |
> | `am.applications.agents.remote.consent.request.signing.ES256` | `es256test`        | ES256                               |
> | `am.applications.agents.remote.consent.request.signing.ES384` | `es384test`        | ES384                               |
> | `am.applications.agents.remote.consent.request.signing.ES512` | `es512test`        | ES512                               |
> | `am.applications.agents.remote.consent.request.signing.RSA`   | `rsajwtsigningkey` | RS256 RS384 RS512 PS256 PS384 PS512 |
>
> (1) If you select an HMAC algorithm for signing consent requests (HS256, HS384, or HS512), the value of the Remote Consent Service secret property is used, instead of an entry from the secret stores.
>
> Since the HMAC secret is shared between AM and the remote consent client, a malicious user compromising the client could potentially create tokens that AM would trust. Therefore, to protect against misuse, AM also signs the token using a non-shared signing key configured in the `am.services.oauth2.jwt.authenticity.signing` secret ID.

> **Collapse: Secret ID mappings for decrypting remote consent responses**
>
> The following table shows the secret ID mapping used to decrypt remote consent responses:
>
> | Secret ID                                               | Default alias | Algorithms(1) |
> | ------------------------------------------------------- | ------------- | ------------- |
> | `am.services.oauth2.remote.consent.response.decryption` | `test`        | RSA-OAEP-256  |
>
> (1) If you select an algorithm other than RSA-OAEP-256 for decrypting consent responses, the value of the Remote Consent Service secret property is used, instead of an entry from the secret stores.

> **Collapse: Secret ID mappings for the OAuth 2.0 example Remote Consent service**
>
> The following table shows the secret ID mappings used for the example Remote Consent service:
>
> | Secret ID                                                | Default alias        | Algorithms                            |
> | -------------------------------------------------------- | -------------------- | ------------------------------------- |
> | `am.services.oauth2.remote.consent.response.signing.RSA` | `rsajwtsigningkey`   | RS256 RSA (at least 2048 bits)        |
> | `am.services.oauth2.remote.consent.request.encryption`   | `selfserviceenctest` | RSA-OAEP-256 RSA (at least 2048 bits) |

> **Collapse: Secret ID mappings for decrypting OpenID Connect request parameters**
>
> The following table shows the secret ID mapping used to decrypt OpenID Connect request parameters:
>
> | Secret ID                                         | Default alias | Algorithms(1)                        |
> | ------------------------------------------------- | ------------- | ------------------------------------ |
> | `am.services.oauth2.oidc.decryption.RSA1.5`       | `test`        | RSA with PKCS#1 v1.5 padding         |
> | `am.services.oauth2.oidc.decryption.RSA.OAEP`     | `test`        | RSA with OAEP with SHA-1 and MGF-1   |
> | `am.services.oauth2.oidc.decryption.RSA.OAEP.256` | `test`        | RSA with OAEP with SHA-256 and MGF-1 |
>
> (1) The following applies to confidential clients only:
>
> If you select an AES algorithm (A128KW, A192KW, or A256KW) or the direct encryption algorithm (dir), the value of the Client Secret field in the OAuth 2.0 Client is used as the secret instead of an entry from the secret stores.
>
> The following signing and encryption algorithms use the Client Secret field to store the secret:
>
> * Signing ID tokens with an HMAC algorithm
>
> * Encrypting ID tokens with AES or direct encryption
>
> * Encrypting parameters with AES or direct encryption
>
> Store only one secret in the Client Secret field; AM will use different mechanisms to sign and encrypt depending on the algorithm, as explained in the OpenID Connect Core 1.0 errata set 1 specification.

> **Collapse: Secret ID mappings for signing OpenID Connect tokens**
>
> The following table shows the secret ID mapping used to sign OpenID Connect ID tokens and backchannel logout tokens:
>
> | Secret ID                               | Default alias      | Algorithms(1)                       |
> | --------------------------------------- | ------------------ | ----------------------------------- |
> | `am.services.oauth2.oidc.signing.ES256` | `es256test`        | ES256                               |
> | `am.services.oauth2.oidc.signing.ES384` | `es384test`        | ES384                               |
> | `am.services.oauth2.oidc.signing.ES512` | `es512test`        | ES512                               |
> | `am.services.oauth2.oidc.signing.RSA`   | `rsajwtsigningkey` | PS256 PS384 PS512 RS256 RS384 RS512 |
> | `am.services.oauth2.oidc.signing.EDDSA` |                    | EdDSA with SHA-512                  |
>
> (1) The following applies to confidential clients only:
>
> If you select an HMAC algorithm for signing ID tokens (HS256, HS384, or HS512), the Client Secret property value in the OAuth 2.0 Client is used as the HMAC secret instead of an entry from the secret stores.
>
> Since the HMAC secret is shared between AM and the client, a malicious user compromising the client could potentially create tokens that AM would trust. Therefore, to protect against misuse, AM also signs the token using a non-shared signing key configured in the `am.services.oauth2.jwt.authenticity.signing` secret ID.

> **Collapse: Secret ID mappings for CA certificates used in mTLS client authentication**
>
> The following table shows the secret ID mapping used to store the CA certificates AM should trust during mTLS client authentication:
>
> | Secret ID                                           | Default alias | Algorithms |
> | --------------------------------------------------- | ------------- | ---------- |
> | `am.services.oauth2.tls.client.cert.authentication` |               |            |

### OAuth 2.0 and OpenID Connect as client/relying party of the Social Identity Provider service

> **Collapse: Secret ID mappings for decrypting ID tokens**
>
> The following table shows the secret ID mapping to support decryption of ID tokens and `userinfo` endpoint data in JWT format when AM is configured as a relying party of the Social Identity Provider Service:
>
> | Secret ID                                       | Default alias | Algorithms                                                   |
> | ----------------------------------------------- | ------------- | ------------------------------------------------------------ |
> | `am.services.oauth2.oidc.rp.idtoken.encryption` | `test`        | Consult the `.well-known` endpoint of the identity provider. |
>
> The public key is exposed in the [/oauth2/connect/rp/jwk_uri](../am-oidc1/managing-rp-jwk_uri.html).
>
> For more information about the algorithms supported, and how to configure this secret ID mapping, refer to [Social authentication](../am-authentication/social-registration.html).

> **Collapse: Secret ID mappings for signing JWTs and objects**
>
> The following table shows the secret ID mapping that AM uses to sign JWTs and objects when configured as a relying party of the Social Identity Provider Service:
>
> | Secret ID                                             | Default alias      | Algorithms                                                   |
> | ----------------------------------------------------- | ------------------ | ------------------------------------------------------------ |
> | `am.services.oauth2.oidc.rp.jwt.authenticity.signing` | `rsajwtsigningkey` | Consult the `.well-known` endpoint of the identity provider. |
>
> The public key is exposed in the [/oauth2/connect/rp/jwk_uri](../am-oidc1/managing-rp-jwk_uri.html).
>
> For more information about the algorithms supported, and how to configure this secret ID mapping, refer to [Social authentication](../am-authentication/social-registration.html).

> **Collapse: Secret ID mappings for CA certificates used in mTLS client authentication**
>
> The following table shows the secret ID mapping used to store CA or self-signed certificates AM uses for mTLS client authentication when configured as a relying party of the Social Identity Provider service:
>
> | Secret ID                                           | Default alias | Algorithms                                                   |
> | --------------------------------------------------- | ------------- | ------------------------------------------------------------ |
> | `am.services.oauth2.tls.client.cert.authentication` |               | Consult the `.well-known` endpoint of the identity provider. |
>
> The public key is exposed in the [/oauth2/connect/rp/jwk_uri](../am-oidc1/managing-rp-jwk_uri.html).
>
> For more information about the algorithms supported, and how to configure this secret ID mapping, refer to [Social authentication](../am-authentication/social-registration.html).

### Web agents and Java agents

> **Collapse: Secret ID mappings for the agents' OAuth 2.0 provider**
>
> The following table shows the secret ID mapping used sign the JWTs provided to web and Java agents:
>
> | Secret ID                                              | Default alias      | Algorithms        |
> | ------------------------------------------------------ | ------------------ | ----------------- |
> | `am.global.services.oauth2.oidc.agent.idtoken.signing` | `rsajwtsigningkey` | RS256 RS384 RS512 |

### Authentication

> **Collapse: Secret ID mappings for persistent cookies**
>
> The following table shows the secret ID mappings used to encrypt and then sign persistent cookies:
>
> | Secret ID                                                       | Default alias     | Algorithms               |
> | --------------------------------------------------------------- | ----------------- | ------------------------ |
> | `am.default.authentication.modules.persistentcookie.encryption` | `test`            | RSA (at least 2048 bits) |
> | `am.default.authentication.modules.persistentcookie.signing`    | `hmacsigningtest` | HS256                    |
>
> For each instance of a persistent cookie module available in a realm, there is a dynamic secret ID associated with that module configuration instance.
>
> For example, in a single realm you can have a Persistent Cookie module instance with the name *helloworld*, and a separate Persistent Cookie module instance with the name *hellomars*.
>
> The following secret ID mappings could be used to encrypt and then sign persistent cookies:
>
> | Secret ID                                                          | Default alias           |
> | ------------------------------------------------------------------ | ----------------------- |
> | `am.authentication.modules.persistentcookie.helloworld.encryption` | `helloworld`            |
> | `am.authentication.modules.persistentcookie.helloworld.signing`    | `hmacsigninghelloworld` |
> | `am.authentication.modules.persistentcookie.hellomars.encryption`  | `hellomars`             |
> | `am.authentication.modules.persistentcookie.hellomars.signing`     | `hmacsigninghellomars`  |
>
> AM will attempt to look up the secrets with the Persistent Cookie module instance name. If unsuccessful, AM will look up the secrets using the default secret ID.

> **Collapse: Secret ID mappings for encrypting authentication trees' secure state data**
>
> The following table shows the secret ID mapping used to encrypt sensitive data stored in the secure state of an authentication tree:
>
> | Secret ID                                  | Default alias   | Algorithms  |
> | ------------------------------------------ | --------------- | ----------- |
> | `am.authn.trees.transientstate.encryption` | `directenctest` | AES 256-bit |

### SAML 2.0

> **Collapse: Secret ID mappings for encrypting SAML 2.0 session storage JWTs**
>
> The following table shows the secret ID mapping used to encrypt the JWTs SAML 2.0 creates in session storage:
>
> | Secret ID                                                | Default alias   | Algorithms |
> | -------------------------------------------------------- | --------------- | ---------- |
> | `am.global.services.saml2.client.storage.jwt.encryption` | `directenctest` | A256GCM    |

> **Collapse: Secret ID mappings for signing SAML 2.0 metadata**
>
> The following table shows the secret ID mappings used to sign SAML 2.0 metadata:
>
> | Secret ID                                | Default alias      | Algorithms  |
> | ---------------------------------------- | ------------------ | ----------- |
> | `am.services.saml2.metadata.signing.RSA` | `rsajwtsigningkey` | RSA SHA-256 |

> **Collapse: Secret ID mappings for SAML 2.0 signing and encryption**
>
> The following table shows the secret ID mappings used to sign and encrypt SAML 2.0 elements:
>
> | Secret ID                                                                  | Default alias      | Algorithms                                                                                             |
> | -------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
> | `am.default.applications.federation.entity.providers.saml2.idp.encryption` | `test`             | RSA with PKCS#1 v1.5 padding RSA with OAEP                                                             |
> | `am.default.applications.federation.entity.providers.saml2.idp.signing`    | `rsajwtsigningkey` | RSA SHA-1(1) ECDSA SHA-256 ECDSA SHA-384 ECDSA SHA-512 RSA SHA-256 RSA SHA-384 RSA SHA-512 DSA SHA-256 |
> | `am.default.applications.federation.entity.providers.saml2.sp.encryption`  | `test`             | RSA with PKCS#1 v1.5 padding RSA with OAEP                                                             |
> | `am.default.applications.federation.entity.providers.saml2.sp.signing`     | `rsajwtsigningkey` | RSA SHA-1(1) ECDSA SHA-256 ECDSA SHA-384 ECDSA SHA-512 RSA SHA-256 RSA SHA-384 RSA SHA-512 DSA SHA-256 |
>
> (1) This algorithm is for compatibility purposes only, and its use should be avoided.
>
> You can specify a custom secret ID identifier for each hosted SAML 2.0 entity provider in a realm, which creates new secret IDs. These secret IDs can be unique to the provider, or shared by multiple providers.
>
> For example, you could add a custom secret ID identifier named *mySamlSecrets* to a hosted identity provider.
>
> AM dynamically creates the following secret IDs, which the hosted identity provider uses for signing and encryption:
>
> * `am.applications.federation.entity.providers.saml2.mySamlSecrets.signing`
>
> * `am.applications.federation.entity.providers.saml2.mySamlSecrets.encryption`
>
> AM will attempt to look up the secrets with the custom secret ID identifier. If unsuccessful, AM will look up the secrets using the default secret IDs.

### IoT

> **Collapse: Secret ID mappings for the IoT trusted JWT issuer**
>
> The following table shows the secret ID mapping that the IoT service uses when configured as a trusted OAuth 2.0 JWT issuer:
>
> | Secret ID                            | Default alias     | Algorithms |
> | ------------------------------------ | ----------------- | ---------- |
> | `am.services.iot.jwt.issuer.signing` | `hmacsigningtest` | HS256      |

> **Collapse: Secret ID mappings for IoT certificate verification**
>
> The following table shows the secret ID mapping for the CA certificate that the [Register Thing node](https://docs.pingidentity.com/auth-node-ref/7.4/self-managed/register-thing.html) uses to verify the X.509 digital certificate included in the proof-of-possession JWT:
>
> | Secret ID                           | Default alias | Algorithms |
> | ----------------------------------- | ------------- | ---------- |
> | `am.services.iot.cert.verification` |               |            |

### Attestation certificates

> **Collapse: Google hardware attestation root certificate**
>
> This table shows the ID for the Google hardware attestation root certificate.
>
> This certificate is used to confirm the keys used by bound Android devices are valid, have not been revoked, and use hardware-backed security storage.
>
> Refer to [Verifying hardware-backed key pairs with Key Attestation](https://developer.android.com/training/articles/security-key-attestation#root_certificate) in the Android developer documentation.
>
> | Secret ID                                   | Default alias | Algorithms  |
> | ------------------------------------------- | ------------- | ----------- |
> | `am.services.attestation.google.public.key` |               | RSA / X.509 |