Best Practice

Best practice for upgrading to AM 6.x

Last updated Nov 30, 2018

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.


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



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