--- title: Changes in AM 7.1.x description: AM now implements the java.util.Base64 utility class for encoding and decoding. This implementation improves standards compliance and is stricter in terms of what is accepted as valid Base64. component: pingam version: release-notes page_id: pingam::changes-7.1 canonical_url: https://docs.pingidentity.com/pingam/release-notes/changes-7.1.html section_ids: critical_changes_in_am_7_1: Critical changes in AM 7.1 base64_encoding_and_decoding: Base64 encoding and decoding decompressed_jwts: Decompressed JWTs maximum_request_body_size: Maximum request body size oauth_2_0_and_openid_connect_clients: OAuth 2.0 and OpenID Connect clients retry_limit_decision_node: Retry Limit Decision node one_time_passwords_stored_in_transient_state: One-time passwords stored in transient state changes_to_oauth_2_0_and_oidc_script_bindings: Changes to OAuth 2.0 and OIDC script bindings important_changes_in_am_7_1_x: Important changes in AM 7.1.x --- # Changes in AM 7.1.x ## Critical changes in AM 7.1 ### Base64 encoding and decoding AM now implements the `java.util.Base64` utility class for encoding and decoding. This implementation improves standards compliance and is stricter in terms of what is accepted as valid Base64. ### 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*. ### OAuth 2.0 and OpenID Connect clients This change affects AM when acting as an OAuth 2.0 or OpenID Connect client. If a redirection URI uses a scheme, host, or port that differs from that of AM, add it to the Validation Service to ensure that it is pre-approved. Otherwise, AM rejects the URI, and redirection fails. For details, refer to *Configuring Success and Failure Redirection URLs*. ### Retry Limit Decision node The new Save Retry Limit to User option in this node is disabled by default after upgrade. For security reasons, it is strongly recommended that you enable this option after upgrade. Enabling the option requires an update to the identity store schema. ### 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. ### Changes to OAuth 2.0 and OIDC script bindings The format for the following script bindings changed for this release: * requestUri Old format: String New format: String with query parameters; for example, `http://openam.example.com:8080/openam/oauth2/authorize?test=test` * requestParams Old format: String New format: Each parameter is returned as an array; for example, `grant_type:[authorization_code]` ## Important changes in AM 7.1.x > **Collapse: AM 7.1.3** > > * OAuth 2.0 introspection changes > > 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. > > * Base URL `X-Forwarded-*` headers > > Previously, if you set the *Base URL source* to `X-Forwarded-* headers` and no `X-Forwarded-Proto` header was provided, the generated URL would have a protocol of `null`, for example `null://host`, which would result in a broken URL. > > From this release, if no `X-Forwarded-Proto` header is provided, a fallback scheme is used, based on the URI of the request. > > * You can now specify a port in the Base URL, using the `X-Forwarded-Port` header. > > * If multiple `X-Forwarded-Host` headers are specified, the outermost proxy host is used. > **Collapse: AM 7.1.2** > > * Java agent property name changes > > The Java agent property names have changed in the 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 | > **Collapse: AM 7.1.1** > > * Connections made by the CTS > > OPENAM-13855 corrected an issue where the CTS was creating too many connections to DS. 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 OAuth 2.0 applications that have been authorized by the demo user: > > ```bash > curl --request GET \ > 'http://openam.example.com:8443/openam/json/users/demo/oauth2/applications?_queryFilter=true' > ``` > > * OAuth 2.0 token introspection > > The OAuth2 token introspection response is now compliant with [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) and returns a `username` rather than a `user_id`. > > * 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. > > | | | > | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | 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. | > > * The OIDC `/oauth2/userinfo` endpoint return values > > AM 7.1.1 changes when the `aud` and `iss` objects are returned in the JWT response of the OIDC `/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](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). > > The `iss` object is no longer returned when the response is an encrypted JWT. > **Collapse: AM 7.1** > > * `AM-SESSION-DESTROYED` no longer logged > > In previous AM releases, session timeout triggered two events. This could cause AM to send two logout tokens on a timeout, if an OAuth 2.0 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. > > * SAML v2.0 IdP discovery service redirection URLs > > The IdP discovery service now includes a mandatory field to configure valid redirection URLs; for example, the URLs of the SPs configured in the CoT to which the discovery service belongs. > > 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, refer to: > > * *Deploying the IdP Discovery Service* > > * *To Configure the Validation Service* > > * Example remote consent service and secret stores > > The remote consent service example has been migrated to use AM's secret store functionality. > > As part of this change, the signing and encryption fields have been removed in the global and realm service configurations. The following secret IDs have been created in their place: > > > **Collapse: Secret ID mappings for the OAuth 2.0 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 details, refer to *The Remote Consent Service*. > > If you configured the remote consent service example before upgrading, the upgrade process will migrate any secret configuration available to global or realm secret stores. > > * `sub` 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, as required by the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). 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 that use 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 easier, AM 7.1 also includes the following: > > * A new advanced server property, `org.forgerock.security.oauth2.enforce.sub.claim.uniqueness`. > > This 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 used in versions of AM earlier than 7.1. It also matches the value of the `sub` claim if you disable the `org.forgerock.security.oauth2.enforce.sub.claim.uniqueness` property. > > 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 you enable the advanced server property, make sure 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 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.1 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*. > > * Web and Java agent profiles > > * Web agents > > > **Collapse: Added properties** > > > > AM Load Balancer Cookie Enabled (`com.forgerock.agents.config.add.amlbcookie`) > > > **Collapse: Renamed properties** > > > > The *Agent Profile ID Whitelist* property is now *Agent Profile ID Allow List*. > > * Java agents > > > **Collapse: 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`) > > > **Collapse: Renamed properties** > > > > The *CDSSO Secure Enable* property is now *Transmit Cookies Securely*. > > > **Collapse: 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`) > > * 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.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 details, refer to *OpenID Connect Discovery*. > > * 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 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.1. > > For details, refer to *Storing Values in a Tree's Node States*. > > * Changes to the TreeContext class > > AM 7.1 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 callbacks)` > > * New method added to provide nodes with access to secureState: `public TreeContext copyWithCallbacks(List callbacks)`