New in AM 7.0.x

AM 7 adds support for draft 12 of the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens specification, a key component of ForgeRock’s Open Banking and Revised Payment Services Directive (PSD2) support.

For information about authenticating an OAuth 2.0 client using mTLS certificates, Authenticating Clients Using Mutual TLS.

For information about issuing certificate-bound OAuth 2.0 access tokens, refer to Certificate-Bound Proof-of-Possession.

AM 7 adds support for scripting the modification of issued OAuth 2.0 access tokens. You can add properties to the access token, for example values taken from the resource owner’s profile such as telephone number or email address.

For information, refer to Modifying the Content of Access Tokens.

AM 7 introduces an OpenID Connect authentication node, for authenticating users from an OpenID Connect-compliant identity provider.

For details, refer to OpenID Connect node in the Authentication and Single Sign-On Guide.

AM 7 introduces support for Client Initiated Backchannel Authentication (CIBA). This allows a client application, known as the consumption device, to obtain authentication and consent from a user without requiring the user to interact with it directly.

Instead, the user authenticates and consents to the operation using a separate, "decoupled" device, known as the authentication device. For example, an authenticator application, or a mobile banking application on their mobile phone.

For more information, refer to Backchannel Request Grant in the OpenID Connect 1.0 Guide.

By default, AM generates a key ID (kid) for each public key exposed in the jwk_uri URI when AM is configured as an OAuth 2.0 authorization server.

AM 7 introduces a new extension point, KeyStoreKeyIdProvider, to customize the key ID values associated with public keys stored in keystore secret stores.

For more information, refer to /oauth2/connect/jwk_uri in the OpenID Connect 1.0 Guide.

AM 7 introduces a new user interface for managing SAML v2.0 entities, and circles of trust. For details, refer to Configuring IDPs, SPs, and CoTs in the SAML v2.0 Guide.

The UI is backed by new /federation and /saml2 REST endpoints, for programmatically creating and managing SAML v2.0 deployments. The endpoints are documented in the REST API Explorer.

In addition, SAML v2.0 signing and encryption now uses AM’s secret stores functionality. AM upgrades SAML v2.0 Service Configurations from previous versions to use secret stores in AM 7. The service itself is no longer required, and is deleted by the upgrade process after the configuration has been migrated. The global service remains unchanged.

For details, refer to Signing and Encryption in the SAML v2.0 Guide.

As part of this change, the way metadata is stored and generated by AM has changed. For example:

The exported metadata remains unchanged. You do not need to share the metadata of your providers again due to the changes previously explained.

AM 7 introduces another change as part of hardening the security around the SAML v2.0 implementation. When AM acts as the hosted service provider, the scheme, FQDN, and port of the URLs specified in the Assertion Consumer Service must exactly match those of the service provider as they appear in its metadata.

To determine the service provider’s endpoint URL, AM uses the Base URL service, if configured.

If the URL does not match, the SAML v2.0 flow will fail and AM will log Invalid Assertion Consumer Location specified in the audit log file.

AM 7 introduces a new REST endpoint, /global-config/services/CorsService, for configuring how to handle cross-origin resource sharing (CORS).

Clients and applications can use the endpoints to configure their own CORS requirements, without having to restart AM or the container in which it runs.

For more information, refer to Configuring CORS Support.

AM 7 introduces support for suspending an authentication tree, and saving any input made so far. The user is sent a URL, sometimes referred to as a magic link, which lets them resume from where they left off, perhaps after closing the browser, in a different browser, or even on a different device.

For more information, refer to Suspended Authentication

AM 7 adds support for applying SameSite cookie rules, as per internet-draft Cookies: HTTP State Management Mechanism.

For more information, refer to Enabling SameSite Cookie Rules.

As part of this change, AM 7 also introduces a filter in its application description file (web.xml) that sets the Secure flag on the cookies AM produces if any of the following is true:

Automatically promoting cookies to secure ensures that the functionality continues to work with the SameSite changes, because you can only opt out of SameSite if a cookie is marked as secure. To ensure that non-secure requests are load-balanced correctly, the amlbcookie cookie is already excluded by default. If you are using a custom cookie for sticky load balancing, you may want to add it to the list of excluded cookies. For more information, refer to Managing the Secure Cookie Filter.

AM 7 adds support for creating Identity Gateway agents. These agents configure the credentials used by Identity Gateway when making policy evaluation calls, and when registering to receive session and policy configuration notifications over the Web Sockets protocol.

For more information, refer to Setting Up AM for the Examples in the Gateway Guide.

AM 7 adds support for failover and affinity deployments of external policy and application stores. Previously you could only specify a single directory server instance, making it a single point of failure.

For details, refer to Setting Up Policy and Application Stores.

AM 7 adds support for OAuth 2.0/OpenID Connect clients to edit and delete their client profile data, as per RFC7592.

Earlier versions of AM offered support for read operations only.

For more information, refer to Dynamic Client Registration.

AM 7 lets client relying parties use the id_token_hint parameter in requests to the authorization endpoint as a hint about the end user’s session. AM uses the ID token to verify whether the end user specified on it has a valid session.

As part of this change, the authorization endpoint supports the new none response type.

For more information, refer to the /oauth2/authorize endpoint and Retrieving Session State without the Check Session Endpoint.

AM 7 adds support for configuring debug logging by using Logback.

Functionality provided by Logback can now be applied to AM’s debug logging output, for example, log file rotation, and file compression.

For more information, refer to Debug Logging.

AM 7 adds support for the JWT profile for OAuth 2.0 Authorization Grant, defined in the RPC 7523 specification.

As part of this feature, AM includes a new agent of the type Trusted JWT Issuer.

For more information, refer to JWT Profile for OAuth 2.0 Authorization Grant.

AM 7 lets you use wildcards (*) in the redirection URI port to match one or more ports.

This feature requires that the URL configured in the redirection URI is localhost, 127.0.0.1, or ::1. For example, http://localhost:*/, https://127.0.0.1:80*/, or \http://[::1]:*.

For more information, refer to the Allow wildcard ports in redirection URIs property in Client Registration.

AM 7 lets clients configure whether the token introspection endpoint should return its response in JSON format or as a JWT, as per the JWT Response for OAuth Token Introspection Internet Draft.

This feature includes a drop-down menu to choose the endpoint’s output format, as well as several parameters to configure whether the JWT should be signed, or signed and encrypted.

By default, even after an upgrade, clients are configured to receive the output in JSON format.

For more information, refer to the /oauth2/introspect endpoint.

AM 7 introduces a session property allowlist setting, Session Properties to return for session queries.

This setting shows a list of properties that can be returned to administrators in a REST session query response.

For more information, refer to Session Property Whitelist Service.

AM 7 supports a new token format called macaroons, that can be used when issuing OAuth 2.0 access and refresh tokens.

Macaroons can have caveats appended to them, to restrict how a token can be used. Macaroons provide additional security, as tokens can be restricted just before use. For example, you can add a 5-second expiry time to a macaroon access token before sending it to an API, or bind it to a TLS client certificate before use.

As part of this change, AM 7 includes the /json/tokens/macaroon endpoint, used to inspect and manipulate macaroons.

For more information, refer to Macaroons as Access and Refresh Tokens.

AM 7 introduces the following Common Federation Configuration settings:

For more information about the Common Federation Configuration settings, see Common Federation Configuration.

AM 7 introduces a number of nodes for profiling devices when using the ForgeRock SDKs:

AM 7 introduces the following authentication nodes:

AM 7 stores SAML v2.0 single sign-on progress as client-side data when using web browsers that support session storage, removing the need to use sticky load balancing.

For more information, refer to Session State Considerations.

AM 7 includes a getSessionInfoAndResetIdleTime endpoint that resets the idle timeout when obtaining information about a session. The existing getSessionInfo endpoint does not reset the idle timeout.

For more information, refer to Managing Sessions (REST).

AM 7 includes a DevOps-friendly way of changing the password of the amAdmin user, based on the secret stores API.

For more information, refer to Changing the amAdmin Password (Secret Stores).

AM 7 adds the am-introspect-all-tokens-any-realm scope, which lets a client introspect tokens issued to other clients, as long as they are registered in the realm of the introspecting client, or in a subrealm of it.

For more information, refer to Special Scopes.

AM 7 introduces a tree shared state called the secure state. In cases where a node needs to process sensitive information later on in the authentication flow, AM promotes the data stored in the transientState object to the secureState object and encrypts it with the key stored in the new am.authn.trees.transientstate.encryption secret ID.

What is affected by this feature?

AM 7 lets you map secrets retrieved from the Google Cloud Key Management Service (KMS) for any feature in AM that supports secret stores.

Support includes:

For more information, refer to Google KMS Secret Stores.

With ForgeRock Go, you can create a secure and seamless login experience by authenticating with any credential on the user’s device that supports FIDO2 WebAuthn.

You can also extend passwordless authentication to include usernameless authentication with popular authenticators that support resident keys; for example, Windows Hello (biometric authenticators).

For information, refer to Configuring Usernameless Authentication with ForgeRock Go.

AM 7 adds support for verifying the attestation data provided by FIDO2 devices against certificate chains issued by the device vendor.

The TM attestation format is now supported.

You can also enable revocation checking, if the certificate chains contain CRL or OCSP entries.

For information, refer to Configuring WebAuthn Trust Anchors.

AM 7.1 includes an Account Active Check authentication module that lets you determine whether an account is marked as active, or locked, without having to run through the rest of the authentication chain.

For details, refer to Account Active Check Module.

The AM /users endpoint now treats _id and username as separate fields that map to LDAP User Search Attribute and Authentication Naming Attribute respectively.

When AM is configured to use different values for these two attributes, and you create a resource without providing an _id, the /users endpoint generates a unique identifier, which is set as the LDAP User Search Attribute.

For more details, refer to Creating Identities.