Upgrading OpenAM Components This chapter is concerned with upgrades for policy agents, OpenAM tools, and services. "To Upgrade Web Policy Agents" "To Upgrade Java EE Policy Agents" "To Upgrade OpenAM Tools" " To Upgrade to Elliptical Curve Signature Algorithms for Stateless Sessions and OpenID Connect " "To Upgrade User Self Services" To Upgrade Web Policy Agents Back up the policy agent installation and configuration directories. Also back up the configuration if it is stored centrally in OpenAM. Redirect client traffic away from the protected application. Stop the web server where the policy agent is installed. Remove the old policy agent as described in the OpenAM Web Policy Agent User’s Guide. If the uninstallation process has changed, refer to the version of the Web Policy Agent Installation Guide that corresponds to your web policy agent. Install the new policy agent using the existing configuration. Start the web server where the policy agent is installed. For new features, the policy agent uses the default configuration until you make changes. Validate that the policy agent is performing as expected. Allow client traffic to flow to the protected application. To Upgrade Java EE Policy Agents Back up the policy agent installation and configuration directories. Also back up the configuration if it is stored centrally in OpenAM. Redirect client traffic away from the protected application. Uninstall the old policy agent. Install the new policy agent. For new features, the policy agent uses the default configuration until you make changes. Validate that the policy agent is performing as expected. Allow client traffic to flow to the protected application. To Upgrade OpenAM Tools Since OpenAM 10.1, the session tools are no longer needed. Upgrading other tools consists of installing new tools and customizing tools scripts as necessary. Install new versions of the tools. Apply any customizations you made to the scripts, referring to the old tools installation as necessary. Once the new tools are working, you can delete the old tools. To Upgrade to Elliptical Curve Signature Algorithms for Stateless Sessions and OpenID Connect OpenAM supports Elliptic Curve Digital Signature Algorithms (ECDSA) for stateless sessions and OpenID Connect in OpenAM 13.5 or later. Generate the public and private keys to use with the ECDSA algorithms using the standard curves parameters using keytool and configure stateless session to use ECDSA algorithms as shown in "Configuring Elliptic Curve Digital Signature Algorithms" in the Administration Guide. Manually add the ECDSA algorithms to OpenAM’s OAuth2 provider as follows: On the OpenAM console, navigate to Configure > Global Services > OAuth2 Provider, and scroll down to ID Token Signing Algorithms supported. In the New Value field, select ES256. Repeat the step to add ES384 and ES512, respectively. For Token Signing Algorithm, select an ECDSA algorithm, such as ES256. In the Token Signing RSA/ECDSA public/private key pair field, enter the alias of the ECDSA signing key in the keystore. Click Save. Update the OpenID Connect Client as follows: On the Top Level Realm, click Agents, and then click OAuth 2.0/OpenID Connect Client. In the Agent box, select an existing OIDC client. In the ID Token Signed Response Algorithm field, enter the ECDSA algorithm. For example, ES256, ES384, or ES512. Click Save. To Upgrade User Self Services OpenAM 13.5 has an improved key management system that allows the user self-service feature to successfully operate in a multi-instance server deployment behind a load balancer. This key management system requires a JCEKS keystore that supports asymmetric and symmetric keys. To help you decide whether to enable a JCEKS keystore after upgrading to OpenAM 13.5, see the following table: User Self Service Feature Upgrade Upgrading from: Enabling JCEKS required? Versions prior to OpenAM 13.0 No OpenAM 13.0 with the REST-based user self-service feature disabled No OpenAM 13.0 with the legacy user self-service feature enabled No OpenAM 13.0 with the REST-based user self-service feature enabled Yes The following steps show how to set up the JCEKS keystore for user self-service: In the OpenAM console, navigate to Configure > Server Defaults > Security > Key Store. Change the Keystore File property to %BASE_DIR%/%SERVER_URI%/keystore.jceks. Change the Keystore Type property to JCEKS. These properties can also be modified on a per-server basis as required by navigating to Deployment > Servers > Server Name > Security > Key Store. For more information about inherited properties, see "Configuring Servers" in the Reference. Restart the OpenAM server. Migrating Legacy Servers Administration Guide