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

Last updated Jan 5, 2021

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.

1 reader recommends this article

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 Release Notes (contains important information about policy changes)
OpenAM 13 Release Notes (contains important information about referral policies no longer supported)
OpenAM Upgrade Guide › About Upgrading OpenAM › Upgrading & Policies
OpenAM Administration Guide › Defining Authorization Policies

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

Stop the web application container in which OpenAM runs.
Add the ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true argument to the CATALINA_OPTS environment variable.
Start the web application container in which OpenAM runs.
Delete the redundant policies in the policy editor (navigate to: Access Control > [Realm Name] > Policies).
Stop the web application container in which OpenAM runs.
Remove the ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true argument from the CATALINA_OPTS environment variable.
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.