Best Practice
Archived

Best practice for upgrading to OpenAM 13.x

Last updated Jan 5, 2021

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.


1 reader recommends this article

Archived

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

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 5.x or 6.x fails when anonymous access is disabled in DS 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 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 (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 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 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)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.