--- title: Upgrade components and services description: 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. component: pingam version: 7.3 page_id: pingam:upgrade-guide:upgrade-components canonical_url: https://docs.pingidentity.com/pingam/8.1/upgrade/upgrade-components.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Upgrade"] --- # 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](upgrade-servers.html), if you are using features described in these lists, you will need to perform additional upgrade tasks: > **Collapse: 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](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts). > > 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](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-anonymous-user-mapping.html), 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](../authentication-guide/social-registration.html#request-native-app-for-userinfo) property, the [normalized-profile-to-managed-user.groovy](../scripting-guide/sample-scripts.html#normalized-profile-to-managed-user-groovy) and [normalized-profile-to-managed-user.js](../scripting-guide/sample-scripts.html#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](../authentication-guide/social-registration.html#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](https://datatracker.ietf.org/doc/html/rfc7662) 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](../reference/deployment-configuration-reference.html#org.forgerock.openam.introspect.token.query.param.allowed) advanced server property. > > - ${am.abbr} 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](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 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. > > > **Collapse: 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 | > > * 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)](../uma-guide/uma-policies.html#delete-an-uma-policy). > **Collapse: 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](../security-guide/control-maximum-size-decompressed-JWT.html). > > * 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](../security-guide/limit-request-body-size.html). > > * 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](../authentication-guide/redirection-url-precedence.html). > > 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](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-retry-limit-decision.html) > > 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](upgrade-servers.html), 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](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-hotp-generator.html) are now stored in the authentication tree's [transient state](../auth-nodes/core-action.html#store-values-in-transient-state). > > Modify any custom authentication nodes or scripts used by the [Scripted Decision node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-scripted-decision.html) to retrieve the one-time passwords from the transient state after upgrading to AM 7.1. > **Collapse: 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](upgrade-profile-whitelist.html). > > * `/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: > > ```json > { > "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 2.0 Secrets > > AM 7 migrated SAML 2.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](upgrade-create-secret-stores.html). > > * `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](../authentication-guide/redirection-url-precedence.html) 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](../cts-guide/cts-tuning-considerations.html#cts-tuning-tokenlimit). > > * 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](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). > > * 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](../security-guide/secure-cookie-filter.html). > **Collapse: 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](../oauth2-guide/oauth2-refresh-tokens.html#enable-refresh-tokens). > **Collapse: 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](upgrade-authenticator-recovery-codes.html). > > * 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](upgrade-create-secret-stores.html). > > * 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](../install-guide/prepare-configuration-store.html). > **Collapse: 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](upgrade-planning.html#review-REST-API-versions).