Mapping and Rotating Secrets

Several AM features require the use of secrets for signing and encryption. For each requirement, AM has a secret ID. To provide AM with the required secret, map one or more aliases from the secret stores you configure to each of the secret IDs. These mappings allow you to choose which is the active aliases, and rotate them when they become expired or compromised.

For a list of secret IDs and their default mappings, see "Secret ID Default Mappings".

Active aliases are used for signature generation and encryption, while the non-active aliases are used for signature verification and decryption. An non-active alias can be rotated to become the active alias, while the old alias will still remain valid. Non-active secrets are mainly used for signature verification and decryption. A secret can be retired when it is no longer considered secure.

For example, if you mapped several aliases for signing OAuth 2.0 client-based tokens, new tokens are signed with the active secret, and incoming tokens are verified against both the active and the non-active secrets.

To Map Aliases in Keystore, HSM, or Google KMS/GSM Secret Stores

  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 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 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.

To Map Files in File System Secret Volumes Secret Stores

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.

    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

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

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 IDDefault AliasAlgorithms
am.global.services.secret.pem.decryptionEncode using encode.jsp

The following table shows the secret ID mapping to use when encrypting client-based sessions:

Secret IDDefault AliasAlgorithms
am.global.services.session.clientbased.encryptiontest
RS256

To use AES-based encryption algorithms, configure the secret in the Encryption Symmetric AES Key field in Configure > Global Services > Sessions > Advanced.

The following table shows the secret ID mapping to use when signing client-based sessions:

Secret IDDefault AliasAlgorithms
am.global.services.session.clientbased.signingrsajwtsigningkey
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

The following table shows the secret ID mapping used to sign several OAuth 2.0 and OpenID Connect-related JWTs:

Secret IDDefault AliasAlgorithms
am.services.oauth2.jwt.authenticity.signinghmacsigningtest
HS256
HS384
HS512

Note

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.

The following table shows the secret ID mapping used to encrypt client-based access tokens:

Secret IDDefault AliasAlgorithms
am.services.oauth2.stateless.token.encryptiondirectentestA128CBC-HS256

The following table shows the secret ID mappings used to sign client-based access tokens:

Secret IDDefault AliasAlgorithms
am.services.oauth2.stateless.signing.ES256es256testES256
am.services.oauth2.stateless.signing.ES384es384testES384
am.services.oauth2.stateless.signing.ES512es512testES512
am.services.oauth2.stateless.signing.HMAChmacsigningtest
HS256
HS384
HS512
am.services.oauth2.stateless.signing.RSArsajwtsigningkey
PS256
PS384
PS512
RS256
RS384
RS512

The following table shows the secret ID mappings used to sign remote consent requests:

Secret IDDefault AliasAlgorithms [a]
am.applications.agents.remote.consent.request.signing.ES256es256testES256
am.applications.agents.remote.consent.request.signing.ES384es384testES384
am.applications.agents.remote.consent.request.signing.ES512es512testES512
am.applications.agents.remote.consent.request.signing.RSArsajwtsigningkey
RS256
RS384
RS512
PS256
PS384
PS512

[a] 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.

The following table shows the secret ID mapping used to decrypt remote consent responses:

Secret IDDefault AliasAlgorithms[a]
am.services.oauth2.remote.consent.response.decryptiontestRSA-OAEP-256

[a] 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.

The following table shows the secret ID mappings used for the example Remote Consent Service:

Secret IDDefault AliasAlgorithms
am.services.oauth2.remote.consent.response.signing.RSArsajwtsigningkey
RS256
RSA (at least 2048 bits)
am.services.oauth2.remote.consent.request.encryptionselfserviceenctest
RSA-OAEP-256
RSA (at least 2048 bits)

The following table shows the secret ID mapping used to decrypt OpenID Connect request parameters:

Secret IDDefault AliasAlgorithms [a]
am.services.oauth2.oidc.decryption.RSA1.5testRSA with PKCS#1 v1.5 padding
am.services.oauth2.oidc.decryption.RSA.OAEPtestRSA with OAEP with SHA-1 and MGF-1
am.services.oauth2.oidc.decryption.RSA.OAEP.256testRSA with OAEP with SHA-256 and MGF-1

[a] 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.

The following table shows the secret ID mapping used to sign OpenID Connect ID tokens and backchannel logout tokens:

Secret IDDefault AliasAlgorithms [a]
am.services.oauth2.oidc.signing.ES256es256testES256
am.services.oauth2.oidc.signing.ES384es384testES384
am.services.oauth2.oidc.signing.ES512es512testES512
am.services.oauth2.oidc.signing.RSArsajwtsigningkey
PS256
PS384
PS512
RS256
RS384
RS512
am.services.oauth2.oidc.signing.EDDSAEdDSA with SHA-512

[a] 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.

The following table shows the secret ID mapping used to store the CA certificates AM should trust during mTLS client authentication:

Secret IDDefault AliasAlgorithms
am.services.oauth2.tls.client.cert.authentication

OAuth 2.0 and OpenID Connect as Client/Relying Party of the Social Identity Provider Service

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 IDDefault AliasAlgorithms
am.services.oauth2.oidc.rp.idtoken.encryptiontest

The public key is exposed in the "/oauth2/connect/rp/jwk_uri".

For more information about the algorithms supported, and how to configure this secret ID mapping, see Social Authentication.

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 IDDefault AliasAlgorithms
am.services.oauth2.oidc.rp.jwt.authenticity.signingrsajwtsigningkey

The public key is exposed in the "/oauth2/connect/rp/jwk_uri".

For more information about the algorithms supported, and how to configure this secret ID mapping, see Social 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 IDDefault AliasAlgorithms
am.services.oauth2.tls.client.cert.authentication

The public key is exposed in the "/oauth2/connect/rp/jwk_uri".

For more information about the algorithms supported, and how to configure this secret ID mapping, see Social Authentication.

Web Agents and Java Agents

The following table shows the secret ID mapping used sign the JWTs provided to Web and Java agents:

Secret IDDefault AliasAlgorithms
am.global.services.oauth2.oidc.agent.idtoken.signingrsajwtsigningkey
RS256
RS384
RS512

Authentication

The following table shows the secret ID mappings used to encrypt and then sign persistent cookies:

Secret IDDefault AliasAlgorithms
am.default.authentication.modules.persistentcookie.encryptiontestRSA (at least 2048 bits)
am.default.authentication.modules.persistentcookie.signinghmacsigningtest
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 IDDefault Alias
am.authentication.modules.persistentcookie.helloworld.encryptionhelloworld
am.authentication.modules.persistentcookie.helloworld.signinghmacsigninghelloworld
am.authentication.modules.persistentcookie.hellomars.encryptionhellomars
am.authentication.modules.persistentcookie.hellomars.signinghmacsigninghellomars

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.

The following table shows the secret ID mapping used to encrypt sensitive data stored in the secure state of an authentication tree:

Secret IDDefault AliasAlgorithms
am.authn.trees.transientstate.encryptiondirectenctestAES 256-bit

SAML v2.0

The following table shows the secret ID mapping used to encrypt the JWTs SAML v2.0 creates in session storage:

Secret IDDefault AliasAlgorithms
am.global.services.saml2.client.storage.jwt.encryptiondirectentestA256GCM

The following table shows the secret ID mappings used to sign SAML v2.0 metadata:

Secret IDDefault AliasAlgorithms
am.services.saml2.metadata.signing.RSArsajwtsigningkeyRSA SHA-256

The following table shows the secret ID mappings used to sign and encrypt SAML v2.0 elements:

Secret IDDefault AliasAlgorithms
am.default.applications.federation.entity.providers.saml2.idp.encryptiontest
RSA with PKCS#1 v1.5 padding
RSA with OAEP
am.default.applications.federation.entity.providers.saml2.idp.signingrsajwtsigningkey
RSA SHA-1 [a]
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.encryptiontest
RSA with PKCS#1 v1.5 padding
RSA with OAEP
am.default.applications.federation.entity.providers.saml2.sp.signingrsajwtsigningkey
RSA SHA-1 [a]
ECDSA SHA-256
ECDSA SHA-384
ECDSA SHA-512
RSA SHA-256
RSA SHA-384
RSA SHA-512
DSA SHA-256

[a] 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 v2.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

The following table shows the secret ID mapping that the IoT service uses when configured as a trusted OAuth 2.0 JWT issuer:

Secret IDDefault AliasAlgorithms
am.services.iot.jwt.issuer.signinghmacsigningtest
HS256

The following table shows the secret ID mapping for the CA certificate that the "Register Thing Node" uses to verify the X.509 digital certificate included in the proof-of-possession JWT.

Secret IDDefault AliasAlgorithms
am.services.iot.cert.verification
Read a different version of :