Upgrading AM/OpenAM

This book provides information on upgrading AM/OpenAM including best practice advice, recommended procedures for different upgrade scenarios and known issues.


Debug Logging


How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

The purpose of this article is to provide information on enabling message level debug logging in the application web container; this is useful if you are experiencing install or upgrade issues with AM/OpenAM as you cannot enable message level debugging in AM/OpenAM until it is installed. Application web container debugging is also useful for startup issues and access failure issues (permissions).

Enabling Message level debugging in the web application container

You can enable Message level debugging in the web application container if you are experiencing issues during the install or upgrade process by setting the following JVM properties:

-Dcom.iplanet.services.debug.level=message
-Dcom.iplanet.services.debug.directory=WRITABLE_DIRECTORY

where WRITABLE_DIRECTORY should be replaced with the path to an existing directory such as /tmp/openam.

Note

You must remove these JVM parameters and the WRITABLE_DIRECTORY once you have successfully configured AM/OpenAM and then restart the web application container. If you do not do this, your AM/OpenAM debug logs will be diverted to the WRITABLE_DIRECTORY instead of the standard debug directory.

Example using Apache Tomcat™ web container

You would enable Message level debugging by specifying CATALINA_OPTS settings in the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (also typically located in the /tomcat/bin/ directory).

To enable Message level debugging, with output to the /tmp/openam directory:

  1. Add the following line to the setenv.sh file:
    export CATALINA_OPTS="-Dcom.iplanet.services.debug.level=message -Dcom.iplanet.services.debug.directory=/tmp/openam"
  2. Restart the web container.

Once you have successfully configured AM/OpenAM, reverse these changes as follows:

  1. Remove the following line from the setenv.sh file:
    export CATALINA_OPTS="-Dcom.iplanet.services.debug.level=message -Dcom.iplanet.services.debug.directory=/tmp/openam"
  2. Delete the /tmp/openam log directory. 
  3. Restart the web container.

Enabling debugging for access failures in the web application container

You can enable debugging in the web application container if you are experiencing issues with access (permissions) by adding the following JVM property:

-Djava.security.debug=access,failure

For the Tomcat web container, you would add this in the same way as detailed above, that is, add the following line to the setenv.sh file and restart the web container:

export CATALINA_OPTS="-Djava.security.debug=access,failure"

The output from this debugging is shown in the console and will give a failure rule that needs adding to the Java® Permissions list. Add the identified permission and repeat; keeping adding permissions and repeating until you have resolved all the access failures.

See Also

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

How do I enable message level debugging for ssoadm in AM/OpenAM (All versions)?

How do I enable debug logging for troubleshooting Policy Agents (All versions)?

How do I collect JVM data for troubleshooting AM/OpenAM (All versions)?

Sending troubleshooting data to ForgeRock Support for analysis

The java.security.debug System Property

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8696 (OpenAM 13 EmbeddedDJ log spam )


Backing Up


How do I make a backup of configuration data in AM/OpenAM (All versions)?

The purpose of this article is to provide information on backing up configuration data in AM/OpenAM, using DS/OpenDJ tools to provide a more reliable and comprehensive backup than using ssoadm.

Background information

The Configuration directory ($HOME/[am_instance]) contains files created during the install process. Some of these files contain critical information that is required when AM/OpenAM initializes; AM/OpenAM cannot start if these files become corrupt or are missing. For this reason, it is essential to back up the Configuration directory to enable you to recover AM/OpenAM to its original state if needed. The files used when AM/OpenAM initializes includes all the files in the /opends directory and the following files:

  • bootstrap or boot.json depending on your version of AM/OpenAM.
  • keystore.jceks or keystore.jks depending on which keystore you are using.
  • certificate stores
  • openam_mon_auth (used in web based monitoring). This file is not required in AM 5 and later.
  • .version
Note

Although you can use the How do I export and import Service configurations for AM/OpenAM (All versions)? command to back up configuration data, there are some known issues with this approach that are included in the Related Issue Tracker IDs section below; in production environments, it is recommended that you use DS/OpenDJ tools to back up your configuration data if you use DS/OpenDJ as your configuration store.

There are two options available for using DS/OpenDJ tools to back up your configuration directory: 

  • DS/OpenDJ backup and restore - this option is the preferred approach; it should be used when you want to back up configuration data with the intention that you can restore it at a later date, if needed, and it would be replicated to other servers.
  • Export-ldif and import-ldif commands - this option is only required if you may need to revert changes from all replicating servers in the future. Typically this isn't required for configuration data, as you can simply reverse a change if it is no longer required. For example, if you change a configuration setting to TRUE, you can change it back to FALSE to revert the change.

In a replicated environment, the replication changelog has a purge delay of 3 days (by default). With either of these backup options, If you restore a backup taken within this period, the restored server will be able to re-sync with the other DS/OpenDJ servers; if you have an older backup, it will never be able to re-sync. It is therefore important to take periodic backups. 

Caution

It is also recommended that you take a file system backup of the directories for each AM/OpenAM server in your deployment as described in Upgrade Guide › About Upgrading › Back Up the Deployment. If you ever need to restore a corrupted AM/OpenAM server, it is essential to have a backup of your configuration store and the file system backup. Additionally, you should back up the $HOME/.openamcfg/ directory; the file used to bootstrap (the bootstrap locator file) is located in this directory.

Using DS/OpenDJ backup and restore

You can use a backup command such as the following to back up your configuration directory:

$ ./backup --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backUpAll --backupDirectory /path/to/ds/bak --start 0
Note

You only need to specify a start time if you are scheduling the backup; you can use --start 0 to perform the backup immediately.

You can tell that the backup command was successful by checking the error log (located in the $HOME/[am_instance]/opends/logs directory). If the backup was successful, you should see messages similar to this:

[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896349 msg=Backup task 20131030104919093 started execution
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend schema
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend tasks
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend userRoot
[30/Oct/2016:10:49:19 +0000] category=JEB severity=NOTICE msgID=8847446 msg=Archived: 00000000.jdb
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944795 msg=The backup process completed successfully
[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896350 msg=Backup task 20131030104919093 finished execution

You can restore changes using the restore command as follows:

$ ./restore --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backupDirectory /path/to/ds/bak

Using export-ldif and import-ldif

Note

The export-ldif  and import-ldif commands must be on the same deployment as the one where the encryption keys are located.

You can back up and restore the configuration directory using export-ldif and import-ldif as follows:

  1. Back up the configuration directory using an export-ldif command such as:
    $ ./export-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  2. Prepare the replicated domain prior to importing the ldif data: You must specify the baseDN of the data you are going to be changing (that is, the one for which you exported ldif data), for example:
    $ ./dsreplication pre-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt
    
  3. Restore the configuration on all servers using an import-ldif command such as:
    $ ./import-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  4. Enter the following command on one of the servers to set the new generation ID for the entire domain:
    $ ./dsreplication post-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt 

The above steps alter the generation ID of the replicated domain. "Old" changes will not get replayed because they were targeting the data using the previous generation ID. The final step calculates a new generation ID for the domain and broadcasts it to all the servers, which allows them to replicate again.

Replication will now proceed as normal, but from the restored point in time.

See Also

FAQ: Backing up AM/OpenAM

How do I export and import Service configurations for AM/OpenAM (All versions)?

Installing and configuring AM/OpenAM

Setup and Maintenance Guide › Maintaining an Instance › Backing Up and Restoring Configurations

Administration Guide › Backing Up and Restoring Data

Administration Guide › Managing Directory Data

Reference › Tools Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-718 (Agent group membership lost after backup/restore)

OPENAM-3165 (NPE during export-svc-cfg)

OPENAM-3793 (import-svc-cfg overrides serverconfigxml from import)

OPENAM-7928 (ssoadm export-svc-cfg / import-svc-cfg should mention that 'ldif-export / ldif-import' can only be used on the same deployment)


FAQ: Backing up AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding backing up AM/OpenAM.

Frequently asked questions

Q. How often should I perform a backup?

A. The frequency of backups depend on your business needs. You should consider things like how often you make customization and configuration changes, and how important it is for you to keep the audit data in your logs.

Q. Do I have to shutdown the AM/OpenAM server before I take a backup?

A. You must shutdown the AM/OpenAM server before backing up the Configuration directory, backing up the Configuration directory while AM/OpenAM is running can introduce problems with the embedded DS/OpenDJ data store.

However, you can back up the Service configuration while AM/OpenAM is running.

Q. What is the difference between the Service configuration backup and the Configuration directory backup?

A. If you use an embedded DS/OpenDJ for your configuration store and back up the Configuration directory as described in To Back Up All Server Configuration Data, all the LDAP data (which contains the Service configuration data in XML) is backed up, in addition to the bootstrap and configuration files detailed in Q. What types of information are contained in the Configuration directory? The Service configuration is the XML blob contained in LDAP that describes the services, policies, etc. 

Note

If you have an external configuration store, you must make separate backups to ensure that data is recoverable. See How do I design and implement my backup and restore strategies for DS/OpenDJ (All versions)? and FAQ: Backup and restore in DS/OpenDJ if you use DS/OpenDJ.

The Configuration directory backup is the most comprehensive and also includes your Service configuration. You must take a backup of the Configuration directory after you have configured AM/OpenAM, but further backups are only needed if you make changes that affect the files in this directory, such as changing the embedded configuration store’s connection parameters. However, it is recommended that you do still take periodic backups of the Configuration directory to be certain that your backup is current, whilst doing Service configuration exports more regularly per How do I export and import Service configurations for AM/OpenAM (All versions)?

In summary:

  • Backing up the Configuration directory backs up the full configuration.
  • Backing up the Service configuration backs up only a subset of the data.
  • If you have a known good Configuration directory backup, you usually only need to back up the Service configuration regularly, as this is the data most likely to change.
  • If you are already doing full Configuration directory backups regularly, a separate Service configuration backup is redundant.

For best practices, you should only import the configuration data if it is known to be more up-to-date than the configuration it is overwriting,  

Note

It is always good practice to export a configuration before importing a new one.

Q. What types of information are contained in the Configuration directory?

A. The Configuration directory ($HOME/[am_instance]) contains files created during the install process. Some of these files contain critical information that is required when AM/OpenAM initializes; AM/OpenAM cannot start if these files become corrupt or are missing. For this reason, it is essential to back up the Configuration directory to enable you to recover AM/OpenAM to its original state if needed. The files used when AM/OpenAM initializes includes all the files in the /opends directory and the following files:

  • bootstrap or boot.json depending on your version of AM/OpenAM.
  • keystore.jceks or keystore.jks depending on which keystore you are using.
  • certificate stores
  • openam_mon_auth (used in web based monitoring). This file is not required in AM 5 and later.
  • .version

Q. What types of information are contained in the xml file generated by ssoadm export-svc-cfg?

A. It is the content of the configuration store that the ssoadm export-svc-cfg exports into XML format.

It basically exports all the nodes under ou=services,ROOT_SUFFIX. This will contain information including configuration data for realms , policies, identity stores URIs and hostnames.

Q. Do I have to include the AM/OpenAM logs and archived-config directories in my backup as they are quite large?

A. Although these directories can be quite large and are not critical when restoring, it is recommended that they are included in your backups. The log data from your last good backup can be very useful if you experience an outage and need to restore from backup as they may contain errors that help you to identify the reason for the outage. Similarly, the archived configs can be useful for reference.

To reduce the size of these directories, you could consider only keeping these files for a selected period of time and then clearing the old files off the server once this period of time has elapsed.

Q. Is there anything else I should back up?

A. You should take a backup of the openam.war file if you have made any changes; this file does not change by itself. You should also back up any service XML schema files that you have customized; these files are located in the $HOME/[am_instance]/config/xml directory.

Finally, it is a good idea to back up any external resources such as user data stores, policy agents etc.

See Setup and Maintenance Guide › Backing Up and Restoring Configurations for further information.

Note

It is also recommended that you take a file system backup of the directories for each AM/OpenAM server in your deployment as described in Upgrade Guide › Back Up the Deployment. If you ever need to restore a corrupted AM/OpenAM server, it is essential to have a backup of your configuration store and the file system backup. Additionally, you should back up the $HOME/.openamcfg/ directory; the file used to bootstrap (the bootstrap locator file) is located in this directory.

See Also

How do I make a backup of configuration data in AM/OpenAM (All versions)? 

FAQ: Backup and restore in DS/OpenDJ

Upgrading AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)


Best Practices


Best practice for upgrading to AM 6.x

The purpose of this article is to provide best practice advice on upgrading to AM 6.x as there are some known issues regarding the upgrade process and issues that may affect you post-upgrade.

Overview

Preparing for Upgrade

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up-to-date backups and recovery plans in case you encounter any issues. You should also make sure you read the AM 6.5 Release Notes and AM 6 Release Notes so that you are fully aware of all changes as well as release notes and Best Practice upgrade articles relevant to any releases between the version you are upgrading from and AM 6.x. 

Before upgrading, you must ensure the following are true:

  • Anonymous access is permitted in DS/OpenDJ
  • Token Signing HMAC Shared Secret is defined for OAuth2 Providers
  • Referrals do not exist in the top level realm

Anonymous access is permitted in DS/OpenDJ

The upgrade is likely to fail if you have disabled anonymous access in DS/OpenDJ by editing relevant global-aci properties or using the following command:

$ ./dsconfig --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:true --trustAll --no-prompt

See Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ for further information on this issue.

Token Signing HMAC Shared Secret is defined for OAuth2 Providers

Upgrading to AM 6 (6.0.0.0 to 6.0.0.4) will fail if the Token Signing HMAC Shared Secret (tokenSigningHmacSharedSecret) is missing. You should ensure this property exists for all OAuth2 Providers.

This is a known issue: OPENAM-13414 (Upgrade to AM6 fails if OAuth2 Provider service lacks tokenSigningHmacSharedSecret), which is resolved in AM 6.0.0.5.

Referrals do not exist in the top level realm

Upgrading to AM 6 will fail if referrals exist in the top level realm, where URL patterns from the referral are being used in sub-realm policies; referrals were removed in OpenAM 13, so this issue will only affect you if you are upgrading from OpenAM 12.x.

If you have referrals in the top level realm, you should delete the referrals and policies prior to upgrade and then re-create the policies in the appropriate realms once you have upgraded.

This is a known issue: OPENAM-12120 (Referrals On Top Level Realm won't allow upgrade to 5.5.1).

Known issues - upgrade process

The following known issues may affect you during the upgrade process - workarounds are included where applicable:​

  • External CTS needs additional schemas after upgrade
  • Custom authentication modules cannot be updated after upgrade

External CTS needs additional schemas after upgrade

When upgrading to AM 6.x from a previous version, you need to import the following schemas else you will not be able to log in:

  • cts-add-multivalue.ldif
  • cts-add-multivalue-indices.ldif

This step is detailed in the Upgrade Guide › To Upgrade From a Supported Version.

Custom authentication modules cannot be updated after upgrade

When upgrading to AM 6 from OpenAM 12.x, there is a known issue which prevents custom authentication modules being updated. This is because schemas in the definition of an authentication service must now contain resourceName attributes. The necessary steps to resolve this are documented: OpenAM 13 Release Notes › Important Changes to Existing Functionality; these can be performed before or after upgrading to AM 6.

If you are upgrading from AM 5.x or OpenAM 13.x, your schema will already be correct. 

Known issues - post upgrade

 The following known issues may affect you post-upgrade - workarounds are included where applicable:​

  • LDAP connection fails with No subject alternative DNS name matching error
  • Internal Server Error response to OAuth2 endpoints after making changes to the keystore
  • Login page does not load or ssoadm fails after upgrading to Apache Tomcat™ 8.5 or 9
  • Minimum password length is 8 error when updating identities via REST
  • Service configuration import fails with Amster if you have a site configured
  • User attributes in SAML responses are not correctly mapped
  • Intermittent shutdown issues

LDAP connection fails with No subject alternative DNS name matching error

Changes in AM and DS have made LDAP SSL hostname validation stricter. You must ensure the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). See LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x for further details about this issue and solution.

Internal Server Error response to OAuth2 endpoints after making changes to the keystore

AM 5 introduced a new configuration property for the signing key alias used by Agents 5, which defaults to test. If you have changed your keystore and/or the default key alias without updating this key alias, you will see an "Internal Server Error". The necessary steps to resolve this are documented in the following Solution article:  Unable to retrieve certificate with alias 'test' from keystore after making changes to the keystore in AM (All versions)

Login page does not load or ssoadm fails after upgrading to Tomcat 8.5 or 9

Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

Minimum password length is 8 error when updating identities via REST

There is a known issue with updating identities via REST where the "Minimum password length is 8" error is shown even though the user's password is valid: OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API). The necessary steps to resolve this are documented in the following Solution article: Minimum password length is 8 error in AM (All versions) when updating identities using the REST API

Service configuration import fails with Amster if you have a site configured

There is a known issue with importing the service configuration using Amster if you have a site configured: OPENAM-11159 (OpenAM Amster export/import for Site have import errors). The necessary steps to resolve this are documented in the following Solution article: Only url, secondaryURLs and _id are valid in write error when importing configuration data via Amster in AM (All versions)

User attributes in SAML responses are not correctly mapped

There is a known issue that can prevent user profile attributes being returned in SAML responses. This issue occurs if you upgrade to AM 6.x and use a custom IdP attribute mapper that extends DefaultLibraryIDPAttributeMapper: OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade). You should revisit your custom IdP mapper code and update any method names that have changed. Alternatively, you could extend DefaultIDPAttributeMapper instead. This class is available from the OpenFM-6.x.x.jar file located in the WEB-INF/lib directory of the AM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.

Intermittent shutdown issues

There is a known issue where AM 6 does not fully shut down after issuing the shutdown command: OPENAM-13008 (Occasional shutdown error for AM). The necessary steps to resolve this are documented in the following Solution article: Error during shutdown message when stopping an AM 6 instance running on Apache Tomcat. This issue is resolved in AM 6.0.0.1.

Other changes

You should also be aware of the following changes in behavior: 

  • Cross-Site Request Forgery (CSRF) improvements: a new CSRF filter has been included, which is enabled by default. In essence, this means that all REST calls (other than GET, HEAD or OPTIONS) to REST endpoints under the json/ root now require at least one of the following headers:
    • X-Requested-With
    • Accept-API-Version
    See Release Notes › New Features for further information.
  • Authentication trees and nodes (intelligent authentication): additional authentication nodes have been included in AM 6 and a Best Practices has been provided to aid with migration: Best practice for migrating Authentication Chains to Trees in AM 6.x.

See Release Notes › Important Changes to Existing Functionality for information about all changes to existing functionality.

See Also

Upgrades

Back Up and Restore

Upgrade Guides and Release Notes

Troubleshooting

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-12120 (Referrals On Top Level Realm won't allow upgrade to 5.5.1).

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)

OPENAM-11159 (OpenAM Amster export/import for Site have import errors)

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)


Best practice for upgrading to AM 5.x

The purpose of this article is to provide best practice advice on upgrading to AM 5.x as there are some known issues regarding the upgrade process and issues that may affect you post-upgrade.

Overview

Preparing for Upgrade

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up-to-date backups and recovery plans in case you encounter any issues. You should also make sure you read the AM 5.5 Release NotesAM 5.1 Release Notes and AM 5 Release Notes so that you are fully aware of all changes as well as release notes and Best Practice upgrade articles relevant to any releases between the version you are upgrading from and AM 5.x. 

You should ensure the following are true prior to upgrading:

  • Anonymous access is permitted in DS/OpenDJ
  • Referrals do not exist in the top level realm

Anonymous access is permitted in DS/OpenDJ

The upgrade is likely to fail if you have disabled anonymous access in DS/OpenDJ using the following command:

$ ./dsconfig --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:true --trustAll --no-prompt

See Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ for further information on this issue.

Referrals do not exist in the top level realm

Upgrading to AM 5.5.1 will fail if referrals exist in the top level realm, where URL patterns from the referral are being used in sub-realm policies; referrals were removed in OpenAM 13, so this issue will only affect you if you are upgrading from a pre-OpenAM 13 version.

If you have referrals in the top level realm, you should delete the referrals and policies prior to upgrade and then re-create the policies in the appropriate realms once you have upgraded.

This is a known issue: OPENAM-12120 (Referrals On Top Level Realm won't allow upgrade to 5.5.1).

Known issues - upgrade process

The following known issues may affect you during the upgrade process - workarounds are included where applicable:​

  • Configuration fails if you have an external user store in AM 5.5.x
  • External CTS needs additional schemas after upgrade
  • Custom authentication modules cannot be updated after upgrade
  • Not found error when viewing authentication modules after upgrading to AM 5 or 5.1.x

Configuration fails if you have an external user store in AM 5.5.x

The Demo user should only be created in an embedded user store, but a known issue in AM 5.5.x causes the configurator or Amster to incorrectly attempt to create the Demo user in an external user store if the configuration store is embedded: OPENAM-11909 (Demo user creation is based on whether a userCfg is specified, rather than when it's set to embedded). This action causes the configuration to fail. You can workaround this issue by either configuring an embedded user store or by using an external configuration store with your external user store.

External CTS needs additional schemas after upgrade

When upgrading to AM 5.x from a previous version, you need to import the following schemas else you will not be able to log in:

  • cts-add-multivalue.ldif
  • cts-add-multivalue-indices.ldif

See Installation Guide › CTS Installation Script for a sample install script that imports these schemas.

Custom authentication modules cannot be updated after upgrade

When upgrading to AM 5.x from OpenAM 12.x, there is a known issue which prevents custom authentication modules being updated. This is because schemas in the definition of an authentication service must now contain resourceName attributes. The necessary steps to resolve this are documented: OpenAM 13 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality; these can be performed before or after upgrading to AM 5.x. If you are upgrading from OpenAM 13.x, your schema will already be correct. 

Not found error when viewing authentication modules after upgrading to AM 5 or 5.1.x

When upgrading to AM 5 or 5.1.x, there is a known issue that prevents access to authentication modules in the console if they have the same name and type: OPENAM-9156 ('Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type). See Creating authentication module via ssoadm causes Not found error in AM 5, 5.1.x and OpenAM 13.0, 13.5 for further information. This issue is resolved in AM 5.5.

Known issues - post upgrade

 The following known issues may affect you post-upgrade - workarounds are included where applicable:​

  • Login page does not load or ssoadm fails after upgrading to Apache Tomcat™ 8.5 or 9
  • Internal Server Error response to OAuth2 endpoints after making changes to the keystore
  • Minimum password length is 8 error when updating identities via REST
  • WDSSO authentication fails after upgrading to AM 5.1.1
  • Service configuration import fails with Amster if you have a site configured
  • ssoadm commands fail after importing a service configuration using Amster
  • User attributes in SAML responses are not correctly mapped
  • Internal server error when using the User Self-Service

Login page does not load or ssoadm fails after upgrading to Tomcat 8.5 or 9

Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

Internal Server Error response to OAuth2 endpoints after making changes to the keystore

AM 5 introduced a new configuration property for the signing key alias used by Agents 5, which defaults to test. If you have changed your keystore and/or the default key alias without updating this key alias, you will see an "Internal Server Error". The necessary steps to resolve this are documented in the following Solution article:  Unable to retrieve certificate with alias 'test' from keystore after making changes to the keystore in AM (All versions)

Minimum password length is 8 error when updating identities via REST

There is a known issue with updating identities via REST where the "Minimum password length is 8" error is shown even though the user's password is valid: OPENAM-11052 (Minimum password length is 8 error in AM 5 when updating identities using the REST API). The necessary steps to resolve this are documented in the following Solution article: Minimum password length is 8 error in AM (All versions) when updating identities using the REST API

WDSSO authentication fails after upgrading to AM 5.1.1

There is a known issue with WDSSO authentication after upgrading to AM 5.1.1:  OPENAM-11610 (WindowSSO module broken in AM 5.1.1 after upgrade). This issue is resolved in AM 5.5.

Service configuration import fails with Amster if you have a site configured

There is a known issue with importing the service configuration using Amster if you have a site configured: OPENAM-11159 (OpenAM Amster export/import for Site have import errors). The necessary steps to resolve this are documented in the following Solution article: Only url, secondaryURLs and _id are valid in write error when importing configuration data via Amster in AM (All versions)

ssoadm commands fail after importing a service configuration using Amster

There is a known issue with running an ssoadm command after importing and exporting a service configuration using Amster: OPENAM-11307 (Amster export should include the com.iplanet.am.version property). The necessary steps to resolve this are documented in the following Solution article: ssoadm command fails to run with null pointer exception in AM 5 and 5.1.x. This issue is resolved in AM 5.5.

User attributes in SAML responses are not correctly mapped

There is a known issue that can prevent user profile attributes being returned in SAML responses. This issue occurs if you upgrade to AM 5.x and use a custom IdP attribute mapper that extends DefaultLibraryIDPAttributeMapper: OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade). You should revisit your custom IdP mapper code and update any method names that have changed. Alternatively, you could extend DefaultIDPAttributeMapper instead. This class is available from the OpenFM-5.x.x.jar file located in the WEB-INF/lib directory of the AM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.

Internal server error when using the User Self-Service

There is a known issue where the global User Self-Service UI does not display the default values that are returned by the server, which causes an "Internal server error" when using the User Self-Service: OPENAM-11057 (Global User Self Service UI does not display values). The necessary steps to resolve this are documented in the following Solution article: Internal server error when using User Self-Service in AM 5 and 5.1. This issue is resolved in AM 5.1.1.

Other changes

You should also be aware of the following changes in behavior: 

Note

AM 5.x is not fully autonomous and crosstalk still occurs for SAML; this crosstalk should be eliminated in a future release. Similarly, policy agent sessions are held in memory rather than being stored in the CTS token store.

  • SSO tokens incompatibility: SSO tokens created in pre-AM 5 versions are not valid in AM 5, meaning users will need to reauthenticate once you have upgraded. See Upgrade Guide › About Upgrading › Supported Upgrade Paths for further information.
  • Clickjacking protection: The X-Frame-Options header is now set to SAMEORIGIN to prevent the page being framed by a malicious site. See FAQ: General AM/OpenAM (Q. How can I protect AM/OpenAM from Clickjacking?) for further information. This change may affect you if you have an existing application that uses frames.
  • Auto-generated OAuth2 policy (OAuth2ProviderPolicy) is no longer created in AM 5.5.x: When you configure AM/OpenAM as an OpenID Connect authorization server in AM 5.5.x, the default OAuth2ProviderPolicy is no longer created as it is not needed.
  • The server-only war file was removed in OpenAM 13: This was previously used to remove console access. You can still remove console access in AM 5.x as detailed in How do I remove console access in AM (All versions) and OpenAM 13.x?

See Release Notes › Important Changes to Existing Functionality for information about all changes to existing functionality.

See Also

Upgrades

Back Up and Restore

Upgrade Guides and Release Notes

Troubleshooting

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-12120 (Referrals On Top Level Realm won't allow upgrade to 5.5.1).

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)

OPENAM-11420 (AM 5 is not fully Autonomous )

OPENAM-11307 (Amster export should include the com.iplanet.am.version property)

OPENAM-11159 (OpenAM Amster export/import for Site have import errors)

OPENAM-11057 (Global User Self Service UI does not display values)

OPENAM-11052 (Minimum password length is 8 error in AM 5 when updating identities using the REST API)

OPENAM-10966 (Missing step for upgrade from AM 13 to 14 - CTS)

OPENAM-10451 (Could not get OpenDJ 2.6.4 to work with OpenAM 14.0.0M10 for External CTS setup)

OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret')


Best practice for upgrading to OpenAM 13.x

The purpose of this article is to provide best practice advice on upgrading to OpenAM 13.x as there are some known issues regarding the upgrade process and issues that may affect you post-upgrade.

Overview

Preparing for Upgrade

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the OpenAM 13 Release Notes and OpenAM 13.5 Release Notes so that you are fully aware of all the changes. 

You should ensure the following are true prior to upgrading:

  • Anonymous access is permitted in OpenDJ
  • Referral rules are correct
  • Policy and rule names are valid

Anonymous access is permitted in OpenDJ

The upgrade is likely to fail if you have disabled anonymous access in OpenDJ using the following command:

$ ./dsconfig --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:true --trustAll --no-prompt

See Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ for further information on this issue.

Referral rules are correct

You should have three referral rules from the top-level realm as per changes that were introduced in OpenAM 11.0.0. Neglecting to have three referral rules will cause your upgrade to fail as detailed in Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies.

You should have three referral rules as follows: 

  • root "/"
  • pages "/*"
  • pages with parameters "/*?*"

See Best practice for creating and testing policies in AM/OpenAM (All versions) for further information on creating and testing policies in OpenAM 13.x.

Caution

Although referrals are not used in OpenAM 13, they still need to be correct prior to upgrading as they are processed during the upgrade procedure as detailed in OpenAM Upgrade Guide › Upgrading OpenAM Servers

Policy and rule names are valid

OpenAM 12.0.0 introduced a new policy engine and policy editor, which means policies are migrated as part of the upgrade process when upgrading to OpenAM 13.x from a pre-OpenAM 12 version. You need to ensure that rule names don't include forward slashes and rule / policy names don't include special characters.

See Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x for further information on policies being migrated and the steps you can take to ensure it is successful.

Known issues - upgrade process

The following known issues may affect you during the upgrade process - workarounds are included where applicable:​

  • OAuth client configurations inherit default response types
  • Upgrade to OpenAM 13.x fails with Failed to modify privilege! when migrating policies
  • Custom authentication modules cannot be updated after upgrade
  • Not found error when viewing authentication modules after upgrading to OpenAM 13.0 or 13.5

OAuth client configurations inherit default response types

When upgrading from OpenAM 11.x, there is a known issue: OPENAM-4076 (Upgrade 11.x->12 cannot successfully migrate configured OAuth2 clients), which causes OAuth client configurations to inherit default response types. The necessary post-upgrade steps to resolve this are documented in the Upgrade guide: To Complete Upgrade from OpenAM 11

Upgrade to OpenAM 13.x fails with Failed to modify privilege! when migrating policies

When upgrading from a pre-OpenAM 12.0.0 release, there is a known issue: OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails) that only occurs if the policies are being migrated to the OpenAM 12.x or 13.x format for the first time. The necessary steps to resolve this are documented in the following Solution article Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies.

Custom authentication modules cannot be updated after upgrade

When upgrading to OpenAM 13.x from an earlier release, there is a known issue which prevents custom authentication modules being updated. This is because schemas in the definition of an authentication service must now contain resourceName attributes. The necessary steps to resolve this are documented in the Release Notes: OpenAM Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality; these can be performed before or after upgrading to OpenAM 13.x.

Not found error when viewing authentication modules after upgrading to OpenAM 13.0 or 13.5

When upgrading to OpenAM 13.0 or 13.5, there is a known issue that prevents access to authentication modules in the OpenAM console if they have the same name and type: OPENAM-9156 ('Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type). See Creating authentication module via ssoadm causes Not found error in AM 5, 5.1.x and OpenAM 13.0, 13.5 for further information. This issue is resolved in OpenAM 13.5.1.

Known issues - post upgrade

 The following known issues may affect you post-upgrade - workarounds are included where applicable:​

  • Login page does not load or ssoadm fails after upgrading to Apache Tomcat™ 8.5 or 9
  • SAML redirect is ignored when doing an IdP or SP initiated SSO with WDSSO/Kerberos authentication in OpenAM 13.0 and 13.5
  • OpenAM 13.5 redirects to server URL instead of site URL in load balanced environment
  • JCEEncryption errors when accessing the OpenAM console after upgrading to OpenAM 13.0
  • Policy import fails in OpenAM 13.0 with Invalid resource type null message
  • Authentication fails in OpenAM 13.0 with an AuthId JWT Signature not valid error
  • Poor OAuth 2.0 performance
  • User attributes in SAML responses are not correctly mapped

Login page does not load or ssoadm fails after upgrading to Tomcat 8.5 or 9

Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

SAML redirect is ignored when doing an IdP or SP initiated SSO with WDSSO/Kerberos authentication in OpenAM 13.0 and 13.5

There is a known issue in OpenAM 13.0 and 13.5, which causes the SAML redirect to be ignored in certain circumstances: OPENAM-8971 (currentGoto : null is received in XUI when a realm dns is being used for Federation and authentication is done via wdsso/kerberos auth module). The necessary steps to resolve this are documented in the following Solution article: SAML redirect is ignored when doing an IdP or SP initiated SSO with WDSSO/Kerberos authentication in OpenAM 13.0 and 13.5. This issue is resolved in OpenAM 13.5.1.

OpenAM 13.5 redirects to server URL instead of site URL in load balanced environment

There is a known redirect issue in OpenAM 13.5 after changing server properties:  OPENAM-9628 (Strange 400 response after changing advanced default server properties from site URL). The necessary steps to resolve this are documented in the following Solution article: OpenAM 13.5 redirects to server URL instead of site URL in load balanced environment. This issue is resolved in OpenAM 13.5.1.

JCEEncryption errors when accessing the OpenAM console after upgrading to OpenAM 13.0

There is a known issue in OpenAM 13.0 that prevents access to the OpenAM console: OPENAM-8214 (JCEEncryption errors are recorded during/after upgrading to 13). The necessary steps to resolve this are documented in the following Solution article: JCEEncryption:: failed to decrypt data error when accessing the admin console in OpenAM 12.x or 13.x.

Policy import fails in OpenAM 13.0 with Invalid resource type null message

There is a known issue with importing a policy in OpenAM 13.0 that was previously exported from OpenAM 12.x or 11.x: OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it). The necessary steps to resolve this are documented in the following Solution article: Policy import fails in OpenAM 13.0 with Invalid resource type null message. This issue is resolved in OpenAM 13.5.

Authentication fails in OpenAM 13.0 with an AuthId JWT Signature not valid error

There is a known issue in OpenAM 13.0, which causes authentication to fail in multi-instance deployments or single-instance deployments that have disabled caching: OPENAM-8269 ("AuthId JWT Signature not valid" error in multi-instance deployments on 13). The necessary steps to resolve this are documented in the following Solution article: Authentication fails in OpenAM 13.0 with an AuthId JWT Signature not valid error. This issue is resolved in OpenAM 13.5.

Poor OAuth 2.0 performance

There is a known performance issue when using OAuth 2.0 in OpenAM 13.0: OPENAM-8023 (OAuth2 load: contention at com.sun.identity.sm.ServiceConfigImpl.getInstance level (perf regression compared to AM12.0.2)). The necessary steps to mitigate this issue are documented in the following article: How do I improve OAuth 2.0 performance in OpenAM 13.0? This issue is resolved in OpenAM 13.5. 

User attributes in SAML responses are not correctly mapped

There is a known issue that can prevent user profile attributes being returned in SAML responses. This issue occurs if you upgrade to OpenAM 13.5.1 and use a custom IdP attribute mapper that extends DefaultLibraryIDPAttributeMapper: OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade). You should revisit your custom IdP mapper code and update any method names that have changed. Alternatively, you could extend DefaultIDPAttributeMapper instead.

Other changes

You should also be aware of the following changes in behavior: 

See Also

Upgrades

Back Up and Restore

OpenAM 13.x Upgrade Guides and Release Notes

Troubleshooting

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)

OPENAM-8269 ("AuthId JWT Signature not valid" error in multi-instance deployments on 13)

OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret')

OPENAM-8023 (OAuth2 load: contention at com.sun.identity.sm.ServiceConfigImpl.getInstance level (perf regression compared to AM12.0.2))

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service)

OPENAM-4076 (Upgrade 11.x->12 cannot successfully migrate configured OAuth2 clients)

OPENAM-3498 (IdRepo connection pool fails if anonymous access is disabled)


Best practice for upgrading to OpenAM 12.x

The purpose of this article is to provide best practice advice on upgrading to OpenAM 12.x as there are some known issues regarding the upgrade process.

Preparation

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the OpenAM Release Notes relating to the new version of OpenAM so that you are fully aware of all the changes. 

You should ensure the following are true prior to upgrading:

  • Anonymous access is permitted in OpenDJ
  • Referral rules are correct
  • Policy and rule names are valid

Anonymous access is permitted in OpenDJ

The upgrade is likely to fail if you have disabled anonymous access in OpenDJ using the following command:

$ ./dsconfig -p [adminport] -h [hostname] -D "cn=Directory Manager" -w [password] set-global-configuration-prop -X -n --set reject-unauthenticated-requests:true 

where [adminport], [hostname] and [password] are specific to your environment.

See Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ for further information on this issue.

Referral rules are correct

You should have three referral rules from the top-level realm as per changes that were introduced in OpenAM 11.0.0. Neglecting to have three referral rules will cause your upgrade to fail as detailed in Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies.

You should have three referral rules as follows: 

  • root "/"
  • pages "/*"
  • pages with parameters "/*?*"

See Best practice for creating and testing policies in AM/OpenAM (All versions) for further information on creating and testing policies in OpenAM 12.x.

Policy and rule names are valid

OpenAM 12.0.0 introduces a new policy engine and policy editor, which means policies are migrated as part of the upgrade process when upgrading to OpenAM 12.x. You need to ensure that rule names don't include forward slashes and rule / policy names don't include special characters.

See Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x for further information on policies being migrated and the steps you can take to ensure it is successful.

Known issues

The following issues are known regarding the upgrade process, including workarounds where applicable:

  • Upgrade hangs when configuration and CTS stores are external
  • Upgrade fails when CTS store is external and has a non-default suffix
  • CTS port settings revert to default
  • OAuth client configurations inherit default response types
  • Oracle® WebLogic class file conflict

Upgrade hangs when configuration and CTS stores are external

When upgrading to OpenAM 12.x, the upgrade may hang because the default connection pool sizing of 10 is too small. This is a known issue, which is fixed in OpenAM 12.0.2: OPENAM-6456 (Upgrading to OpenAM 12 hangs in DirectoryContentUpgrader).

See Upgrade to OpenAM 12.0.0 or 12.0.1 hangs in DirectoryContentUpgrader when configuration and CTS stores are external for further information and a workaround to resolve this issue.

Upgrade fails when CTS store is external and has a non-default suffix

When upgrading to OpenAM 12.x, the upgrade may fail because OpenAM looks up the default suffix for the external CTS store and then tries to create it even though it does exist (but as a different suffix). This is a known issue, which is fixed in OpenAM 12.0.2: OPENAM-6457 (DirectoryContentUpgrader causes Entry Already Exists exception for CTS suffix when upgrading OpenAM).

See Upgrade to OpenAM 12.0.0 or 12.0.1 fails with Entry Already Exists exception when CTS store is external with non-default suffix for further information.

CTS port settings revert to default

When upgrading to OpenAM 12.0.0, the CTS port settings revert to 389. You should check and correct your CTS port settings if they should be anything other than 389. This is a known issue, which is fixed in OpenAM 12.0.1: OPENAM-5183 (CTS port settings are reverted to default when doing upgrade from AM 11 to AM 12).

OAuth client configurations inherit default response types

When upgrading from OpenAM 11.x, there is a known issue OPENAM-4076 (Upgrade 11.x->12 cannot successfully migrate configured OAuth2 clients) which causes OAuth client configurations to inherit default response types. The necessary post-upgrade steps to resolve this are documented in the Upgrade guide: To Complete Upgrade from OpenAM 11.0.

Oracle WebLogic class file conflict

If you use an Oracle WebLogic server, you may experience a class file conflict depending on which version of OpenAM you have come from (pre-OpenAM 11.0.0 only) and the version of Oracle WebLogic you are running. The following Solution articles outline the issues you may experience depending on your Oracle WebLogic version:

Upgrade to OpenAM 12.0.x or 13.x fails with Failed to modify privilege! when migrating policies

When upgrading from a pre-OpenAM 12.0.0 release, there is a known issue OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails) that will only occur if the policies are being migrated to the OpenAM 12.x or 13.x format for the first time. The necessary steps to resolve this are documented in the following Solution article  Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x 

OpenAM 12.0.0, 12.0.1, 12.0.2 and 13.0 login fails with User name/password combination is invalid error if you use host-based cookies

How do I upgrade AM/OpenAM (All versions) with minimal downtime when replication is used?

How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

FAQ: Upgrading AM/OpenAM

OpenAM 12 Upgrade Guide

OpenAM 12.0.4 Release Notes

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3498 (IdRepo connection pool fails if anonymous access is disabled)

OPENAM-4076 (Upgrade 11.x->12 cannot successfully migrate configured OAuth2 clients)

OPENAM-5183 (CTS port settings are reverted to default when doing upgrade from AM 11 to AM 12)

OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service)

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-6455 (ConnectionCount logic does not produce a sensible ConnectionFactory max pool size for some scenarios)

OPENAM-6456 (Upgrading to OpenAM 12 hangs in DirectoryContentUpgrader)

OPENAM-6457 (DirectoryContentUpgrader causes Entry Already Exists exception for CTS suffix when upgrading OpenAM)

OPENAM-6499 (Configuration store servers are not listed in Directory Configuration)


Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

The purpose of this article is to provide best practice advice on migrating policies when upgrading to OpenAM 12.x or 13.x from a pre-OpenAM 12 release. OpenAM 12.0.0 introduced a new policy engine and policy editor.

Archived

This article has been archived and is no longer maintained by ForgeRock.

Prerequisites

Before you upgrade to OpenAM 12.x or 13.x, you should read: 

OpenAM 12.0.0 introduced many changes to policies and it is worth understanding how these will affect you when migrating and creating policies. As of OpenAM 13, referral policies are no longer available in OpenAM. If you are upgrading from a previous version of OpenAM and currently use referral policies, please refer to OpenAM 13 Upgrade Guide › Upgrading OpenAM Servers for migration information.

Referral rules

Note

You should also have three referral rules from the top-level realm as per changes that were introduced in OpenAM 11.0.0. Neglecting to have three referral rules will cause your upgrade to fail as detailed in Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies.

You should have three referral rules as follows: 

  • root "/"
  • pages "/*"
  • pages with parameters "/*?*"

See Best practice for creating and testing policies in AM/OpenAM (All versions) for further information on creating and testing policies in OpenAM 12.x and 13.x.

Note

Although referrals are not used in OpenAM 13, they still need to be correct prior to upgrading as they are processed during the upgrade process as detailed in OpenAM 13 Upgrade Guide › Upgrading OpenAM Servers.

Check your Pre-OpenAM 12 policies for forward slashes and spaces

Policies are migrated as part of the upgrade process when upgrading to OpenAM 12.x or 13.x from an earlier version; during this process, the new policy name is formed as follows:

"pre-upgrade policy name"_"pre-upgrade rule name"

Therefore if you had a policy name of AdminUsers and a rule name of AllowGET/POST in OpenAM 11.x, the migrated policy would have the following name:

AdminUsers_AllowGET/POST

Due to the forward slash in the migrated policy name, you would not be able to edit or delete the policy in OpenAM 12.x or 13.x if you are running either the Apache Tomcat™ or JBoss® web containers without setting the ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true argument in the CATALINA_OPTS environment variable before starting the OpenAM web container. 

Caution

This is a Tomcat / JBoss imposed limitation and it is strongly recommended that you do not set this argument when running OpenAM in production as it introduces a security risk. See OpenAM 12.0.0 Release Notes › OpenAM Changes & Deprecated Functionality › Important Changes to Existing Functionality for further information.

Note

There is a known issue with forward slashes at the end of policy names that affects all web containers:  OPENAM-5400 (Policy Editor: Unable to edit/delete policy whose name ends in a '/' character). This is fixed in OpenAM 12.0.3 and later.

If you do have forward slashes or spaces in your rule names, you have two options:

  • Pre-Upgrade - Export all your pre-OpenAM 12.x policies, edit them to remove the forward slashes and spaces from the rule names and then reimport them prior to performing the upgrade. This can be time consuming if you have lots of realms as you would have to do this per realm.
  • Post-Upgrade - Perform the upgrade to OpenAM 12.x or 13.x. Export all your policies to a single XACML file, edit it to remove the forward slashes and spaces from the policy names and then reimport the XACML file. This approach would be simpler if you have lots of realms and policies as you only need to edit one file.

See How do I export and import policies in AM/OpenAM (All versions)? for further information.

Redundant policies in policy editor

Occasionally, you may find that the redundant policies containing forward slashes still show in the policy editor once you have imported the amended XACML file. If this happens, you need to do the following to remove them if you are running either the Tomcat or JBoss web container:

  1. Stop the web application container in which OpenAM runs.
  2. Add the ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true argument to the CATALINA_OPTS environment variable.
  3. Start the web application container in which OpenAM runs.
  4. Delete the redundant policies in the policy editor (navigate to: Access Control > [Realm Name] > Policies).
  5. Stop the web application container in which OpenAM runs.
  6. Remove the ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true argument from the CATALINA_OPTS environment variable.
  7. Start the web application container in which OpenAM runs.

Check your Pre-OpenAM 12 policies for special characters

In OpenAM 12.x and 13.x, special characters are not allowed in policy names. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000).

As migrated policy names are made up of the pre-upgrade policy name and rule name, you must ensure that you do not have special characters in your policy names or rules names. 

Note

Although question marks (?) are not considered special characters, there is a known issue where you cannot edit policies if the policy name contains question marks: OPENAM-5364 (11.0 format policies with "?" in the rule name cannot be edited by the Policy Editor). This is fixed in OpenAM 12.0.3 and later.

As per the advice for forward slashes, you can either make changes to remove special characters pre-upgrade or after to make your migrated policies compatible with OpenAM 12.x or 13.x. 

See Also

Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

Policy import fails in OpenAM 13.0 with Invalid resource type null message

Best practice for creating and testing policies in AM/OpenAM (All versions)

Best practice for upgrading to OpenAM 12.x

Best practice for upgrading to OpenAM 13.x

OpenAM 12.0.0 Release Notes › OpenAM Changes & Deprecated Functionality › Important Changes to Existing Functionality

OpenAM Upgrade Guide › About Upgrading OpenAM › Upgrading & Policies

OpenAM 13 Upgrade Guide › Upgrading OpenAM Servers

OpenAM Administration Guide › Defining Authorization Policies

OpenAM Developer's Guide › Developing Client Applications › Requesting Policy Decisions

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5114 (User should be able to rename or clone an existing Application containing policies without first deleting the policies)

OPENAM-5187 (Can't delete a migrated policy using Policy Editor)

OPENAM-5364 (11.0 format policies with "?" in the rule name cannot be edited by the Policy Editor)

OPENAM-5386 (Policy editor doesn't always use realm-specific REST endpoints)

OPENAM-5400 (Policy Editor: Unable to edit/delete policy whose name ends in a '/' character)

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)

OPENAM-6691 (Not Found error displayed when Policy Name has a space in it with XUI)

OPENAM-7962 (With referrals gone in 13 realm alias referrals are no longer supported)


Recommended Processes


How do I upgrade AM/OpenAM (All versions) if I am using a site configuration?

The purpose of this article is to provide information on upgrading AM/OpenAM if you have a site configuration with multiple servers and require minimal downtime.

Overview

Note

As with any software upgrade, we strongly recommend testing the procedure in your own staging environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the Release Notes relating to the new version of AM/OpenAM so that you are fully aware of all the changes.

If you are using a Site configuration with multiple servers, it is recommended that you temporarily split your site into two prior to upgrading and then upgrade per this article. This example has 4 AM/OpenAM servers in a site configuration (SiteA) with each AM/OpenAM server pointing to its own DS/OpenDJ configuration store. The following table gives the corresponding hostnames and port numbers used in this article:

AM Host             

DS Host Admin Port

Replication Port

AM1 ds1 4444 50989
AM2 ds2 5444 58989
AM3 ds3 6444 59989
AM4 ds4 7444 60989

AM 5 and later

SSO tokens created in pre-AM 5 versions are not valid in AM 5 and later, meaning users will need to reauthenticate once you have upgraded. See Upgrade Guide › Supported Upgrade Paths for further information.

If this is unacceptable, you must schedule downtime to perform the upgrade.

OpenAM 13 and 12.x

In OpenAM 13 and earlier, you must ensure the hostname and port details used for the embedded DS/OpenDJ during install exactly match the details you use when re-enabling replication (this includes the case used for the hostname) else replication will fail if you make any subsequent changes to the embedded DS/OpenDJ configuration. See OPENAM-8254 (Uppercase characters in server URL hostnames break embedded replication) and OPENAM-11263 (Improve Embedded DJ logging to pick up replication configuration errors.) for further information. A mismatch in these connection details when re-enabling replication will trigger AM/OpenAM to run its clean up process, which removes the replication servers on startup. At this point, replication threads are shutdown and replication fails. 

Upgrading a site configuration

  1. Take servers AM3 and AM4 out of your load balancer configuration. Traffic should now only to go to servers AM1 and AM2. 
  2. Split servers AM3 and AM4 out of your site (SiteA) as follows depending on your AM/OpenAM version:
    • AM / OpenAM 13.5 console:
      1. Navigate to Deployment > Servers and click the name of the server you want to remove from the site (AM3).
      2. Set the Parent Site field to [empty] and click Save Changes.
      3. Repeat steps 1 and 2 for the other server (AM4). 
    • Pre-OpenAM 13.5 console:
      1. Navigate to Configuration > Servers and Sites and click the name of the server you want to remove from the site (AM3).
      2. Set the Parent Site field to __NONE__ and click Save.
      3. Repeat steps 1 and 2 for the other server (AM4).
  3. Stop replication on ds3 and ds4 using the dsreplication command applicable to your version:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication unconfigure --unconfigureAll --port 6444 --hostname ds3.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
      $ ./dsreplication unconfigure --unconfigureAll --port 7444 --hostname ds4.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication disable --disableAll --port 6444 --hostname ds3.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
      $ ./dsreplication disable --disableAll --port 7444 --hostname ds4.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
  4. Verify that ds3 and ds4 have been removed from the replication configuration in ds1 and ds2 using the dsreplication status command, for example:
    $ ./dsreplication status --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll
    $ ./dsreplication status --port 5444 --hostname ds2.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll
    
Note

If ds3 and/or ds4 still appear in the dsreplication status output from ds1 or ds2, you need to repair your replication configuration. See How do I repair replication configuration in DS/OpenDJ (All versions) when dsreplication has failed? for further details; in Pre-DS 5, you can use the Replica Removal tool under Support supervision as detailed in How do I use the Replica Remover tool in OpenDJ 2.6.x and 3.x to remove replication when the --disableAll command has failed?

  1. Create a new temporary site (SiteB). You must use a DNS alias for the load balancer as AM/OpenAM will not allow the same primary URL for both sites. For example, you could have something similar to the following where both hostnames point to the same host IP:
    SiteA  host1.example.com:8080/openam
    SiteB  openam.example.com:8080/openam
  2.  Add servers AM3 and AM4 to SiteB.
  3. Re-enable replication between ds3 and ds4 in this site using the dsreplication command applicable to your version: 
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds3.example.com --port1 6444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 59989 --host2 ds4.example.com --port2 7444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 60989 --trustAll --no-prompt
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication enable --adminUID admin --adminPassword password --baseDN dc=example,dc=com --host1 ds3.example.com --port1 6444 --bindDN1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 59989 --host2 ds4.example.com --port2 7444 --bindDN2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 60989 --trustAll --no-prompt
      
  4. Pause replication on ds4:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication suspend --hostname ds4.example.com --port 7444 --adminUid admin --adminPassword password --trustAll --no-prompt
      
    • Pre-DS 5 (pre-AM 5):
      $ ./dsconfig set-synchronization-provider-prop --hostname ds4.example.com --port 7444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt 
  5.  Upgrade AM3 in SiteB:
    1. Deploy the new AM/OpenAM war file and restart AM3.
    2. Navigate to the AM/OpenAM URL, for example: http://AM3.example.com:8080/openam and follow the instructions in the Upgrade Wizard.
    3. Restart AM3 once the upgrade finishes.
  6. Upgrade AM4 in SiteB:
    1. Resume replication on ds4 using the command applicable to your version:
      • DS 5 and later (AM 5 and later):
        $ ./dsreplication resume --hostname ds4.example.com --port 7444 --adminUid admin --adminPassword password --trustAll --no-prompt
        
      • Pre-DS 5 (pre-AM 5):
        $ ./dsconfig set-synchronization-provider-prop --hostname ds4.example.com --port 7444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt   
        
    2. Deploy the new AM/OpenAM war file and restart AM4.
  7. Transfer traffic from SiteA to the newly upgraded SiteB at the load balancer.
  8. Repeat steps 8 to 10 to upgrade AM1 and AM2 in SiteA; in summary:
    1. Pause replication on ds2.
    2. Upgrade AM1.
    3. Resume replication on ds2.
    4. Deploy new war file on AM2.
    5. Restart AM2.
  9. Transfer traffic from SiteB back to SiteA at the load balancer.
  10. Delete SiteB; this removes servers AM3 and AM4 from the site.
  11. Stop replication on ds3 and ds4 using the dsreplication command applicable to your version:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication unconfigure --unconfigureAll --port 6444 --hostname ds3.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
      $ ./dsreplication unconfigure --unconfigureAll --port 7444 --hostname ds4.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication disable --disableAll --port 6444 --hostname ds3.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
      $ ./dsreplication disable --disableAll --port 7444 --hostname ds4.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
  12. Add servers AM3 and AM4 back in to the original SiteA and restart both servers; in OpenAM 12.x, you must restart both servers in the site individually.
  13. Re-enable replication between ds3 and ds4 using the dsreplication command applicable to your version:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds3.example.com --port1 6444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 59989 --host2 ds4.example.com --port2 7444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 60989 --trustAll --no-prompt
      
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication enable --adminUID admin --adminPassword password --baseDN dc=example,dc=com --host1 ds3.example.com --port1 6444 --bindDN1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 59989 --host2 ds4.example.com --port2 7444 --bindDN2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 60989 --trustAll --no-prompt
      
  14. Enable replication between ds1 and ds3 using the dsreplication command applicable to your version:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds1.example.com --port1 4444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 50989 --host2 ds3.example.com --port2 6444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 59989 --trustAll --no-prompt
      
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication enable --adminUID admin --adminPassword password --baseDN dc=example,dc=com --host1 ds1.example.com --port1 4444 --bindDN1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 50989 --host2 ds3.example.com --port2 6444 --bindDN2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 59989 --trustAll --no-prompt
      
  15. Reinitialize all the DS/OpenDJ servers from one of the servers that remained on SiteA (ds1 or ds2) to ensure the re-added servers have all the changes that have occurred since you split the site:
    $ ./dsreplication initialize-all --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostname ds1.example.com --port 4444 --trustAll --no-prompt
  16. Add the two servers AM3 and AM4 back in to your load balancer configuration. Traffic should now go to all four servers again. 

Policy agent sessions

If policy agent sessions were created on a server in the temporary site that you created during upgrade (SiteB in this example), those sessions will not be valid once the upgrade is complete. AM/OpenAM cannot process any requests for sessions that contain invalid server IDs for security reasons.

You will see errors in the agent debug log to indicate this, for example:

2017-08-16 12:03:19.430     Info 18236:159d470 NamingService: NamingService::parseNamingResponse() server side error: Invalid sessionid format:[AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.* ]java.lang.IllegalArgumentException: Invalid server id in session id:[02]com.iplanet.services.naming.ServerEntryNotFoundException: Cannot find server.

Decoding the session cookie in this error per FAQ: Cookies in AM/OpenAM (Q. What information is contained in the AM/OpenAM session cookie?) indicates the site and server on which the cookie was created.

With Web policy agents 4.x, the user can just log in again to create a new valid session; with Web policy agents 3.x, users will see a 500: Internal server error00 error and will need to clear their browser cookies before they can log in again.

See Also

How do I upgrade AM/OpenAM (All versions) with minimal downtime when replication is used?

FAQ: Upgrading AM/OpenAM

​​​​FAQ: Backing up AM/OpenAM

Upgrading AM/OpenAM

Release Notes

Upgrade Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11263 (Improve Embedded DJ logging to pick up replication configuration errors.)

OPENAM-10874 (Adding a new server (site) requires a Restart on all the old servers)

OPENAM-8254 (Uppercase characters in server URL hostnames break embedded replication) 

OPENAM-480 (Adding a server to a site requires restart of OpenAM)


How do I upgrade AM/OpenAM (All versions) with minimal downtime when replication is used?

The purpose of this article is to provide information on upgrading AM/OpenAM with minimal downtime when replication is used. This article includes information on upgrading AM/OpenAM with an external or embedded DS/OpenDJ configuration store, regardless of whether you have a load balancer in place or not.

Upgrading AM/OpenAM with minimal downtime

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the release notes relating to the new version of AM/OpenAM so that you are fully aware of all the changes.

This article covers upgrading AM/OpenAM with minimal downtime in the following scenarios:

AM 5 and later

SSO tokens created in pre-AM 5 versions are not valid in AM 5 and later, meaning users will need to reauthenticate once you have upgraded. See  Upgrade Guide › Supported Upgrade Paths for further information.

If this is unacceptable, you must schedule downtime to perform the upgrade.

OpenAM 13 and 12.x

In OpenAM 13 and earlier, you must ensure the hostname and port details used for the embedded DS/OpenDJ during install exactly match the details you use when re-enabling replication (this includes the case used for the hostname) else replication will fail if you make any subsequent changes to the embedded DS/OpenDJ configuration. See OPENAM-8254 (Uppercase characters in server URL hostnames break embedded replication) and OPENAM-11263 (Improve Embedded DJ logging to pick up replication configuration errors.) for further information. A mismatch in these connection details when re-enabling replication will trigger AM/OpenAM to run its clean up process, which removes the replication servers on startup. At this point, replication threads are shutdown and replication fails. 

External DS/OpenDJ - with a load balancer

If you have a load balancer in place, you can do a High Availability upgrade. The following details the steps you would need to follow with an example two AM/OpenAM servers (AM1 and AM2) and two external DS/OpenDJ configuration stores (DS1 and DS2):

  1. Remove AM1 from the load balancer.
  2. Temporarily stop replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  3. Perform the following steps on AM1:
    • Deploy the new AM/OpenAM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  4. Restore AM1 to the load balancer.
  5. Remove AM2 from the load balancer.
  6. Deploy the new AM/OpenAM war file on AM2.
  7. Resume replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  8. Initialize the contents of DS1 to DS2 to allow the new upgrade changes to be replicated to DS2. Use a dsreplication initialize-all command on DS1, for example:
    $ ./dsreplication initialize-all --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostname ds1.example.com --port 4444 --trustAll --no-prompt
  9. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example:
    $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt
    
    Suffix DN         : Server               : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4)
    ------------------:----------------------:---------:---------------------:-------:-------:-------------:----------:--------------:-------------
    dc=example,dc=com : ds1.example.com:4444 : 2518    : true                :   933 : 17014 : 8989        : 0        :              : false
    dc=example,dc=com : ds2.example.com:4444 : 2518    : true                : 24857 :  8513 : 9989        : 0        :              : false
    
  10. Restart AM2.
  11. Restore AM2 to the load balancer.

External DS/OpenDJ - no load balancer

If you do not have a load balancer in place, you can use a similar procedure to upgrade AM/OpenAM. The following details the steps you would need to follow with an example two AM/OpenAM servers (AM1 and AM2) and two external DS/OpenDJ configuration stores (DS1 and DS2); if you have more than two servers, perform the steps for AM2 / DS2 on each additional server:

  1. Temporarily stop replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  2. Perform the following steps on AM1:
    • Deploy the new AM/OpenAM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  3. Deploy the new AM/OpenAM war file on AM2.
  4. Resume replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  5. Initialize the contents of DS1 to DS2 to allow the new upgrade changes to be replicated to DS2. Use a dsreplication initialize-all command on DS1, for example:
    $ ./dsreplication initialize-all --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostname ds1.example.com --port 4444 --trustAll --no-prompt
  6. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example:
    $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt
    
    Suffix DN         : Server               : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4)
    ------------------:----------------------:---------:---------------------:-------:-------:-------------:----------:--------------:-------------
    dc=example,dc=com : ds1.example.com:4444 : 2518    : true                :   933 : 17014 : 8989        : 0        :              : false
    dc=example,dc=com : ds2.example.com:4444 : 2518    : true                : 24857 :  8513 : 9989        : 0        :              : false
    
  7. Restart AM2.

Embedded DS/OpenDJ - with a load balancer

If you have a load balancer in place, you can do a High Availability upgrade. The following details the steps you would need to follow with an example two AM/OpenAM servers (AM1 and AM2) and two embedded DS/OpenDJ configuration stores (DS1 and DS2):

  1. Remove AM1 from the load balancer.
  2. Temporarily stop replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  3. Perform the following steps on AM1:
    • Deploy the new AM/OpenAM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  4. Restore AM1 to the load balancer.
  5. Remove AM2 from the load balancer.
  6. Resume replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  7. Perform the following steps on AM2:
    • Deploy the new AM/OpenAM war file.
    • Restart the server.
  8. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example:
    $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt
    
    Suffix DN         : Server               : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4)
    ------------------:----------------------:---------:---------------------:-------:-------:-------------:----------:--------------:-------------
    dc=example,dc=com : ds1.example.com:4444 : 2518    : true                :   933 : 17014 : 8989        : 0        :              : false
    dc=example,dc=com : ds2.example.com:4444 : 2518    : true                : 24857 :  8513 : 9989        : 0        :              : false
    
  9. Restore AM2 to the load balancer.

Embedded DS/OpenDJ - no load balancer

If you do not have a load balancer in place, you can use a similar procedure to upgrade AM/OpenAM. The following details the steps you would need to follow with an example two AM/OpenAM servers (AM1 and AM2) and two embedded DS/OpenDJ configuration stores (DS1 and DS2); if you have more than two servers, perform the steps for AM2 / DS2 on each additional server:

  1. Temporarily stop replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  2. Perform the following steps on AM1:
    • Deploy the new AM/OpenAM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  3. Resume replication on DS2 using a dsconfig command, for example:
    $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  4. Perform the following steps on AM2:
    • Deploy the new AM/OpenAM war file.
    • Restart the server.
  5. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example:
    $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt
    
    Suffix DN         : Server               : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4)
    ------------------:----------------------:---------:---------------------:-------:-------:-------------:----------:--------------:-------------
    dc=example,dc=com : ds1.example.com:4444 : 2518    : true                :   933 : 17014 : 8989        : 0        :              : false
    dc=example,dc=com : ds2.example.com:4444 : 2518    : true                : 24857 :  8513 : 9989        : 0        :              : false
    

See Also

How do I upgrade AM/OpenAM (All versions) if I am using a site configuration?

FAQ: Backing up AM/OpenAM

FAQ: Upgrading AM/OpenAM

Upgrading AM/OpenAM

Upgrade Guide

Release Notes

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11263 (Improve Embedded DJ logging to pick up replication configuration errors.)

OPENAM-8254 (Uppercase characters in server URL hostnames break embedded replication) 


Frequently Asked Questions


FAQ: Upgrading AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding upgrading AM/OpenAM.

Frequently asked questions

Q. How can I find everything that has been fixed in a release?

A. You can look in the Issue Tracker to see what has been fixed against a given release. Links for recent releases are included below:

Note

The release notes also list all the key fixes that have been included as well as any known issues that are still outstanding at the time of the release: AM 6.5 Release Notes, AM 6 Release Notes, AM 5.5 Release Notes, AM 5 Release NotesOpenAM 13.5 Release Notes, and OpenAM 13 Release Notes.

Q. Where can I find end of support life (EOSL) dates for AM/OpenAM?

A. The release dates and end of support life dates for AM/OpenAM are available from: Checking your product versions are supported

Q. Where can I find AM/OpenAM upgrade instructions and best practices?

A. The Upgrade Guide provides planning, best practices and instructions for performing your upgrade and covers common aspects of upgrading an AM/OpenAM deployment, whether you are moving to a new maintenance release, upgrading to a new major release or migrating from a legacy release to a newer AM/OpenAM release.

You should also consult the following articles / specific sections for further information on planning and best practices for upgrades:

Q. How do I debug issues when I am upgrading AM/OpenAM?

A. There are a couple of files that can be useful for debugging the upgrade process:

  • The Upgrade report (called upgradereport.yyyymmddhhmmss) logs the upgrade details shown in the browser during the upgrade process and is located in the $HOME/[am_instance]/upgrade directory.
  • The amUpgrade debug log is generated if any errors are encountered during the upgrade process and is located in the $HOME/[am_instance]/openam/debug/ directory. 

You can also enable Message level debugging in the web application container as described in How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

Q. How do I find the hardware and software requirements for the new release?

A. Before upgrading, you should read the Before You Install... section in the release notes applicable to the release you are upgrading to.

See Release Notes › Before You Install for further information on AM 6.5.

Q. Does upgrading the Apache Tomcat™ web application container affect my AM/OpenAM deployment?

A. No, providing you install the new version of Tomcat in the exact same location with the same directory structure, AM/OpenAM is not affected.

Note

Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

Q. Do I need to upgrade Amster when I upgrade AM?

A. Yes, you should always upgrade Amster to the corresponding version when you upgrade AM. This is stated in the release notes: Amster Release Notes › What's New.

Q. Do I need to upgrade the ssoadm administration tool when I upgrade AM/OpenAM?

A. Yes you do; you must ensure you are running the equivalent version of the ssoadm administration tool. The ssoadm administration tool is not automatically upgraded when you upgrade AM/OpenAM and must be done separately.

See Upgrade Guide › Upgrading Tools for further information.

Q. How can I retain AM/OpenAM customizations when I upgrade?

A. You can retain customizations by preparing a war file containing any customizations you require as described in Upgrade Guide › Apply Customization Before Upgrading.

Alternatively, you can use the Maven overlay functionality, which enables you to replace standard implementations with your customizations during the build process.

See Maven war plugin - overlays for further information.

Q. What is the best approach to upgrading if I am using Site configuration?

A. If you are using a Site configuration with multiple servers, it is recommended that you temporarily split your site into two prior to upgrading and then upgrade per the steps in How do I upgrade AM/OpenAM (All versions) if I am using a site configuration?

Note

You must stop replication when you upgrade regardless of whether you split your site per the article above or shut down all servers.

Q. How can I upgrade AM/OpenAM without using the console?

A. You can use the upgrade.jar tool (openam-upgrade-tool-14.1.1.3.jar for AM 6) to upgrade AM/OpenAM using a configuration file providing you are using an embedded configuration store. This tool allows you to easily perform a silent, unattended upgrade and can be included in scripts to automate the upgrade process if required.

Note

The upgrade.jar tool is included in AM/OpenAM but is not installed by default.

See Installation Guide › Setting up Configuration Tools for an overview of the process. The most important part is creating a valid config.file as this is used for the actual upgrade. A sampleupgrade file is included when you install the configuration tools, which you should use as the basis of your configuration file; the properties that can be set within this file are described in Reference › upgrade.jar.

If you want to make configuration changes to your upgraded server, you can do this using the configurator.jar tool, which is described in more detail in FAQ: Configuring AM/OpenAM

Caution

You cannot import a Service configuration that was created in a different version of AM/OpenAM using ssoadm. This is possible with Amster; for example, you can export a configuration from AM 5 and import it into AM 5.5. 

Q. Where can I find information on forthcoming OpenAM releases?

A. You can look at the AM/OpenAM product roadmap: AM/OpenAM Roadmap

Caution

You should bear in mind that the roadmap indicates the current proposed product direction and does not represent commitments from ForgeRock.

See Also

How do I upgrade AM/OpenAM (All versions) with minimal downtime when replication is used?

How do I upgrade AM/OpenAM (All versions) if I am using a site configuration?

Upgrading AM/OpenAM

FAQ: AM/OpenAM compatibility with third-party products

FAQ: Source code in AM/OpenAM

FAQ: Installing AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: AM/OpenAM performance and tuning

Upgrade Guide › Best Practices for Upgrades

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)


FAQ: Installing AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing AM/OpenAM.

Frequently asked questions

Q. Is AM/OpenAM compatible with Oracle Java Development Kit (JDK) 9 or later?

A. No, Oracle JDK 9 is not currently supported. You should only use supported versions to prevent compatibility issues. Future versions of AM will be targeting compatibility with Java 11.

Q. Why does AM/OpenAM require a JDK rather than just a JRE?

A. AM/OpenAM primarily requires a JDK to compile the bundled JSP files. Most web application containers include a JDK, although Tomcat does not. However, Tomcat includes a JSP engine (Jasper) that will compile JSPs. Although AM/OpenAM should run if deployed on Tomcat without a JDK, it should be noted that this is not supported. Additionally, utilities such as jar and jstack, which are referred to in the product documentation and used for troubleshooting, are only available when the JDK is installed.

Q. Can AM/OpenAM be used with OpenJDK?

A. Yes, OpenJDK 8 is supported as of AM 5. Prior to this, OpenJDK has not been tested with OpenAM, but is expected to work since OpenJDK is a compliant JDK and is fully compatible. However, as it has not been tested, there may be incompatibility issues with other third-party products.

Q. Is the Pivotal TC Server supported?

A. The Pivotal TC Server is a Web application server based on open-source Apache Tomcat™, but it is customized in a way that the configuration filename and its location etc are not compliant with the default Tomcat server. For example:

pivotal-tc-server-developer-3.1.7.RELEASE/templates/base-tomcat-7/conf $ls
catalina-fragment.properties    catalina.policy      logging-fragment.properties    server-fragment.xml  web-fragment.xml

pivotal-tc-server-developer-3.1.7.RELEASE/tomcat-7.0.72.B.RELEASE $ls
LICENSE    NOTICE    bin    lib

As such, AM/OpenAM cannot install on the Pivotal TC Server by default, it has not been tested nor is it supported. If you encounter any issues running on the Pivotal TC Server, you will be asked to reproduce them on a supported container.

Q. Does AM/OpenAM support IPv6?

A. Yes, Internet Protocol version 6 (IPv6) is fully supported in addition to IPv4.

Note

When deploying OpenAM 13.0 components on Microsoft® Windows® in an IPv6 environment, you must use the Java® 7 Development Kit on Windows (due to JDK-6230761, which is fixed only in Java 7).

Q. Can I install AM/OpenAM on a system configured with SELinux in Enforcing mode?

A. Yes you can, but you must perform some additional steps prior to installing AM/OpenAM, otherwise the installation will never complete.

See How do I install AM/OpenAM (All versions) with Apache Web Policy Agent on Red Hat Enterprise Linux or CentOS configured with SELinux? for further information.

Q. Do I need to be a root user to install and administer AM/OpenAM?

A. No, AM/OpenAM does not require root user usage. Providing Apache Tomcat™ does not attempt to use ports below 1024, you can use any user for AM/OpenAM. When running as a non-root user, the web application container must be able to write to its own home directory as this is where AM/OpenAM stores its configuration files.

Q. Can I use an IP address for the AM/OpenAM server URL?

A. No, you must use a Fully Qualified Domain Name (FQDN) for the AM/OpenAM server URL, otherwise cookies will not work. The FQDN should be in the format hostname.domainname for the AM/OpenAM server, for example, http://<hostname.domain>:8080/openam 

See Installation Guide › Preparing a Fully Qualified Domain Name for further information.

Note

You must never use the localhost domain for AM/OpenAM, not even for testing purposes.

Q. How do I debug issues when I am installing or upgrading AM/OpenAM?

A. You can enable Message level debugging in the web application container as described in How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

Q. How do I add a new server to a Site configuration?

A. You can follow the procedure outlined in the documentation: Installation Guide › To Add a Server to a Site.

Note

You must restart all servers in the Site configuration (including existing ones) to complete the setup. This is a known issue in OpenAM 13.5.1 and earlier: OPENAM-480 (Adding a server to a site requires restart of OpenAM) and OPENAM-10874 (Adding a new server (site) requires a Restart on all the old servers), which is resolved in OpenAM 13.5.2 and later. 

Q. What is the difference between the primary URL and secondary URLs?

A. Sites have a primary URL, which is normally the VIP through which all access to the site is routed.

One or more secondary site URLs can be included, which is useful for internal VIPs or as alternate entry point to the site. It’s essentially there to make AM/OpenAM aware that it should handle other FQDNs in addition to the primary URL. The secondary site URLs are not used by any AM/OpenAM clients like policy agents or SDK; the way that AM/OpenAM functions means only the primary site ID will be included in the SSOToken and therefore policy agents will always use the primary site URL to communicate with AM/OpenAM.

See Reference › Deployment Configuration for further information.

Q. Can I use the embedded configuration and/or user stores in production?

A. You can for small systems, but it is not generally recommended for large-scale production systems. You should also consider that using external data stores allows you to tune your LDAP servers separately, which gives you greater control over performance. If you have a small scale deployment that is relatively simple, the embedded stores may be suitable for your needs; you should performance test this option to check it is appropriate before continuing.

Note

If you plan on using external configuration/user stores, it is recommended that you start with the external stores rather than migrating to them after you have gone live. 

This advice also applies to the CTS store; see FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM (Q. Can I used the embedded CTS store in production?) for further information.

Q. Can I have the user store and configuration store on the same DS/OpenDJ instance?

A. It is best practice to keep the user store and configuration store in separate DS/OpenDJ installations. This means you can cache and index these stores differently. Additionally, by having two installations you will have separate Java Virtual Machines (JVM), which means you can tune the stores differently as well.

Q. Can two separate instances of AM/OpenAM share the same DS/OpenDJ user store?

A. Yes they can.

Q. Does AM/OpenAM support user stores with a dynamic groups LDAP structure?

A. Yes it does. You should ensure the Attribute Name for Group Membership property is set to isMemberOf in your data store configuration; AM/OpenAM will use this attribute to fetch group membership, which includes dynamic groups. See Setup and Maintenance Guide › Setting Up Identity Data Stores for further information.

See isMemberOf attribute does not return current group membership details for a user in AM/OpenAM (All versions) for details of returning group membership details via REST.

Resolved RFE: OPENAM-9030 (Improve group management implementation)

Q. Can I have a fully operational AM/OpenAM cluster where the nodes are running different AM/OpenAM versions?

A. It is not recommended other than for upgrade purposes and will always depend on the actual differences between the releases. If there are changes to the AM/OpenAM schema and these changes are replicated to all the other configuration stores, it is very likely that the old nodes will not be compatible and may not be fully functional.

Although it is usually possible to have a mix of AM/OpenAM versions in a cluster for upgrade purposes, you should not make any changes to the configuration until all nodes in the cluster have been updated. As a precaution, it is also recommended that you temporarily remove old nodes from the cluster once the first node has been upgraded and that you remove the node that is currently being upgraded to prevent your users seeing an Upgrade AM/OpenAM page.

See Also

How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

FAQ: Installing and using ssoadm in AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: AM/OpenAM compatibility with third-party products

FAQ: Source code in AM/OpenAM

FAQ: General AM/OpenAM

Installing and configuring AM/OpenAM

Installation Guide

User Guide › Installing ForgeRock Access Management with Amster

Related Training

ForgeRock Access Management Core Concepts (AM-400)


What versions of DS/OpenDJ are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between DS/OpenDJ and AM/OpenAM versions. This includes the embedded DS/OpenDJ versions shipped with AM/OpenAM and, the supported Java® versions for each combination.

DS/OpenDJ and AM/OpenAM compatibility

Embedded DS/OpenDJ

Embedded DS/OpenDJ versions are shipped with AM/OpenAM and cannot be upgraded; however, when you upgrade to a newer version of AM/OpenAM, the embedded DS/OpenDJ instance is also upgraded. The following embedded DS/OpenDJ versions are included with AM/OpenAM:

AM/OpenAM versions Embedded DS/OpenDJ version
AM 6.5 DS 6.5
AM 6 DS 6
AM 5.5 and 5.5.1 DS 5.5
AM 5 and 5.1.x DS 5
OpenAM 13.5.2 OpenDJ 3.5.3
OpenAM 13.5.1 OpenDJ 3.5.2
OpenAM 13.5 OpenDJ 3.5
OpenAM 13.0 OpenDJ 3.0
OpenAM 12.0.4 OpenDJ 2.6.4
OpenAM 12.0.0 to 12.0.3 OpenDJ 2.6.2

External DS/OpenDJ

The following matrix indicates compatibility between AM/OpenAM and external DS/OpenDJ versions:

  DS 6.x DS 5.x OpenDJ 3.x OpenDJ 2.6.x
AM 6.x Yes Yes Yes --
AM 5.5 -- Yes Yes --
AM 5 and 5.1.x -- Yes Yes Partly (User Store only)
OpenAM 13.x -- -- Yes Yes
OpenAM 12.x -- -- -- Yes
Note

It is strongly recommended that you always upgrade to the latest maintenance releases for whichever versions of AM/OpenAM and DS/OpenDJ you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • DS 6.5 and later.

Java 9

  • DS 6 only.

Java 8

  • AM 5 and later; OpenAM 12.0.0 and later
  • DS 5 and later; OpenDJ 2.6.2 and later

Java 7

  • AM 5 and 5.1.x; OpenAM 12.x and 13.x
  • OpenDJ 2.6.x and 3.x. Java 7 can be used in DS 5 but support for it is deprecated.

Java 6

  • OpenAM 12.x
  • OpenDJ 2.6.x

Software and Hardware requirements

AM/OpenAM

DS/OpenDJ

See Also

What operating systems are ForgeRock products supported on?

Checking your product versions are supported

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Installing and configuring DS/OpenDJ

Installing and configuring AM/OpenAM

Installing and Administering DS/OpenDJ

Related Training

N/A

Related Issue Tracker IDs

N/A


What versions of Policy Agents are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between Policy Agents and AM/OpenAM versions. Also included is the supported Java® versions for each combination.

Policy Agents and AM/OpenAM compatibility

Caution

Web policy agents 4.x and JEE policy agents 3.5.x are not supported in AM 6.5; you will need to upgrade to the latest Agents 5 release ahead of upgrading to AM 6.5. 

Web policy agents

The following matrix indicates compatibility between AM/OpenAM and Web policy agent versions:

  Web Agents 5.x Web Policy Agents 4.x
AM 6.5 Yes (5.0.1 or later) --
AM 6 Yes (5.0.1 or later) Yes *
AM 5.5 Yes Yes
AM 5 and 5.1.x -- Yes
OpenAM 13.x -- Yes
OpenAM 12.x -- Yes

* Profile changes are required in AM 6 if you do a new AM install or add a new agent profile; see How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)? for details. 

Java policy agents

The following matrix indicates compatibility between AM/OpenAM and Java policy agent versions:

  Java Agents 5.x JEE Policy Agents 3.5.x
AM 6.5 Yes (5.0.1 or later) --
AM 6 Yes (5.0.1 or later) Yes *
AM 5.5 Yes Yes
AM 5 and 5.1.x -- Yes
OpenAM 13.x -- Yes
OpenAM 12.x -- Yes

* Profile changes are required in AM 6 if you do a new AM install or add a new agent profile; see How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)? for details.

Note

It is strongly recommended that you always upgrade to the latest maintenance releases for the specific versions of AM/OpenAM and Policy Agents you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.

Java 8

  • AM 5 and later; OpenAM 12.x and 13.x
  • JEE Policy Agents 3.5 and later

Java 7

  • AM 5.0 and 5.1.x; OpenAM 12.x and 13.x
  • JEE Policy Agents 3.5

Java 6

  • OpenAM 12.x
  • JEE Policy Agents 3.5

Software and Hardware requirements

AM/OpenAM

Web Policy Agents

Java EE Policy Agents

See Also

What versions of DS/OpenDJ are compatible with AM/OpenAM?

What operating systems are ForgeRock products supported on?

FAQ: Configuring Policy Agents in AM/OpenAM

Installing and configuring AM/OpenAM

Maintenance and Patch availability policy

ForgeRock End of Service Life (EOSL) policy

Related Training

N/A

Related Issue Tracker IDs

N/A


What versions of IG/OpenIG are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between IG/OpenIG and AM/OpenAM versions. Also included is the supported Java® versions for each combination.

IG/OpenIG and AM/OpenAM compatibility

The following matrix indicates compatibility between AM/OpenAM and IG/OpenIG versions:

  IG 6.x IG 5.5 IG 5 OpenIG 4.x
AM 6.x Yes -- -- --
AM 5.5 Yes Yes -- --
AM 5 and 5.1.x Partly * (most features) Yes Yes --
OpenAM 13.5.x Partly * (limited features) Partly * (most features) Yes Yes
OpenAM 13 -- -- -- Yes

* For details of the specific features supported in these versions, please refer to the relevant IG release notes:

Note

It is strongly recommended that you always upgrade to the latest maintenance releases for whichever versions of AM/OpenAM and IG/OpenIG you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • IG 6.5 and later (OpenJDK only).

Java 8

  • AM 5 and later; OpenAM 13.x
  • IG 5 and later; OpenIG 4.x

Java 7

  • AM 5 and 5.1.x; OpenAM 13.x
  • IG 5 and OpenIG 4.x

Software and Hardware requirements

AM/OpenAM

IG/OpenIG

See Also

What operating systems are ForgeRock products supported on?

Checking your product versions are supported

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Installing and configuring IG/OpenIG

Installing and configuring AM/OpenAM

Installing and configuring IG/OpenIG


What automation tools are available for installing, upgrading and configuring AM/OpenAM deployments (All versions)?

The purpose of this article is to provide information on the tools available to automate your AM/OpenAM deployments. These tools let you perform silent installations and upgrades, as well as configure or update a deployed AM/OpenAM server from a configuration file or using the REST API.

Automation tools

The following automation tools are available in AM/OpenAM:

See Also

Install and configuration

ssoadm

REST API

Amster

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management – Customization and APIs

Related Issue Tracker IDs

N/A


Known Issues


AM/OpenAM (All versions) upgrade fails when com.iplanet.am.version is empty or corrupted

The purpose of this article is to provide assistance if your AM/OpenAM upgrade fails, that is, the Upgrade page is not shown after deploying the new war file and the com.iplanet.am.version property is empty or invalid. This property indicates the AM/OpenAM version and is needed for the upgrade process.

Symptoms

The Upgrade page is not shown when you access the server URL after deploying a new war file for a later AM/OpenAM version. You may see the console as normal, a Loading... page or the following message instead:

HTTP 500 error in AMSetupFilter: 
type Exception report

message AMSetupFilter.doFilter

description The server encountered an internal error that prevented it from fulfilling this request.

You will see some errors in the web application container logs, but they will vary by version and you will also notice the com.iplanet.am.version property is empty or corrupted. See Checking the com.iplanet.am.version property section below for further information on checking this value.

You will see errors similar to the following in the web application container log (for example, catalina.out for Apache Tomcat™) depending on which version of AM/OpenAM you are upgrading to:

  • AM 6 and later:
    org.forgerock.openam.upgrade.UpgradeException: Unable to parse product versions for comparison. Current: null war: ForgeRock Access Management 6.0.0 Build 3676519ec1 (2018-May-08 10:07)
       org.forgerock.openam.upgrade.VersionUtils.isVersionNewer(VersionUtils.java:100)
       org.forgerock.openam.upgrade.VersionUtils.isVersionNewer(VersionUtils.java:87)
       com.sun.identity.setup.AMSetupManager.isVersionNewer(AMSetupManager.java:72)
       com.sun.identity.setup.AMSetupFilter.isConfigStoreDown(AMSetupFilter.java:162)
       com.sun.identity.setup.AMSetupFilter.doFilter(AMSetupFilter.java:115)
       org.forgerock.openam.audit.context.AuditContextFilter.doFilter(AuditContextFilter.java:46)
    
  • AM 5.1.x:
    com.google.inject.ProvisionException: Guice provision errors:
    
    1) Error injecting constructor, java.lang.IllegalStateException: Failed to load monitoring configuration
       at com.sun.identity.monitoring.MonitoringConfig.<init>(Unknown Source)
       at com.sun.identity.monitoring.MonitoringConfig.class(Unknown Source)
       while locating com.sun.identity.monitoring.MonitoringConfig
         for parameter 0 at com.sun.identity.monitoring.MonitoringManager.<init>(Unknown Source)
       at com.sun.identity.monitoring.MonitoringManager.class(Unknown Source)
       while locating com.sun.identity.monitoring.MonitoringManager
    
    1 error
       at com.google.inject.internal.InjectorImpl$4.get(InjectorImpl.java:987)
       at com.google.inject.internal.InjectorImpl.getInstance(InjectorImpl.java:1013)
       at org.forgerock.guice.core.InjectorHolder.getInstance(InjectorHolder.java:72)
       at com.sun.identity.monitoring.MonitoringUtil.isRunning(MonitoringUtil.java:58)
       at com.sun.identity.log.LogManager.updateMonitConfigForLogService(LogManager.java:679)
       at com.sun.identity.log.LogManager.readConfiguration(LogManager.java:538)
       at com.sun.identity.log.Logger.<clinit>(Logger.java:94)
       at org.forgerock.openam.oauth2.OAuth2AuditLogger.init(OAuth2AuditLogger.java:52)
       at org.forgerock.openam.oauth2.OAuth2AuditLogger.<init>(OAuth2AuditLogger.java:45)
    ...
    Caused by: java.lang.IllegalStateException: Failed to load monitoring configuration
       at com.sun.identity.monitoring.MonitoringConfig.<init>(MonitoringConfig.java:63)
       at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
       at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
       at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
       at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
    ...
    Caused by: java.lang.IllegalStateException: Failed to load monitoring configuration
       at com.sun.identity.monitoring.MonitoringConfig$HotSwappableMonitoringConfig.<init>(MonitoringConfig.java:187)
       at com.sun.identity.monitoring.MonitoringConfig.<init>(MonitoringConfig.java:48)
     ... 104 more
    Caused by: java.lang.NumberFormatException: null
       at java.lang.Integer.parseInt(Integer.java:454)
       at java.lang.Integer.valueOf(Integer.java:582)
       at com.sun.identity.monitoring.MonitoringConfig$HotSwappableMonitoringConfig.loadSettings(MonitoringConfig.java:204)
       at com.sun.identity.monitoring.MonitoringConfig$HotSwappableMonitoringConfig.<init>(MonitoringConfig.java:183)
     ... 105 more
    
  • AM 5:
    javax.servlet.ServletException: Servlet execution threw an exception
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:315)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:207)
       at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:240)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:207)
       at org.forgerock.openam.validation.ResponseValidationFilter.doFilter(ResponseValidationFilter.java:36)
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:240)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:207)
       at org.forgerock.openam.headers.SetHeadersFilter.doFilter(SetHeadersFilter.java:80)
    ...
    Caused by: java.lang.NoClassDefFoundError: Could not initialize class com.sun.identity.authentication.service.AuthD
     at com.sun.identity.authentication.service.AuthUtils.getAuthContext(AuthUtils.java:199)
     at com.sun.identity.authentication.service.AuthUtils.getAuthContext(AuthUtils.java:172)
     at com.sun.identity.authentication.UI.LoginViewBean.forwardTo(LoginViewBean.java:412)
     at com.iplanet.jato.ApplicationServletBase.dispatchRequest(ApplicationServletBase.java:981)
     at com.iplanet.jato.ApplicationServletBase.processRequest(ApplicationServletBase.java:615)
     at com.iplanet.jato.ApplicationServletBase.doGet(ApplicationServletBase.java:459)
     at javax.servlet.http.HttpServlet.service(HttpServlet.java:622)
     at javax.servlet.http.HttpServlet.service(HttpServlet.java:729)
     at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:292)
     ... 35 more
    
  • OpenAM 13.5.0:
    javax.servlet.ServletException: Servlet execution threw an exception
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:326)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)
       at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:241)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)
       at org.forgerock.openam.validation.ResponseValidationFilter.doFilter(ResponseValidationFilter.java:44)
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:241)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)
       at org.forgerock.openam.xui.XUIFilter.doFilter(XUIFilter.java:131)
       at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:241)
       at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)
       at com.sun.identity.setup.AMSetupFilter.doFilter(AMSetupFilter.java:111)
    ...
    Caused by: java.lang.ExceptionInInitializerError
       at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
       at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source)
       at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source)
    ...
    Caused by: java.lang.IllegalStateException: Unable to initialize AuthD
       at com.sun.identity.authentication.service.AuthD.<init>(AuthD.java:262)
       at com.sun.identity.authentication.service.AuthD.<init>(AuthD.java:101)
       at com.sun.identity.authentication.service.AuthD$SingletonHolder.getInstance(AuthD.java:123)
       at com.sun.identity.authentication.service.AuthD.getAuth(AuthD.java:532)
       at com.sun.identity.authentication.UI.AuthExceptionViewBean.<clinit>(AuthExceptionViewBean.java:298)
    	... 44 more
    Caused by: com.google.inject.ProvisionException: Guice provision errors:
    1) Error injecting constructor, java.lang.NullPointerException
       at org.forgerock.openam.audit.AuditServiceProviderImpl.<init>(Unknown Source)
       at org.forgerock.openam.audit.AuditServiceProviderImpl.class(Unknown Source)
       while locating org.forgerock.openam.audit.AuditServiceProviderImpl
       while locating org.forgerock.openam.audit.AuditServiceProvider
         for parameter 0 at org.forgerock.openam.audit.AuditEventPublisherImpl.<init>(Unknown Source)
       at org.forgerock.openam.audit.AuditEventPublisherImpl.class(Unknown Source)
       while locating org.forgerock.openam.audit.AuditEventPublisherImpl
       while locating org.forgerock.openam.audit.AuditEventPublisher
         for parameter 0 at com.iplanet.dpro.session.service.SessionAuditor.<init>(Unknown Source)
       at com.iplanet.dpro.session.service.SessionAuditor.class(Unknown Source)
       while locating com.iplanet.dpro.session.service.SessionAuditor
         for parameter 11 at com.iplanet.dpro.session.service.SessionService.<init>(Unknown Source)
       at com.iplanet.dpro.session.service.SessionService.class(Unknown Source)
       while locating com.iplanet.dpro.session.service.SessionService
    1 error
       at com.google.inject.internal.InjectorImpl$4.get(InjectorImpl.java:987)
       at com.google.inject.internal.InjectorImpl.getInstance(InjectorImpl.java:1013)
       at org.forgerock.guice.core.InjectorHolder.getInstance(InjectorHolder.java:80)
       at com.sun.identity.authentication.service.AuthD.getSessionService(AuthD.java:799)
       at com.sun.identity.authentication.service.AuthD.initAuthSession(AuthD.java:815)
       at com.sun.identity.authentication.service.AuthD.<init>(AuthD.java:243)
       ... 48 more
    Caused by: java.lang.NullPointerException
    
Note

You may see the "Unable to parse product versions for comparison" error during upgrade even though the com.iplanet.am.version property is populated correctly. If this happens, you should also check your AM debug logs for a "No subject alternative DNS name matching" error and refer to LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x for further information.

You may also see an error similar to the following in the debug.out log:

amAudit:08/17/2017 10:21:35:895 AM EDT: Thread[localhost-startStop-1,5,main]: TransactionId[45e67abf-fcbc-42a8-a8ca-7081d9be1605-0]
ERROR: Error accessing service AuditService
Message:Service does not exist : AuditService
   at com.sun.identity.sm.ServiceSchemaManagerImpl.isValid(ServiceSchemaManagerImpl.java:138)
   at com.sun.identity.sm.ServiceSchemaManagerImpl.<init>(ServiceSchemaManagerImpl.java:116)
   at com.sun.identity.sm.ServiceSchemaManagerImpl.getInstance(ServiceSchemaManagerImpl.java:640)
   at com.sun.identity.sm.ServiceConfigManagerImpl.getGlobalConfig(ServiceConfigManagerImpl.java:194)
   at com.sun.identity.sm.ServiceConfigManager.getGlobalConfig(ServiceConfigManager.java:253)
   at org.forgerock.openam.audit.configuration.AuditServiceConfigurationProviderImpl.getAuditGlobalConfiguration(AuditServiceConfigurationProviderImpl.java:270)
   at org.forgerock.openam.audit.configuration.AuditServiceConfigurationProviderImpl.getDefaultConfiguration(AuditServiceConfigurationProviderImpl.java:137)
   at org.forgerock.openam.audit.AuditServiceProviderImpl.refreshDefaultAuditService(AuditServiceProviderImpl.java:132)
   at org.forgerock.openam.audit.AuditServiceProviderImpl.access$000(AuditServiceProviderImpl.java:47)
   at org.forgerock.openam.audit.AuditServiceProviderImpl$1.globalConfigurationChanged(AuditServiceProviderImpl.java:93)
   at org.forgerock.openam.audit.configuration.AuditServiceConfigurationProviderImpl.addConfigurationListener(AuditServiceConfigurationProviderImpl.java:100)
   at org.forgerock.openam.audit.AuditServiceProviderImpl.registerListeners(AuditServiceProviderImpl.java:90)
   at org.forgerock.openam.audit.AuditServiceProviderImpl.<init>(AuditServiceProviderImpl.java:69)

Checking the com.iplanet.am.version property

You can check the com.iplanet.am.version property in the configuration store of the current AM/OpenAM version (that is, the one you are upgrading from) using one of the following methods. The value of this property should specify the product version and build details (per the table in the Solutions section):

  • Check a previous configuration export for this value assuming you have a recent backup.
  • Use the ldapsearch command to check the value, for example:
    $ ./ldapsearch --hostname ds1.example.com --port 50389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "ou=server-default,ou=com-sun-identity-servers,ou=default,ou=GlobalConfig,ou=1.0,ou=iPlanetAMPlatformService,ou=services,dc=openam,dc=forgerock,dc=org" '(objectclass=*)' '+' '*' | grep am.version
    
  • Use ssoadm to check the value, for example:
    $ ./ssoadm list-server-cfg -u amadmin -f pwd.txt -s default | grep am.version
  • Check the value of the com.iplanet.am.version property in the console (if the console is available). In AM / OpenAM 13.5, navigate to: Configure > Server Defaults > Advanced and in pre-OpenAM 13.5, navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced.

Example corrupted or incomplete values that can cause this issue are:

com.iplanet.am.version=@VERSION@ (@DATESTAMP@)
com.iplanet.am.version=OpenAM 14.0.0

If you are upgrading to a customized AM/OpenAM, that is, you have deployed a custom war file, you should also check the version is correct in the customized war file: Check the com.iplanet.am.version property value in the serverdefaults.properties file (located in the WEB-INF/classes directory in the war file) and ensure it corresponds to the version you are upgrading to per the table in the Solutions section.

Recent Changes

Deployed a later AM/OpenAM war file in order to upgrade.

Deployed a custom war file.

Used Amster to export and import service configurations.

Causes

The com.iplanet.am.version property indicates the AM/OpenAM version and is used to determine when the upgrade process should be started. The upgrade process is triggered if the version in the deployed AM/OpenAM war file is newer than the version defined in the configuration store. If the value in the configuration store is missing, incomplete or corrupted, the upgrade will not proceed correctly.

Possible reasons for an invalid com.iplanet.am.version property include:

  • You have deployed a custom war file - this may be the currently deployed AM/OpenAM or the one you are upgrading to.
  • You exported and imported a service configuration using Amster in AM 5 or 5.1.x; there is a known issue, which removes the com.iplanet.am.version property value: OPENAM-11307 (Amster import should not set the com.iplanet.am.version property). This issue is resolved in AM 5.5.

Solution

This issue can be resolved using one of the following approaches:

  • Modify the com.iplanet.am.version value directly in the configuration store.
  • Modify the com.iplanet.am.version value in AM/OpenAM.

Modify the com.iplanet.am.version value directly in the configuration store

  1. Create an ldif file to update the com.iplanet.am.version value, ensuring you specify the value that corresponds to the version you are upgrading from (find the required value in the table below). For example, if you are upgrading from OpenAM 13.5.0:
    $ cat version.ldif
    dn: ou=server-default,ou=com-sun-identity-servers,ou=default,ou=GlobalConfig,ou=1.0,ou=iPlanetAMPlatformService,ou=services,dc=openam,dc=forgerock,dc=org
    changetype: modify
    replace: com.iplanet.am.version 
    com.iplanet.am.version=OpenAM 13.5.0 Build 550cfe7d60 (2016-July-13 08:43)
    
  2. Update the configuration store with this modified entry using the following command depending on your version:
    • DS 5 and later:
      $ ./ldapmodify --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password version.ldif --UseSSL --trustALL
    • Pre-DS 5:
      $ ./ldapmodify --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --filename version.ldif --UseSSL --trustALL
      
  3. Restart the web application container in which AM/OpenAM runs to pick up this updated configuration; this should initiate the upgrade process again.

Modify the com.iplanet.am.version value in AM/OpenAM

  1. Modify the com.iplanet.am.version to the AM/OpenAM version currently deployed (that is, the version you are upgrading from) using either the console (if the console is available) or ssoadm (find the required value in the table below):
    • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Advanced and add the com.iplanet.am.version property and appropriate value. Once you have entered the property and value, click + to add followed by Save Changes.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced and add the com.iplanet.am.version property and appropriate value.
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s default -a com.iplanet.am.version="[version]"
      replacing [adminID], [passwordfile] and [version] with appropriate values, where the [version] must be quotes.
  2. Restart the web application container in which AM/OpenAM runs to update the configuration; this should initiate the upgrade process again.

AM/OpenAM version and corresponding com.iplanet.am.version values

The following table shows the required value depending on your AM/OpenAM version:

AM/OpenAM version com.iplanet.am.version
AM 6.5 ForgeRock Access Management 6.5.0 Build f8ac1261d9 (2018-November-28 15:19)
AM 6.0.0.6 ForgeRock Access Management 6.0.0.6 Build 92d60f32d1 (2018-November-26 06:25)
AM 6.0.0.5 ForgeRock Access Management 6.0.0.5 Build 70748811ef (2018-October-12 05:22)
AM 6.0.0.4 ForgeRock Access Management 6.0.0.4 Build 36b7da0716 (2018-August-19 21:05)
AM 6.0.0.3 ForgeRock Access Management 6.0.0.3 Build 6b8d8d357c (2018-July-15 21:12)
AM 6.0.0.2 ForgeRock Access Management 6.0.0.2 Build 3a1761ce2e (2018-June-12 22:40) 
AM 6.0.0.1 ForgeRock Access Management 6.0.0.1 Build e149ecbb9b (2018-May-23 20:06)
AM 6 ForgeRock Access Management 6.0.0 Build 3676519ec1 (2018-May-08 10:07)
AM 5.5.1 ForgeRock Access Management 5.5.1 Build 96b47ad4f1 (2017-October-26 15:41)
AM 5.5 ForgeRock Access Management 5.5.0 Build 95de0e129b (2017-October-19 14:37)
AM 5.1.1 OpenAM 14.1.1 Build 2de1c7b98b (2017-August-09 12:33)
AM 5.1 OpenAM 14.1.0 Build 0d174ec57d (2017-June-06 09:33)
AM 5 OpenAM 14.0.0 Build 2db9af6287 (2017-March-29 05:21)
OpenAM 13.5.2 OpenAM 13.5.2 Build 3242213173 (2018-June-05 14:43)
OpenAM 13.5.1 OpenAM 13.5.1 Build 15db0458c8 (2017-July-21 10:54)
OpenAM 13.5.0 OpenAM 13.5.0 Build 550cfe7d60 (2016-July-13 08:43)
OpenAM 13.0 OpenAM 13.0.0 Build 5d4589530d (2016-January-14 21:15)
OpenAM 12.0.4 OpenAM 12.0.4 Build 55a318123d (2016-October-12 08:25)
OpenAM 12.0.3 OpenAM 12.0.3 Build 29988e300d (2016-May-18 11:37)
OpenAM 12.0.2 OpenAM 12.0.2 Build 15797 (2015-September-21 17:41)
OpenAM 12.0.1 OpenAM 12.0.1 Build 14322 (2015-June-22 16:03)
OpenAM 12.0.0 OpenAM 12.0.0 Build 11961 (2014-December-17 21:16)

See Also

ssoadm command fails to run with null pointer exception in AM 5 and 5.1.x

Best practice for upgrading to AM 6.x

Best practice for upgrading to AM 5.x

Best practice for upgrading to OpenAM 13.x

How do I upgrade AM/OpenAM (All versions) with minimal downtime when replication is used?

How do I upgrade AM/OpenAM (All versions) if I am using a site configuration?

FAQ: Upgrading AM/OpenAM

Upgrading AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11547 (Missing entry or corrupted value in "com.iplanet.am.version" causes upgrade failure )

OPENAM-11307 (Amster import should not set the com.iplanet.am.version property)

OPENAM-9967 (OpenAM upgrade can hang if com.iplanet.am.version is not found)

OPENAM-2090 (OPENAM_HOME/.version file is not updated)


Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ

The purpose of this article is to provide assistance if your upgrade to AM/OpenAM fails with a "Connect Error: No operational connection factories available". This issue will only affect you if you are using DS/OpenDJ for your configuration store and anonymous access is disabled for that DS/OpenDJ instance.

Symptoms

The upgrade process fails and a Upgrade Failed message is shown if you are using the upgrade.jar tool (openam-upgrade-tool-13.0.0.jar for OpenAM 13.0) to perform the upgrade. If you are using the Upgrade Wizard, the upgrade hangs on the Upgrade in progress window.

An error similar to the following is shown in the amUpgrade log when this happens:

amUpgrade:10/08/2015 09:32:11:664 AM GMT: Thread[http-bio-8080-exec-11,5,main]
ERROR: An error occurred while trying to get a connection
org.forgerock.opendj.ldap.ConnectionException: Connect Error: No operational connection factories available
    at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:210)
    at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:172)
    at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:142)
... 
Caused by: org.forgerock.opendj.ldap.ConnectionException: Server Connection Closed: Heartbeat failed
    at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:210)
... 
Caused by: org.forgerock.opendj.ldap.ErrorResultException: Unwilling to Perform: Rejecting the requested operation because the connection has not been authenticated

Correspondingly, the DS/OpenDJ access log shows a CONNECT and DISCONNECT without a SEARCH occurring:

[12/Jun/2015:15:46:31 +0100] CONNECT conn=6 from=127.0.0.1:35590 to=127.0.0.1:20389 protocol=LDAP 
[12/Jun/2015:15:46:31 +0100] UNBIND REQ conn=6 op=1 msgID=2 
[12/Jun/2015:15:46:31 +0100] DISCONNECT conn=6 reason="Client Unbind"  

Recent Changes

Disabled anonymous access in DS/OpenDJ using the following command:

$ ./dsconfig --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:true --trustAll --no-prompt

Causes

Completely disabling anonymous access in DS/OpenDJ prevents the SEARCH request from succeeding if AM/OpenAM uses the heartbeat mechanism (which it does by default) and causes connections from AM/OpenAM to fail. AM/OpenAM needs access to the configuration store during the upgrade process, so the upgrade process fails if AM/OpenAM cannot connect.

See How does AM/OpenAM (All versions) use anonymous access calls to DS/OpenDJ? for further information.

Solution

This issue can be resolved by re-enabling anonymous access in DS/OpenDJ using the following command and then performing the upgrade again:

$ ./dsconfig --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:false --trustAll --no-prompt

You can use Access Control Instruction (ACI) in DS/OpenDJ to prevent anonymous access without affecting the heartbeat mechanism. See How do I prevent anonymous access in DS/OpenDJ (All versions)? for further information.

See Also

How do I prevent anonymous access in DS/OpenDJ (All versions)?

How does AM/OpenAM (All versions) use anonymous access calls to DS/OpenDJ?

AM/OpenAM (All versions) fails to connect to the user data store when anonymous access is disabled in DS/OpenDJ

Best practice for upgrading to OpenAM 13.x

Best practice for upgrading to OpenAM 12.x

Setup and Maintenance Guide › Setting Up Identity Data Stores

Installation Guide › Implementing the Core Token Service

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3498 (IdRepo connection pool fails if anonymous access is disabled)


Outdated JSP pages causing problems after upgrading AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you are experiencing issues caused by outdated JSP pages after upgrading AM/OpenAM on Apache Tomcat™.

Symptoms

You see old JSP pages instead of the updated ones, even after a restart.

You may see failures due to old JSP pages calling out-of-date classes.

You notice traces of the old deployment even though you have upgraded.

Recent Changes

Upgraded AM/OpenAM.

Causes

The Tomcat cache has stored old JSP pages and is using them instead of the updated versions. This can happen if your server clock is wrong, causing the new JSP pages to have an older timestamp than the cached pages.

Solution

This issue can be resolved by clearing out the Tomcat cache and correcting your server clock.

You can clear out the Tomcat cache as follows:

  1. Make a backup of the files in the following work directory:
    /path/to/tomcat/work/Catalina/localhost/openam
  2. Stop the server.
  3. Delete the files in the work directory:
    $ rm -rf /path/to/tomcat/work/Catalina/localhost/openam
  4. Restart the server.

See Also

FAQ: Upgrading AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


Error during shutdown message when stopping an AM 6 instance running on Apache Tomcat

The purpose of this article is to provide assistance if you encounter an "Error during shutdown" message when stopping an AM instance running on Apache Tomcat™. This is an intermittent issue.

Symptoms

The AM instance is not fully shut down after issuing the shutdown command. You can observe this using the ps command, which will show the process is still running. See How do I check if AM/OpenAM (All versions) is up and running? for further information.

The following error is shown in the CoreSystem debug log when this happens:

SystemTimer:05/08/2018 11:50:07:525 PM BST: Thread[localhost-startStop-2,5,main]: TransactionId[ec243db4-0458-4907-a387-9ef923cf96d0-1188]
ERROR: TimerPool:shutdown() terminating remaining worker thread[189]
amUtil:05/08/2018 11:50:08:461 PM BST: Thread[localhost-startStop-2,5,main]: TransactionId[ec243db4-0458-4907-a387-9ef923cf96d0-1188]
ERROR: Error during shutdown
java.util.concurrent.RejectedExecutionException: Task java.util.concurrent.FutureTask@6566ca14 rejected from java.util.concurrent.ThreadPoolExecutor@146e55b4[Terminated, pool size = 0, active threads = 0, queued tasks = 0, completed tasks = 2446]
   at java.util.concurrent.ThreadPoolExecutor$AbortPolicy.rejectedExecution(ThreadPoolExecutor.java:2047)
   at java.util.concurrent.ThreadPoolExecutor.reject(ThreadPoolExecutor.java:823)
   at java.util.concurrent.ThreadPoolExecutor.execute(ThreadPoolExecutor.java:1369)
   at java.util.concurrent.AbstractExecutorService.submit(AbstractExecutorService.java:112)
   at org.forgerock.openam.audit.context.AuditRequestContextPropagatingExecutorService.submit(AuditRequestContextPropagatingExecutorService.java:111)
   at com.iplanet.dpro.session.monitoring.SessionMonitoringStore.storeRefreshTime(SessionMonitoringStore.java:90)
   at com.iplanet.dpro.session.monitoring.MonitoredOperations.refresh(MonitoredOperations.java:84)
   at com.iplanet.dpro.session.service.SessionService.refresh(SessionService.java:339)
   at com.iplanet.sso.providers.dpro.SSOProviderImpl.isValidToken(SSOProviderImpl.java:264)
   at com.iplanet.sso.SSOTokenManager.isValidToken(SSOTokenManager.java:459)
   at com.iplanet.sso.SSOTokenManager.isValidToken(SSOTokenManager.java:444)
   at com.sun.identity.security.AdminTokenAction.run(AdminTokenAction.java:186)
   at com.sun.identity.security.AdminTokenAction.run(AdminTokenAction.java:67)
   at java.security.AccessController.doPrivileged(Native Method)
   at com.sun.identity.idm.plugins.internal.SpecialRepo.removeListener(SpecialRepo.java:526)
   at com.sun.identity.idm.server.IdRepoPluginsCache.clearIdRepoPluginsCache(IdRepoPluginsCache.java:318)
   at com.sun.identity.idm.server.IdServicesImpl.clearIdRepoPlugins(IdServicesImpl.java:2592)
   at com.sun.identity.idm.server.IdCachedServicesImpl$1.shutdown(IdCachedServicesImpl.java:153)
   at com.sun.identity.common.ShutdownManager.shutdown(ShutdownManager.java:217)
   at com.sun.identity.common.ShutdownServletContextListener.contextDestroyed(ShutdownServletContextListener.java:51)
   at org.apache.catalina.core.StandardContext.listenerStop(StandardContext.java:4837)
   at org.apache.catalina.core.StandardContext.stopInternal(StandardContext.java:5484)
   at org.apache.catalina.util.LifecycleBase.stop(LifecycleBase.java:232)
   at org.apache.catalina.core.ContainerBase$StopChild.call(ContainerBase.java:1575)
   at org.apache.catalina.core.ContainerBase$StopChild.call(ContainerBase.java:1564)
   at java.util.concurrent.FutureTask.run(FutureTask.java:266)
   at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
   at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
   at java.lang.Thread.run(Thread.java:745)

The following messages are shown in catalina.out:

May 08, 2018 11:50:07 PM org.apache.catalina.core.StandardServer await
INFO: A valid shutdown command was received via the shutdown port. Stopping the Server instance.
May 08, 2018 11:50:07 PM org.apache.coyote.AbstractProtocol pause
INFO: Pausing ProtocolHandler ["http-bio-28080"]
May 08, 2018 11:50:07 PM org.apache.coyote.AbstractProtocol pause
INFO: Pausing ProtocolHandler ["ajp-bio-28009"]
May 08, 2018 11:50:07 PM org.apache.catalina.core.StandardService stopInternal
INFO: Stopping service Catalina
May 08, 2018 11:50:08 PM org.apache.catalina.loader.WebappClassLoader clearReferencesThreads
SEVERE: The web application [/openam] appears to have started a thread named [RxSchedulerPurge-1] but has failed to stop it. This is very likely to create a memory leak.
May 08, 2018 11:50:08 PM org.apache.catalina.loader.WebappClassLoader clearReferencesThreads
SEVERE: The web application [/openam] appears to have started a thread named [RxCachedWorkerPoolEvictor-1] but has failed to stop it. This is very likely to create a memory leak.
May 08, 2018 11:50:08 PM org.apache.catalina.loader.WebappClassLoader clearReferencesThreads
SEVERE: The web application [/openam] appears to have started a thread named [OpenDJ LDAP SDK Default Scheduler] but has failed to stop it. This is very likely to create a memory leak.
...

If you restart the instance, the browser will show a Loading... message and you will be unable to use the console.

Recent Changes

Shut down an AM 6 instance.

Causes

Threads not being terminated upon shutdown is a known issue: OPENAM-13008 (Occasional shutdown error for AM).

Solution

This issue can be resolved by upgrading to AM 6.0.0.1 or later; you can download this from BackStage.

Workaround

You can workaround this issue using one of the following options:

  • Forcibly end process using kill -9
  • Define CATALINA_PID environment variable to issue kill -9  only if needed

Forcibly end process

  1. Identify the process ID using the following command:
    $ ps –ef |grep tomcat
    Example response, where process ID is 2240:
    forgero+  2240     1  3 10:34 pts/1    00:01:31 /usr/lib/jvm/java-8-oracle/bin/java -Djava.util.logging.config.file=/opt/tomcat/am6/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Xms2048m -Xmx2048m -XX:MaxPermSize=512m -Xss256k -XX:+UseParallelGC -XX:MaxGCPauseMillis=1500 -XX:GCTimeRatio=9 -server -XX:+DisableExplicitGC -Djava.endorsed.dirs=/opt/tomcat/am6/endorsed -classpath /opt/tomcat/am6/bin/bootstrap.jar:/opt/tomcat/am6/bin/tomcat-juli.jar -Dcatalina.base=/opt/tomcat/am6 -Dcatalina.home=/opt/tomcat/am6 -Djava.io.tmpdir=/opt/tomcat/am6/temp org.apache.catalina.startup.Bootstrap start
    forgero+  2966  2193  0 11:14 pts/1    00:00:00 grep --color=auto tomcat
  2. End the process using the following command and the identified process ID, for example:
    $ kill -9 2240 
  3. Repeat step 2 if more than one process is running for the AM instance you are trying to shut down (this can happen if you started and stopped the instance again).

You can now restart the AM instance successfully.

Define CATALINA_PID environment variable

You can configure Tomcat to mitigate this issue in the future by defining the CATALINA_PID environment variable in the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (also typically located in the /tomcat/bin/ directory). 

  1. End the process if it is still running using the steps above (identify process ID and use kill -9).
  2. Add the following line to the setenv.sh file:
    CATALINA_PID="$CATALINA_BASE/bin/catalina.pid"
  3. Restart the web container.

You can now shut down AM 6 instances by appending the shutdown command with -force, which issues a kill -9 command for the relevant process after 5 seconds if it has not shutdown cleanly. For example:

$ ./shutdown.sh -force

See Also

Best practice for upgrading to AM 6.x

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13008 (Occasional shutdown error for AM)


Creating authentication module via ssoadm causes Not found error in AM 5, 5.1.x and OpenAM 13.0, 13.5

The purpose of this article is to provide assistance if you create an authentication module via ssoadm and get a "Not found error" when trying to open the new module in the AM/OpenAM console.

Symptoms

When you create an authentication module via ssoadm with a command such as the following, where the module name and type match:

$ ./ssoadm create-auth-instance -u amadmin -f pwd.txt -e / -m HOTP -t HOTP 

the module appears to be created but when you try to open it in the console, you will see the following message:

Not found error.

Please note: 

  • You can create authentication modules with the same module name and type via the console. 
  • This issue affects all authentication modules, including custom ones.
  • This issue also affects authentication modules that were created in earlier versions of AM/OpenAM, where the module name and type match. If you upgrade to an affected version and then try to open an authentication module that was created in an earlier version of OpenAM with the same module name and type, you will see the "Not found error."

Recent Changes

Upgraded to, or installed AM 5 or 5.1.x.

Upgraded to, or installed OpenAM 13.0 or 13.5.

Causes

The sub-configuration is not created if the name of the authentication module is the same as the auth type when the module is created using ssoadm.

Solution

This issue can be resolved by upgrading to AM 5.5 and later, or OpenAM 13.5.1; you can download this from BackStage.

Workaround

You can workaround this issue by using a different module name and type when creating the authentication module via ssoadm. For example:

$ ./ssoadm create-auth-instance -u amadmin -f pwd.txt -e / -m HOTPmodule -t HOTP

Alternatively, you can create the authentication module via the console, which allows you to use the same module name and type if required.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9156 ('Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type)

OPENAM-8574 (The OpenAM CREST processing chain doesn't contain a RuntimeException handler)


Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

The purpose of this article is to provide assistance if your upgrade to OpenAM 12.x or 13.x fails with ERROR: "Failed to modify privilege!" when migrating policies. This issue will only occur if you are upgrading from a pre-OpenAM 12.0.0 release and the policies are being migrated to the OpenAM 12.x or 13.x format for the first time.

Symptoms

The upgrade fails and you see the following message in the Upgrade wizard:

Failed to modify privilege!

An error similar to the following is shown in the amUpgrade log when the Upgrade fails:

amUpgrade:10/12/2015 04:07:22:665 PM PDT: Thread[catalina-exec-1,5,main]
ERROR: Failed to modify privilege!
com.sun.identity.entitlement.EntitlementException: Invalid Resource https://openam.example.com:8443/web/personal-details?*
	at com.sun.identity.entitlement.Entitlement.validateResourceNames(Entitlement.java:826)
	at com.sun.identity.entitlement.Privilege.validateResourceNames(Privilege.java:164)
	at com.sun.identity.entitlement.opensso.PolicyPrivilegeManager.modify(PolicyPrivilegeManager.java:265)
	at org.forgerock.openam.upgrade.steps.policy.conditions.OldPolicyConditionMigrationUpgradeStep.perform(OldPolicyConditionMigrationUpgradeStep.java:193)
	at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186)
	at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)
...	
amUpgrade:10/12/2015 04:07:22:666 PM PDT: Thread[catalina-exec-1,5,main]
ERROR: Error occured while upgrading OpenAM
org.forgerock.openam.upgrade.UpgradeException: Failed to modify privilege!
	at org.forgerock.openam.upgrade.steps.policy.conditions.OldPolicyConditionMigrationUpgradeStep.perform(OldPolicyConditionMigrationUpgradeStep.java:196)
	at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186)
	at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)

Recent Changes

Upgrading from a pre-OpenAM 12.0.0 release.

Causes

You only have one referral rule from the top-level realm. As per changes that were introduced in OpenAM 11.0.0, you should have three referral rules, for example: 

  • root "/"
  • pages "/*"
  • pages with parameters "/*?*"

Solution

This issue can be resolved by adding the other two referral rules and re-running the upgrade. 

For example, if your current referral rule is: 

https://openam.example.com:8443/*

You would need to add the following referral rules:

https://openam.example.com:8443/
https://openam.example.com:8443/*?*
Note

Although referrals are not used in OpenAM 13, they still need to be correct prior to upgrading as they are processed during the upgrade process as detailed in OpenAM 13 Upgrade Guide › Upgrading OpenAM Servers.

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

Best practice for creating and testing policies in AM/OpenAM (All versions)

OpenAM 11.0.0 Release Notes › OpenAM Changes & Deprecated Functionality › Important Changes to Existing Functionality 

OpenAM 12.0.0 Release Notes › OpenAM Changes and Deprecated Functionality › Important Changes to Existing Functionality

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-5333 (Upgrade failure when policy has more than one rule)

OPENAM-3509 (PolicyEvaluation strips off trailing '/' from resource resulting in wrong enforcement on agent side)


REST API calls fail after upgrading to OpenAM 12.x or 13.x

The purpose of this article is to provide assistance if your REST API calls (that worked previously) fail after upgrading to OpenAM 12.x or 13.x. This includes requests made indirectly; for example, when you create a REST STS instance in the OpenAM console.

Symptoms

The REST call, or OpenAM functionality that has an underlying REST request, fails after upgrading to OpenAM 12.x or 13.x. The same behavior worked in a previous release.

Example failed request 

The following example shows a REST call and the possible failed responses:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Content-Type: application/json" --data '{"currentpassword":"changeit","userpassword":"newpassword"}' http://openam.example.com:8080/openam/json/users/user.0?_action=changePassword

Which can result in:

{"code":501,"reason":"Not Implemented","message":"Actions are not supported for resource instances"}

Or:

{"code":404,"reason":"Not Found","message":"User not found"}

Example failed functionality with underlying REST request

When adding a REST STS instance in the OpenAM console, you may receive the following error:

HTTP Status 500 - AMSetupFilter.doFilter

Recent Changes

Upgraded to OpenAM 12.x or 13.x.

Causes

The resource version associated with the REST request is incompatible with the endpoint being called and OpenAM release combination.  

Since OpenAM 12.0.0, REST API features have been assigned version numbers to allow for compatibility between OpenAM releases. The version number of a feature increases when OpenAM introduces a non-backwards-compatible change that affects clients making use of the feature. Versioning is provided for the resource and protocol elements. See OpenAM Developer's Guide › Developing Client Applications › REST API Versioning for further information on versioning.

Both OpenAM 12.x and 13.x support protocol version 1.0; supported resource versions vary according to the endpoint and the release you are using. You should check the Supported resource Versions table for the relevant release of OpenAM:

Solution

This issue can be resolved by ensuring you use a resource version that is appropriate to the endpoint and OpenAM release you are using.

You can configure a global setting to determine version compatibility and/or specify the versions in your REST request.

Global setting

You can configure the global setting using either the OpenAM console or ssoadm:

  • OpenAM 13.5 console: navigate to: Configure > Global Services > REST APIs > Default Version and select the appropriate option. 
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > REST APIs > Default Version and select the appropriate option. 
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s RestApisService -t Global -u [adminID] -f [passwordfile] -a openam-rest-apis-default-version=[version]
    replacing [adminID], [passwordfile] and [version] with appropriate values, where [version] is LATEST, OLDEST or NONE.

The options available are:

  • LATEST: The latest available supported version of the API is used. This is the preset default for new installations of OpenAM.
  • OLDEST: The oldest available supported version of the API is used. This is the preset default for upgraded OpenAM instances.
  • NONE: If a version is not specified in the request, it will not be defaulted. 
Caution

If you select NONE for the global setting, you must always specify the version in the REST request. If the version is not specified the request will not be handled and will results with a 400 Bad Request error.

You can include the Accept-API-Version header in your REST call to specify the versions. For example, to include resource version 2.0 and protocol version 1.0 you would include the following header:

"Accept-API-Version: resource=2.0, protocol=1.0"

For example:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Accept-API-Version: resource=2.0, protocol=1.0" --header "Content-Type: application/json" --data '{"currentpassword":"changeit", "userpassword":"newpassword"}' http://openam.example.com:8080/openam/json/users/user.0?_action=changePassword

 See OpenAM Developer's Guide › Developing Client Applications › Specifying an Explicit REST API Version for further information.

See Also

FAQ: REST API in AM/OpenAM

OpenAM Developer's Guide › Developing Client Applications › REST API Versioning

OpenAM Administration Guide › Configuring REST APIs

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8380 (REST API Versioning, How to upgrade Rest API version if one upgrade from OpenAM 11x to 12x)


JCEEncryption:: failed to decrypt data error when accessing the admin console in OpenAM 12.x or 13.x

The purpose of this article is to provide assistance if you encounter an "ERROR: JCEEncryption:: failed to decrypt data" when accessing the OpenAM console.

Symptoms

The following error is shown in the IdRepo debug log when this happens:

amSDK:01/28/2016 10:37:25:166 AM JST: Thread[localhost-startStop-1,5,main]: TransactionId[b3fea1eb-aaad-4d20-9b66-941b90e78ad8-2]
ERROR: JCEEncryption:: failed to decrypt data
javax.crypto.BadPaddingException: Given final block not properly padded
        at com.sun.crypto.provider.CipherCore.doFinal(CipherCore.java:966)
        at com.sun.crypto.provider.CipherCore.doFinal(CipherCore.java:824)
        at com.sun.crypto.provider.PBES1Core.doFinal(PBES1Core.java:416)
        at com.sun.crypto.provider.PBEWithMD5AndDESCipher.engineDoFinal(PBEWithMD5AndDESCipher.java:316)
        at javax.crypto.Cipher.doFinal(Cipher.java:2165)
        at com.iplanet.services.util.JCEEncryption.pbeDecrypt(JCEEncryption.java:251)
        at com.iplanet.services.util.JCEEncryption.decrypt(JCEEncryption.java:149)
        at com.iplanet.services.util.Crypt.decode(Crypt.java:350)
        at com.iplanet.services.util.Crypt.decode(Crypt.java:375)
        at com.iplanet.services.ldap.LDAPUser.getPasswd(LDAPUser.java:117)
        at com.iplanet.services.ldap.ServerInstance.getPasswd(ServerInstance.java:128)

You may see the following message in the browser when accessing the OpenAM console:

Authentication service is not initialized. Contact your system administrator.
Note

You may also notice "ERROR: JCEEncryption:: Unsupported version: -98" errors in the IdRepo log. This is a known issue: OPENAM-3009 (IdRepo - JCEEncryption 98 ). If you are not experiencing any functional problems, you can safely ignore these messages.

Recent Changes

Upgraded to OpenAM 12.0.4 or 13.0. 

Causes

This error can occur for one of the following reasons depending on your version of OpenAM:

  • OpenAM 12.0.4 and 13.0 only: When OpenAM starts, the configuration manager (DSConfigMgr) is first initialized with the password values from the bootstrap file; these are used as placeholders and are encrypted with the bootstrap encryption key. The actual server configuration is subsequently loaded from the OpenDJ config store, the JCEEncryption password is set to the correct value for this site and the encryption key is updated to the one specified in the AM_ENC_KEY property (set when you configure OpenAM). DSConfigMgr is then reinitialized to a new instance with the actual configuration data. However, since the SMS ServerConfigurationFactory caches the DSConfigMgr instance when it is first requested, it's a race as to which version of the configuration manager is retrieved. If the first copy is retrieved with the placeholder passwords, OpenAM is unable to decrypt the passwords from the actual configuration since it is using the wrong encryption key. This is a known issue: OPENAM-8214 (JCEEncryption errors are recorded during/after upgrading to 13).
  • All versions of OpenAM: The encryption key is corrupt, which means the directory manager's password (which is stored in the bootstrap file) cannot be decrypted. The encryption key is specified in the AM_ENC_KEY property when you configure OpenAM.

Solution

The solution depends on your version of OpenAM.

OpenAM 12.0.4 and 13.0

You should first ensure your encryption key is correct using one of the following approaches:

If you still see the error after restarting the web application container in which OpenAM runs, it means you are encountering the known issue. This can be resolved by upgrading to OpenAM 13.5 or later; you can download this from BackStage.

Other versions of OpenAM

You should correct your encryption key using one of the following options:

Note

Restarting the web application container in which OpenAM runs will clear the "Authentication service is not initialized. Contact your system administrator." message shown in the browser.

See Also

How do I re-create a bootstrap file for OpenAM 12.x and 13.x if the bootstrap file has become corrupt?

FAQ: Upgrading AM/OpenAM

OpenAM 12.0.4 Installation Guide › Removing OpenAM Software

OpenAM 13.0.0 Installation Guide › Removing OpenAM Software

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8215 (Guice provision errors during upgrade to 13)

OPENAM-8214 (JCEEncryption errors are recorded during/after upgrading to 13)

OPENAM-3009 (IdRepo - JCEEncryption 98 )


OpenAM 13.0 hangs when creating or updating policies and policy sets with BLOCKED and WAITING threads

The purpose of this article is to provide assistance if OpenAM 13.0 hangs when creating or updating policies and policy sets, and you see BLOCKED or WAITING threads. You may also encounter these symptoms in other policy related scenarios, including exporting policies using the ssoadm list-xacml command, accessing UMA resources and upgrading with a large number of policies.

Symptoms

OpenAM intermittently hangs when creating or updating policies and policy sets, exporting policies using the ssoadm list-xacml command or accessing UMA resources. Once it hangs, restarting the web application container in which OpenAM runs will temporarily restore functionality.

You will see either BLOCKED or WAITING threads in a JStack when OpenAM hangs, for example:

http-/0.0.0.0:8080-14" #109 daemon prio=5 os_prio=0 tid=0x0000000022a0d800 nid=0xfc0 in Object.wait() [0x000000002617a000]
java.lang.Thread.State: WAITING (on object monitor)
        at java.lang.Object.wait(Native Method)
        at java.lang.Object.wait(Object.java:502)
        at org.forgerock.util.promise.PromiseImpl.await(PromiseImpl.java:572)
        - locked <0x00000000c7a5ec00> (a org.forgerock.util.promise.PromiseImpl)
        at org.forgerock.util.promise.PromiseImpl.getOrThrow(PromiseImpl.java:143)
        at org.forgerock.opendj.ldap.CachedConnectionPool.getConnection(CachedConnectionPool.java:789)
        at com.sun.identity.sm.ldap.SMDataLayer.getConnection(SMDataLayer.java:107)
        at com.sun.identity.sm.ldap.SMSLdapObject.getConnection(SMSLdapObject.java:574)
        at com.sun.identity.sm.ldap.SMSLdapObject.search(SMSLdapObject.java:591)
        at com.sun.identity.sm.SMSEntry.search(SMSEntry.java:1069)
        at com.sun.identity.entitlement.opensso.DataStore.searchPrivileges(DataStore.java:902)
        at com.sun.identity.entitlement.opensso.DataStore.search(DataStore.java:822)
        at com.sun.identity.entitlement.opensso.OpenSSOIndexStore$SearchTask.run(OpenSSOIndexStore.java:96)
...
        at com.sun.identity.entitlement.ApplicationPrivilegeManager.getInstance(ApplicationPrivilegeManager.java:188)

Thread 2931: (state = BLOCKED)
 - sun.misc.Unsafe.park(boolean, long) @bci=0 (Interpreted frame)
 - java.util.concurrent.locks.LockSupport.parkNanos(java.lang.Object, long) @bci=20, line=226 (Interpreted frame)
 - java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.awaitNanos(long) @bci=68, line=2082 (Interpreted frame)
 - java.util.concurrent.LinkedBlockingQueue.poll(long, java.util.concurrent.TimeUnit) @bci=62, line=467 (Interpreted frame)
 - org.forgerock.opendj.ldif.ConnectionEntryReader.getNextResponse() @bci=21, line=398 (Interpreted frame)
 - org.forgerock.opendj.ldif.ConnectionEntryReader.hasNext() @bci=1, line=231 (Interpreted frame)
 - com.sun.identity.sm.ldap.SMSLdapObject.searchObjects(com.iplanet.sso.SSOToken, java.lang.String, java.lang.String, int, int, boolean, boolean, org.forgerock.opendj.ldap.Connection) @bci=81, line=702 (Interpreted frame)

Upgrade process

This issue can also cause the upgrade process to hang with one of the following errors in the amUpgrade debug log, in addition to BLOCKED threads:

ERROR: Error occured while upgrading OpenAM
org.forgerock.openam.upgrade.UpgradeException: Failed to gather policies for application iPlanetAMWebAgentService
   at org.forgerock.openam.upgrade.steps.policy.UpgradeResourceTypeStep.upgradePrivileges(UpgradeResourceTypeStep.java:416)
   at org.forgerock.openam.upgrade.steps.policy.UpgradeResourceTypeStep.perform(UpgradeResourceTypeStep.java:249)
   at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:151)
   at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:83)
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
ERROR: Error occured while upgrading OpenAM
org.forgerock.openam.upgrade.UpgradeException: Application cloning failed
   at org.forgerock.openam.upgrade.steps.RemoveReferralsStep.instateReferredApplications(RemoveReferralsStep.java:204)
   at org.forgerock.openam.upgrade.steps.RemoveReferralsStep.perform(RemoveReferralsStep.java:195)
   at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:151)
   at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:83)

Recent Changes

Upgraded to, or installed OpenAM 13.0.

Causes

Connections are being opened but not closed and returned to the connection pool, which eventually causes OpenAM to hang. During the upgrade process, this can happen when the upgrade reaches the policy section and is migrating policies or removing policy referrals.

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

How do I export and import policies in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8531 (Connection leak in policy codebase)

OPENAM-8459 (LDAPAuthUtils should set operations timeout in seconds)

OPENAM-10116 (Search timeout for LDAP filter condition should be in seconds)


Upgrade to OpenAM 12.0.0 or 12.0.1 fails with Entry Already Exists exception when CTS store is external with non-default suffix

The purpose of this article is to provide assistance if your upgrade to OpenAM 12.0.0 or 12.0.1 fails with "Entry Already Exists" exception when CTS store is external with a non-default suffix.

Symptoms

An error similar to the following is shown in the amUpgrade log when the upgrade fails:

amUpgrade:08/10/2015 11:29:48:557 AM BST: Thread[http-bio-8080-exec-10,5,main]
ERROR: An error occurred while processing /WEB-INF/template/ldif/sfha/cts-container.ldif
org.forgerock.opendj.ldap.ErrorResultIOException: org.forgerock.opendj.ldap.ConstraintViolationException: Entry Already Exists: The entry ou=tokens,dc=example,dc=com cannot be added because an entry with that name already exists
        at org.forgerock.opendj.ldif.ConnectionChangeRecordWriter.writeChangeRecord(ConnectionChangeRecordWriter.java:109)
        at org.forgerock.opendj.ldif.ConnectionChangeRecordWriter.writeChangeRecord(ConnectionChangeRecordWriter.java:56)
        at org.forgerock.opendj.ldif.ChangeRecordVisitorWriter.visitChangeRecord(ChangeRecordVisitorWriter.java:59)
        at org.forgerock.opendj.ldif.ChangeRecordVisitorWriter.visitChangeRecord(ChangeRecordVisitorWriter.java:39)
        at org.forgerock.opendj.ldap.requests.AddRequestImpl.accept(AddRequestImpl.java:58)
        at org.forgerock.opendj.ldif.ConnectionChangeRecordWriter.writeChangeRecord(ConnectionChangeRecordWriter.java:131)
        at org.forgerock.opendj.ldif.ConnectionChangeRecordWriter.writeChangeRecord(ConnectionChangeRecordWriter.java:56)
        at org.forgerock.openam.upgrade.DirectoryContentUpgrader.processLDIF(DirectoryContentUpgrader.java:180)
        at org.forgerock.openam.upgrade.DirectoryContentUpgrader.upgrade(DirectoryContentUpgrader.java:212)
        at org.forgerock.openam.upgrade.steps.UpgradeDirectoryContentStep.perform(UpgradeDirectoryContentStep.java:72)
        at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186)
        at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

Recent Changes

Upgrade to OpenAM 12.0.0 or 12.0.1 where you have an external config, separate CTS store and a different suffix used for the external CTS store

Causes

When upgrading to OpenAM 12.0.0 or 12.0.1 and an external CTS is configured, a bug in the upgrader process can cause OpenAM to connect to the configuration store instead of the external CTS directory when verifying the CTS backend exists. Since the CTS suffix does not exist in this store, it causes the upgrade to fail with an Entry Already Exists error.

Solution

This issue can be resolved by upgrading to OpenAM 12.0.2 or later; you can download this from BackStage.

See Also

Upgrade to OpenAM 12.0.0 or 12.0.1 hangs in DirectoryContentUpgrader when configuration and CTS stores are external

Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ

Best practice for upgrading to OpenAM 12.x

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6457 (DirectoryContentUpgrader causes Entry Already Exists exception for CTS suffix when upgrading OpenAM)


Upgrade to OpenAM 12.0.0 or 12.0.1 hangs in DirectoryContentUpgrader when configuration and CTS stores are external

The purpose of this article is to provide assistance if your upgrade to OpenAM 12.0.0 and 12.0.1 hangs in DirectoryContentUpgrader when configuration and CTS stores are external (either running on the same or separate OpenDJ instances).

Symptoms

An error similar to the following is shown in the amUpgrade log when the upgrade hangs:

amUpgrade:08/10/2015 01:18:25:955 PM UTC: Thread[http-bio-38080-exec-59,5,main]
ERROR: An error occurred while trying to get a connection
org.forgerock.opendj.ldap.ConnectionException: Connect Error: No operational connection factories available
	at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:210)
	at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:172)
	at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:142)
	at org.forgerock.opendj.ldap.AbstractLoadBalancingAlgorithm.getMonitoredConnectionFactory(AbstractLoadBalancingAlgorithm.java:389)
	at org.forgerock.opendj.ldap.AbstractLoadBalancingAlgorithm.access$100(AbstractLoadBalancingAlgorithm.java:55)
	at org.forgerock.opendj.ldap.AbstractLoadBalancingAlgorithm$MonitoredConnectionFactory.getConnection(AbstractLoadBalancingAlgorithm.java:84)
	at org.forgerock.opendj.ldap.LoadBalancer.getConnection(LoadBalancer.java:53)
	at org.forgerock.openam.upgrade.DirectoryContentUpgrader.upgrade(DirectoryContentUpgrader.java:210)
	at org.forgerock.openam.upgrade.steps.UpgradeDirectoryContentStep.perform(UpgradeDirectoryContentStep.java:72)
	at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186)
	at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)
...

Correspondingly, you may see BLOCKED or WAITING threads relating to DirectoryContentUpgrader when the upgrade hangs, similar to the following example stack traces:

  • BLOCKED:
    Thread 17573: (state = BLOCKED)
     - sun.misc.Unsafe.park(boolean, long) @bci=0 (Interpreted frame)
     - java.util.concurrent.locks.LockSupport.park(java.lang.Object) @bci=14, line=186 (Interpreted frame)
     - java.util.concurrent.locks.AbstractQueuedSynchronizer.parkAndCheckInterrupt() @bci=1, line=834 (Interpreted frame)
     - java.util.concurrent.locks.AbstractQueuedSynchronizer.doAcquireSharedInterruptibly(int) @bci=72, line=994 (Interpreted frame)
     - java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireSharedInterruptibly(int) @bci=24, line=1303 (Interpreted frame)
     - com.forgerock.opendj.util.AsynchronousFutureResult$Sync.innerGet() @bci=2, line=144 (Interpreted frame)
     - com.forgerock.opendj.util.AsynchronousFutureResult.get() @bci=4, line=267 (Interpreted frame)
     - org.forgerock.opendj.ldap.CachedConnectionPool.getConnection() @bci=5, line=772 (Interpreted frame)
     - org.forgerock.opendj.ldap.AbstractLoadBalancingAlgorithm$MonitoredConnectionFactory.getConnection() @bci=4, line=79 (Interpreted frame)
     - org.forgerock.opendj.ldap.LoadBalancer.getConnection() @bci=9, line=53 (Interpreted frame)
     - org.forgerock.openam.upgrade.DirectoryContentUpgrader.upgrade() @bci=6, line=210 (Interpreted frame)
     - org.forgerock.openam.upgrade.steps.UpgradeDirectoryContentStep.perform() @bci=4, line=72 (Interpreted frame)
     - org.forgerock.openam.upgrade.UpgradeServices.upgrade(com.iplanet.sso.SSOToken, boolean) @bci=94, line=186 (Interpreted frame)
     - com.sun.identity.config.upgrade.Upgrade.doUpgrade() @bci=12, line=79 (Interpreted frame)
    ...
    
  • WAITING:
    http-bio-8080-exec-3" daemon prio=3 tid=0x0000000105e37800 nid=0xae waiting on condition [0xffffffff6bdfa000] 
    java.lang.Thread.State: WAITING (parking) 
    at sun.misc.Unsafe.park(Native Method) 
    - parking to wait for <0x00000007b2cd1e20> (a com.forgerock.opendj.util.AsynchronousFutureResult$Sync) 
    at java.util.concurrent.locks.LockSupport.park(LockSupport.java:186) 
    at java.util.concurrent.locks.AbstractQueuedSynchronizer.parkAndCheckInterrupt(AbstractQueuedSynchronizer.java:834) 
    at java.util.concurrent.locks.AbstractQueuedSynchronizer.doAcquireSharedInterruptibly(AbstractQueuedSynchronizer.java:994) 
    at java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireSharedInterruptibly(AbstractQueuedSynchronizer.java:1303) 
    at com.forgerock.opendj.util.AsynchronousFutureResult$Sync.innerGet(AsynchronousFutureResult.java:144) 
    at com.forgerock.opendj.util.AsynchronousFutureResult.get(AsynchronousFutureResult.java:267) 
    at org.forgerock.opendj.ldap.CachedConnectionPool.getConnection(CachedConnectionPool.java:772) 
    at org.forgerock.opendj.ldap.AbstractLoadBalancingAlgorithm$MonitoredConnectionFactory.getConnection(AbstractLoadBalancingAlgorithm.java:79) 
    at org.forgerock.opendj.ldap.LoadBalancer.getConnection(LoadBalancer.java:53) 
    at org.forgerock.openam.upgrade.DirectoryContentUpgrader.upgrade(DirectoryContentUpgrader.java:210) 
    at org.forgerock.openam.upgrade.steps.UpgradeDirectoryContentStep.perform(UpgradeDirectoryContentStep.java:72) 
    at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186) 
    at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)
    ...
    
Note

If you need help capturing stack traces, see How do I collect JVM data for troubleshooting AM/OpenAM (All versions)? for further information.

Recent Changes

N/A

Causes

The default connection pool sizing of 10 is too small due to the way the upgrade process creates connection factories. Due to this sizing issue, the upgrade process hangs at this point.

Solution

This issue can be resolved by upgrading to OpenAM 12.0.2 or later; you can download this from BackStage.

Workaround

Alternatively, this issue can be resolved by temporarily overriding your maximum connection pool size values in your web application container and then performing the upgrade again.

You can override your maximum connection pool size values by setting the following JVM property:

-Dmax_conn_pool=24

Example using Apache Tomcat™ web container

You would override your maximum connection pool size values by specifying CATALINA_OPTS settings in the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (also typically located in the /tomcat/bin/directory).

To override your maximum connection pool size values:

  1. Add the following line to the setenv.sh file:
    export CATALINA_OPTS="-Dmax_conn_pool=24"
  2. Restart the web container.

See Also

Upgrade to OpenAM 12.0.0 or 12.0.1 fails with Entry Already Exists exception when CTS store is external with non-default suffix

Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ

Best practice for upgrading to OpenAM 12.x

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6455 (ConnectionCount logic does not produce a sensible ConnectionFactory max pool size for some scenarios)

OPENAM-6456 (Upgrading to OpenAM 12 hangs in DirectoryContentUpgrader)


java.lang.NoSuchMethodError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle WebLogic 11g server

The purpose of this article is to provide assistance if you encounter a ServletException, java.lang.NoSuchMethodError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle® WebLogic 11g server.

Symptoms

An Upgrade is available page is shown with the following error when you navigate to the OpenAM console after performing the upgrade:

Transaction id: 0 
HTTP Status: 500 
Status code message: Internal Server error

Clicking the Upgrade to OpenAM link does nothing.

An error similar to the following is shown in the server log:

####<Jan 14, 2014 11:36:42 AM CET> <Error> <HTTP> <svvuoam01> <OAMServer1> <[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <<WLS Kernel>> <> <> <1389695802486> <BEA-101017> <[ServletContext@1225998403[app:openam module:openam.war path:/openam spec-version:2.5]] Root cause of ServletException. 
java.lang.NoSuchMethodError: org.apache.commons.lang.StringUtils.join(Ljava/util/Collection;Ljava/lang/String;)Ljava/lang/String; 
at org.forgerock.openam.upgrade.steps.UpgradeServiceSchemaStep.getShortReport(UpgradeServiceSchemaStep.java:355) 
at org.forgerock.openam.upgrade.UpgradeServices.generateShortUpgradeReport(UpgradeServices.java:219) 
at com.sun.identity.config.upgrade.Upgrade.onRender(Upgrade.java:73) 
at org.apache.click.ClickServlet.performOnRender(ClickServlet.java:792) 
at org.apache.click.ClickServlet.processAjaxPageEvents(ClickServlet.java:1865) 
at org.apache.click.ClickServlet.processPage(ClickServlet.java:559) 
at org.apache.click.ClickServlet.handleRequest(ClickServlet.java:383) 
at org.apache.click.ClickServlet.doGet(ClickServlet.java:276) 
at javax.servlet.http.HttpServlet.service(HttpServlet.java:707) 
at javax.servlet.http.HttpServlet.service(HttpServlet.java:820) 
at weblogic.servlet.internal.StubSecurityHelper$ServletServiceAction.run(StubSecurityHelper.java:227) 
at weblogic.servlet.internal.StubSecurityHelper.invokeServlet(StubSecurityHelper.java:125) 
at weblogic.servlet.internal.ServletStubImpl.execute(ServletStubImpl.java:301) 
at weblogic.servlet.internal.TailFilter.doFilter(TailFilter.java:26) 
at weblogic.servlet.internal.FilterChainImpl.doFilter(FilterChainImpl.java:56) 
at org.forgerock.openam.validation.ResponseValidationFilter.doFilter(ResponseValidationFilter.java:44) 
at weblogic.servlet.internal.FilterChainImpl.doFilter(FilterChainImpl.java:56) 
at com.sun.identity.setup.AMSetupFilter.doFilter(AMSetupFilter.java:111) 
at weblogic.servlet.internal.FilterChainImpl.doFilter(FilterChainImpl.java:56) 
at weblogic.servlet.internal.WebAppServletContext$ServletInvocationAction.wrapRun(WebAppServletContext.java:3730) 
at weblogic.servlet.internal.WebAppServletContext$ServletInvocationAction.run(WebAppServletContext.java:3696) 
at weblogic.security.acl.internal.AuthenticatedSubject.doAs(AuthenticatedSubject.java:321) 
at weblogic.security.service.SecurityManager.runAs(SecurityManager.java:120) 
at weblogic.servlet.internal.WebAppServletContext.securedExecute(WebAppServletContext.java:2273) 
at weblogic.servlet.internal.WebAppServletContext.execute(WebAppServletContext.java:2179) 
at weblogic.servlet.internal.ServletRequestImpl.run(ServletRequestImpl.java:1490) 
at weblogic.work.ExecuteThread.execute(ExecuteThread.java:256) 
at weblogic.work.ExecuteThread.run(ExecuteThread.java:221) 

Recent Changes

Upgraded to OpenAM 11.x or 12.x

Causes

The com.bea.core.apache.commons.lang_2.1.0.jar file that is included in the WebLogic installation also includes the class: org.apache.commons.lang.StringUtils. This version of the class file conflicts with the version supplied by OpenAM.

Solution

This issue can be resolved by changing the <prefer-web-inf-classes> element to true so that the classes in the WEB-INF directory of OpenAM are loaded in preference to the classes in the WebLogic server.

This can be achieved by creating a weblogic.xml file that contains the following text:

<?xml version="1.0" encoding="UTF-8"?>
<weblogic-web-app xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-web-app 
http://xmlns.oracle.com/weblogic/weblogic-web-app/1.3/weblogic-web-app.xsd">
    <context-root>/openam</context-root>
    <container-descriptor>
        <prefer-web-inf-classes>false</prefer-web-inf-classes>
        <prefer-application-packages>
            <package-name>org.apache.commons.lang.*</package-name>
        </prefer-application-packages>
    </container-descriptor>
</weblogic-web-app>

And then including this file in the openam.war/WEB-INF directory before you deploy the openam.war file

Note

You must restart the WebLogic application container in which OpenAM runs to apply these configuration changes. 

See Also

java.lang.LinkageError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle® WebLogic 12c server

OpenAM Installation Guide › Preparing For Installation › Preparing Oracle WebLogic

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3529 (Class loading error in Weblogic deploy)


java.lang.LinkageError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle® WebLogic 12c server

The purpose of this article is to provide assistance if you encounter a class loader constraint violation weblogic.application.ModuleException: java.lang.LinkageError: when starting OpenAM following an upgrade to OpenAM 11.x or 12.x deployed on an Oracle WebLogic 12c server.

Symptoms

The following error is shown when OpenAM is starting up

<May 13, 2014 1:51:13 PM CEST> <Error> <Deployer> <BEA-149265> <Failure occurred in the execution of deployment request with ID "1399981871678" for task "9". Error is: "weblogic.application.ModuleException: java.lang.LinkageError: loader constraint violation: when resolving method "org.slf4j.impl.StaticLoggerBinder.getLoggerFactory()Lorg/slf4j/ILoggerFactory;" the class loader (instance of weblogic/utils/classloaders/ChangeAwareClassLoader) of the current class, org/slf4j/LoggerFactory, and the class loader (instance of sun/misc/Launcher$AppClassLoader) for resolved class, org/slf4j/impl/StaticLoggerBinder, have different Class objects for the type LoggerFactory; used in the signature" 
weblogic.application.ModuleException: java.lang.LinkageError: loader constraint violation: when resolving method "org.slf4j.impl.StaticLoggerBinder.getLoggerFactory()Lorg/slf4j/ILoggerFactory;" the class loader (instance of weblogic/utils/classloaders/ChangeAwareClassLoader) of the current class, org/slf4j/LoggerFactory, and the class loader (instance of sun/misc/Launcher$AppClassLoader) for resolved class, org/slf4j/impl/StaticLoggerBinder, have different Class objects for the type LoggerFactory; used in the signature 
at weblogic.application.internal.ExtensibleModuleWrapper.start(ExtensibleModuleWrapper.java:140) 
at weblogic.application.internal.flow.ModuleListenerInvoker.start(ModuleListenerInvoker.java:124) 
at weblogic.application.internal.flow.ModuleStateDriver$3.next(ModuleStateDriver.java:213) 
at weblogic.application.internal.flow.ModuleStateDriver$3.next(ModuleStateDriver.java:208) 
at weblogic.application.utils.StateMachineDriver.nextState(StateMachineDriver.java:42) 
Truncated. see log file for complete stacktrace 
Caused By: java.lang.LinkageError: loader constraint violation: when resolving method "org.slf4j.impl.StaticLoggerBinder.getLoggerFactory()Lorg/slf4j/ILoggerFactory;" the class loader (instance of weblogic/utils/classloaders/ChangeAwareClassLoader) of the current class, org/slf4j/LoggerFactory, and the class loader (instance of sun/misc/Launcher$AppClassLoader) for resolved class, org/slf4j/impl/StaticLoggerBinder, have different Class objects for the type LoggerFactory; used in the signature 
at org.slf4j.LoggerFactory.getILoggerFactory(LoggerFactory.java:299) 
at org.slf4j.LoggerFactory.getLogger(LoggerFactory.java:269) 
at org.slf4j.LoggerFactory.getLogger(LoggerFactory.java:281) 
at org.forgerock.jaspi.filter.AuthNFilter.<clinit>(AuthNFilter.java:69) 
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) 
Truncated. see log file for complete stacktrace

Recent Changes

Upgraded to OpenAM 11.x or 12.x

Migrated from Oracle WebLogic 11g server to 12c.

Causes

This version of Weblogic uses an updated version of the com.bea.core.apache.commons.lang jar file that previously caused a conflict with OpenAM. This updated version no longer causes a conflict; however, if you previously changed the <prefer-web-inf-classes> element to true to resolve this conflict, you will now get an exception.

Solution

This issue can be resolved by changing the <prefer-web-inf-classes> element back to false in the weblogic.xml file. This file should then be included in the openam.war/WEB-INF directory before you deploy the openam.war file.

Note

You must restart the WebLogic application container in which OpenAM runs to apply these configuration changes. 

See Also

java.lang.NoSuchMethodError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle WebLogic 11g server

OpenAM Installation Guide › Preparing For Installation › Preparing Oracle WebLogic

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4000 (Class loading error in Weblogic 12c)


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...