PingAM release notes

Documentation updates

In addition to the changes described elsewhere in these notes, the published documentation for each AM version includes the following important changes.

AM 7.5

Date Description

2024-04-02

Initial release of AM 7.5 software. The following documentation issues were addressed as part of this release:

  • OPENAM-22207: List HiddenValueCallback as interactive not read-only

  • OPENAM-22098: Additional information required in JWT validation example

  • OPENAM-22065: Fix Knowledge Base link in documentation

  • OPENAM-22061: The Get Session Data Node updates the objectAttributes

  • OPENAM-21964: Update and align documentation for secret default mappings

  • OPENAM-21914: Clarify deprecation and replacement of shared and transient state bindings

  • OPENAM-21900: The Identify Existing User Node updates the shared state username

  • OPENAM-21885: Clarify statement on realms in the API Explorer docs

  • OPENAM-21882: Document minimum OTP length for HOTP Generator node

  • OPENAM-21851: Clarify use of setting for the IdP

  • OPENAM-21801: Next generation scripting: Update nodeState.getObject

  • OPENAM-21798: Next generation scripting: Document "get" wrapper functions

  • OPENAM-21759: Clarify use of Java class allowlisting in next-generation scripting

  • OPENAM-21754: Add warning to library scrips about use of third party libraries

  • OPENAM-21723: Attribute Present Decision node: Add note about case-sensitivity

  • OPENAM-21711: Incorrect acr_values step in Backchannel request grant

  • OPENAM-21706: Policy evaluation will succeed for failed transactional authorization under certain conditions

  • OPENAM-21699: Fix example for authenticating to specific services

  • OPENAM-21696: Add a note to the Set Custom Cookie node docs around host vs domain cookies

  • OPENAM-21670: Setup guide: Check and update link to affinity load balancing

  • OPENAM-21667: Sessions guide: Set JWT token expiry if you update max session TTL

  • OPENAM-21622: Retry limit decision node: Wrong shared state property name

  • OPENAM-21620: Node development: Improve and correct Node class documentation

  • OPENAM-21603: Missing spaces in catalina opts example prevents tomcat starting

  • OPENAM-21504: List Prometheus output with better description.

  • OPENAM-21418: Fix numbering in JWT profile sequence diagram

  • OPENAM-21413: Sample script in SAML docs does not work

  • OPENAM-21344: Update profile data scripting examples with try-catch blocks

  • OPENAM-20906: Artifact changes in AM 7.3 are not documented in Release Notes

  • OPENAM-20752: OAuth2 scripted policy condition variables needs updating

  • OPENAM-20522: State in docs that Sector Identifier URI is needed for Pairwise OAuth2Client profile

  • OPENAM-20349: Add detail to the Device Match node docs

  • OPENAM-19204: Customer cannot rely on Transient Node data for WebAuthN Authentication Node

  • OPENAM-18095: Update documentation with all available audit log fields

AM 7.4

Date Description

2024-08-28

Release of AM 7.4.1. The following documentation issues were addressed as part of this release:

  • AME-27930: Prepare truststore should use 7.x DS security model

  • AME-27531: Incorrect description for Scripting Engine configuration for Thread pool queue size

  • AME-25385: Document the HTTP client asynchronous feature

  • OPENAM-22635: Procedure for enabling the AM reaper is incorrect

  • OPENAM-22207: List HiddenValueCallback as interactive not read-only

  • OPENAM-22099: Remove misleading information about unsupported custom callbacks

  • OPENAM-22098: Additional information required in JWT validation example

  • OPENAM-22066: Document Social Provider Handler node nodeState updates

  • OPENAM-22065: Fix Knowledge Base link in documentation

  • OPENAM-21914: Clarify deprecation and replacement of shared and transient state bindings

  • OPENAM-21851: Clarify use of Single SignOn Service setting for the IdP

  • OPENAM-21801: Next generation scripting: Update nodeState.getObject

  • OPENAM-21798: Next generation scripting: Document "get" wrapper functions

  • OPENAM-21754: Add warning to library scrips about use of third party libraries

  • OPENAM-21699: Fix example for authenticating to specific services

  • OPENAM-21696: Add a note to the Set Custom Cookie node docs around host vs domain cookies

  • OPENAM-21667: Sessions guide: Set JWT token expiry if you update max session TTL

  • OPENAM-21666: Security guide: Byte and MB values of request body limit don’t match

  • OPENAM-21620: Node development: Improve and correct Node class documentation

  • OPENAM-21603: Missing spaces in catalina opts example prevents tomcat starting

  • OPENAM-21457: Clarify where the Failure node routes a user

  • OPENAM-21419: Security guide: Attach Java examples for custom secret stores

  • OPENAM-21413: Fix sample script in SAML docs

  • OPENAM-21344: Update profile data scripting examples with try-catch blocks

  • OPENAM-20752: OAuth 2.0 scripted policy condition variables need updating

  • OPENAM-20522: State that Sector Identifier URI is needed for Pairwise OAuth2Client profile

  • OPENAM-18598: Clarify account linking in Social Provider Handler Node documentation

  • OPENAM-18095: List all usable audit log attributes

2023-10-09

Initial release of AM 7.4 software.

  • Corrected name of SSOResponse binding in SAML SP adapter sample script.

  • Added links to Knowledge Base articles about restricting access to endpoints.

  • Updated social identity provider configuration reference with more information about transformation scripts and added realm to redirect URL example.

  • Provided more detail about audit log events.

  • Corrected error in WDSSO REST call in Authentication guide.

  • Note added about a SESSION_BLACKLIST token that exists for client-side authentication sessions.

  • Clarified documentation for the OIDC user info plugin that the /userinfo retrieves claims from the profile scope only.

  • Added explanation for audit filtering example in the Security guide.

  • Amended wording describing the Amster version used for upgrading exported configuration.

  • Updated instructions to download the UI source.

  • Documented changes to the OAuth 2.0 device authorization grant.

  • Updated format of scripting logger names

  • Fixed error in Device Profile Collector node documentation.

  • Clarified information around tuning the CTS connection pool.

  • Added note to caution that a certificate must exist in the keystore before mapping secrets to that keystore.

  • Removed references to unsupported CoreWrapper API from the documentation.

  • Improved the information about the bindings available to OAuth 2.0 scripted extensions.

  • Added more information for the following authentication nodes:

  • Corrected information about storing device data in shared state for OATH Registration node.

  • Updated Node development documentation with a note that OTP Email Sender node supports plain text notifications only.

  • Added note to advise installers and upgraders to remove web.xml entry to prevent a click-servlet exception.

  • Documented the new org.forgerock.openam.ldap.secure.protocol.version advanced property for defining the protocols AM uses to connect to a secure LDAP server.

  • Added new REST STS configuration property, STS Instance is running as remote instance. For details, refer to REST STS configuration

  • Updated Authentication guide with links to WS-Federation implementation steps in Knowledge Base.

  • Clarified supported claims when requesting policy decisions.

  • Added a table to list the certificates used in SAML 2.0 flows with their corresponding secret mappings. For details, refer to Certificates and secrets.

  • Clarified the steps to remove an AM instance in the installation guide.

  • Added the default path for audit logs on Windows.

  • Added a note about adding urls to Valid WReply List to ensure successful WS-Federation sign-on flow.

  • Added Inner Tree Node capabilities and restrictions.

  • Corrected an error in the deployment diagram. Refer to Example deployment topology.

  • Updated module information to refer readers to Knowledge Base articles about certificate authentication.

  • Fixed a documentation error relating to OAuth 2.0 email service configuration values.

  • Documented authentication session state management scheme differences and concerns. For details, refer to Server-side sessions and Client-side sessions.

  • Updated instructions for setting CATALINA_OPTS on Windows.

  • Documented the setting to configure the rotatable amadmin secret cache expiry time. Refer to org.forgerock.openam.secrets.special.user.secret.refresh.seconds.

  • Documented the new Enabled setting for external data stores.

AM 7.3

Date Description

2024-02-26

Release of AM 7.3.1. The following documentation issues were addressed as part of this release:

  • AME-25154: Update the CATALINA_OPTS in setenv.bat for Windows

  • OPENAM-21699: Fix example for authenticating to specific services

  • OPENAM-21620: Node development: Improve and correct Node class documentation

  • OPENAM-21580: Improve documentation on updating OAuth 2.0 clients

  • OPENAM-21579: Java keystores require ASCII passwords

  • OPENAM-21573: Amster upgrade documentation description contains an error

  • OPENAM-21383: Instructions to download the UI source code are out of date

  • OPENAM-21344: Update profile data scripting examples with try-catch blocks

  • OPENAM-21254: Complete note in Invalidate all sessions for a user section

  • OPENAM-21051: Update logger name and review debug logging page

  • OPENAM-21048: Error in Device Profile Collector node documentation

  • OPENAM-20925: Inaccurate documentation on CTS tuning

  • OPENAM-20911: Corewrapper object no longer accessible in authentication nodes

  • OPENAM-20909: Align multi-version release notes with content of previous versions

  • OPENAM-20906: Artifact changes in AM 7.3 aren’t documented in Release Notes

  • OPENAM-20903: Clarify audit filtering example

  • OPENAM-20870: Access token script API is incomplete

  • OPENAM-20835: Explain the SESSION_BLACKLIST token that exists for client-side authentication sessions

  • OPENAM-20666: Caution against duplicate OIDC ACR mappings

  • OPENAM-20591: Prevent ClassNotFoundException when removing click-* jars

  • OPENAM-20522: State that Sector Identifier URI is needed for Pairwise OAuth2Client profile

  • OPENAM-20311: Document AM property for LDAPS protocol

  • OPENAM-20038: Document which URLs for REST STS are made locally/remotely

  • OPENAM-19215: Missing documentation for WS Federation in Admin guide

  • OPENAM-19214: Authorization guide: Clarify supported claims in requesting policy decisions

  • OPENAM-19149: Clarify SAML certificates and secrets usage

  • OPENAM-18606: The documentation to remove an AM instance is misleading

  • OPENAM-18495: Provide details of each audit log event name in the AM documentation

  • OPENAM-18468: Maintenance guide: Update config store connection pool values

  • OPENAM-18099: Explanation of rawProfile information and mappings

  • OPENAM-18092: Provide better explanation on default Social Identity Provider configuration

  • OPENAM-18078: Review documentation on endpoints

  • OPENAM-17906: State default path for audit logs on windows

  • OPENAM-17580: Document configuration settings needed for AM 6.5.3+ for WS-Federation token issuer endpoints

  • OPENAM-17535: Authorization guide: Building the sample plugin is showing outdated info

  • OPENAM-16325: Inner Tree node capabilities and restrictions

  • OPENAM-16311: Rework transactional authorization over REST

  • OPENAM-16191: Deployment images lost accuracy between release 13.5 and 6

  • OPENAM-15083: Certificate Auth module needs detailed documentation

2023-04-04

Initial release of AM 7.3 software.

  • Removed instructions on using deprecated chains and modules to set up push authentication. Use authentication trees instead, as described in Push authentication journeys.

  • Updated the format of these release notes to list cumulative changes, instead of reflecting only the changes for the current release.

  • Clarified that AM truncates sequences of whitespace with a single whitespace when creating SAML v2.0 values such as entity IDs.

  • Removed use of deprecated with method from Scripted decision node API callbacks.

  • Documented new Use mixed case for password change messages property for the LDAP Decision node.

  • Added missing HTTP connector settings to WildFly setup instructions.

  • Updated information about --acceptLicense parameter in the Set up administration tools steps.

  • Removed access token from header in call to /oauth2/connect/endSession.

  • Documented how to mark configuration properties as passwords in the Node development guide.

  • Improved documentation for dynamic client registration.

  • Improved description of the Transformation Script field for the Social Provider Handler node.

  • Documented how to use the amupgrade tool to upgrade configuration.

  • Improved navigation of the authentication nodes configuration reference.

  • Clarified that the ForgeRock Authenticator app supports JPEG and PNG image formats.

  • Clarified location of setenv script in the Evaluation guide.

  • Updated installation and deployment graphics to show less complex DS installations.

  • Described the role of the Latest Access Time Update Frequency property in session management.

AM 7.2

Date Description

2023-06-26

Release of AM 7.2.2. The following documentation issues were addressed as part of this release:

  • OPENAM-22207: List HiddenValueCallback as interactive not read-only

  • OPENAM-22099: Remove misleading information about unsupported custom callbacks

  • OPENAM-22065: Fix Knowledge Base link in documentation

  • OPENAM-21851: Clarify use of Single SignOn Service setting for the IdP

  • OPENAM-21815: Clarify how transient state is removed after next callback

  • OPENAM-21383: Instructions to download the UI source code are out of date

  • OPENAM-21071: Add more information for LDAP availability (KeepAlive) changes

  • OPENAM-21048: Error in Device Profile Collector node documentation

  • OPENAM-20929: Switch to multi-version release notes

  • OPENAM-20835: Explain the SESSION_BLACKLIST token that exists for client-side authentication sessions

  • OPENAM-20591: Prevent ClassNotFoundException when removing click-* jars

  • OPENAM-20522: State that Sector Identifier URI is needed for Pairwise OAuth2Client profile

  • OPENAM-20311: Document AM property for LDAPS protocol

  • OPENAM-19215: Missing documentation for WS Federation in Admin guide

  • OPENAM-19214: Authorization Guide: Clarify supported claims in Requesting Policy Decisions

  • OPENAM-19149: Clarify SAML certificates and secrets usage

  • OPENAM-18606: The documentation to remove an AM instance is misleading

  • OPENAM-18468: Maintenance guide: Update config store connection pool values

  • OPENAM-18099: Explanation of rawProfile information and mappings

  • OPENAM-17580: Document configuration settings needed for AM 6.5.3+ for WS-Federation token issuer endpoints

  • OPENAM-17535: Authorization guide: Building the sample plugin is showing outdated info

  • OPENAM-16325: Inner Tree node capabilities and restrictions

  • OPENAM-15083: Certificate Auth module needs detailed documentation

2023-04-04

Release of AM 7.2.1. In addition to these release notes, the following changes were made to the documentation:

September 30, 2022

  • Updated the Choice Collector node documentation to clarify that the default choice is the first in the list if no default choice is specified.

  • Recommended the removal of the velocity-1.7.jar library after install or upgrade.

  • Added a step to the instructions on building custom nodes.

  • Added Logback.jsp logger names to the Debug logging documentation.

2022-06-30

Initial release of AM 7.2.

AM 7.1

Date Description

2023-07-11

Release of AM 7.1.4

  • Cautioned that host-based cookies should be used for security reasons (Securing the Session Cookie)

  • Changed the default expiry time of server-side agent sessions (com.iplanet.am.session.agentSessionIdleTime)

  • Updated docs to indicate that the failureUrl is not included in REST responses if it is empty

  • Clarified SAML certificates and secrets usage

  • Clarified supported claims when requesting policy decisions over REST

  • Fixed an error in the Device Profile Collector node docs

  • Documented settings for WS-Federation token issuer endpoints (Federation Authentication Module)

  • Added Inner Tree Node capabilities and restrictions

  • Documented AM property for LDAPS protocol org.forgerock.openam.ldap.secure.protocol.version)

  • Advised that changes to Authentication Naming Attribute after setup require existing identities to be updated

  • Enhanced the documentation of the Provision Dynamic Account node

  • Advised administrators to increase DS search limits for large numbers of SAML entities SAML Deployment Considerations)

  • Documented evalThreadSize setting as tuning parameter for policy evaluation

  • Clarified that SAML assertion must be signed when using HTTP-POST

  • Clarified use of auditEntryDetail for scripted decision node

  • Added missing HTTP connector setting to JBoss setup instructions

  • Updated instructions on validating a goto URL

  • Enhanced the documentation on the LDAP availability / KeepAlive changes, new in 7.1.3

  • Removed incorrect wording about namespaces in the node development docs

  • Noted that the JavaScript Origins property of an OAuth2 client does not support non-standard headers

  • Creating a SAML2 entity with a double space results in SAML2 entity with a single space

  • Updated Changes in AM 7.1.x with changes to the TreeContext class

  • Updated the upgrade instructions with information on custom server default properties

2022-10-13

Release of AM 7.1.3

  • Updated Changes in AM 7.1.x with changes to the TreeContext class.

  • Added the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

  • Added the org.forgerock.openam.ldap.dncache.expire.time advanced server property, which sets the DN cache timeout.

  • Updated the OATH Registration node and Push Registration node documentation for the customizable QR code message.

  • Updated the Remote consent documentation to describe the new JWKs URI.

  • Clarified the limitation on using ID tokens as access tokens. For details, refer to Additional Use Cases for ID Tokens.

  • Improved the logback documentation.

  • Updated the documentation on scripted policy conditions.

  • Documented the crypto settings in the IDM Provisioning service.

  • Added information on specifying remote entity encryption methods.

  • Added subject and body to the OTP Email Sender Node and OTP SMS Sender Node.

2022-05-03

  • Added guidance on naming custom nodes.

  • Corrected an error in the ForceAuth documentation for authentication trees.

  • Corrected an error in the OIDC hybrid flow documentation.

  • Described how to customize account lockout messages.

  • Updated the documentation on custom post-authentication plugin hooks.

  • Updated the documentation on the OAuth2 Device flow.

  • Add information on overriding and customizing OIDC claims scripts.

  • Clarified change to CORS filter configuration from AM 7 onwards.

  • Documented the nonProxyHosts advanced server property for HTTP client connections.

2022-03-15

Release of AM 7.1.2

  • Added guidance on protecting user profile attributes.

  • Updated Multi-Factor Authentication Nodes with details of the OATH nodes that replicate the existing OATH module functionality:

    • OATH Registration Node

    • OATH Token Verifier Node

For information on how to create and test an authentication tree using the OATH nodes, refer to One-Time Password Authentication Using Trees.

2021-12-06

Initial release of AM 7.1.1

  • Updated the examples in the Accessing Shared State Data section.

  • Added documentation in Supported Callbacks about the following callbacks:

    • BooleanAttributeInputCallback

    • BooleanAttributeInputCallback

    • ConsentMappingCallback

    • KbaCreateCallback

    • NumberAttributeInputCallback

    • StringAttributeInputCallback

    • TermsAndConditionsCallback

    • ValidatedCreatePasswordCallback

    • ValidatedCreateUsernameCallback

  • Updated the Preparing for Development section to specify that you must include a nodeDescription property in nodes to ensure that they appear in the authentication tree designer.

  • Improved the procedure on mapping files in file system secret volumes to add more detail about how to encrypt and create filesystem-based secrets.

  • Updated the Directory Server Requirements to indicate that DS 5.+ is required as External Directory Server for 7.1.+.

2021-11-15

Added a change in behavior to the logging on session timeout.

2021-05-12

Release of AM 7.1.

AM 7.0

Date Description

2022-xx-xx

Release of AM 7.0.3.

2021-05-27

Release of AM 7.0.2.

  • Indicated that scripts should be upgraded as part of the upgrade process.

  • Improved the documentation about the request parameter of the /oauth2/authorize endpoint.

  • Noted support for Internet Explorer 11 ends August 17, 2021, in alignment with the announcement from Microsoft ending support for Internet Explorer 11.

  • Updated Session Upgrade documentation to clarify that the ForceAuth parameter used with an authentication tree causes AM to issue a new session token, regardless of the security requirements.

2021-01-07

  • Updated the Supported Upgrade Paths section to remove the upgrade from OpenAM 13.X and add upgrade path from AM 7.x.

  • Added a new section, Managing the Secure Cookie Filter.

  • Removed information about Oracle Weblogic from the installation guide as it is not supported in this version.

  • Added a new section, OAuth 2.0 Scopes Policy Script API Functionality.

  • Updated the Scripting Environment documentation to show how to obtain the Groovy and JavaScript engine version that AM is using.

  • As part of hardening the security around the SAML v2.0 implementation that occurred in AM 7, the URLs specified in the Assertion Consumer Service must exactly match the SP’s scheme, FQDN, and port.

  • Added a new section, Setting Session Properties.

2020-11-04

Release of AM 7.0.1.

  • Added documentation on Adding Audit Information.

  • Improved the documentation on Tuning Authentication Node/Module LDAP Connections.

  • Added information on determining if an existing session is present before using the Get Session Data Node.

  • Added information on configuring the public key or HMAC secret in Authenticating Clients Using JWT Profiles.

  • Added information on using the ssoadm command with secure connections in Setting Up Administration Tools.

  • Updated Web or Java Agents SSO and SLO with Java Agent 5.7 and Web Agent 5.7 properties.

  • Updated JVM tuning properties.

  • Documented commands to export policy and application store LDIF files.

  • Clarified documentation on OAuth 2.0 JWK URI cache settings in To Create and Configure a Client Profile.

  • Clarified documentation on SAML v2.0 hosted SP attribute map in Hosted Service Provider Configuration Properties.

  • Corrected the Device Tampering Verification documentation to indicate that the device determines the score, rather than the node or the ForgeRock SDKs.

  • Updated how to create an HTTPS connector for Tomcat in Configuring AM’s Container for HTTPS.

  • Corrected the account mapper classes in Example: Protecting a Web Site With OAuth 2.0.

  • Added documentation about HTTP options when configuring a JVM proxy in front of AM in Preparing the Environment.

  • Updated the Linking Identities Automatically with Auto-Federation section to use the new UI.

  • Corrected the user required to perform policy evaluation with REST in To Evaluate a Policy.

  • Corrected the procedure on SAML v2.0 chains, in Linking Identities by Using Authentication Trees or Chains.

2020-08-30

Initial release of AM 7.