Changes to Existing Functionality

This chapter covers both "Critical Changes" and "Important Changes" to existing functionality.

Critical Changes

As part of planning your upgrade, you need to consider that certain changes in later AM versions may have an impact on your environment. Usually, these changes are driven by changes in specification, security policies, or performance.

When possible, the upgrade process makes the appropriate changes on AM configuration. However, sometimes you will need to perform additional configuration based on your environment needs.

In addition to mandatory upgrade steps outlined in Upgrading AM Instances, if you are using features described in the following table you will need to perform additional upgrade tasks:

Critical Changes to Existing Functionality
AM VersionComponent or FeatureChange
7User Profile Whitelist

The profile attribute whitelist controls the information returned to non-administrative users when accessing json/user endpoints.

Common profile attributes are whitelisted by default, but you need to add any custom attribute you want your non-administrative users to see. For more information, see "Configuring the User Profile Whitelist".

/json/authenticate Endpoint

When a client makes a call to the /json/authenticate endpoint appending a valid SSO token, AM returns the tokenId field empty if HttpOnly cookies are enabled. For example:

{
    "tokenId":"",
    "successUrl":"/openam/console",
    "realm":"/"
}
Secure Authentication Tree State Secret ID

An AES 256-bit key called directenctest must be available in the environment during upgrade, but it does not need to be the same key that AM provides on the default keystore.

After upgrade, ensure that the am.authn.trees.transientstate.encryption secret ID is always mapped to an existing, resolvable secret or key alias. Failure to do so may result in trees not working as expected.

The Embedded DS

The embedded DS can only be used for single AM instances, for test and demo purposes. Sites are not supported.

Sites using embedded DS servers must be migrated to external DS servers before upgrading.

SAML v2.0 Secrets AM 7 migrated SAML v2.0 to use secret stores. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see "Configuring Secret Stores After Upgrade".
goto and gotoOnFail Query Parameter Redirection Redirection URLs for authentication services, agents, and SAML v.2.0 must be configured in the Validation Service if they are not in the same scheme, FQDN, and port as AM, or are not relative to AM's URL.
Web Agents of a Version Earlier than 5.6.3

Several properties that used to be configured as custom properties (com.sun.identity.agents.config.freeformproperties) have been added as regular properties. Due to this change, upgrading to AM 7 will overwrite the value of the original custom properties with the default value of the new UI properties.

To work around this issue, perform one of the following actions:

  • Upgrade to Web Agents 5.6.3 or later before upgrading to AM 7.

  • After upgrading to AM 7, reconfigure the properties that you configured as custom properties in their new UI counterparts.

Changes on the CTS Reaper Tuning Properties

AM 7 changes the way the CTS reaper searches for expired tokens.

After upgrading, retune the CTS Reaper using the information in "Reaper Search Size".

OpenID Connect Clients Authenticating with JWTs

OpenID Connect clients authenticating with JWTs must include in the JWT a jti claim containing a unique identifier, in line with OpenID Connect Core 1.0 incorporating errata set 1.

Cookie Filter

AM flags cookies as secure if they come through a connection marked as secure, or if they come through HTTPS. See "Managing the Secure Cookie Filter".

6.5.0.2 // 6.5.1OAuth 2.0 Refresh Tokens

AM only issues refresh tokens to clients that have the refresh token grant type configured in their client profile.

After an upgrade to 6.5 or later using the UI or the openam-upgrade-tool .jar file, existing OAuth 2.0 clients are configured to use all grant flows, including the Refresh Token Grant flow.

To configure the refresh token grant type manually, see "To Configure AM to Issue Refresh Tokens".

6.5Recovery Codes Recovery Codes are encrypted, and existing codes are no longer displayed to the user. For more information, see "Upgrading Device Recovery Codes".
Secret Stores AM 6.5 introduced secret stores for OAuth 2.0 and the persistent cookie module. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see "Configuring Secret Stores After Upgrade".
External Configuration Store

DS 6.5 introduced setup profiles, which pre-configure instances for different usages, such as CTS or configuration data. The default base DN for a DS configuration store instance (ou=am-config) is different than the default used by previous versions of AM (dc=openam,dc=forgerock,dc=org).

You should not attempt to run multiple instances of AM where the configuration store base DNs do not match. Use the same configuration store base DNs when configuring external DS 6.5+ instances that will be used simultaneously alongside existing DS 6 or earlier configuration store instances.

For more information, see "Preparing Configuration Stores".

6JSON Endpoints AM's CSRF protection filter requires that either the X-Requested-With or the Accept-API-Version headers are included on requests to endpoints under the json root. For more information, see "Reviewing REST API Versions Before Upgrading".

Important Changes

This section lists changes done to existing functionality, services, endpoints, and others in the current release of AM.

Important Changes in AM 7.0.1
Important Changes in AM 7
  • 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.

    • (AM 6 or earlier) Go to Deployment > Servers > Server Name > Advanced, and check the value of the com.sun.identity.sm.sms_object_class_name advanced property.

      If the value is com.sun.identity.sm.ldap.SMSEmbeddedLdapObject, the server is an evaluation instance of AM, and is using an embedded DS instance as the configuration store.

    • In the server where AM is installed, check if the opends directory exists under the /path/to/openam directory.

      You may have migrated it to an external directory and not deleted the directory, though. Check the files in the opends/logs directory to determine if the embedded DS is running.

    • Go to Deployment > Servers > Server Name > Directory Configuration > Server, and check the value of the host name column.

      When using an external configuration store, the AM instances point to the FQDN of the load balancer in front of the DS cluster, or to the FQDN of the DS affinity deployment.

      When using an embedded configuration store, each AM instance points to its own hostname, since the embedded DS is stored alongside the AM instance.

  • 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.

    Note

    Evaluation installs of AM attempt to automatically add DS's self-signed certificate to the truststore defined by the javax.net.ssl.truststore property.

    If the property is not defined, it creates a copy of the JDK's default lib/security/cacerts truststore, names it truststore, and places it in /path/to/openam/security/keystores/.

    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.

    Consider an example AM deployment configured in https://am.example.com:8443/am:

    URLNeeds to be configured in the Validation Service?
    http://am.example.com:8080/am/XUI/#login Yes, the scheme and port are different.
    https://am.example.com:443/am/XUI/#login Yes, the port is different.
    /am/XUI/#loginNo, the paths relative to the AM URL are trusted.
    https://mypage.example.com/app/logout.jspYes, the scheme, port, and FQDN are different.

    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.

    Tip

    You can use the "Account lockout Node" to check the user status property at any point in the authentication tree, provided that you have first obtained a username.

  • 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:

    DirectoryDescription
    /path/to/openam/configContains files used for configuring AM, for example, the boot.json file.
    /path/to/openam/securityContains directories for storing keys, keystores, and secrets.
    /path/to/openam/varContains folders for transient, writeable data, such as audit and debug log files.

    Note

    New installations of AM 7 will have the new configuration folder layout described above. Upgrading from a previous version will leave the structure the same as in the previous version.

  • 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:

    • User UI, which is located at /openam/XUI. This contains any end user pages. For example, login screens, and user profiles.

    • Admin UI, which is located at /openam/ui-admin. This contains any pages related to the administration of an AM server. Note, administrative logins are delegated to the User UI.

  • 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:

    Previous LocationNew Location
    openam-ui/openam-ui-ria/src/resources/templates/admin/views/common/navigation/_TreeNavigationLeaf.htmlopenam-ui/openam-ui-user/src/resources/themes/default/partials/navigation/_TreeNavigationLeaf.html
    openam-ui/openam-ui-ria/src/resources/templates/user/uma/views/resource/_DeleteLabelButton.htmlopenam-ui/openam-ui-user/src/resources/themes/default/partials/uma/_DeleteLabelButton.html
    openam-ui/openam-ui-ria/src/resources/templates/user/uma/views/resource/_NestedList.htmlopenam-ui/openam-ui-user/src/resources/themes/default/partials/uma/_NestedList.html
    openam-ui/openam-ui-ria/src/resources/templates/user/uma/views/resource/_UnshareAllResourcesButton.htmlopenam-ui/openam-ui-user/src/resources/themes/default/partials/uma/_UnshareAllResourcesButton.html

    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:

    • org.forgerock.openam.debug.prefix

    • org.forgerock.openam.debug.suffix

    • org.forgerock.openam.debug.rotation

    • org.forgerock.openam.debug.rotation.maxsize

    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.1 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:

    com.sun.identity.sm.ChoiceValues

    The class now extends a parent interface that adds no additional methods to implement.

    org.forgerock.openam.secrets.Secrets

    The import for this evolving API class has changed.

  • The ssoadm Command Now Requires a User DN

    The value for the -u parameter when using the ssoadm command now requires the full DN of an administrative user.

    For example:

    $ ./ssoadm list-servers -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f $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:

    • The default value of the for org.forgerock.services.cts.reaper.search.pollFrequencyMilliseconds property has changed from 300000 to 5000 milliseconds (from 5 minutes, to 5 seconds).

    • The org.forgerock.services.cts.reaper.search.pageSize property has been replaced with the org.forgerock.services.cts.reaper.search.tokenLimit.

      In earlier versions of AM, if the amount of expired tokens was larger than the value of the pageSize property, the CTS reaper would make multiple requests of the value of the pageSize property until all expired tokens were deleted.

      On environments with very large amounts of expired tokens, this could lead to very long pruning cycles that could cause a performance degradation on the CTS token store.

      In AM 7, the CTS reaper makes one request of the value of the tokenLimit property, then sleeps for the value of the org.forgerock.services.cts.reaper.search.pollFrequencyMilliseconds property.

      Requesting the reaper to run more times and recover smaller amounts of tokens avoids the performance impact of the previous implementation.

    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:

    • Recovery Flows

      When KBA or email are enabled as security methods, the flow will not stop when the user introduces the invalid username. Instead, AM does one of the following, depending on which security method is configured:

      • Presents the user with a random KBA question before failing.

      • Presents the user with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, but does not actually send an email.

      If both methods are configured, then AM presents the user with the email message.

    • Registration Flow

      When email is enabled as a security method, AM presents the user with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, and then sends an email with a registration link to the address that the user entered.

      Clicking on the link sends the user to the registration page again, and AM shows a message similar to One or more user account values are invalid.

  • 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.

    WDSSO Keytab File
Read a different version of :