Changes to Existing Functionality

This chapter covers both "Critical Changes" and "Important Changes" to existing functionality.

Critical Changes

As part of planning your upgrade, you need to consider that certain changes in later AM versions may 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 mandatory upgrade steps outlined in Upgrading AM Instances, if you are using features described in the following table you will need to perform additional upgrade tasks:

Critical Changes to Existing Functionality

AM Version	Component or Feature	Change
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 "Controlling the Maximum 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 "Limiting 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 "Configuring 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 Upgrading 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.
7	User Profile Whitelist	The profile attribute whitelist controls the information returned to non-administrative users when accessing `json/user` endpoints. Common profile attributes are whitelisted by default, but you need to add any custom attribute you want your non-administrative users to see. For more information, see "Configuring the User Profile Whitelist".
	`/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 "Configuring 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 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 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 "Managing the Secure Cookie Filter".
6.5.0.2 // 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".
6.5	Recovery Codes	Recovery Codes are encrypted, and existing codes are no longer displayed to the user. For more information, see "Upgrading 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 "Configuring 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 than the default used by previous versions of AM (`dc=openam,dc=forgerock,dc=org`). You should not attempt to 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 "Preparing Configuration Stores".
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".

Tip

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

Important Changes

This section lists changes made to existing functionality, services, endpoints, and others in the current release of AM.

Important Changes in AM 7.1.2

Java Agent Property Name Changes in AM console

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

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

Important Changes in AM 7.1.1

Number of 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.
Delegated admin can now query user profile attributes.
Admin privileges have been changed to let a delegated admin read user profile attributes. For example, this request returns the OAuth2 applications that have been authorized by the demo user:
```
curl --request GET \
'http://openam.example.com:8443/openam/json/users/demo/oauth2/applications?_queryFilter=true
```
OAuth2 Token Introspection
The OAuth2 token introspection response is now compliant with RFC 7662 and returns a username rather than a user_id.
Changes to the expires_in Value Returned From OAuth 2.0 Endpoints
AM 7.1.1 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.1.1 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.
Note
The expires_in object is not always present in the endpoint response:
Introspection endpoint: AM only returns the expires_in object for client-based 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-based tokens issued to a client configured in a different realm than the resource owner's.
Changes to the Values Returned From the OpenID Connect User Information Endpoint
AM 7.1.1 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.1.1 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.

Important Changes in AM 7.1

AM-SESSION-DESTROYED no longer logged when a session times out
In previous AM releases, session timeout triggered two events. This could cause AM to send two logout tokens on a timeout, if an OAuth2 client was registered for back-channel logout notifications on the session. With this change, a session is still destroyed on timeout but this is done as part of the timeout event, and the AM-SESSION-DESTROYED activity is not logged.
The SAML v2.0 IdP Discovery Service Now Requires Configuring a List of Valid Redirection URLs
The IdP discovery service application now includes a mandatory field to configure valid redirection URLs. Those are, for example, the URLs of the SPs configured in the CoT the discovery service belongs to.
After upgrading to AM 7.1, you must:
- Redeploy the IdP discovery application and reconfigure it to include the valid redirection URLs.
- Configure the valid redirection URLs in the Validation Service of each of the IdPs, in the Top Level Realm.
For more information, see:
- Deploying the IdP Discovery Service
- "To Configure the Validation Service"

The Example Remote Consent Service Now Uses Secret Stores

The Remote Consent Service example has been migrated to use AM's secret store functionality.

As part of this change, the example Remote Consent Service signing and encryption fields have been removed in the global and realm service configurations. The following secret IDs have been created in their place:

The following table shows the secret ID mappings used for the example Remote Consent Service:

Secret ID

Default Alias

Algorithms

am.services.oauth2.remote.consent.response.signing.RSA

rsajwtsigningkey

RS256

RSA (at least 2048 bits)

am.services.oauth2.remote.consent.request.encryption

selfserviceenctest

RSA-OAEP-256

RSA (at least 2048 bits)

For more information, see "To Configure the AM Example Remote Consent Service".

If you have the Remote Consent Service example configured before upgrading, the upgrade process will migrate any secret configuration available to global or realm secret stores.

Changes to the sub Claim in Access Tokens and ID Tokens
The subject claim of access tokens and ID tokens has changed formats to ensure that it is locally unique, as required by the OpenID Connect specification. The new Backchannel logout tokens also use the new format.
The subject claim is in the format (type!subject), where:
- subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.
- type can be one of the following:
  age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.
  usr. Specifies that the subject is a user/identity.
For example, (usr!demo), or (age!myOAuth2Client).
Clients using the sub claim to determine the identity about which the token asserts information are impacted by this change. To make transitioning to the new format as painless as possible, AM 7.1 also includes the following:
- A new advanced server property, org.forgerock.security.oauth2.enforce.sub.claim.uniqueness.
  The property controls whether AM should create tokens using the new sub claim format or not, and it is disabled after an upgrade to AM 7.1, and enabled in new installations.
  Tokens using the old sub format will still be accepted after the property is enabled. However, earlier versions of AM cannot read tokens with the new format.
- A new claim: subname.
  The value of the subname claim matches the value of the sub claim as it was returned in earlier versions of AM, or as returned in AM 7.1 when the new advanced server property is disabled.
  An example of the value of the subname claim is demo, or myOauth2Client.
  AM adds the subname claim to access and logout tokens regardless of the configuration of the new advanced server property. The claim is also available to ID tokens, but it is not included in the OIDC Claims Script. Therefore, AM does not add it to ID tokens by default.
Before enabling the advanced server property, ensure that your clients can use the new sub claim format, or a combination of the sub and the subname claims.
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.1 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 not, change the default value to a larger number after upgrade.
For more information about changing the default value, see "Controlling the Maximum Size of Compressed JWTs".
Maximum Size of Request Body Enforced
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.1 rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size, and returns an HTTP 413 error response.
For more information about changing the default value, see "Limiting the Size of the Request Body".
Changes to Web and Java Agent Profiles
- Web Agents
  Added Properties
  AM Load Balancer Cookie Enabled (com.forgerock.agents.config.add.amlbcookie)
  Renamed Properties
  The Agent Profile ID Whitelist property is now Agent Profile ID Allow List.
- Java Agents
  Added Properties
  Load Balancer Cookie Enabled (org.forgerock.agents.load.balancer.cookies.enabled)
  Load Balancer Cookie Name (org.forgerock.agents.load.balancer.cookie.name)
  Client IP Validation Mode (org.forgerock.agents.original.ip.check.mode.map)
  Client IP Validation Address Range (org.forgerock.agents.acceptable.ip.address.map)
  Perform Policy Evaluation in User Authenticated Realm (org.forgerock.agents.user.realm.overrides.policy.evaluation.realm.enabled)
  Accept SSO Tokens (org.forgerock.agents.accept.sso.tokens.enabled)
  SSO Cookie Domain List (org.forgerock.agents.ipdp.cookie.domain.list)
  Expired Session Cache Timeout (org.forgerock.agents.sso.expired.session.cache.ttl.minutes)
  Expired Session Cache Max Records (org.forgerock.agents.expired.session.cache.size)
  HTTP 302 Redirects Enabled (org.forgerock.agents.302.redirects.enabled)
  HTTP 302 Redirect Replacement HTTP Code (org.forgerock.agents.302.redirect.http.status.code)
  HTTP 302 Redirect Content Type (org.forgerock.agents.302.redirect.http.content.type)
  HTTP 302 Redirect Data (org.forgerock.agents.302.redirect.http.data)
  HTTP 302 Redirect Not Enforced List (org.forgerock.agents.302.redirect.ner.list)
  HTTP 302 Redirect Invert Not Enforced List (org.forgerock.agents.302.redirect.invert.enabled)
  Renamed Properties
  The CDSSO Secure Enable property is now Transmit Cookies Securely.
  Removed Properties
  Secure Cookies (org.forgerock.agents.jwt.cookie.secure.enabled)
  Session Logout Notification (org.forgerock.agents.session.change.notifications.enabled)
  Debug Logfile Directory (com.iplanet.services.debug.directory)
  Audit Logfile Path (org.forgerock.agents.local.audit.file.path)
  Service Resolver Class Name (org.forgerock.agents.service.resolver.class.name)
The OpenID Connect Discovery Endpoint is Now 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.1, 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 more information about the endpoint, see "OpenID Connect Discovery".
Changes to the OAuth 2.0 and OpenID Connect Clients
AM 7.1 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 that the error relates to.
One-Time Passwords Now 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.1.
For more information about the transient state, see "Storing Values in a Tree's Node State".

Changes to Existing Functionality

Critical Changes

Tip

Important Changes

Note