Access Management 7.3.2

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, refer to Secret ID default mappings.

Active secrets are used for signature generation and encryption. Non-active secrets are used for signature verification and decryption.

For example, if you mapped 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.

A non-active secret can be rotated to become an active secret (while the old secret remains valid). A secret can be retired when it is 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.

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

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

    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

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

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
Secret ID mappings for encrypting client-side sessions

The following table shows the secret ID mapping to use when encrypting client-side 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.

Secret ID mappings for signing client-side sessions

The following table shows the secret ID mapping to use when signing client-side 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

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.
Secret ID mappings for encrypting client-side OAuth 2.0 tokens

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

Secret ID Default alias Algorithms

am.services.oauth2.stateless.token.encryption

directentest

A128CBC-HS256
Secret ID mappings for signing client-side OAuth 2.0 tokens

This table shows the secret ID mappings used to sign client-side 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
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.

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.

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

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

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.

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

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.

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

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

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

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

Secret ID mappings for encrypting SAML v2.0 session storage JWTs

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

Secret ID Default alias Algorithms

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

directentest

A256GCM
Secret ID mappings for signing SAML v2.0 metadata

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

Secret ID Default alias Algorithms

am.services.saml2.metadata.signing.RSA

rsajwtsigningkey

RSA SHA-256
Secret ID mappings for SAML v2.0 signing and encryption

The following table shows the secret ID mappings used to sign and encrypt SAML v2.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 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

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
Secret ID mappings for IoT certificate verification

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 ID Default alias Algorithms

am.services.iot.cert.verification