PingAM release notes

Changes in AM 7.0.x

Critical changes in AM 7.0.2

Decompressed JWTs

By default, AM rejects any JWT that expands to more than 32 KiB (32768 bytes) when decompressed.

For information about changing this default value, refer to Controlling the Maximum Size of Compressed JWTs.

Maximum request body size

By default, AM rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size, and returns an HTTP 413 error response.

For information about changing the default value, refer to Limiting the Size of the Request Body.

One-time passwords stored in transient state

One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient state, instead of in the shared state.

Modify any custom authentication nodes or scripts used by the Scripted Decision node to retrieve the one-time passwords from the transient state after upgrading.

Critical changes in AM 7.0.0

User profile allowlist

The profile attribute allowlist controls the information returned to non-administrative users when accessing json/user endpoints.

Common profile attributes are allowlisted by default, but you need to add any custom attribute you want your non-administrative users to see. For more information, refer to Configuring the User Profile Whitelist.


When a client makes a call to the /json/authenticate endpoint appending a valid SSO token, AM returns the tokenId field empty if HttpOnly cookies are enabled. For example:


Secure authentication tree state secret ID

An AES 256-bit key called directenctest must be available in the environment during upgrade, but it does not need to be the same key that AM provides on the default keystore.

After upgrade, ensure that the am.authn.trees.transientstate.encryption secret ID is always mapped to an existing, resolvable secret or key alias. Failure to do so may result in trees not working as expected.

Embedded DS

The embedded DS can only be used for single AM instances, for test and demo purposes. Sites are not supported.

Sites using embedded DS servers must be migrated to external DS servers before upgrading.

SAML v2.0 secrets

AM 7 migrated SAML v2.0 to use secret stores. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, refer to "Configuring Secret Stores After Upgrade".

goto and gotoOnFail redirections

Redirection URLs for authentication services, agents, and SAML v.2.0 must be configured in the Validation Service if they are not in the same scheme, FQDN, and port as AM, or are not relative to AM’s URL.

Web agents earlier than version 5.6.3

Several properties that used to be configured as custom properties (com.sun.identity.agents.config.freeformproperties) have been added as regular properties. Due to this change, upgrading to AM 7 will overwrite the value of the original custom properties with the default value of the new UI properties.

To work around this issue, perform one of the following actions:

  • Upgrade to Web Agents 5.6.3 or later before upgrading to AM 7.

  • After upgrading to AM 7, reconfigure the properties that you configured as custom properties in their new UI counterparts.

Changes to the CTS reaper tuning properties

AM 7 changes the way the CTS reaper searches for expired tokens.

After upgrading, retune the CTS Reaper using the information in Reaper Search Size.

OIDC clients authenticating with JWTs

OIDC clients authenticating with JWTs must include in the JWT a jti claim containing a unique identifier, in line with OpenID Connect Core 1.0 incorporating errata set 1.

AM flags cookies as secure if they come through a connection marked as secure, or if they come through HTTPS. See "Managing the Secure Cookie Filter".

Important changes in AM 7.0.x

AM 7.0.2
Maximum size of decompressed JWTs enforced

A number of AM features accept JWTs to receive information. Some examples are:

  • The Remote Consent service, when it receives consent responses.

  • The OAuth 2.0/OpenID Connect authorization service, when:

    • OpenID Connect clients send request parameters as an encrypted JWT instead of as HTTP parameters.

    • OpenID Connect clients register dynamically using software statements.

  • The Authentication service, when configured to issue client-based sessions.

    These JWTs that AM receives can be signed and/or encrypted. Sometimes, if they are fairly large, they can also be compressed so that requests reach AM faster. Decompressing a JWT makes it expand in size. By default, AM 7.0.2 rejects any JWT that expands to more than 32 KiB (32768 bytes). Before upgrade, ensure that the decompressed JWTs your clients send to AM are smaller than 32 KiB before compression.

    If they are not, change the default value to a larger number after upgrade. For information about changing the default value, refer to Controlling the Maximum Size of Compressed JWTs.

Maximum request body size

Application servers can usually mitigate against DoS attacks that POST large amounts of form data, but AM endpoints may receive large amounts of POST data in different ways, such as in JSON, JWT, or JWK formats.

By default, AM 7.0.2 rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size, and returns an HTTP 413 error response.

For information about changing the default value, refer to Limiting the Size of the Request Body.

OAuth 2.0 and OpenID Connect clients

AM 7.0.2 returns an error if the administrator tries to save a client configuration containing an unsupported signing or encryption algorithm.

For example, upon saving the configuration, AM will return an error if there is a typo on an algorithm, or a symmetric signing or encryption algorithm is configured on a public client: these algorithms are derived from the client’s secret, which public clients do not have.

Clients registering dynamically must also send supported algorithms as part of their configuration, or AM will reject the registration request.

Different features support different algorithms. Refer to the documentation or to the UI for more information.

The following are examples of the errors:

  • Unknown encryption algorithm configured for User info encrypted response algorithm

  • Symmetric encryption algorithm configured for ID Token Encryption Algorithm is not allowed for a public client

    The error messages are also logged at ERROR level, and identify the client ID to which the error relates.

One-time passwords stored in transient state

One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient state, instead of in the shared state.

Modify any custom authentication nodes or scripts used by the Scripted Decision node to retrieve the one-time passwords from the transient state after upgrading to AM 7.0.2.

OpenID Connect Discovery endpoint disabled by default

The /.well-known/webfinger OpenID Connect discovery endpoint is now disabled by default, and can only be enabled by realm.

To enable the endpoint for a realm, configure the OAuth2 Provider service on the realm and next, enable the new OIDC Provider Discovery switch. Enabling the endpoint for the realm allows searches for users within that realm only.

After upgrading to AM 7.0.2, the endpoint will be enabled on realms that had the OAuth2 Provider service configured. Disable the endpoint on those realms that are not using OpenID Connect discovery.

For details, refer to OpenID Connect Discovery.

OAuth 2.0 token introspection

The /oauth2/introspect endpoint now returns an additional member, username, which specifies the user that authorized the introspected token.

As part of this change, the user_id member, which was used by earlier versions of the specification, is deprecated. It will be removed in a future version of AM.

This change aligns the endpoint’s response with the OAuth 2.0 Token Introspection specification.

AM 7.0.1
Ability to configure a failure URL in server-side authentication scripts

Server-side scripts can now redirect users to specific URLs after authentication failure.

For more information, refer to Redirecting the User After Authentication Failure.

AM 7.0.0
Upgrading with embedded DS

The embedded DS server is not supported for production in AM 7. Therefore, if you have a site configured with embedded DS, you must migrate it to an external DS store before upgrading to AM 7.

The embedded DS is deprecated in 7 and will be removed in a future release.

As part of this change, the embedded DS does not support replication, and cannot be configured as part of a site. The relevant replication options for the installer UI and Amster have been removed.

How do I know if my deployment uses the embedded DS?
  • (AM 6 or earlier) Go to Deployment > Servers > Server Name > Advanced, and check the value of the advanced property.

    If the value is, the server is an evaluation instance of AM, and is using an embedded DS instance as the configuration store.

  • In the server where AM is installed, check if the opends directory exists under the /path/to/openam directory.

    You might have migrated it to an external directory and not deleted the directory, though. Check the files in the opends/logs directory to determine if the embedded DS is running.

  • Go to Deployment > Servers > Server Name > Directory Configuration > Server, and check the value of the host name column.

    When using an external configuration store, the AM instances point to the FQDN of the load balancer in front of the DS cluster, or to the FQDN of the DS affinity deployment.

    When using an embedded configuration store, each AM instance points to its own hostname, because the embedded DS is stored alongside the AM instance.

AM 7 requires secure connections

AM 7 introduces a secure by default approach. One aspect of this approach is that all connections to DS instances must be secure; for example, by using LDAPS.

To connect to a DS instance using LDAPS, AM requires access to the self-signed certificate that DS generates.

To provide these certificates to AM, you must use a truststore that contains the necessary certificates, and configure AM to use that truststore when starting up.

Evaluation installs of AM attempt to automatically add DS’s self-signed certificate to the truststore defined by the property.

If the property is not defined, it creates a copy of the JDK’s default lib/security/cacerts truststore, names it truststore, and places it in /path/to/openam/security/keystores/.

For details, refer to Preparing a Truststore.

goto and gotoOnFail redirections

Earlier versions of AM redirected the user to the URL specified in the goto and gotoOnFail query string parameters supplied to the authentication service, SAML v2.0 entities, or agents during login and logout. To harden security against phishing attacks, we recommended that you configure the Validation Service.

By default, AM 7 only redirects to the URLs specified in those query string parameters if the URLs are in the same scheme, FQDN, and port as AM, or to URLs relative to AM. You must configure any other URL in the Validation Service.

Account lockout in authentication trees

AM 7 introduces improvements when handling account lockout when using authentication trees.

The Success and Failure nodes now increment or reset the invalid attempts count, and check the user status property, when reached.

For details, refer to About Account Lockout for Trees

As part of these changes, the Data Store Decision node does not check the user status property. Tree evaluation continues along the True path if the credentials are correct and the user is found, even if the user status is set to inactive.

You can use the Account Lockout node to check the user status property at any point in the authentication tree, as long as you have obtained a username first.

Default password of the "demo" evaluation user

The password for the demo user, that AM creates for evaluation purposes, changed in AM 7:

Old password: changeit

New password: Ch4ng31t

SSO token no longer returned on authentication endpoint with existing session

When a client appends a valid SSO token to a call to the json/authenticate endpoint, earlier versions of AM return the SSO token again in the tokenId field of the JSON response, regardless of the flags configured for the session cookie. For example:


AM 7 returns the tokenId field empty when HttpOnly cookies are enabled. For example:


Remember that AM upgrades cookies to secure cookies (except the amlbcookie cookie) when requests arrive over a secure channel.

To check if HttpOnly session cookies are configured, refer to Configuring HttpOnly Session Cookies.

Change any custom login pages or applications that were expecting the old response.

AM configuration directory structure

The location of numerous files and directories inside the AM configuration directory have changed. Similar date types are now stored together.

This table describes the new directories located within the AM configuration directory, for example /path/to/openam:

Directory Description


Contains files used for configuring AM, for example, the boot.json file.


Contains directories for storing keys, keystores, and secrets.


Contains folders for transient, writeable data, such as audit and debug log files.

New installations of AM 7 will have the new configuration folder layout described above. Upgrading from a previous version will leave the structure the same as in the previous version.
Audit event allowlisting

AM 7 introduces an allowlist that controls the information that can be logged in audit events. The default allowlist only records values that do not contain sensitive information.

You can add values to the allowlist that are recorded in audit events. You can also override the allowlist by adding items you do not want in the output to a denylist. Anything added to the denylist is not recorded in audit events.

When upgrading from a previous version of AM, any denylisted values are copied into the denylist of the upgraded server, unless they do not exist in the default denylist, and would therefore not be recorded anyway.

For information about audit logging, refer to Implementing the Audit Logging Service.

Admin UI and user UI

In earlier versions of AM, all files related to the UI were located in /openam/XUI.

In AM 7, the UI files are divided as follows:

  • User UI, located at /openam/XUI. This contains any end user pages. For example, login screens, and user profiles.

  • Admin UI, located at /openam/ui-admin. This contains any pages related to the administration of an AM server. Note, administrative logins are delegated to the User UI.

Localizing user-facing UI text required rebuilding the UI

In earlier versions of AM, you could copy user-facing localization files into your custom AM .war file. Downloading, localizing, and rebuilding the UI was not necessary.

AM 7 builds the localization text directly into the UI JavaScript files. Therefore, you must rebuild the UI to apply localization. Once rebuilt, redeploy the UI or pack it into your custom .war file.

For information about downloading and rebuilding the UI, refer to the UI Customization Guide.

UI templates and partial files moved

The location of the default UI templates and partials has moved to the /openam-ui-user/src/resources/themes/default/ directory.

When customizing the layout of the user interface, AM uses the partials and templates from the /themes/default directory if an equivalent file is not found in your customized theme.

As part of these changes, the following files have also moved:

Previous Location New Location









If you have customized any of these files, make sure that you move them to the new location when upgrading to AM 7.

For information on customizing the user interface, refer to UI Customization Guide.

Debug logging uses Logback

In earlier versions of AM, debug logging was configured by going to Debug.jsp.

AM 7 uses Logback for debug logging.

To configure debug logging in AM 7, either go to Logback.jsp to make temporary changes, or create a logback.xml configuration file in the AM classpath to make persistent changes.

For information on configuring Logback, refer to Debug Logging.

Because Logback can be configured to provide the same functionality, the following properties that could be added to the file are no longer used in AM 7:

  • org.forgerock.openam.debug.prefix

  • org.forgerock.openam.debug.suffix

  • org.forgerock.openam.debug.rotation

  • org.forgerock.openam.debug.rotation.maxsize

The Debug.jsp page has also been removed.

LDAPv3Repos LDAP servers stored in comma-separated ordered list

For multiple data stores behind a load balanced deployment, AM now stores servers in a comma-separated list, rather than an ordered list.

Consider, for example a site configuration, ID 02, with two servers, IDs 01 and 03. In previous releases, AM would store the servers as an ordered list:

$./ldapsearch -p 51636 -D "cn=Directory Manager" -w cangetin \
 -b "ou=services,dc=openam,dc=forgerock,dc=org" "objectclass=*"  > backup.ldif
$ grep "sun-idrepo-ldapv3-config-ldap-server" backup.ldif
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=localhost:51636

AM 7 stores this multi-server configuration as a comma-separated ordered list:

$./ldapsearch -p 51636 -D "cn=Directory Manager" -w cangetin \
 -b "ou=services,dc=openam,dc=forgerock,dc=org" "objectclass=*"  > backup.ldif
$ grep "sun-idrepo-ldapv3-config-ldap-server" backup.ldif
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=[0]\|01\|02,\|03\|02,localhost:51636,\|01\|02,\|03\|02
request_uri values must be pre-registered

In earlier versions of AM, you could configure the OAuth 2.0/OpenID Connect provider to require clients to pre-register their request_uri values.

In AM 7, pre-registration of request_URI values is mandatory, and the option to disable it has been removed.

Advanced server property opensso.protocol.handler.pkgs replaced

In earlier versions of AM, you could configure the opensso.protocol.handler.pkgs property with a value of com.sun.identity.protocol.

AM 7 replaces this property with the org.forgerock.openam.http.ssl.connection.manager property. This property must point to a class that implements the org.forgerock.openam.http.SslConnectionManager interface, which controls keystore and truststore settings, and hostname verification.

The property name and value will be corrected when upgrading from a previous version. However, if you have a value other than com.sun.identity.protocol then you must manually set the value of the new property, and create a new implementation of the org.forgerock.openam.http.SslConnectionManager interface.

Labeling of supported and evolving APIs in Javadoc

AM 7 alters the way an API is marked as "supported" or "evolving". To determine whether something is supported or evolving, you might need to assess the object hierarchy to check if a parent is labelled. Previously, each item was marked individually.

alg parameter removed from keys returned by JWK URI endpoints

AM 7 removes the alg parameter from the keys returned by the JWK URI endpoints. As a result, each kid is now unique.

Encrypted ID tokens Added to OpenID Connect end session endpoint

In earlier versions of AM, trying to end a session using an encrypted ID token resulted in failure because the request did not include enough information for AM to decrypt the token.

To support ending sessions when ID tokens are encrypted, AM 7 requires that the request to the end session endpoint includes the client ID for which AM issued the ID token.

This change diverges from the specification defined in the OpenID Connect Session Management 1.0-draft 5.

For details, refer to the /oauth2/connect/checkSession endpoint.

SAML v2.0 failover enabled by default

In earlier versions of AM, you had to manually enable SAML v2.0 failover, by going to Configure > Global Services > SAML v2.0 Service Configuration > Global Attributes, and then choosing the Enable SAML v2.0 failover option.

In AM 7, the Enable SAML v2.0 failover option is enabled by default and cannot be changed. The option no longer appears in the user interface.

For details, refer to Session State Considerations.

SAML v2.0 RelayState redirection restricted to same domain as AM

AM 7 alters the behavior of the Relay State URL List whitelisting property. If you do not specify any URLs in this property, AM will only redirect to URLs that match its deployment domain; for example,

To redirect using the RelayState parameter to a URL that does not match the instance of AM, you MUST add the URL to the Relay State URL List property.

For details, refer to Relay State URL List or Relay State URL List.

Supported and evolving APIs may require recompilation

The method signature or imports of some supported and evolving APIs may change between versions of AM. We recommend recompiling any customizations implementations you have for each new version of AM.

For example, the following classes related to the Service Management Service (SMS) have changed. You might need to recompile custom implementations that use any of the following classes:


    The class now extends a parent interface that adds no additional methods to implement.

  • org.forgerock.openam.secrets.Secrets

    The import for this evolving API class has changed.

ssoadm command requires a user DN

The value for the --adminid (-u) parameter when using the ssoadm command now requires the universal ID of an administrative user.

For example:

$ ./ssoadm list-servers --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org --password-file $HOME/.pwd.txt

For details, refer to Setting Up Administration Tools.

LDAP connection pool property name corrected

The property has been corrected. If you have any files or scripts that have the previous spelling ( with three `n`s) you should change them to the correct spelling.

For details about this property, refer to Tuning LDAP Connectivity.

Service configuration notifications processed sequentially by default

The property now defaults to 1. This causes notifications to be processed sequentially, avoiding any potential out-of-order conditions.

For details about this property, refer to Notification Settings.

Using the Device Profile authentication nodes requires an identity repository schema update

If you intend to use the ForgeRock SDKs with the new device profiling authentication nodes available in AM 7, you might need to update the schema in your identity repository.

Update the schema if any of the following are true:

Removed default value of the Json Web Key URI for OAuth 2.0/OpenID Connect clients

When creating a new OAuth 2.0 or OpenID Connect client, earlier versions of AM set the value of the Json Web Key URI field to the jwk_uri endpoint in AM. For example,

The value of the Json Web Key URI field in the client should not be AM’s jwk_uri endpoint, but an external URL that holds the client’s public JWK.

New clients created in AM 7 will have this field empty to avoid confusion. Existing clients will not be modified after upgrade.

CTS Reaper tuning properties

AM 7 changes the name and behavior of some advanced server properties used to tune the AM CTS reaper searches:

  • The default value of the for property has changed from 300000 to 5000 milliseconds (from 5 minutes, to 5 seconds).

  • The property has been replaced with the

    In earlier versions of AM, if the number of expired tokens was larger than the value of the pageSize property, the CTS reaper would make multiple requests of the value of the pageSize property until all expired tokens were deleted.

    In environments with very large numbers of expired tokens, this could lead to long pruning cycles that could cause performance degradation on the CTS token store.

    In AM 7, the CTS reaper makes one request of the value of the tokenLimit property, then sleeps for the value of the property.

    Requesting the reaper to run more times and recover smaller numbers of tokens avoids the performance impact of the previous implementation.

    You should retune the CTS reaper after upgrading AM to account for these changes.

    For more information, refer to Reaper Search Size.

JWT ID parameter (jti) required in OpenID Connect JWT client authentication

AM 7 requires that OpenID Connect clients authenticating with a JWT include a jti claim in the JWT. The jti claim must contain a unique identifier, in line with the OpenID Connect Core 1.0 specification.

If the claim is missing, AM returns an HTTP 400 invalid_request error with JWT ID is missing.

For related information, refer to Authenticating Clients Using JWT Profiles.

Changes to Audit Logging service

AM 6.5 introduced the AM-IDENTITY-CHANGE and AM-GROUP-CHANGE audit events to log user and group-related changes such as password changes, user creation and deletion, and others.

AM 7 does not log this information by default because doing so can have a performance impact.

To configure whether the Audit Logging service should log these events, AM 7 includes the advanced server property, which also enables and disables the logging of AM-ACCESS-ATTEMPT events.

This property replaces the org.forgerock.openam.audit.access.attempt.enabled advanced server property, which has been removed.

For details, refer to Advanced Properties.

Changes to user self-service flows

AM 7 no longer reports that an account does not exist when recovering a username or password, or that an account already exists when registering a new one:

  • Recovery flows

    When KBA or email are enabled as security methods, the flow does not stop if the user provides an invalid username. Instead, AM does one of the following, depending on which security method is configured:

    • Presents the user with a random KBA question before failing.

    • Presents the user with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, but does not actually send an email.

    If both methods are configured, AM presents the user with the email message.

  • Registration flow

    When email is enabled as a security method, AM presents the user with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, and then sends an email with a registration link to the address that the user entered.

    Clicking on the link sends the user to the registration page again, and AM shows a message similar to One or more user account values are invalid.

WDSSO: Absolute path of keytab file must be specified

When configuring the Windows Desktop SSO (WDSSO) authentication module, the absolute path of the keytab file must be specified, instead of the URL.

Changes to the TreeContext class

AM 7 introduces the following changes to the TreeContext class:

  • New method added to preserve the secureState for internal nodes contained in a Page node: public TreeContext copyWithCallbacksAndState(JsonValue sharedState, JsonValue transientState, JsonValue secureState, List<? extends Callback> callbacks)

  • New method added to provide nodes with access to secureState: public TreeContext copyWithCallbacks(List<? extends Callback> callbacks)

  • Constructors updated with a new parameter, universalId, to let nodes resolve identities using the universal ID.

  • Constructors updated with a new parameter, identityResource, to move managed object resource collection from nodes to tree configuration. The default is managed/user.

  • New method to retrieve field from secure state: public JsonValue getSecureState(String stateKey)

  • New method to retrieve field from transient state: public JsonValue getTransientState(String stateKey)

  • New constructor added to let suspended trees work with the Inner Tree Evaluator node: public TreeContext(JsonValue sharedState, JsonValue transientState, JsonValue secureState, ExternalRequestContext request, List<? extends Callback> callbacks, boolean resumedFromSuspend)

  • New method: public boolean hasResumedFromSuspend()

Copyright © 2010-2024 ForgeRock, all rights reserved.