PingAM 7.5.0

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. For a list of secret labels and their default mappings, refer to 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.

Active secrets are used for signature generation, encryption, verification, and decryption. Non-active secrets are used 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.

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.

    For information about the different secret label mappings, refer to 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. AM 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.

Secret label default mappings

The following sections list the secret labels used by the AM features and their default mappings, if any.

General

PEM decryption password

The following table shows the secret label 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 label Default alias Algorithms

am.global.services.secret.pem.decryption

Encode using encode.jsp
Encrypt client-side sessions

The following table shows the secret label mapping to use when encrypting client-side sessions:

Secret label Default alias Algorithms

am.global.services.session.clientbased.encryption.RSA

RS256

am.global.services.session.clientbased.encryption.AES(1)

aestest

AES256

am.global.services.session.clientbased.encryption(2)

test

RS256

(1) This secret label replaces the legacy Encryption Symmetric AES Key configuration property (under Configure > Global Services > Sessions > Advanced). If you set both the configuration property and the secret label mapping, the mapping takes precedence.

(2) This secret label is deprecated and will be removed in a future release. Use the algorithm-specific secret labels in this table instead. These secret labels make it easier to configure and rotate secrets.

Sign client-side sessions

The following table shows the secret label mapping to use when signing client-side sessions:

Secret label Default alias Algorithms

am.global.services.session.clientbased.signing.RSA

RS256

am.global.services.session.clientbased.signing.ES256

ES256

am.global.services.session.clientbased.signing.ES384

ES384

am.global.services.session.clientbased.signing.ES512

ES512

am.global.services.session.clientbased.signing.HMAC(1)

hmacsigningtest

HMAC

am.global.services.session.clientbased.signing(2)

rsajwtsigningkey

RS256
ES256
ES384
ES512

(1) This secret label replaces the legacy Signing HMAC Shared Secret configuration property (under Configure > Global Services > Sessions > Advanced). If you set both the configuration property and the secret label mapping, the mapping takes precedence.

(2) This secret label is deprecated and will be removed in a future release. Use the algorithm-specific secret labels in this table instead. These secret labels make it easier to migrate and rotate secrets. If you set this secret label and an algorithm-specific secret label, the algorithm-specific label takes precedence.

mTLS certificate for the CRL cache server

The secret label mapping to encrypt the certificate used to authenticate to the CRL cache server.

Learn more about CRL caching in Certificate revocation list caching.

Secret label Default alias Algorithms

am.servers.crl.cache.directory.mtls.cert
HTTP client proxy password secret

The secret label mapping for the HTTP client proxy password used to authenticate HTTP outbound requests.

Secret label Default alias Algorithms

am.servers.httpclienthandler.proxy.secret

If you update this mapping, you must restart AM for the changes to take effect.

Attestation certificates

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 in the Android developer documentation.

Secret label Default alias Algorithms

am.services.attestation.google.public.key

RSA / X.509

Authentication

Encrypt authentication tree secure state data

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

Secret label Default alias Algorithms

am.authn.trees.transientstate.encryption

directenctest

AES 256-bit
Sign authentication requests

The secret label mappings for the HMAC secret used to sign and verify the authentication token (authID):

Secret label Default alias Algorithms

am.authn.authid.signing.HMAC

hmacsigningtest

This mapping overrides the randomly-generated core authentication attribute, Organization Authentication Signing Secret.

You can map multiple secrets to this label to enable secret rotation. AM signs the authentication token with the active secret but checks all mapped secrets when verifying the authentication token signature. Therefore, if you rotate the active secret while an authentication request is in progress, the returned authentication token can still be verified.

If you delete the secret that was used to sign an authentication token, the authID returned in the authentication request can’t be verified and authentication fails.

Authentication nodes

The dynamic secret labels for authentication nodes, where identifier is defined in the node configuration:

Node Secret label

Set Persistent Cookie node

am.authentication.nodes.persistentcookie.identifier.signing

Persistent Cookie Decision node

am.authentication.nodes.persistentcookie.identifier.signing

OTP SMS Sender node

am.authentication.nodes.otp.sms.identifier.password

OTP Email Sender node

am.authentication.nodes.otp.sms.identifier.password

LDAP Decision node

am.authentication.nodes.ldap.decision.mtls.identifier.cert

WebAuthn Registration node

am.authentication.nodes.webauthn.truststore.identifier

Certificate Validation node

am.authentication.nodes.certificate.validation.mtls.identifier.cert

Custom authentication node

am.authentication.nodes.customauth.identifier.secret

Encrypted device storage services

Encrypt device storage services

The secret label mappings for services that use encrypted device storage.

These mappings override the encryption keys set in the service configuration.

Service Secret label Default alias Algorithms

Device ID Service

am.services.deviceid.encryption

Device Binding Service

am.services.devicebinding.encryption

Device Profile Service

am.services.deviceprofile.encryption

WebAuthn Profile Encryption Service

am.services.authenticatorwebauthn.encryption

ForgeRock Authentication (OATH) Service

am.services.authenticatoroath.encryption

ForgeRock Authentication (PUSH) Service

am.services.authenticatorpush.encryption

IoT

IoT trusted JWT issuer

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

secret label Default alias Algorithms

am.services.iot.jwt.issuer.signing

hmacsigningtest

HS256
IoT certificate verification

The following table shows the secret label 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 label Default alias Algorithms

am.services.iot.cert.verification

OAuth 2.0 and OpenID Connect

As provider

JWT authenticity signing

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

Secret label 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.
Encrypt client-side OAuth 2.0 tokens

This table shows the secret label mapping used to encrypt client-side access tokens:

Secret label Default alias Algorithms

am.services.oauth2.stateless.token.encryption

directentest

A128CBC-HS256
Sign client-side OAuth 2.0 tokens

This table shows the secret label mappings used to sign client-side access tokens:

Secret label 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
Authenticate OAuth 2.0 clients

The secret label mappings used to authenticate OAuth 2.0 clients:

Secret label Default alias Algorithms

am.applications.oauth2.client.identifier.secret(1)

am.applications.oauth2.client.identifier.jwt.public.key(2)

am.applications.oauth2.client.identifier.mtls.trusted.cert(3)

am.applications.oauth2.client.identifier.id.token.enc.public.key(4)

(1) Map the am.applications.oauth2.client.identifier.secret dynamic secret label to override the OAuth 2.0 client’s Client secret property, where identifier is the value of the Secret Label Identifier set in the client configuration. (2) Map the am.applications.oauth2.client.identifier.jwt.public.key dynamic secret label to override the OAuth 2.0 client’s Client JWT Bearer Public Key, where identifier is the value of the Secret Label Identifier set in the client configuration. (3) Map the am.applications.oauth2.client.identifier.mtls.trusted.cert dynamic secret label to override the OAuth 2.0 client’s mTLS Self-Signed Certificate, where identifier is the value of the Secret Label Identifier set in the client configuration. (4) Map the am.applications.oauth2.client.identifier.id.token.enc.public.key dynamic secret label to override the OAuth 2.0 client’s Client ID Token Public Encryption Key, where identifier is the value of the Secret Label Identifier set in the client configuration.

Salt hashes

The secret label for salting hashes in OAuth 2.0 and OIDC flows.

Secret label Default alias Algorithms

am.services.oauth2.provider.hash.salt.secret

Use this secret label instead of setting Subject Identifier Hash Salt in the provider configuration.

This secret can’t be rotated.

Decrypt OIDC request parameters

This table shows the secret label mapping used to decrypt OIDC request parameters:

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

Sign OIDC tokens

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

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

CA certificates used in mTLS client authentication

This table shows the secret label mapping used to store the CA certificates AM should trust during mTLS client authentication:

Secret label Default alias Algorithms

am.services.oauth2.tls.client.cert.authentication

As client/relying party of the Social Identity Provider service

Decrypt ID tokens

This table shows the secret label 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 label 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.

For more information about the algorithms supported, and how to configure this secret label mapping, refer to Social authentication.

Sign JWTs and objects

This table shows the secret label mapping that AM uses to sign JWTs and objects when configured as a relying party of the Social Identity Provider Service:

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

For more information about the algorithms supported, and how to configure this secret label mapping, refer to Social authentication.

CA certificates used in mTLS client authentication (RP)

The following table shows the secret label 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 label Default alias Algorithms

am.services.oauth2.mtls.client.cert.authentication

Consult the .well-known endpoint of the identity provider.

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 label mapping, refer to Social authentication.

Policy Configuration service

Policy Configuration service

The secret label mappings to encrypt the certificate used to authenticate Policy Configuration service connections:

Secret label Default alias Algorithms

am.policy.configuration.service.mtls.cert

Push Notification service

Push Notification service

The secret label mapping for the Amazon Simple Notification Service access key used by the Push Notification service. The secret mapping overrides the SNS Access Key Secret set in the service configuration.

Secret label Default alias Algorithms

am.services.pushnotification.sns.accesskey.secret

SAML v2.0

Encrypt SAML v2.0 session storage JWTs

This table shows the secret label mapping used to encrypt the JWTs SAML v2.0 creates in session storage:

Secret label Default alias Algorithms

am.global.services.saml2.client.storage.jwt.encryption

directentest

A256GCM
Sign SAML v2.0 metadata

This table shows the secret label mappings used to sign SAML v2.0 metadata:

Secret label Default alias Algorithms

am.services.saml2.metadata.signing.RSA

rsajwtsigningkey

RSA SHA-256
SAML v2.0 signing and encryption

The following table shows the secret label mappings used to sign and encrypt SAML v2.0 elements, and to enable mTLS authentication between entity providers:

Secret label 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

am.default.applications.federation.entity.providers.saml2.sp.mtls(2)

am.applications.federation.entity.providers.saml2.identifier.basicauth(3)

(1) This algorithm is for compatibility purposes only. Avoid its use.

(2) For artifact resolution requests only, the SP uses the certificates mapped to this secret label for mTLS authentication to the remote IDP. These certificates are exported with <KeyDescriptor use="signing"> in the SP metadata.

(3) The SP uses the certificate mapped to this secret label for basic authentication. If you set a Secret Label Identifier, and AM finds a mapping to am.applications.federation.entity.providers.saml2.identifier .basicauth, AM uses this secret and ignores the value of the Password field. For basic authentication, there is no default secret label for the realm, or globally.

You can specify a custom Secret Label Identifier for each SAML v2.0 entity provider in a realm. AM generates new secret labels that can be unique to the provider, or shared by multiple providers.

For example, you could add a custom secret label identifier named mySamlSecrets to a hosted identity provider. AM then dynamically creates the following secret labels, 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 attempts to look up the secrets with the custom secret label identifier. If unsuccessful, AM looks up the secrets using the default secret labels.

UMA

UMA persisted claims tokens

The secret label mappings to encrypt UMA persisted claims tokens (PCTs):

Secret label Default alias Algorithms

am.services.uma.pct.encryption

directenctest

Web agents and Java agents

Sign JWTs for Web and Java agents

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

Secret label Default alias Algorithms

am.global.services.oauth2.oidc.agent.idtoken.signing

rsajwtsigningkey

RS256
RS384
RS512
Copyright © 2010-2024 ForgeRock, all rights reserved.