Changes to Existing Functionality

Maximum Size of Decompressed JWTs Enforced

A number of AM features accept JWTs to receive information. Some examples are:

These JWTs that AM receives can be signed and/or encrypted. Sometimes, if they are fairly large, they can also be compressed so that requests reach AM faster.

Decompressing a JWT makes it expand in size. By default, AM 7.0.2 rejects any JWT that expands to more than 32 KiB (32768 bytes).

Before upgrade, ensure that the decompressed JWTs your clients send to AM are smaller than 32 KiB before compression. If not, change the default value to a larger number after upgrade.

For more information about changing the default value, see "Controlling the Maximum Size of Compressed JWTs".

Maximum Size of Request Body Enforced

Application servers can usually mitigate against DoS attacks that POST large amounts of form data, but AM endpoints may receive large amounts of POST data in different ways, such as in JSON, JWT, or JWK formats.

By default, AM 7.0.2 rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size, and returns an HTTP 413 error response.

For more information about changing the default value, see "Limiting the Size of the Request Body".

Changes to the OAuth 2.0 and OpenID Connect Clients

AM 7.0.2 returns an error if the administrator tries to save a client configuration containing an unsupported signing or encryption algorithm.

For example, upon saving the configuration, AM will return an error if there is a typo on an algorithm, or a symmetric signing or encryption algorithm is configured on a public client: these algorithms are derived from the client's secret, which public clients do not have.

Clients registering dynamically must also send supported algorithms as part of their configuration, or AM will reject the registration request.

Different features support different algorithms. Refer to the documentation or to the UI for more information.

The following are examples of the errors:

The error messages are also logged at ERROR level, and identify the client ID that the error relates to.

One-Time Passwords Now Stored in Transient State

One-time passwords created by the "HOTP Generator Node" are now stored in the authentication tree's transient state, instead of in the shared state.

Modify any custom authentication nodes or scripts used by the "Scripted Decision Node" to retrieve the one-time passwords from the transient state after upgrading to AM 7.0.2.

For more information about the transient state, see "Storing Secret Values in Transient Tree State and the Secure State".

The OpenID Connect Discovery Endpoint is Now Disabled by Default

The /.well-known/webfinger OpenID Connect discovery endpoint is now disabled by default, and can only be enabled by realm.

To enable the endpoint for a realm, configure the OAuth2 Provider service on the realm and next, enable the new OIDC Provider Discovery switch. Enabling the endpoint for the realm allows searches for users within that realm only.

After upgrading to AM 7.0.2, the endpoint will be enabled on realms that had the OAuth2 Provider service configured. Disable the endpoint on those realms that are not using OpenID Connect discovery.

For more information about the endpoint, see "OpenID Connect Discovery".

Changes to the OAuth 2.0 Introspection Response

The /oauth2/introspect endpoint now returns an additional member, username, which specifies the user that authorized the introspected token.

As part of this change, the user_id member, which was used by earlier versions of the specification, is deprecated. It will be removed in a future version of AM.

This change aligns the endpoint's response with the OAuth 2.0 Token Introspection specification.

Ability to Configure a Failure URL in Server-Side Authentication Scripts

Server-side scripts can now redirect users to specific URLs after authentication failure. For more information, see "Redirecting the User After Authentication Failure".

Upgrading with Embedded DS Is Not Supported

The embedded DS server is not supported for production in AM 7. Therefore, if you have a site configured with embedded DS, you must migrate it to an external DS store before upgrading to AM 7.

See the KB article How do I migrate from an embedded to external DS/OpenDJ in AM/OpenAM (All versions)?.

The embedded DS is deprecated in 7 and will be removed in a future release.

As part of this change, the embedded DS does not support replication, and cannot be configured as part of a site. The relevant replication options for the installer UI and Amster have been removed.

Directory Services 7 is Secure by Default and Requires Secure Connections

Directory Services 7 introduces a secure by default approach. One aspect of this approach is that all connections to DS instances must be secure; for example, by using LDAPS.

To connect to a DS instance using LDAPS, AM requires access to the self-signed certificate that DS generates.

To provide these certificates to AM, you must use a truststore that contains the necessary certificates, and configure AM to use that truststore when starting up.

For more information, see "Preparing a Truststore".

Changes to the goto and gotoOnFail Redirections

Earlier versions of AM redirected the user to the URL specified in the goto and gotoOnFail query string parameters supplied to the authentication service, SAML v2.0 entities, or agents during login and logout. To harden security against phishing attacks, we recommended that you configure the Validation Service.

By default, AM 7 only redirects to the URLs specified in those query string parameters if the URLs are in the same scheme, FQDN, and port as AM, or to URLs relative to AM. You must configure any other URL in the Validation Service.

For more information, "Configuring Success and Failure Redirection URLs".

Changes to Account Lockout in Authentication Trees

AM 7 introduces improvements when handling account lockout when using authentication trees.

The Success and Failure nodes now increment or reset the invalid attempts count, and check the user status property, when reached.

For more information, see "About Account Lockout for Trees"

As part of these changes, the "Data Store Decision Node" does not check the user status property. Tree evaluation continues along the True path if the credentials are correct and the user is found, even if the user status is set to inactive.

The Default Password of the "Demo" Evaluation User Has Changed

The password for the demo user, that AM creates for evaluation purposes, is changing in AM 7:

Old password: changeit

New password: Ch4ng31t

SSO Token Not Returned When Authentication Endpoint Called with an Existing Session and HttpOnly Cookies Are Enabled

When a client appends a valid SSO token to a call to the json/authenticate endpoint, earlier versions of AM return the SSO token again in the tokenIdfield of the JSON response, regardless of the flags configured for the session cookie. For example:

{
    "tokenId":"AQIC5wM2...",
    "successUrl":"/openam/console",
    "realm":"/"
}

AM 7 now returns the tokenId field empty when HttpOnly cookies are enabled. For example:

{
    "tokenId":"",
    "successUrl":"/openam/console",
    "realm":"/"
}

Remember that AM upgrades cookies to secure cookies (except the amlbcookie cookie) when requests arrive over a secure channel.

To check if HttpOnly session cookies are configured, see "Configuring HttpOnly Session Cookies".

Change any custom login pages or applications that were expecting the old response.

AM Configuration Directory Structure Changed

The location of numerous files and directories inside the AM configuration directory has moved, so that similar types of data are stored together.

The following describes the new directories located within the AM configuration directory, for example /path/to/openam:

Audit Event Whitelisting

AM 7 introduces a whitelist that controls the information that can be logged in audit events. AM has a predefined whitelist built in that only records values that do not contain sensitive information.

You can add additional allowed values to the whitelist that are recorded in audit events. You can also override the whitelist by adding items you do not want in the output to a blacklist. Anything added to the blacklist is not recorded in audit events.

When upgrading from a previous version of AM, any blacklisted values are copied into the blacklist of the upgraded server, unless they do not exist in the builtin whitelist, and would therefore not be recorded anyway.

For more information on audit logging, see "Implementing the Audit Logging Service".

Admin UI and User UI

In earlier versions of AM, all of the UI was located at /openam/XUI.

In AM 7, the UI is now split in the following way:

Localizing User-Facing UI Text Requires Rebuilding the UI

In earlier versions of AM, you could copy user-facing localization files in your custom AM .war file. Downloading, localizing, and rebuilding the UI was not necessary.

AM 7 builds the localization text directly into the UI JavaScript files and, therefore, you need to rebuild the UI to apply the localization. Once rebuilt, redeploy the UI or pack it into your custom .war file.

For more information about downloading and rebuilding the UI, see the UI Customization Guide.

UI Templates and Partial Files Moved

In AM 7, the location of the default UI templates and partials has moved, and are now located in the /openam-ui-user/src/resources/themes/default/ directory.

When customizing the layout of the user interface, AM uses the partials and templates from the /themes/default directory if an equivalent file is not found in your customized theme.

As part of these changes, the following files have also moved:

If you have customized any of the files above, ensure that you move them to the new location when upgrading to AM 7.

For more information on customizing the user interface, see the UI Customization Guide.

Debug Logging Now Uses Logback

In earlier versions of AM, debug logging was configured by navigating to Debug.jsp.

AM 7 uses Logback for configuration of debug logging.

To configure debug logging in AM 7, either navigate to Logback.jsp to make temporary changes, or create a logback.xml configuration file in the AM classpath to make persistent changes to debug logging.

For more information on configuring Logback, see Debug Logging.

As Logback can be configured to provide the same functionality, the following properties that could be added to the debugconfig.properties file are no longer used in AM 7:

The Debug.jsp page has also been removed.

LDAPv3Repos LDAP Servers are Now Stored in Comma-Separated Ordered List

For multiple data stores behind a load balancer deployment, AM now stores its servers as a comma-separated list, rather than orderedlist.

For example, given a site configuration, ID 02, with two servers, IDs 01 and 03. In previous releases (prior to AM 7.0.2 and earlier), AM would store the servers as an orderedlist:

$./ldapsearch -p 51636 -D "cn=Directory Manager" -w cangetin -b "ou=services,dc=openam,dc=forgerock,dc=org" "objectclass=*"  > backup.ldif
   $ grep "sun-idrepo-ldapv3-config-ldap-server" backup.ldif
   sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=xxx.example.com:1636|01|02
   sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=zzz.example.com:1636|01|02
   sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=xxx.example.com:1636|03|02
   sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=localhost:51636
   sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=zzz.example.com:1636|03|02

Now, AM stores its multi-server configuration as a comma-separated ordered list:

$./ldapsearch -p 51636 -D "cn=Directory Manager" -w cangetin -b "ou=services,dc=openam,dc=forgerock,dc=org" "objectclass=*"  > backup.ldif
   $ grep "sun-idrepo-ldapv3-config-ldap-server" backup.ldif
   sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=[0]=xxx.example.com:1636|01|02,xxx.example.com:1636|03|02,localhost:51636,zzz.example.com:1636|01|02,zzz.example.com:1636|03|02

request_uri Values Must Be Pre-Registered

In earlier versions of AM, you could configure the OAuth 2.0/OpenID Connect provider to require clients to pre-register their request_uri values.

Now, pre-registration of request_URI values is mandatory, and the option to disable it has been removed.

Advanced Server Property opensso.protocol.handler.pkgs Replaced

In earlier versions of AM, you could configure the opensso.protocol.handler.pkgs property with a value of com.sun.identity.protocol.

AM 7 replaces this property with the new org.forgerock.openam.http.ssl.connection.manager property, which must point to a class that implements the org.forgerock.openam.http.SslConnectionManager interface, which controls both keystore and truststore settings, as well as hostname verification.

The property name and value will be corrected when upgrading from a previous version. However, if you have a value other than com.sun.identity.protocol then you must manually set the value of the new property, and create a new implementation of the org.forgerock.openam.http.SslConnectionManager interface.

Changes to how Supported and Evolving APIs are Labelled in Javadoc

AM 7 alters the way that an API is marked as "supported" or "evolving". To determine if something is supported or evolving, you may need to navigate up through the object hierarchy to see if a parent is labelled. Previously, each item was marked individually.

alg Parameter Removed from Keys Returned by JWK URI Endpoints

AM 7 removes the alg parameter from the keys returned by the JWK URI endpoints. As a result, each kid is now unique.

Support for Encrypted ID Tokens Added to the OpenID Connect End Session Endpoint

In earlier versions of AM, trying to end a session using an encrypted ID token resulted in failure since the request did not include enough information for AM to decrypt the token.

To support ending sessions when ID tokens are encrypted, AM 7 requires that the request to the end session endpoint includes the client ID for which AM issued the ID token.

This change diverges from the specification defined in the OpenID Connect Session Management 1.0-draft 5.

For more information, see "/oauth2/connect/checkSession".

SAML v2.0 Failover is Enabled by Default

In earlier versions of AM, you had to manually enable SAML v2.0 failover, by navigating to Configure > Global Services > SAML v2.0 Service Configuration > Global Attributes, and then selecting the Enable SAML v2.0 failover option.

In AM 7, the Enable SAML v2.0 failover option is enabled by default and cannot be changed. The option no longer appears in the user interface.

For more information, see "Session State Considerations".

SAML v2.0 RelayState Redirection Restricted to Same Domain as the AM Instance

AM 7 alters the behavior of the Relay State URL List whitelisting property. If you do not specify any URLs in this property, AM will only redirect to URLs that match its deployment domain; for example, example.com.

To be able to redirect using the RelayState parameter to a URL that does not match the instance of AM, you MUST add the URL to the Relay State URL List property.

For more information, see Relay State URL List - Hosted IDP or Relay State URL List - Hosted SP

Supported and Evolving APIs May Require Recompilation

The method signature or imports of some supported and evolving APIs may change between versions of AM. We recommend recompiling any customizations implementations you have for each new version of AM.

For example, the following classes related to the Service Management Service (SMS) have changed. Custom implementations that use any of the following require recompiling:

The ssoadm Command Now Requires a User DN

The value for the --adminid (-u) parameter when using the ssoadm command now requires the universal ID of an administrative user.

For example:

$ ./ssoadm list-servers --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org --password-file $HOME/.pwd.txt

For more information, see "To Set Up Administration Tools".

LDAP Connection Pool Property Name Corrected

The com.sun.am.ldap.connection.idle.seconds property has been corrected. If you have any files or scripts which have the previous spelling, com.sun.am.ldap.connnection.idle.seconds, you should correct them to the new, correct spelling.

For more information about this property, see "Tuning LDAP Connectivity".

Service Configuration Notifications Processed Sequentially by Default

The com.sun.identity.sm.notification.threadpool.size property now defaults to 1, which causes notifications to be processed sequentially, avoiding any potential out-of-order conditions.

For more information about this property, see "Notification Settings".

Using the Device Profile Authentication Nodes Requires an Identity Repository Schema Update

If you intend to use the ForgeRock SDKs with the new device profiling authentication nodes that are in AM 7, you may need to update the schema in your identity repository.

You should update the schema if any of the following are true:

Removed Default Value of the Json Web Key URI Field for OAuth 2.0/OpenID Connect Clients

When creating a new OAuth 2.0 or OpenID Connect client, earlier versions of AM set the value of the Json Web Key URI field to the jwk_uri endpoint in AM. For example, https://openam.example.com:8443/openam/oauth2/connect/jwk_uri.

The value of the Json Web Key URI field in the client should not be AM's jwk_uri endpoint, but an external URL holding the client's public JWK.

New clients created in AM 7 will have this field empty to avoid confusion, but existing clients will not be modified after upgrade.

Changes in AM CTS Reaper Tuning Properties

AM 7 changes the name and behavior of some of the advanced server properties used to tune the AM CTS reaper searches:

We recommend that you retune the CTS reaper after upgrading the AM to account for these changes.

For more information and recommendations about these properties, see "Reaper Search Size".

JWT ID Parameter (jti) Required in OpenID Connect JWT Client Authentication

AM 7 now requires that OpenID Connect clients authenticating with a JWT include a jti claim in the JWT containing a unique identifier, in line with OpenID Connect Core 1.0 incorporating errata set 1.

If the claim is missing, AM returns an HTTP 400 invalid_request error with the JWT ID is missing message.

For more related information, see "Authenticating Clients Using JWT Profiles".

Changes to the Audit Logging Service

AM 6.5 introduced the AM-IDENTITY-CHANGE and AM-GROUP-CHANGE audit events to log user and group-related changes our updates such as password changes, user creation and deletion, and others.

AM 7 does not log this information by default, since doing so may have a performance impact on the AM instances.

To configure whether the Audit Logging Service should log these events, AM 7 includes the org.forgerock.openam.audit.identity.activity.events.blacklist advanced server property, which also enables and disables the logging of AM-ACCESS-ATTEMPT events.

This property replaces the org.forgerock.openam.audit.access.attempt.enabled advanced server property, which has been removed.

For more information, see "Advanced Properties".

Changes to the User Self-Service Flows

AM 7 no longer reports if an account does not exist while recovering a username or password, or if an account already exists when registering a new one:

WDSSO: Absolute Path of Keytab File Must Be Specified

When configuring the Windows Desktop SSO (WDSSO) authentication module, the absolute path of the keytab file must be specified, instead of the URL.