PingAM release notes

Changes in AM 8.0.x

AM 8.0

Support for Tomcat 10

AM 8.0 supports Apache Tomcat 10 as a web application container. If you use Apache Tomcat, you must upgrade to at least version 10 before you upgrade to AM 8.0.

Find more information in Upgrade Tomcat.

As part of this change, you should rewrite scripts that used the javax.servlet.request.X509Certificate attribute in the servlet request to obtain the client certificate. Your updated scripts should use the jakarta.servlet.request.X509Certificate attribute instead.

Authentication modules and chains

Authentication modules and chains have been removed in AM 8.0. If you’re still using modules and chains for authentication, you must migrate to nodes and trees as soon as possible.

It’s recommended that you migrate to nodes and trees before upgrading to AM 8.

If that’s not possible, and you need access to modules and chains for migration purposes, you can temporarily re-enable them in AM 8.0.
Re-enable modules and chains

  1. Go to Configure > Server Defaults > Advanced in the AM admin UI.

  2. Add the org.forgerock.am.authentication.chains.enabled property and set it to true.

  3. Save your changes.

  4. Restart AM or the container where it runs.

You can now access modules and chains through the REST endpoints. Modules and chains aren’t accessible through the AM admin UI.

The option to re-enable modules and chains is only for migration purposes in AM 8.0. Authentication modules and chains will be removed completely in an upcoming release.

Providing OAuth 2.0 client certificates to AM

Clients can provide mTLS certificates to AM using trusted headers. AM now supports certificates in Base64-encoded PEM and DER format.

The corresponding value of the TLS Client Certificate Header Format configuration property on the OAuth2 Provider service has therefore changed from URLENCODED_PEM to BASE64_ENCODED_CERT.

Change in behavior for WebAuthn flows

Previously, for WebAuthn flows, if an authenticator provided an attestation that included the certificate authority (CA) root certificate, AM would remove and silently ignore the certificate. This behavior has changed in AM 8.0.

Now, if the authenticator provides an attestation that contains an invalid certificate chain (including the root CA certificate in the chain), PingAM rejects the attestation and throws an InvalidDataException error. The root certificate must be issued and securely distributed by a CA.

Endpoint for monitoring server activity with Prometheus

To monitor server activity with Prometheus, use one of the new endpoints:

  • /metrics/prometheus

    The path of this endpoint is format-agnostic, but the response payload is identical to that from the /json/metrics/prometheus endpoint.

    Although this endpoint is new, it is also deprecated in this release and support for its use will be removed in a future release. Move to the /metrics/prometheus/0.0.4 endpoint as soon as convenient.

  • /metrics/prometheus/0.0.4

    The path of this endpoint is format-agnostic, but the response payload is slightly different to that from the /metrics/prometheus endpoint.

Learn more in Monitor with Prometheus.

Sessions terminology

Sessions that are created to track progress through an authentication tree were previously referred to as authentication sessions, and sessions that are created after a user has authenticated were just referred to as sessions.

This release introduces the following new terminology to clarify and simplify the distinction between these session types:

  • Journey session (previously called authentication session)

  • Authenticated session (previously called session).

This change is reflected in the documentation.

Change to custom OIDC Social IDP configuration

You no longer need to specify a well-known endpoint when configuring a custom OIDC Social Identity Provider service.

If the well-known endpoint isn’t specified, AM verifies signatures using the JWK location, keystore location, or the client secret.

Changes to audit logging

  • The following events have been added to the audit log:

    • AM-TREE-LOGIN-STARTED

      Logged when authentication through a tree starts.

    • AM-TREE-LOGIN-COMPLETED with exception

    Learn more in the Audit logging reference.

  • The org.forgerock.openam.audit.identity.activity.events.blacklist advanced server property contains a comma-separated list of audit events that won’t be logged. In previous releases, you could only add the AM-ACCESS-ATTEMPT, AM-IDENTITY-CHANGE, and AM-GROUP-CHANGE events to this list. From AM 8.0, you can prevent logging of any event.

    Logging all events can impact performance. You should log only those events you intend to monitor.

WS-Federation com.sun.identity.wsfederation.logout.wreply URL validation

To facilitate logging out of WS-Federation and multiprotocol environments (WS-Federation communicating with SAML 2.0), you must add the URL specified in the com.sun.identity.wsfederation.logout.wreply query parameter to the Valid goto URL Resources field in the validation service. If you don’t add this URL, redirection fails.

Learn more in Add a URL to the validation service.

Changes to LinkedIn social identity provider configuration

The OAuth 2.0 version of the LinkedIn social identity provider configuration profile is deprecated by LinkedIn. This deprecated version has been renamed to LinkedIn (Legacy).

To configure your social identity provider with the latest OIDC version of the LinkedIn profile, use the LinkedIn profile.

SOAP STS service

The SOAP STS service has been removed in this release. If you’re still using the SOAP STS, you must migrate to the REST STS.

When you upgrade to AM 8, the SOAP STS agents and configuration are deleted. Make sure you retain anything useful to your migration prior to upgrading.

The accountId field in JWT script binding operations

Two new fields, subject and issuer, replace the accountId field used by the jwtAssertion and jwtValidator script bindings. This lets you specify separate values for these JWT claims.

If specified, the accountId is now used as the values for issuer, stableId, and subject when these values aren’t provided.

Learn more in Generate and validate JWTs.