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

Changes to the OIDC claim classes

The org.forgerock.openidconnect.Claim class has been deprecated. The new org.forgerock.oauth.clients.oidc.Claim class, in the ForgeRock commons library, replaces its functionality.

This new class has a getNameWithLocale() method that returns a string of claim names, appended with # and the locale, in line with the OIDC specification.

A new getJavaLocale() method has been added to the Claim class, and lets a caller get the Locale object associated with the claim. The existing getLocale() method remains unchanged, and is equivalent to calling getJavaLocale().toLanguageTag().

The new Claim class contains a ClaimBuilder class, that you should use to create instances of the Claim. The Claim class is immutable and should not be extended. (It cannot be marked as final, for compatibility reasons.)
The ClaimBuilder class no longer contains a withValues method. This method has been split into the following, more granular methods (with corresponding new methods for single items):
- withBooleanValues and withBooleanValue
- withNumericalValues and withNumericalValue
- withJsonValues and withJsonValue
- withStringValues and withStringValue
The new ClaimsMapper class separates and encapsulates the functionality for converting claims to and from JSON. The `asMap method has therefore been removed from the Claim class.

Anonymous user inactive by default

The default anonymous user, used, for example, by the Anonymous User Mapping node, is now Inactive by default. If you have existing nodes, modules, or other clients that reference this user, you must explicitly set the user status to Active.

normalized-profile-to-managed-user scripts

For Apple SSO configurations that use the Request Native App for UserInfo property, the normalized-profile-to-managed-user.groovy and normalized-profile-to-managed-user.js scripts have been updated to set a flag that specifies how userinfo objects should be patched.

If you use these scripts, or a custom variation of these scripts, in your Apple SSO authentication tree, you should update your scripts to set the flag. You should also update your social provider journey to add a Scripted Decision node, as described in Request Native App for UserInfo.

Connections made by the CTS

OPENAM-13855 corrected an issue where the CTS was creating too many connections to the Directory Services. This fix might imply that the number of connections created is now different in your deployment, corrected to be the expected number of connections. Monitor your environments to ensure that this corrected number of connections is sufficient, and increase it if necessary.

Script content stored in clear text

In file-based configurations, script content is now stored in cleartext, rather than as a base64-encoded string. This makes it easier to find differences between old and new configurations. If you are upgrading AM from a previous version, existing scripts will still appear as base64-encoded strings in their corresponding configuration files. These scripts must be saved again in order for the cleartext script content to be stored in the configuration file. Note that script content is still base64-encoded in REST requests and responses.

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.

HTTP GET requests are now disallowed on the /oauth2/introspect endpoint by default. Using token as a query parameter on this endpoint is also disallowed. To change this behavior to suit existing clients, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

AM 7.2 changes the way the /oauth2/introspect and the /oauth2/tokeninfo endpoints return the value of the expires_in object.

The expires_in object specifies the time, in seconds, that a token is valid for. For example, 3600 seconds. This value is set at token creation time, and it depends on the configuration of the OAuth2 Provider Service.

When providing a token introspection or token information response, earlier versions of AM returned the value of the expires_in object as it was stored in the token. This means that any call to the endpoints while the token is valid returned the same value for the expires_in object.

AM 7.2 calculates the amount of seconds the token is still valid for and returns this value in the expires_in object. Therefore, repeated calls to the endpoints return different values for the object.

However, the actual value of the expires_in object in the token does not change. Inspecting the token without using AM will show the value set at token creation time.

The expires_in object is not always present in the endpoint response:

Introspection endpoint: AM only returns the expires_in object for client-side tokens issued to a client configured in the same realm as the resource owner’s.
Token information endpoint: AM does not return the expires_in object for client-side tokens issued to a client configured in a different realm than the resource owner’s.

OpenID Connect userinfo endpoint: AM 7.2 changes when the aud and iss objects are returned in the JWT response of the /oauth2/userinfo endpoint.

Earlier versions of AM returned the iss object when the user information response was a signed, encrypted, or a signed and encrypted JWT. The aud object was never returned.

AM 7.2 now returns both the aud and iss objects when response is a signed, or a signed and encrypted JWT, according to the OpenID Connect Core 1.0 incorporating errata set 1 specification.

The iss object is no longer returned when the response is an encrypted JWT.

Web and Java agent properties in AM admin UI

Web agent properties added
- Use Built-in Apache HTTPD Authentication Directives (com.forgerock.agents.no.remoteuser.module.compatibility)
- Hostname to IP Address Map (com.forgerock.agents.config.hostmap)
- Retain Session Cache After Configuration Change (com.forgerock.agents.session.cache.eventually.consistent)
Java agent properties added
- Recheck availability of AM (org.forgerock.agents.am.unavailability.recheck.window.in.seconds)
- Enable Notification of Session Logout (org.forgerock.agents.session.change.notifications.enabled)
Deprecated Java agent properties removed
- Fall-Forward Mode (org.forgerock.agents.fallforward.mode.enabled)
- PDP Cache TTL in Milliseconds (com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl)

Java agent property name changes

The Java Agent property names have changed in AM admin UI. The new names reflect the names now used in the Java Agent documentation.

Summary of new names

Old Name	New Name
Accept SSO Tokens	Enable SSO Token Acceptance
Agent Configuration Change Notification	Enable Notifications of Agent Configuration Change
Agent Filter Mode	Agent Filter Mode Map
Allow Custom Login Mode	Enable Custom Login Mode
AM Conditional Login URL	OAuth Login URL List
AM Conditional Logout URL	Conditional Logout URL List
AM Login URL	AM Login URL List
Application Logout URI	Logout URI Map
Attribute Cookie Encode	Enable Attribute Encoding
Authentication Fail Reason Url	Authentication Fail URL
CDSSO Domain List	JWT Cookie Domain List
CDSSO Redirect URI	Authentication Redirect URI
Continuous Security Cookies	Continuous Security Cookie Map
Continuous Security Headers	Continuous Security Header Map
Convert SSO Tokens into OpenID Connect JWTs	Convert SSO Tokens Into OIDC JWTs
Cookies Reset Domain Map	Reset Cookie Domain Map
Cookies Reset Name List	Reset Cookie List
Cookies Reset Path Map	Reset Cookie Path Map
Custom Conditional Login URL	Legacy Login URL List
Custom Response Header	Custom Response Header Map
Encode Cookies	Enable Encoded Cookies
Exchanged SSO Token Cache Size	Max Entries in SSO Exchange Cache
Exchanged SSO Token Cache Time to Live	Exchanged SSO Token Cache TTL
Expired Session Cache Max Records	Max Entries in Expired Session Cache
FQDN Check	Enable FQDN Checking
FQDN Default	Default FQDN
HTTP 302 Redirect Not Enforced List	HTTP 302 Redirect Not-Enforced List
HTTP 302 Redirect Replacement HTTP Code	HTTP 302 Redirect Replacement HTTP Status Code
HTTP 302 Redirects Enabled	Enable HTTP 302 Redirects
Http Only	Enable HTTP Only Cookies
Invert Not Enforced IPs	Invert Not-Enforced IPs
Invert Not Enforced URIs	Invert Not-Enforced URIs
JWT Cache Size	Max Entries in JWT Cache
Legacy User Agent Support Enable	Enable Legacy Support Handlers
Load Balancer Cookie Enabled	Enable Load Balancer Cookies
Login Form URI	Login Form URI List
Logout Entry URI	Logout Entry URI Map
Logout Introspect Enabled	Enable Logout Introspection
Logout Request Parameter	Logout Request Parameter Map
Missing PDP entry URI	Missing POST Data Preservation Entry URI Map
Not Enforced Client IP List	Not-Enforced Client IP List
Not Enforced Favicon	Not-Enforced Favicon
Not Enforced IP Cache Flag	Enable Not-Enforced IP Cache
Not Enforced IP Cache Size	Max Entries in Not-Enforced IP Cache
Not Enforced URIs Cache Enabled	Enable Not-Enforced URIs Cache
Not Enforced URIs Cache Size	Max Entries in Not-Enforced URI Cache
Not Enforced URIs	Not-Enforced URIs
PDP Cache TTL in Minutes	POST Data Preservation Cache TTL
PDP Maximum Cache Size	POST Data Preservation Cache Size
PDP Maximum Number of Cache Entries	Max Entries in POST Data Preservation Cache
PDP Stickysession key-value	POST Data Preservation Sticky Session Key Value
PDP Stickysession mode	POST Data Preservation Sticky Session Mode
Perform Policy Evaluation in User Authenticated Realm	Enable Policy Evaluation in User Authentication Realm
Policy Cache Per User	Max Entries in Policy Cache per Session
Policy Cache Size	Max Sessions in Policy Cache
Policy Evaluation Realm	Policy Evaluation Realm Map
Policy Set	Policy Set Map
Port Check Enable	Enable Port Checking
Port Check File	Port Check Filename
Port Check Setting	Port Check Protocol Map
Possible XSS code elements	XSS Code Element List
Post Data Preservation enabled	Enable POST Data Preservation
Pre-Authenticated Cookie Max Age	Max Age of Pre-Authentication Cookie
Pre-Authenticated Cookie Name	Pre-Authentication Cookie Name
Profile Attribute Mapping	Profile Attribute Map
Regular Expression Remove Query Parameters	Regex Remove Query Parameters List for Policy Evaluation
Remove Query Parameters	Remove Query Parameters List for Policy Evaluation
Resource Access Denied URI	Access Denied URI Map
Response Attribute Mapping	Response Attribute Map
Restrict To Realm	Restrict to Realm Map
Retain Query Parameters	Query Parameter List for Policy Evaluation
Rotate Local Audit Log	Enable Local Audit Log Rotation
Samesite Cookie Attributes Excluded User Agents Pattern List	Exclude Agents From Samesite Cookie Attributes
Session Attribute Mapping	Session Attribute Map
URL Policy Env GET Parameters	GET Parameter List for URL Policy Env
URL Policy Env jsession Parameters	JSession Parameter List for URL Policy Env
URL Policy Env POST Parameters	POST Parameter List for URL Policy Env
User Principal Flag	Enable User Principal Flag
User Token Name	User Session Name
XSS detection redirect URI	XSS Redirect URI Map

Old Name

New Name

Accept SSO Tokens

Enable SSO Token Acceptance

Agent Configuration Change Notification

Enable Notifications of Agent Configuration Change

Agent Filter Mode

Agent Filter Mode Map

Allow Custom Login Mode

Enable Custom Login Mode

AM Conditional Login URL

OAuth Login URL List

AM Conditional Logout URL

Conditional Logout URL List

AM Login URL

AM Login URL List

Application Logout URI

Logout URI Map

Attribute Cookie Encode

Enable Attribute Encoding

Authentication Fail Reason Url

Authentication Fail URL

CDSSO Domain List

JWT Cookie Domain List

CDSSO Redirect URI

Authentication Redirect URI

Continuous Security Cookies

Continuous Security Cookie Map

Continuous Security Headers

Continuous Security Header Map

Convert SSO Tokens into OpenID Connect JWTs

Convert SSO Tokens Into OIDC JWTs

Cookies Reset Domain Map

Reset Cookie Domain Map

Cookies Reset Name List

Reset Cookie List

Cookies Reset Path Map

Reset Cookie Path Map

Custom Conditional Login URL

Legacy Login URL List

Custom Response Header

Custom Response Header Map

Encode Cookies

Enable Encoded Cookies

Exchanged SSO Token Cache Size

Max Entries in SSO Exchange Cache

Exchanged SSO Token Cache Time to Live

Exchanged SSO Token Cache TTL

Expired Session Cache Max Records

Max Entries in Expired Session Cache

FQDN Check

Enable FQDN Checking

FQDN Default

Default FQDN

HTTP 302 Redirect Not Enforced List

HTTP 302 Redirect Not-Enforced List

HTTP 302 Redirect Replacement HTTP Code

HTTP 302 Redirect Replacement HTTP Status Code

HTTP 302 Redirects Enabled

Enable HTTP 302 Redirects

Http Only

Enable HTTP Only Cookies

Invert Not Enforced IPs

Invert Not-Enforced IPs

Invert Not Enforced URIs

Invert Not-Enforced URIs

JWT Cache Size

Max Entries in JWT Cache

Legacy User Agent Support Enable

Enable Legacy Support Handlers

Load Balancer Cookie Enabled

Enable Load Balancer Cookies

Logout Entry URI

Logout Entry URI Map

Logout Introspect Enabled

Enable Logout Introspection

Logout Request Parameter

Logout Request Parameter Map

Missing PDP entry URI

Missing POST Data Preservation Entry URI Map

Not Enforced Client IP List

Not-Enforced Client IP List

Not Enforced Favicon

Not-Enforced Favicon

Not Enforced IP Cache Flag

Enable Not-Enforced IP Cache

Not Enforced IP Cache Size

Max Entries in Not-Enforced IP Cache

Not Enforced URIs Cache Enabled

Enable Not-Enforced URIs Cache

Not Enforced URIs Cache Size

Max Entries in Not-Enforced URI Cache

Not Enforced URIs

Not-Enforced URIs

PDP Cache TTL in Minutes

POST Data Preservation Cache TTL

PDP Maximum Cache Size

POST Data Preservation Cache Size

PDP Maximum Number of Cache Entries

Max Entries in POST Data Preservation Cache

PDP Stickysession key-value

POST Data Preservation Sticky Session Key Value

PDP Stickysession mode

POST Data Preservation Sticky Session Mode

Perform Policy Evaluation in User Authenticated Realm

Enable Policy Evaluation in User Authentication Realm

Policy Cache Per User

Max Entries in Policy Cache per Session

Policy Cache Size

Max Sessions in Policy Cache

Policy Evaluation Realm

Policy Evaluation Realm Map

Policy Set

Policy Set Map

Port Check Enable

Enable Port Checking

Port Check File

Port Check Filename

Port Check Setting

Port Check Protocol Map

Possible XSS code elements

XSS Code Element List

Post Data Preservation enabled

Enable POST Data Preservation

Pre-Authenticated Cookie Max Age

Max Age of Pre-Authentication Cookie

Pre-Authenticated Cookie Name

Pre-Authentication Cookie Name

Profile Attribute Mapping

Profile Attribute Map

Regular Expression Remove Query Parameters

Regex Remove Query Parameters List for Policy Evaluation

Remove Query Parameters

Remove Query Parameters List for Policy Evaluation

Resource Access Denied URI

Access Denied URI Map

Response Attribute Mapping

Response Attribute Map

Restrict To Realm

Restrict to Realm Map

Retain Query Parameters

Query Parameter List for Policy Evaluation

Rotate Local Audit Log

Enable Local Audit Log Rotation

Samesite Cookie Attributes Excluded User Agents Pattern List

Exclude Agents From Samesite Cookie Attributes

Session Attribute Mapping

Session Attribute Map

URL Policy Env GET Parameters

GET Parameter List for URL Policy Env

URL Policy Env jsession Parameters

JSession Parameter List for URL Policy Env

URL Policy Env POST Parameters

POST Parameter List for URL Policy Env

User Principal Flag

Enable User Principal Flag

User Token Name

User Session Name

XSS detection redirect URI

XSS Redirect URI Map

Session and OAuth 2.0 token terminology: Sessions and OAuth 2.0 (or Open ID Connect) tokens that are stored in the CTS token store were previously referred to as CTS-based, and sessions/tokens that are returned to the client were referred to as client-based.

This release introduces new terminology to clarify and simplify the distinction between the two types of sessions and tokens, moving away from low-level descriptions to the following terms:

Server-side (previously called CTS-based)
Client-side (previously called client-based)

This change is reflected in both the documentation and the configuration settings that you see in the user interface.

Terminology for denying or allowing access: The AM 7.2 release initiates the move towards more descriptive and inclusive terminology for the concept of allowing or denying access to components or services.

Where you might previously configure a whitelist or a blacklist, you now configure an allowlist or a denylist. This renaming task is ongoing throughout the ForgeRock documentation and user interfaces.

Change in behavior when deleting UMA policies: In previous AM releases, deleting an UMA policy did not impact any nested UMA policies. In AM 7.2.0, if you delete an UMA policy, any nested UMA policies are deactivated.

For details, see Delete an UMA policy (REST).

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

[/mnt/scratch/workspaces/workspace/am-docs-release_7.3.x/target/asciidoc/modules/ROOT/attachments/endpoints/authenticate.bash:#authenticate-expected-when-session-exists]

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

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.

For information on the endpoints deprecated or removed in previous versions, and their current equivalents, see the following Knowledge Base article.

AM 7.3.1

Upgrade components and services