Upgrade components and services

As part of planning your upgrade, consider that some changes in later AM versions will have an impact on your environment. Usually, these changes are driven by changes in specification, security policies, or performance.

When possible, the upgrade process makes the appropriate changes on AM configuration. However, sometimes you will need to perform additional configuration based on your environment needs.

In addition to the mandatory upgrade steps outlined in Upgrade AM instances, if you are using features described in these lists, you will need to perform additional upgrade tasks:

Changes in AM 7.1

Decompressed JWTs: By default, AM rejects any JWT that expands to more than 32 KiB (32768 bytes) when decompressed. For more information about changing this default value, see Control the size of compressed JWTs.
Request Body Size: By default, AM rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size. For more information about changing this default value, see Limit the size of the request body.
Pre-Approval for Redirection URIs Enforced: This change affects AM when acting as an OAuth 2.0 and OpenID Connect client.

If a redirection URI uses a scheme, host, or port that differs from that of AM, you must now add it to the global validation service to ensure that it is pre-approved. This is described in Configure success and failure redirection URLs.

Otherwise, AM rejects the URI, and redirection fails.
Subject Claim in Access and ID Tokens: The subject claim of access tokens and ID tokens has changed formats to ensure that it is locally unique. The new format is not enforced after upgrading to AM 7.1, but new installations default to it.

The org.forgerock.security.oauth2.enforce.sub.claim.uniqueness advanced server property controls the format of the sub claim.

Before enabling it, ensure that your clients can use the new sub claim format, or a combination of the sub and the subname claims.
The Retry Limit Decision node: The new Save Retry Limit to User feature in this node is enabled by default after upgrade and requires upgrading the identity store schema.

Ensure you update the schema following the instructions in Upgrade AM instances, or disable the feature. ForgeRock recommends keeping it enabled for security reasons.

Failure to take any of the actions will break the authentication journey for trees using this node.
One-Time Passwords in Authentication Nodes: One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient 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.1.

Changes in AM 7

User Profile Whitelist: 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, see Configure the user profile allowlist.
/json/authenticate Endpoint: 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:

{
    "tokenId":"",
    "successUrl":"/openam/console",
    "realm":"/alpha"
}

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.

The 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, see Configure secret stores after upgrade.

goto and gotoOnFail Query Parameter Redirection

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

Web Agents of a Version Earlier than 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 on 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.

OpenID Connect Clients Authenticating with JWTs: OpenID Connect 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.
Cookie Filter: AM flags cookies as secure if they come through a connection marked as secure, or if they come through HTTPS. See Secure cookie filter.

Changes in AM 6.5.0.2 and 6.5.1

OAuth 2.0 Refresh Tokens: AM only issues refresh tokens to clients that have the refresh token grant type configured in their client profile.

After an upgrade to 6.5 or later using the UI or the openam-upgrade-tool .jar file, existing OAuth 2.0 clients are configured to use all grant flows, including the Refresh Token Grant flow.

To configure the refresh token grant type manually, see To Configure AM to Issue Refresh Tokens.

Changes in AM 6.5

Recovery Codes: Recovery Codes are encrypted, and existing codes are no longer displayed to the user. For more information, see Upgrade device recovery codes.
Secret Stores: AM 6.5 introduced secret stores for OAuth 2.0 and the persistent cookie module. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see Configure secret stores after upgrade.
External Configuration Store: DS 6.5 introduced setup profiles, which pre-configure instances for different usages, such as CTS or configuration data. The default base DN for a DS configuration store instance (ou=am-config) is different to the default used by previous versions of AM (dc=openam,dc=forgerock,dc=org).

Do not run multiple instances of AM where the configuration store base DNs do not match. Use the same configuration store base DNs when configuring external DS 6.5+ instances that will be used simultaneously alongside existing DS 6 or earlier configuration store instances.

For more information, see Prepare a configuration store.

Changes in AM 6

json/ Endpoints: AM’s CSRF protection filter requires that either the X-Requested-With or the Accept-API-Version headers are included on requests to endpoints under the json root. For more information, see Reviewing REST API Versions Before Upgrading.

Access Management 7.2.2

Upgrade components and services