About Upgrading OpenAM

This chapter covers common aspects of upgrading an 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 OpenAM release.

Release levels, and how much change to expect in a maintenance, minor, or major release, are defined in "Product Release Levels" in the Administration Guide. Release levels are identified by version number.

Supported Upgrade Paths

The following table contains information about the supported upgrade paths to OpenAM 16.1.4:

Upgrade Paths
Version Upgrade Supported?

OpenAM 9.0.x

No

OpenAM 9.5.x

No

OpenAM 10.0.x

No

OpenAM 11.0.x

Yes

OpenAM 12.0.x

Yes

OpenAM 13.x.x

Yes

OpenAM 14.x.x

Yes

OpenAM 15.x.x

Yes

Planning the Upgrade

How much you must do to upgrade OpenAM software depends on the magnitude of the differences between the version you currently use and the new version.

  • Maintenance releases have a limited effect on current functionality but contain necessary bug and security fixes. You should keep up to date with maintenance releases as the fixes are important and the risk of affecting service is minimal.

  • When upgrading to a new major or minor release, always plan and test the changes before carrying out the upgrade in production. Make sure you read release notes for intervening versions with care, identifying any changes likely to affect your deployment, and then plan accordingly.

  • These suggestions are true both for OpenAM server components, and also for policy agents.

To upgrade from an OpenAM server, use the Upgrade wizard. The OpenAM server Upgrade wizard appears when you replace a deployed OpenAM server .war file with a newer version and browse to the deployment URL. The Upgrade wizard brings the OpenAM configuration, including the version number, up to date with the new version. The CLI counterpart of the Upgrade wizard is openam-upgrade-tool-16.1.4.jar, which you install as described in "To Set Up Configuration Tools" in the Installation Guide.

Upgrading & Policies

When upgrading from OpenAM 11.0.x, the upgrade process changes how OpenAM represents policies. Most earlier policies transform directly to the newer representation.

If however the upgrade process encounters problems during the transformation, it writes messages about the problems in the upgrade log. When you open a policy in the policy editor that caused problems during the upgrade process, the policy editor shows the issues, but does not let you fix them directly. Instead you must create equivalent, corrected policies in order to use them in OpenAM.

You should therefore plan to test policy upgrade before upgrading the service, and to correct any problems encountered before using the upgraded service.

For details on how to configure OpenAM policies, see "Defining Authorization Policies" in the Administration Guide.

Upgrading & Authentication Defaults

This release changes three authentication defaults: module-based authentication is disabled, account lockout is enabled, and the account lockout duration is 30 minutes rather than 0. They apply to new installations only. An upgraded installation keeps the defaults it has, in every realm, and nothing in the upgrade rewrites an authentication setting — the behavior of your realms after upgrading is the behavior they had before it.

Adopting the new defaults in an existing deployment is worth doing, and is a decision to take per realm rather than a step to run blind, because disabling module-based authentication is a trade-off of availability against exposure. In a realm where it is disabled, the following stop working:

  • Login by module, using the module=module-name login parameter, or authIndexType=module in the REST API.

  • Login by authentication level, using the authlevel=level login parameter, or authIndexType=level in the REST API.

  • Policies whose environment conditions include Authentication Level or Authentication Scheme. The re-authentication such a condition asks for reaches OpenAM as module-typed composite advice, which is refused along with the rest of module-based authentication, so the user is denied access instead of being sent to authenticate. Express policy step-up with the Authenticate to Realm or Authenticate to Service conditions instead, which are unaffected.

The Application module and modules of type Federation are exempt from the switch, so policy agent authentication and federation flows continue to work. A federation deployment whose SAML v2 Authentication Context mapping names an ordinary module — an entry of the form module=module-name in the IdP extended metadata — is an exception: that login is made by module and is refused like any other. Map such a context onto a chain with service=chain-name, or leave its authentication scheme empty, which is what the shipped mapping does.

The Liberty ID-WSF Authentication Service is another exception. Its PLAIN and CRAM-MD5 SASL mechanisms, exposed at /openam/Liberty/*, log in through IndexType.MODULE_INSTANCE against the top level realm, aimed at the modules named by PlainMechanismAuthModule and CramMD5MechanismAuthModule (both default to DataStore, and neither is Application nor of type Federation). Disabling module-based authentication in the top level realm therefore refuses every SASL request to that endpoint with MODULE_BASED_AUTH_NOT_ALLOWED. Where such an integration exists, leave module-based authentication enabled in the top level realm alone.

The Security Token Service is another. The default authentication target mappings of a REST STS instance validate OpenID Connect ID tokens against the oidc module and X.509 certificates against cert_module with authIndexType=module, and the default X.509 mapping of a SOAP STS instance does the same. In a realm where module-based authentication is disabled, these validations are refused with MODULE_BASED_AUTH_NOT_ALLOWED. Keep module-based authentication enabled in the realm of the STS instance, or map the token type onto a chain that contains the module, for example OPENIDCONNECT|service|oidcChain|oidc_id_token_auth_target_header_key=oidc_id_token. The SOAP STS agent logs in through the Application module and is unaffected.

Account lockout has a requirement of its own: keep the lockout duration above 0. A duration of 0 selects physical locking, which sets inetuserstatus=Inactive on an account after five failed logins and leaves it switched off until an administrator re-enables it, so enabling lockout while the duration is 0 turns five bad passwords into a lasting denial of service against any account whose name can be guessed. That is why the two defaults moved together.

Once you have weighed both, apply them to a realm with:

$ ssoadm set-realm-svc-attrs \
 --adminid amadmin \
 --password-file pwd.txt \
 --realm / \
 --servicename iPlanetAMAuthService \
 --attributevalues sunEnableModuleBasedAuth=false \
                   iplanet-am-auth-login-failure-lockout-mode=true \
                   iplanet-am-auth-lockout-duration=30

The same settings are on the console page Realms > Realm Name > Authentication > Settings, under the Security and Account Lockout tabs. For details of the attributes, see "Core Authentication Attributes - Security" and "Core Authentication Attributes - Account Lockout" in the Administration Guide.

What the upgrade does do is deactivate the identities the configurator created with a password published in the OpenAM installer source — demo, wsc, wsp, SecurityTokenService, and agentAuth — where they still have that password and are still active. Their passwords are not changed. A deployment that uses WS-Security, the STS, or the agent authenticator with the shipped credentials must give the identity a password of its own and activate it again after upgrading; the upgrade report lists every identity that was switched off. The anonymous user of the Top Level Realm no longer authenticates with a password at all, which takes effect as soon as this version is deployed; the Anonymous authentication module is unaffected.

ssoadm authenticates administrators against the Administrator Authentication Configuration of the top level realm — the chain that already serves a browser login to /openam/console — rather than by naming the DataStore module, so that it keeps working in a realm where module-based authentication is disabled. Where the realm names no administrator chain, it falls back to the Organization Authentication Configuration. It answers only user name and password callbacks, so a top level realm whose chain requires more than that — a one-time password, a choice, a confirmation — refuses ssoadm where the pinned module previously succeeded. If you pinned the mechanism with org.forgerock.openam.ssoadm.auth.indexType and org.forgerock.openam.ssoadm.auth.indexName in the ssoadm script, an indexType of module_instance only works while that realm allows module-based authentication; use service and the name of a chain that a user name and a password satisfy, or remove both properties and let ssoadm follow the administrator chain.

Best Practices for Upgrades

Be prepared before you begin an upgrade, even if the upgrade is for a maintenance release.

Route Around Servers During Downtime

Upgrading servers takes at least one of your OpenAM sites down while the server configurations are being brought up to date with the newer version. Plan for this site to be down, routing client applications to another site until the upgrade process is complete and you have validated the result. Make sure client application owners are well aware of the change, and let them know what to expect.

If you only have a single OpenAM site, make sure the downtime happens in a low usage window, and make sure you let client application owners plan accordingly.

During an upgrade you must restrict access to OpenAM Console: The Upgrade Wizard page does not require authorization; any user with access to OpenAM Console immediately after you deploy the new .war can therefore initiate the upgrade process.

Back Up the Deployment

Always back up your deployment before you upgrade, as you must be able to roll back should something go wrong during the upgrade process.

  • Backing up your configuration as described in "Backing Up and Restoring OpenAM Configurations" in the Administration Guide is good for production environments.

  • In preparation for upgrading OpenAM servers and their configurations, also take LDIF backups of the configuration store data in the directory servers. If possible, stop servers before upgrading and take a file system backup of the deployed servers and also of their configuration directories as well. This can make it easier to roll back from a failed upgrade.

    For example, if you deploy OpenAM server in Apache Tomcat under /openam, you might take a file system backup of the following directories for each OpenAM server.

    • /path/to/tomcat/webapps/openam/

    • ~/openam/

    • ~/.openamcfg/

  • When upgrading web policy agents, take a file system backup of the policy agent installation and configuration directories.

    When upgrading Java EE policy agents, it can be easier to uninstall the new version and reinstall the old version than to restore from file system backup.

  • When upgrading tools, keep copies of any tools scripts that you have edited for your deployment. Also back up any trust stores used to connect securely.

Apply Customization Before Upgrading

Before you upgrade OpenAM servers, prepare a .war file that contains any customizations you require. Customizations include any changes you have made to the OpenAM server installation, such as the following.

  • Plugins and extensions such as custom authentication modules, response attribute providers, post authentication plugins, SAML v2.0 attribute mappers, and OAuth 2.0 scope implementations

    These are described in the Developer’s Guide.

  • Customized JSPs, redesigned login or service pages, additional CSS and visual content, and modified authentication module callback files

    These are described in the "Customizing the OpenAM End User Pages" in the Installation Guide.

  • Any changes to OpenAM classes

  • Any changes or additional Java class libraries (such as .jar files in WEB-INF/lib)

If you have customized the OAuth 2.0 device flow user code page, carry the CSRF token into your copy before you upgrade. The endpoint /oauth2/device/user refuses any submission without a valid csrf parameter with HTTP 400, and the stock page supplies that token through two lines that a customized copy made from an earlier release lacks. Without them, every user code a browser submits is refused.

  • In a customized CodeVerificationForm.ftl (for example, one placed in WEB-INF/classes/templates), add the token to pageData:

    <#if csrf??>csrf: "${csrf?js_string}",</#if>

  • In a customized XUI templates/user/DeviceTemplate.html, add a hidden field inside the form:

    <input type="hidden" name="csrf" value="{{csrf}}">

Users of the stock pages are covered by the same .ftl: it sets a urlArgs value on RequireJS so the browser stops reusing DeviceTemplate.html cached from the previous release (that file is served for a month, and its URL is not versioned otherwise), and it registers a submit-time listener that appends the CSRF token to any device form that reaches the DOM without it. Neither of these lines is included in a customized copy of CodeVerificationForm.ftl unless the customization brings them across.

Clients that post the user code directly, without the page, send their session ID as the csrf parameter. For details, see "To Grant Consent in the OAuth 2.0 Device Flow" in the Developer’s Guide.

A link or QR code that opens the device verification page with the user code in the query string, such as /oauth2/device/user?user_code=BDCT-HQKD, now redirects (HTTP 303) to the same address without that parameter. The user types the code into the empty form the redirect leads to. The endpoint has no way to tell a code the user chose from one a foreign page chose for them, so the code has to be typed where only the user can type it. OpenAM itself does not produce this URL - /oauth2/device/code answers with a bare verification_uri and never issues verification_uri_complete - but any out-of-tree device app or QR code that appends ?user_code=<code> to the verification URI is affected and must be updated to reflect that users now retype the code on arrival.

/oauth2/authorize and /oauth2/device/user now read the consent decision (decision) and the "remember this choice" flag (save_consent) from the request body alone; values sent only in the query string are ignored. On /oauth2/authorize, a submission that carries no decision in the body fails closed as a denial; on /oauth2/device/user such a submission is the user code form itself: it leads to the consent page, or approves the device code at once when the client’s consent is implied. The stock consent page and the documented headless curl invocations already send both in the body, so a deployment using either is unaffected; a bespoke client that put decision=allow in the URL of a redirect has to move it into the POST body.

Plan for Rollback

Sometimes even a well-planned upgrade operation fails to go smoothly. In such cases, you need a plan to roll back smoothly to the pre-upgrade version.

For OpenAM servers, you can roll back by restoring from file system backup. If you use an external configuration directory service, restore the old configuration from LDIF before restarting the old servers. For more information, see "Backing Up and Restoring OpenAM Configurations" in the Administration Guide.

For web policy agents, you can roll back by restoring from file system backup. If you used configuration only available to newer agents, restore the pre-upgrade configuration before restarting the old agents.

For Java EE policy agents, uninstall the newer agents and reinstall the older agents, including the old configurations.