PingAM release notes

New in AM 8.0.x

AM 8.0.1

AM 8.0.1 is a maintenance release that introduces functional enhancements and fixes.

Ability to refresh device IDs

The Push Notification service and the Ping SDKs now support the ability to refresh device IDs in user device profiles, rather than having to delete and recreate device profiles when a device ID changes.

You can find more information in Refresh push device IDs.

AM 8.0

AM 8.0 is a major release that introduces new features, functional enhancements, and fixes.

AM 8 introduces many new features and changes, but some key changes to be aware of are:

  • Tomcat 10 is the only supported Tomcat version.

  • Authentication modules and chains have been removed.

  • Embedded DS has been removed.

Make sure you review Incompatible changes and Removed in addition to this section before upgrading.

FBC in production deployments

Previous versions of AM provided a technology preview of the file-based configuration (FBC) migration utility.

In AM 8.0, FBC is supported in production deployments.

Learn more in the following topics:

Node Designer

AM 8.0 introduces a new way to create authentication node types that can be reused and shared across journeys and deployments.

The Node Designer lets you create scripted node types that have the following benefits:

  • Configurable bindings

  • Access to next-generation script bindings

  • Potential for less code repetition

  • Easier and quicker to innovate custom node types with scripting

Learn more in Custom scripted nodes.

Dynamic client registration script

You can configure AM to run a custom script after dynamic client registration. Create a next-generation script to modify a client profile after a successful create, update, or delete operation.

Learn more in Customize dynamic client registration.

Support for DER-formatted certificates for OAuth 2.0 client authentication

AM now accepts X.509 certificates in both PEM and DER format to authenticate OAuth 2.0 clients.

Learn more in Authenticate clients with mutual TLS.

RADIUS server configuration update

The RADIUS server service has a new configuration property that enforces the inclusion of the Message-Authenticator attribute in requests and responses.

Use this attribute to verify incoming RADIUS access requests to prevent spoofing.

IDM policy condition

Authorization policies have a new environment condition type named IDM User. This condition type lets you query an IDM resource to form the basis of the policy evaluation. AM must be part of a Ping Identity Platform deployment to use this environment condition.

Backchannel authentication

Backchannel authentication lets a third-party federation service initiate authentication with AM on behalf of a user. The federation service collects the user data and transmits this data directly to AM. AM redirects the user to complete the authentication process without having to re-enter the collected data.

Learn more in Backchannel authentication.

FIDO certification

PingAM is now a FIDO Certified Provider. PingAM has passed the FIDO Alliance’s rigorous testing program and meets their requirements regarding security and interoperability with other FIDO components.

Find more information about configuring AM for FIDO in Web authentication (WebAuthn).

Ability to trace the request flow through Ping Identity Platform

When a user interacts with Ping Identity Platform, the request can travel through multiple services before it completes. Distributed tracing lets you monitor the request flow through Ping Identity Platform.

Tracing provides a single view of a request’s journey and makes it easier to locate bottlenecks and errors.

Learn more in Trace incoming and outgoing requests.

Improved REST API for transactional authorization

For transactional authorization requests, you can now provide an authIndexType of transaction and an authIndexValue of transactionId to the authenticate endpoint. This new parameter lets you complete transactional authorization without sending URL-encoded XML over REST.

For example:

curl \
--cookie "iPlanetDirectoryPro=sso-cookie" \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=transaction&authIndexValue=transactionId'

The behavior of the new parameter is identical to the existing parameter:

…​/authenticate?authIndexType=composite_advice&authIndexValue=URL-encoded-XML,

The existing parameter remains supported.

Certificate Collector node supports DER certificates

For certificates supplied in HTTP headers, the Certificate Collector node now supports certificates in DER format in addition to PEM format. There are no configuration changes in the node itself.

The certificate format is inferred from the encoded certificate contents. The supported DER format encoding is compliant with RFC 9440.

OAuth 2.0 application journeys

You can now associate an OAuth 2.0 client with a specific authentication journey (tree). The associated journey is always run, regardless of existing sessions or configured authentication context class reference (acr) values.

You can only associate a tree with OAuth 2.0 applications configured for the Authorization Code, Implicit, and Device Code grant types.

To access information about the incoming OAuth 2.0 request, configure your tree to include a Scripted Decision node that queries the oauthApplication script binding.

Learn more in client application registration.

SAML 2.0 application journeys

Configure the remote SP so that a specific authentication journey (tree) is always run for users authenticating with your SAML 2.0 app. The federation flow invokes the associated journey regardless of any existing sessions or configured authentication context.

You can access the requested authentication context and configured mappings by including a Scripted Decision node in the journey that queries the new samlApplication script binding.

Learn more in Configure a SAML 2.0 application journey.

Customize SAML NameID mapping with a script

You can now use a script to customize the NameID attribute in the SAML 2.0 assertion per SP. Create a next-generation script of type Saml2 NameID Mapper and configure the remote SP entity to use the custom script.

You can find more information in NameID mapper.

Http Client service

The new Http Client service lets you create named instances that you can reference from a next-generation script using the httpclient binding.

On each instance, define secret labels that map to certificates in secret stores and are used during mTLS connections.

The service also provides settings to override connection and response timeouts for HTTP requests and to configure certificate checks per instance.

Learn more in Http Client service.

Default trees

The following new default trees have been added to AM:

  • ldapService: replaces the ldapService authentication chain.

  • Agent: replaces the Application module.

  • amsterService: replaces the amsterService authentication chain.

These trees provide direct replacements for the corresponding default modules and chains. This ensures any authentication processes that rely on them are unaffected by the removal of modules and chains in this release.

Learn more about these trees in Default trees.

Configure trees to run to completion

Set the mustRun property to force trees to always run to completion regardless of the existing user sessions.

Learn more in Configure an authentication tree to always complete.

Configure no session trees

Set the noSession property to create trees that don’t result in an authenticated session when they successfully complete.

Learn more in Configure a no session tree.

Session duration and timeout control

We’ve made changes to AM to provide greater control over journey session duration and authenticated session timeouts.

Journey session duration

You can now override global and realm level duration values in a tree or a node:

Find out how AM derives the journey session duration as a result of these changes in Configure suspended authentication.

Authenticated session timeouts

You can now override global and realm level timeout settings (maximum session time and maximum idle time) in a tree or a node.

Find out how AM derives the authenticated session timeouts as a result of these changes in Configure authenticated session timeout settings.

LINE login support

You can now configure a social provider authentication with LINE login. There are two new social provider configuration profiles, LINE (Browser) and LINE (Native), for browser and mobile app integrations.

The LINE (Browser) integration must not reference a well-known endpoint to ensure AM verifies signatures using the client secret instead.

Next-generation script bindings

The following next-generation script bindings have been improved for this release:

Common bindings

  • cookieName: Access the name of the cookie as a string to perform session actions such as ending all sessions for a user.

  • httpClient:

    • Use the new form attribute to send url-encoded form requests.

    • Reference an instance of the new Http Client service to enable mTLS connections to external services.

  • policy: Lets you access the policy engine API and evaluate policies from within scripts.

  • secrets: Reference secrets and credentials stored in secret stores.

  • utils: Use this new utility binding to perform functions such as:

    • Base64 encode/decode strings

    • Generate random values and UUIDs

    • Encrypt and decrypt values

    • Compute hash values

    • Sign and verify data

Make sure you don’t use the same name for a local variable as that of a common binding in your script. These names are reserved for common bindings only.

If you have already defined a local variable with the same name as one that’s added to common bindings in a more recent version of PingAM; for example, utils, you must rename the variable in your scripts before you upgrade.

Learn more in Script bindings.

Scripted decision node bindings

  • action:

    • Use the new suspend(String message) and suspend(String message, SuspensionLogic logic) methods to suspend the current authentication session and send a message to the user.

      You can also implement custom logic with the resume URI, for example, to send an email or SMS using the HTTP client service.

    • You can now access the following methods through the ActionWrapper object to return additional information to the client:

      • withHeader(String header)

      • withDescription(String description)

      • withStage(String stage)

  • jwtAssertion and jwtValuation:

    • You can now generate JWT assertions with custom non-registered claims.

    • Data fields are more aligned with the JWT specification, so you can now specify separate values for issuer and subject. These replace the existing accountId.

    • The bindings work with RS256 or HS256 signed JWTs, and JWTs that are encrypted using the A128CBC-HS256 algorithm.

  • nodeState: You can now merge data, including objectAttributes values, into existing state with the new mergeShared and mergeTransient methods.

  • oauthApplication: Access request and application information if the node is part of a journey associated with an OAuth 2.0 client application.

  • requestCookies: Use this new decision node script binding to access request cookies directly.

  • samlApplication: Access request and application information if the node is part of a journey associated with a SAML 2.0 client application.

Learn more in the Scripted Decision node API.

Library scripts

Library scripts now have access to all common bindings.

Learn more in Library scripts.

Next-generation script types

The following existing script types are now enabled for the next-generation script engine:

Scripted Decision node and Device Match node scripts now have different context types depending on the script engine. For legacy scripts, the context is AUTHENTICATION_TREE_DECISION_NODE, and for next-generation scripts, the contexts are SCRIPTED_DECISION_NODE and DEVICE_MATCH_NODE respectively.

Access PingOne Verify transaction data

The verifyTransactionsHelper next-generation binding lets you manage PingOne Verify user transactions and PingOne user accounts.

Learn more in Access PingOne Verify transactions and manage associated user

Flow Control node

The Flow Control node lets you control the authentication flow by randomly sending traffic down different paths of a tree (journey). This means you can use the node to evaluate changes before rolling them out to a production environment.

For example, configure the node to direct a percentage of requests to a new authentication journey to observe the user experience and check for potential failures.

Customize the JSON in the authentication response

The following nodes are new for this release.

Set Success Details node

The Set Success Details node lets you add details to the JSON response on successful authentication.

You can add either or both of the following:

  • Success Details: Lets you add static key:value fields to the JSON response.

  • Session Properties: Lets you add key:value fields to the JSON response, where value corresponds to the value of the specified session property.

Set Failure Details node

The Set Failure Details node lets you add details to the JSON response on authentication failure.

You can add either or both of the following:

  • Failure Message: Lets you add a custom, localized message to display to the user and return in the JSON response.

  • Failure Details: Lets you add key:value fields to the JSON response.

Set Error Details node

The Set Error Details node lets you add details to the JSON response when a journey ends in an error.

You can add either or both of the following:

  • Error Message: Lets you add a custom, localized message to display to the user and return in the JSON response.

  • Error Details: Lets you add key:value fields to the JSON response.

Configurable clock skew for OIDC ID token expiry time

The org.forgerock.openam.oauth2.tokenexpiry.skewAllowance advanced server property lets you configure the period, in seconds, during which an OIDC ID token remains valid after its expiry time.

This property allows for clock skews between servers.

In previous releases, the clock skew for ID token expiry times was hard coded to 5 minutes. For compatibility purposes, this is the default value of the new property.

Update signing certificate in remote SP metadata

You can now update the signing or encryption certificate for an existing SP without needing to delete and recreate the entire SP configuration.

Learn more in Update remote SP certificate.

Configure client certificate in SP metadata

You can now configure the hosted SP to exclude the client certificate from metadata.

To override the default behavior, enable the Exclude Client Certificate from Metadata option in the SP’s configuration.

Consistent errors when refreshing tokens

The following new methods ensure consistent error messages when refreshing tokens:

com.sun.identity.idm.IdRepoListener

  • objectChanged(String name, String previous, IdType idType, int changeType, Map cMap)

com.sun.identity.idm.IdEventListener

  • identityRenamed(String universalId, String previousUniversalId)

If a token is refreshed but the username has changed since the original refresh token was issued, the following error is now shown with these methods:

{
   "error_description" : "grant is invalid",
   "error" : "invalid_grant"
}

Configuration Provider node

The following improvements have been made to the Configuration Provider node:

Backchannel logout token contains exp claim

The logout token generated during backchannel logout now contains an exp claim.

Learn more in Backchannel logout.

New ssoadm commands update attributes in a realm service

A fix to the deprecated ssoadm tool adds the following new commands:

  • add-realm-default-attributes

  • set-realm-default-attributtes

  • remove-realm-default-attributes

  • get-realm-default-attributes

These commands work on realm defaults from AM 7 onwards.

System property for social provider sub claim uniqueness

A new system property (org.forgerock.openam.oidc.SocialProvider.sub.claim.is.not.unique) indicates that the OIDC social provider doesn’t return a unique value for the sub claim.

This is false by default.