Best Practice

Best practice for upgrading to AM 5.x

Last updated Sep 12, 2018

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.


8 readers recommend this article

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')



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...