Upgrading OpenAM Servers

This chapter covers upgrade from OpenAM core server 11.0.0 or later to the current version. For other OpenAM components, see "Upgrading OpenAM Components".

OpenAM server upgrade relies on the Upgrade Wizard to make the necessary changes to the configuration store. You must then restart OpenAM or the container in which it runs. Even a version number change requires that you run the Upgrade Wizard, so needing to run the Upgrade Wizard says nothing about the significance of the changes that have been made to OpenAM. You must run the Upgrade Wizard even for maintenance releases.

Make sure you try upgrading OpenAM in a test environment before applying the upgrade in your production environment.

If you are upgrading from an unsupported version of OpenAM to a later version, you must first upgrade to a supported version. In some cases, you may need to upgrade again depending on the upgrade path.

Starting with this release the legacy Liberty ID-WSF SOAP endpoints (/Liberty/ and /WSPRedirectHandler/) are disabled by default as part of the GHSA-p462-xxwx-pqf4 hardening. Existing deployments that rely on Liberty ID-WSF, IDPP, Discovery, AuthnSvc, or Interaction services must explicitly opt in by setting the advanced server property com.sun.identity.liberty.enabled=true.

Two related advanced server properties were also introduced and now default to a fail-close behaviour:

  • com.sun.identity.liberty.soap.sensitiveHandlers (default idpp,disco,authnsvc,interaction) — list of SOAP RequestHandler keys that reject the unauthenticated null:null mechanism and the ANONYMOUS security profile.

  • com.sun.identity.liberty.allowAnonymousWSC (default false) — restores the legacy minting of an anonymous Web Service Client session for null-family mechanisms without a client credential.

If your deployment depends on the previous (insecure) behaviour, review and adjust these properties before promoting the upgrade. See "Advanced" in the Reference.

Starting with this release the SAML 2.0 and ID-FF IDP discovery reader and writer endpoints (/saml2reader, /saml2writer, /idffreader, /idffwriter) validate the RelayState redirect URL as part of the GHSA-2pf8-52jh-5x3m hardening. Relative and same-origin redirect URLs continue to work unchanged. Absolute URLs that point to a different host are now rejected with HTTP 400 unless they match the new advanced server property org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist (a semicolon-separated list of URL patterns, empty by default).

If your common-domain discovery deployment hosts service providers on a different host than OpenAM, add their return URLs to this property before promoting the upgrade. See "Advanced" in the Reference.

Starting with this release the legacy Liberty ID-FF (Liberty Alliance 1.x) SOAP endpoint (/SOAPReceiver/, served by FSSOAPReceiver) is *disabled by default as part of the GHSA-qcqm-7432-wg7r hardening. Existing deployments that actively use Liberty ID-FF federation must explicitly opt in by setting the advanced server property com.sun.identity.federation.services.soap.enabled=true. The kill-switch disables the whole endpoint, including ID-FF browser-artifact single sign-on and LECP, not only the state-changing operations. In a multi-server site set this property on every server: cross-node single logout forwards the logout SOAP message to a peer server’s own /SOAPReceiver, so a node where the endpoint is still disabled would reject the forwarded request with HTTP 404 and single logout would fail.

Also starting with this release, inbound ID-FF state-changing and disclosure operations (federation termination, name registration, single logout, and name-identifier mapping) require a verified XML signature by default (com.sun.identity.federation.services.requireSignature, default true), even when message signing is otherwise optional. This applies to the SOAP binding and to the HTTP-Redirect binding endpoints /ProcessTermination/, /ProcessLogout/, and /ProcessRegistration/*, which are reachable without authentication and act on the user named by an opaque handle in the request. Unlike the SOAP endpoint, the redirect binding is not disabled by default, so this change affects any deployment that uses ID-FF over the redirect binding.

Enable message signing along with it. OpenAM signs its own outbound ID-FF messages only when XMLSigningOn is enabled, and that setting is false on a stock installation. If you leave com.sun.identity.federation.services.requireSignature at its default without enabling signing, OpenAM’s own single logout, federation termination, and name registration messages are sent unsigned and rejected by the receiving provider. Before promoting the upgrade, either:

  • set XMLSigningOn to true under the sunFAMIDFFConfiguration service (advanced server property com.sun.identity.federation.services.signingOn) and configure a signing certificate alias on every participating hosted provider, with the matching certificate published in the metadata each partner consumes. This setting is now read for each operation, so changing it takes effect without restarting the server; in earlier releases it was cached at startup and a restart was required; or

  • set com.sun.identity.federation.services.requireSignature=false to restore the previous, insecure behaviour if your federation partners do not sign ID-FF messages.

See "Advanced" in the Reference.

Starting with this release the OAuth 2.0 authorization endpoint applies the OAuth2 Provider property Code Verifier Parameter Required to every request whose response_type includes code, as part of the GHSA-5p2f-7vcr-6vfh hardening. Previously the OpenID Connect hybrid flows (code token, code id_token, and code id_token token) escaped the check and were issued authorization codes with no code_challenge bound to them. That property is enabled by default, so hybrid-flow clients that send no code_challenge now fail at /oauth2/authorize.

The token endpoint fails closed to match: while the property is enabled, an authorization code that carries no code_challenge is rejected at /oauth2/access_token. Authorization codes issued before the upgrade, or before the property was turned on, therefore stop being redeemable. The exposure lasts at most one authorization code lifetime (the OAuth2 Provider property Authorization Code Lifetime (seconds), 120 by default), so if in-flight codes matter, leave client traffic redirected elsewhere for that long before promoting the upgrade.

Update hybrid-flow clients to send a code_challenge at the authorization endpoint and the matching code_verifier at the token endpoint, or disable Code Verifier Parameter Required for the realm. Disabling it never relaxes verification for codes that were issued with a challenge. See "OAuth2 Provider" in the Reference.
To Upgrade From a Supported OpenAM Version

Follow these steps to upgrade a site of OpenAM servers.

During the upgrade process, you must take the OpenAM servers in the site out of production, instead redirecting client application traffic elsewhere. This is required because upgrade involves making changes to OpenAM’s configuration model. If the upgrade fails, you must be able to roll back before the configuration changes impact other sites.

Do not perform an upgrade by deploying the new version and then importing an existing configuration by running the ssoadm import-svc-config command. Importing an outdated configuration can result in a corrupted installation.

  1. Prepare your customized OpenAM server .war file.

  2. Back up your deployment.

  3. Route client application traffic to another site during the upgrade.

  4. For servers in the site, stop OpenAM, or if necessary stop the container where OpenAM runs.

  5. For servers in the site, deploy your customized server .war file.

    When you deploy the new .war file, you might have to delete working files left by the old installation. For example, if you deploy on Apache Tomcat, replacing /path/to/tomcat/webapps/openam.war, then also recursively delete the /path/to/tomcat/webapps/openam/ and /path/to/tomcat/work/Catalina/localhost/openam/ directories before restarting the server.

  6. For servers in the site, restart OpenAM or the container where it runs.

  7. To upgrade the data in the configuration store, perform one of the following actions in one of the servers in the site:

    • Navigate to the OpenAM URL, for example https://openam.example.com:443/openam, and follow the instructions in the Upgrade Wizard for an interactive upgrade.

    • Use the openam-upgrade-tool-16.1.3.jar tool for an unattended upgrade:

      1. Install the openam-upgrade-tool-16.1.3.jar tool as described in "To Set Up Configuration Tools" in the Installation Guide. A sampleupgrade file will be expanded in the directory where you install the tool.

      2. Create a configuration file for the openam-upgrade-tool-16.1.3.jar. You can use the sampleupgrade file as a template to create a configuration file, for example upgrade.properties.

        An upgrade configuration file may resemble the following:

        $ grep -v "^#" upgrade.properties
    SERVER_URL=http://openam.example.com:8080
     DEPLOYMENT_URI=/openam
     ACCEPT_LICENSES=true

      3. Upgrade OpenAM by using the tool with the properties file following this example:

        $ java -jar openam-upgrade-tool-16.1.3.jar --file upgrade.properties

Writing Backup; Done.
Upgrading Services
New service iPlanetAMAuthPersistentCookieService; Done.
New service iPlanetAMAuthOpenIdConnectService; Done.
New service OAuth2Provider; Done.
New service iPlanetAMAuthDevicePrintModuleService; Done.
New service crestPolicyService; Done.
New service RestSecurity; Done.
New service MailServer; Done.
New service dashboardService; Done.
New service iPlanetAMAuthOATHService; Done.
Add Organization schema to sunFAMSAML2Configuration; Done.
Upgrade sunAMAuthHOTPService; Done.
Upgrade sunAMAuthADService; Done.
Upgrade sunAMAuthOAuthService; Done.
Upgrade iPlanetAMAuthCertService; Done.
Upgrade sunIdentityRepositoryService; Done.
Upgrade iPlanetAMPasswordResetService; Done.
Upgrade iPlanetAMSessionService; Done.
Upgrade iPlanetAMAuthService; Done.
Upgrade iPlanetAMAuthLDAPService; Done.
Upgrade sunAMAuthDataStoreService; Done.
Upgrade AgentService; Done.
New sub schema sunIdentityRepositoryService; Done.
New sub schema AgentService; Done.
Delete service sunFAMLibertyInteractionService; Done.
Delete service sunFAMLibertySecurityService; Done.
Creating entitlement application type crestPolicyService; Done.
Creating entitlement application crestPolicyService; Done.
Re-enabling Generic LDAPv3 Data Store; Done.
Upgrading data store embedded; Done.
Updating Platform Properties; Done.
Writing Upgrade Log; Done.

Upgrade Complete.

        For additional information about the command-line tool, see the reference documentation for upgrade.jar(1) in the Reference.

      4. Restart OpenAM or the container where it runs.

  8. (Optional) If you installed OpenAM using an external directory server as the configuration store, add an access control instruction (ACI) to the external directory to give the OpenAM administrative user server-side sorting privileges.

    The ACI should be similar to the following:

    aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;acl "Allow
 server-side sorting"; allow (read)(userdn = "ldap:///
 uid=openam,ou=admins,dc=example,dc=com");)

    See "Preparing an External Configuration Data Store" in the Installation Guide for more information about using an external directory server as the OpenAM configuration store.

  9. (Optional) If you want to configure the upgraded system for the Core Token Service (CTS), read "Configuring the Core Token Service" in the Installation Guide.

  10. Referral policies are not supported in OpenAM 16.1.3. If your OpenAM deployment has referral policies, the following warning message will appear when you upgrade your OpenAM server to OpenAM 16.1.3:

    Referrals found that require removing

    OpenAM will take the following actions during the upgrade:

    • Removing all referral policies from your OpenAM configuration.

    • Copying resource types and policy sets associated with removed referral policies to the realms targeted by the referral policies.

    For example, suppose you had an OpenAM 12 deployment with a referral policy in realm A, and that referral policy referred to policies in realm B. During an upgrade, OpenAM would delete the referral policy in realm A and copy all the resource types and policy sets associated with the deleted referral policy from realm A to realm B.

    After upgrading to OpenAM 16.1.3, you are responsible for reconfiguring OpenAM so that policy evaluation that previously depended upon referrals continues to function correctly. You might need to take one or both of the following actions:

    • Reconfiguring your policy agent with the realm and policy set [1] that contain policies to be evaluated when that agent requests a policy decision from OpenAM. Previously, you might have configured the agent to use a realm that contained a referral policy. Because referral policies are not supported in OpenAM 16.1.3, this is no longer possible.

    For more information about configuring an agent with a realm and policy set, see "Working With Realms and Policy Agents" in the Administration Guide.

    • Copying or moving a policy or a group of policies. OpenAM 16.1.3 has new REST API endpoints that let you copy and move policies. This functionality might be helpful when migrating away from policy deployments that use referral policies. For more information about the REST endpoints that let you copy and move policies, see "Copying and Moving Policies" in the Developer’s Guide.

  11. Validate that the service is performing as expected.

  12. Allow client application traffic to flow to the upgraded site.

To Complete Upgrade from OpenAM 11.0.x

After upgrade from OpenAM 11.0.x, all OAuth 2.0 client configurations inherit the default response types:

  • code

  • token

  • id_token

  • code token

  • token id_token

  • code id_token

  • code token id_token

  1. For each OAuth 2.0 client configuration, edit the list of response types to remove any that are not supported or not required.

  2. For each OAuth 2.0 client configuration, update the client password.

    As part of a fix for OpenID Connect ID Token signing, the password storage format for OAuth 2.0 clients has changed. OpenAM now stores client passwords using reversible encryption. OpenAM 11.0 stores client passwords using a one-way hash algorithm, and therefore the passwords cannot be recovered.

    You can update the client password by using either OpenAM console or the ssoadm update-agent command with the --attributevalues option to update the value of the userpassword attribute.

To Complete Upgrade from OpenAM 13.0.x

If you configured one or more JDBC audit event handlers in OpenAM 13.0.x, make the following changes to the audit tables' schema:

  1. Run the following command on Oracle databases that support OpenAM audit event handlers:

    ALTER TABLE am_auditaccess ADD (response_detail CLOB NULL);

    This command adds the response_detail column to the am_auditaccess table.

  2. Run the following commands on MySQL databases that support OpenAM audit event handlers:

    ALTER TABLE audit.am_auditconfig CHANGE COLUMN configobjectid objectid VARCHAR(255);
ALTER TABLE audit.am_auditaccess ADD COLUMN response_detail TEXT NULL;

    The commands change the name of the configobjectid column in the am_auditconfig table to objectid and add the response_detail column to the am_auditaccess table.

  3. If you use databases other than Oracle or MySQL to support OpenAM audit event handlers, review their schema.

    If the am_auditconfig table has a column named configobjectid, change that column’s name to objectid.

    If the am_auditaccess table does not have a column named response_detail, add that column to the table’s schema.

1. The agent configuration UI refers to a policy set as an application.