PingAM release notes

Changes in AM 7.2.x

AM 7.2.2

Change in behavior for journeys containing a Certificate Collector node

Previously, for journeys containing a Certificate Collector node, AM would throw an exception in the following scenario:

  • You set the node’s Certificate Collection Method property to Either or Header

  • You specified an HTTP header name

  • The certificate was missing from the browser (and from the request if Either was selected)

Now, in this scenario, the journey continues down the Not Collected path.

Change to OAuth 2.0 refresh token introspection response types

Previously, introspecting a stateful refresh token returned some claims as an array containing a single string.

For consistency, the following claims are now returned as strings:

  • realm

  • userName

  • authGrantId

  • clientID

AM 7.2.1

Change in behavior of httpOnly flag for trees

When HttpOnly session cookies are enabled and a client calls the /json/authenticate endpoint with a valid SSO token, AM should return an empty tokenId. While this has always been the case for authentication chains, it was not previously the case for authentication trees.

From AM 7.2.1, this behavior is the global default for authentication trees on new installations. It is also the default on new realms created on servers that have been upgraded to AM 7.2.1. For compatibility with previous versions, you can control this behavior using the Stops sending tokenId authentication configuration option.

  • Globally: Go to Configure > Authentication > Core Attributes > Trees.

  • By realm: Go to Realms > Realm Name > Authentication > Settings > Trees.

If your existing deployment relies on the previous behavior, where a valid tokenId is returned, disable the Stops sending tokenId option for that particular realm. For security reasons, you should adjust scripts and clients that rely on a tokenId in this situation and re-enable the option as soon as is feasible for your deployment.

Change to access token modification

With the introduction of persistent claims, access token modification is now performed before the id_token and the refresh_token are available to the access token modification script. This functionality dependency can be solved by persistent claims.

AM 7.2.0

OIDC claim classes

  • The org.forgerock.openidconnect.Claim class has been deprecated. The new org.forgerock.oauth.clients.oidc.Claim class 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 Claim.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 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.

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

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.

Behavior when deleting UMA policies

In previous AM releases, deleting an UMA policy did not impact any nested UMA policies. In AM 7.2, if you delete an UMA policy, any nested UMA policies are deactivated.

For details, refer to Delete an UMA policy (REST).

Changes to the TreeContext class

AM 7.2 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<? extends Callback> callbacks)

Copyright © 2010-2024 ForgeRock, all rights reserved.