PingAM release notes

New in AM 8.1.x

AM 8.1.0

AM 8.1.0 is a minor release that introduces new features, functional enhancements, and fixes.

Node versioning

We’ve made changes to AM to provide node versioning functionality. When we make changes to a node in the future, we’ll create a new version of the node. Learn more in Node versions.

You can create versioned nodes for your custom Java nodes. Additionally, you can choose the version of the node to imitate in the Configuration Provider node.

Other node versioning changes include:

Resource version 3.0 for authenticationtrees REST endpoint

We’ve added a version-aware 3.0 resource to the realm-config/authentication/authenticationtrees endpoint. When sending a request to this endpoint, set the Accept-API-Version header to protocol=2.1,resource=3.0.

Resource versions 1.0 and 2.0 are deprecated.

Learn more in Create a tree over REST.

Versioned node endpoints

The realm-config/authentication/authenticationtrees/nodes endpoint is now versioned. Specify the version of the node in the request URL, for example: https://am.example.com:8443/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/UsernameCollectorNode/2.0.

Versionless node endpoints are deprecated.

Learn more in Create a tree over REST.

Audit logging

The node version is logged in the Authentication log under the AM-NODE-LOGIN-COMPLETED event.

By default, version is logged only for node versions greater than 1.0. To log version for all node versions, add the org.forgerock.am.auth.node.versioning.enable.v1.audit.detail advanced server property and set it to true.

Node definitions endpoint

A new listLatestNodeDefinitions action on the realm-config/authentication/authenticationtrees/nodes endpoint provides a list of node definitions for the latest version of each node.

This action combines the responses from the following separate actions into a single response:

  • getAllTypes action on the realm-config/authentication/authenticationtrees/nodes endpoint

  • schema, template and listOutcomes actions on the realm-config/authentication/authenticationtrees/nodes/node-name endpoint

Learn more in List latest node definitions.

Identity for AI

We’ve added support for AI agents in AM. AI agents are specialized OAuth 2.0 identities that securely perform tasks on behalf of end users through a delegated token exchange process, ensuring distinct accountability and granular access control.

You can use AI agents to securely build digital assistants that operate on behalf of end users, such as a chatbot on a retail website helping a user navigate products, or an internal workforce assistant acting on behalf of an employee to access enterprise tools like Salesforce.

Learn more in AI agents.

FIPS compliance

AM can be configured to run in a FIPS-approved mode of operation with Bouncy Castle FIPS keystores to comply with FIPS 140-3.

Find more information in FIPS 140–3 compliance.

WebAuthn conditional UI

AM now supports the WebAuthn conditional UI, also known as passkey autofill. This lets users sign in with a passkey if they’ve previously saved one in their browser. If they don’t have a suitable passkey, the browser lets them authenticate using a different method, such as their username and password or social authentication.

This feature provides a more seamless login experience to end users and can help increase the adoption of passkeys.

Learn more in Configure WebAuthn conditional UI.

Support for Android key attestation

AM now supports the Android Key Attestation Statement Format in WebAuthn requests.

Find more information in the documentation for the WebAuthn Registration node.

RADIUS authentication

The RADIUS server service in AM now supports authentication trees. You can create a journey that’s compatible with the RADIUS protocol, and then configure clients within the RADIUS server service to use that journey for authentication. Learn more in AM as a RADIUS server.

Additionally, there are new nodes to support RADIUS authentication from within a journey, where AM is acting as the RADIUS client.

Transactional authentication trees

A transactional authentication tree only runs when AM starts a transaction, which happens when AM does one of the following:

You can only configure transactional authentication trees using the REST API. Set the transactionalOnly property to true in the tree configuration.

Learn more in Configure a transactional authentication tree.

New authentication nodes

AD Decision node

The AD Decision node lets you verify credentials against a specified Active Directory data store.

The node also checks whether the user account is locked, disabled, or has expired.

Backchannel authentication nodes

The following new nodes provide backchannel authentication functionality from within a journey:

JWT Password Replay node

The JWT Password Replay node secures the user’s password within an encrypted JSON Web Token (JWT). Applications, such as PingGateway, can then use a shared secret to decrypt the JWT and replay the credentials for authentication.

Learn more in Password replay with AM.

Policy nodes

Policy Decision node

A new Policy Decision node lets you evaluate an authorization policy against resources within an authentication journey.

You can configure the node to target a specific policy or application, or use a Configuration Provider node script to determine the policy dynamically.

The node sets the outcome based on the policy’s decision. It doesn’t handle advices.

App Policy Decision node

The App Policy Decision node is a specialized version of the Policy Decision node designed to simplify the evaluation of application access policies within a journey.

It automatically identifies the policy set and resource (OAuth 2.0 client ID or SAML SP entity ID) from the journey context.

RADIUS authentication nodes

Two new nodes provide RADIUS authentication functionality from within a journey, where AM is acting as the RADIUS client:

These nodes replace the RADIUS authentication module.

RSA SecurID authentication node

A new RSA SecurID node lets you perform multi-factor authentication (MFA) by integrating with RSA SecurID.

This node replaces the SecurID authentication module.

Set Logout Details node

A new Set Logout Details node lets you add details to the JSON response when a journey ends with the user logging out. You can also use this to add a goto parameter that redirects the user to a specified URL on logout.

The ability to add details to the logout response is made possible with new logout hooks, which let you run custom server-side logic on logout.

Policy cache

The ability to store policy definitions in cache memory results in improved performance for policy evaluation.

Find more information in Tune policy evaluation.

Cache script values

The cache manager service lets you cache, retrieve, and manage data using the cacheManager binding in a Scripted Decision node script. This improves performance by storing frequently used or computationally expensive values, such as access tokens from an external service, reducing the need to fetch or calculate them on every execution.

The service automatically runs a load() function from a configured cache when a script requests a value that isn’t in the cache. Subsequent requests return the stored value until it expires.

Learn more in Cache script values.

Next-generation scripting support

We’ve added support for next-generation scripting to the following scripting contexts:

SAML 2.0 customization scripts

All the SAML 2.0 customization scripts are now enabled for next-generation:

OAuth 2.0 customization scripts

All the OAuth 2.0 scripted extension points can now use the next-generation scripting engine:

Learn more in Migrate OAuth scripts to next-generation scripts.

Social Identity Provider scripts

We’ve introduced next-generation script contexts for social identity provider components. While these functions previously relied on a single legacy social identity profile transformation script, you can now use specialized scripts for:

Next-generation script bindings

The following improvements have been made to script bindings for this release:

  • journey: Use this new binding to identify the current journey and access information about journey configuration.

  • locales: Use this new binding to return the localized version of a string from a translation map.

These bindings are available to the Configuration Provider node, Scripted Decision node, and Device Match node scripts.

Common bindings

  • utils.crypto.subtle:

    • You can now use the ECDSA algorithm to generate keys, and to sign and verify signatures.

    • Use the new crypto.subtle.deriveKey method to derive a key given a base key and some random salt.

  • utils.base64url now supports byte operations with the following new methods:

    • String base64url.encode(byte[] toEncode)

    • byte[] base64url.decodeToBytes(String toDecode)

  • httpClient:

    • Reference an instance of the Http Client service to route requests through a proxy connection.

    • You can now access this binding from SAML 2.0 IdP scripts.

Learn more in Script bindings.

Scripted Decision node bindings

  • samlApplication:

    • This binding has a new method, getAssertion(), that returns the assertion as a JSON map.

    • The samlApplication object is present in SAML 2.0 trees or set as the redirect tree on the hosted SP.

      You can also make sure the binding is available for all SAML flows by enabling the application context in the hosted IdP or remote SP entity configuration.

  • identity:

    The identity object returned by idRepository.getIdentity() now includes an exists() method. This lets you check whether the identity exists before performing further operations on the object.

Learn more in the Scripted Decision node API.

Dynamic client registration scripting

The clientIdentity binding has new methods to make it easier to set attributes without requiring LDAP formatting.

Learn more in the Dynamic client registration scripting API.

Scope validation scripting improvements

The following next-generation scripting changes have been made to improve customization and control over scope validation:

  • scopeValidatorHelper:

    This new binding has methods that let you customize refresh token scopes and that let you trigger an InvalidScopeException for unauthorized or malformed scope requests.

  • availableScopes:

    You can use this new binding to access all the scopes currently configured on the OAuth 2.0 client making the request.

Learn more in the Scope validation API.

Create global library scripts

To create a global library script that can be accessed from all realms, perform an HTTP POST using the /json/scripts endpoint, with an _action parameter set to createGlobal.

Learn more in Create a global library script.

Support for configuring proxy settings per request

AM now lets you define proxy settings at the request level.

Route a request through a proxy by configuring the httpClient binding to reference an instance of the Http Client service.

The service settings override the *.system.proxy.* advanced properties.

Learn more in Http Client service.

SAML 2.0 IdP-initiated SSO in integrated mode

AM 8.1.0 introduces the following improvements to enable an IdP-initiated SSO flow using trees:

Redirect to a tree on the remote SP

Configure the hosted SP to redirect to a tree when a response is received from the IdP.

Learn more in Redirect Tree.

SAML2 Authentication node

Use the new configuration option to check that the IdP entity ID in the incoming SAML assertion matches the IdP entity ID configured for the node.

Learn more in SAML2 Authentication node.

Scripted access to the SAML 2.0 assertion

The samlApplication binding, available to Scripted Decision nodes, now includes the getAssertion() method, which returns the SAML assertion as a JSON map.

Learn more in Query SAML application and authentication request.

SAML 2.0 audit logging (hosted IdP)

Details about the IdP and SP are now added to the Access log under the AM-ACCESS-OUTCOME event. The entity information is logged for SAML 2.0 flows where AM is the hosted IdP and the user has successfully authenticated. These additional details let you identify the SAML 2.0 application used in an authentication attempt.

Learn more in Access log format.

Application authorization

To support authorization for OIDC and SAML applications within authentication journeys, the following features have been introduced:

  • A new Authentication resource type includes a wildcard pattern to support unique identifiers such as OAuth 2.0 client IDs or SAML entity IDs.

  • A new Customer Application Policy Set that uses the resource type is now included as a default policy set.

  • Two new nodes, the Policy nodes and the [app-policy-decision-node], let you evaluate and enforce authorization policies directly within a journey.

Find more information in Policy sets and Resource types.

PingDirectory support

PingDirectory is now a supported type when you’re configuring an identity store.

LDIF files are also available for PingDirectory, which can be used to create the schemas required by AM.

Learn more in Identity stores and Set up directory schemas with LDIF.

Custom CTS DN for FBC installs

When you’re installing AM with a file-based configuration (FBC), you can now specify a custom DN for the CTS. Previous versions supported only the default CTS DN (ou=famrecords,ou=openam-session,ou=tokens).

Find more information in Additional startup properties in the FBC installation topic.

Authentication node enhancements

PingOne nodes

A number of improvements have been made to the nodes that allow integration with PingOne.

PingOne Protect Initialize node

The following configuration properties have been added to the PingOne Protect Initialize node:

  • Enable Universal Device Identification lets you tie the device payload to a non-extractable crypto key stored in the browser for content authenticity verification.

  • Enable Agent Identification lets the PingOne Signals (Protect) SDK collect device attributes from the PingID Device Trust Agent.

  • Timeout for Agent lets you specify the maximum time for establishing a connection with the PingID Device Trust Agent.

  • Port Number for Agent lets you specify the port number to use when connecting to the PingID Device Trust Agent.

  • Additional Signals SDK Initialization Options lets you pass additional signals (not included in the existing node configuration properties) to the PingOne Signals (Protect) SDK.

A number of configuration attributes that are no longer supported in PingOne Protect have been removed from this node.

Set Detail nodes

The Set Success Details, Set Failure Details, and Set Error Details nodes now let you set custom response headers in addition to customizing the JSON response.

Social Provider Handler nodes

We’ve made the following changes to the Social Provider Handler node:

  • Added support for handling connection timeouts.

  • Added the ability to specify the attribute to use to search for an existing user. This option only applies when you have an AM standalone deployment that uses an identity store other than PingDS.

    This option is also available in the Legacy Social Provider Handler node.

The Persistent Cookie Decision and Set Persistent Cookie nodes now include support for configuring the SameSite attribute for persistent cookies.

Device Binding nodes

The Device Binding and Device Signing Verifier nodes now let you specify a clock skew between the client device and AM. This helps prevent binding failures caused by clocks being out of sync.

OAuth 2.0 / OIDC improvements

Closer alignment with PAR and JAR specifications

A new advanced server property, am.oauth2.request.object.restrictions.enforced aligns AM behavior with the following specifications:

  • OAuth 2.0 Pushed Authorization Requests (PAR) (RFC 9126)

  • OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) (RFC 9101).

These specifications indicate the following:

  • The authorization server should ignore authorize parameters outside the request_uri.

  • When sending a JWT-Secured Authorization Request (JAR), the request_uri must be an https URI.

Allow unauthenticated user code entry at the realm level

A new setting on the OAuth2 Provider service lets you manage the device code flow configuration at the realm level.

Enabling Allow unauthenticated user code entry (under Realms > Realm Name > Services > OAuth2 Provider > Device Code lets users access and input a user code without first logging in during an OAuth 2.0 device code flow.

If you set the value in the global service configuration (on the Global Attributes tab) and in the realm service configuration (on the Device Flow tab), the realm-level setting takes precedence. If AM can’t determine the realm value (for example, if the realm isn’t provided in the verification URL), it uses the value set on the Global Attributes tab.

Map custom key IDs to secrets

You can now map custom kid header values for JWTs signed with the signing key to a specific secret alias.

Find more information in Map custom key IDs to secrets.

Perform OAuth 2.0 client authentication with a third-party issuer

You can now configure an OAuth 2.0 client to accept a JWT from an issuer other than the client ID.

Add the alternative issuer to the Accepted JWT Issuers list for OAuth 2.0 authentication to succeed.

Enable application context for OAuth 2.0 / OIDC flows

You can now access the application context for all OAuth 2.0 / OIDC flows through the oauthApplication binding by setting Enable Application Context in the OAuth 2.0 provider or at the client level.

Find more information in the OAuth2 provider configuration.

Require exp claim in JWT request object

You can now enforce the inclusion of the (expiration time) exp claim in the request object specified at the /oauth2/authorize or /oauth2/par endpoints.

Enable the Require exp claim in Request Object setting in the OAuth2 provider configuration.

Customize refresh token scopes with scope validation scripts

We’ve added support for dynamically adjusting the scopes granted to refresh tokens during the refresh flow.

Use a next-generation scripted scope validator to call scopeValidatorHelper.inheritAccessTokenScopesOnRefresh() to ensure a refresh token inherits the newly evaluated scopes granted to the access token. Previously, refresh tokens always retained their originally granted scopes.

Learn more about scope validation scripting changes in the Scope validation API.

Test the PingOne worker connection

You can now test the connection from AM to PingOne after you configure the worker service to verify the details. Use either the AM admin UI or the testConnection action on the realm-config/services/pingOneWorkerService/workers/pingone-worker-service-name endpoint.

Learn more in Test the connection.

CDSSO login template for PingGateway

The PingGateway agent in AM can now be configured to redirect to a specified URL when CDSSO fails. Add the new gotoOnFailure parameter to the existing template in Login URL Template for CDSSO.

Learn more in Register PingGateway with AM.

Secret store integration for user self-service features

User self-service features can now use a secret store for managing the keys used to sign and encrypt snapshot tokens (JWTs).

Learn more in Create a user self-service instance.

Support for Rich Authorization Requests (RAR)

AM 8.1.0 provides initial support for RAR, as specified in RFC 9396: OAuth 2.0 Rich Authorization Requests.

Learn more in Remote consent.

The interface stability for RAR support is Technology Preview. Technology previews offer access to new technology that is not yet supported in production. Technology preview features may be functionally incomplete and subject to change without notice. Find more details in Interface stability.