Upgrade
This guide covers common aspects of upgrading an AM 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 AM release.
Release levels, and how much change to expect in a maintenance, minor, or major release, are defined in ForgeRock Product Release Levels. Release levels are identified by version number.
AM supports several versions of the web and Java agents, so you don’t usually need to upgrade your agents when you upgrade AM. For a compatibility matrix between the agents and AM, see the following Knowledge Base article. For information about upgrading web agents and Java agents, see the ForgeRock Web Agents documentation or the ForgeRock Java Agents documentation. |
ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.
Supported upgrade paths
This table contains information about the supported upgrade paths to AM 7.3.1:
Version | Upgrade Supported? |
---|---|
AM 6.5.x |
✔ |
AM 7.x |
✔ |
For details, refer to the ForgeRock Product Support Lifecycle Policy in the ForgeRock Knowledge Base.
If you are upgrading from an unsupported version of AM 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.
The embedded DS server is not supported for production in AM 7.3.1. If you have an existing site configured with embedded DS, you must migrate it to an external DS store before upgrading to AM 7.3.1. The embedded DS was deprecated in AM 7, and will be removed in a future release. How do I know if my deployment uses the embedded DS?
Use either of the following methods to migrate an embedded data store to an external store before attempting to upgrade to AM 7.3.1:
|
Plan the upgrade
How much you must do to upgrade AM 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. 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 the release notes for intervening versions with care, identifying any changes likely to affect your deployment, and then plan accordingly.
Review the following best practices before you upgrade AM:
Route around servers during downtime
Upgrading servers takes at least one of your AM 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 AM 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 the AM console: The Upgrade Wizard page does not require authorization; any user with access to the AM admin UI immediately after you deploy the new WAR file 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 Back up configurations is good for production environments.
-
In preparation for upgrading AM 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 AM server in Apache Tomcat under
/openam
, you might take a file system backup of the following directories for each AM server.-
/path/to/tomcat/webapps/openam/
-
~/openam/
-
~/.openamcfg/
-
-
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.
-
Record any custom advanced server properties configured under Configure > Server Defaults > Advanced or Deployment > Servers > Server Name > Advanced in the AM admin UI. These properties are lost during the upgrade and will need to be added again after the upgrade is complete.
Review REST API versions before upgrading
Upgrading AM may update the default API version of several AM endpoints. After an upgrade, your applications may experience issues connecting to endpoints if they do not specify API version information in REST calls.
By default, an upgraded AM instance responds to REST calls that do not specify version information with the oldest version available for the endpoint. However, the oldest supported version may not be the one required by the application, as API versions become deprecated or unsupported.
To avoid version conflicts between application calls and REST endpoint APIs,
consider specifying the protocol and resource version required by the application
in the Accept-API-Version
header when making requests to REST endpoints.
For more information,
see Specifying REST API Versions.
Starting in version 6, AM includes a CSRF protection filter that is enabled by default.
REST requests other than GET, HEAD, and OPTIONS made to endpoints under the For more information, see Protect against CSRF attacks. |
You can configure AM’s default REST API behavior. For more information, see Configuring the Default REST API Version.
Review Directory Services certificates before upgrading
Before upgrading, review that the certificates used to establish secure connections between AM and the DS stores.
If the FQDN value from the subject
field of a non-wildcard certificate
does not match the FQDN obtained from DNS for the DS instance,
AM will not be able to establish a secure connection with DS.
Additionally, if the DS instance responds to multiple FQDNs, they must be specified in the certificate as well.
This step is critical for the configuration store. If AM cannot establish communication with the configuration store, it will fail to start up.
For more information about setting up DS server certificates, see Key Management in the DS documentation.
Customize before upgrading
Prepare a .war
file that contains any customizations you require.
Customizations include any changes you have made to the AM server installation, such as the following:
-
Custom plugin and extensions, for example:
-
Custom authentication modules.
-
Custom authentication nodes.
-
Post-authentication plugins.
-
Custom SAML v2.0 attribute mappers.
-
Custom OAuth 2.0 scope validators.
New functionality oftentimes changes the samples provided with AM.
Do not copy custom plugins or extensions from a previous version of AM to the
.war
file.You must customize the samples of the version you are upgrading to before adding them to the
.war
file. For example, download the custom scope validator sample of the version you are upgrading to, customize it, recompile it, and then add the resulting.jar
file to the.war
file.Failure to use the new version’s samples as the base for your customizations may result in unexpected behavior.
-
-
Customized JSPs, redesigned login or service pages, additional CSS and visual content, and modified authentication module callback files.
-
Any changes to AM classes or APIs.
Recompile any custom implementations you have created with each release of AM, as the method signature or imports for supported and evolving APIs can change in each version.
-
Any changes or additional Java class libraries (such as .jar files in
WEB-INF/lib
).
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 AM 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 Back up configurations.
Upgrade AM instances
To upgrade an AM deployment, you must upgrade each server instance in your site. For older AM versions, you might not be able to upgrade directly to AM 7.3. For details, refer to Supported upgrade paths.
Upgrade the following elements of an AM instance:
- AM server software
-
The server is upgraded when you deploy the WAR file of the new version.
- Configuration
-
Use one of the following methods to upgrade the configuration:
-
This utility is provided in the
AM-7.3.1.zip
file and upgrades a configuration exported using Amster. This is the recommended way to update the configuration. -
The upgrade wizard is launched when you replace a deployed AM .war file with a newer version, then go to the deployment URL.
-
The
openam-upgrade-tool-14.1.3.21.jar
is installed when you set up the configuration tools.
You cannot upgrade the configuration by deploying a new version and then using ssoadm import-svc-config
to import an existing configuration. -
- Schema
-
Generally, the configuration store schema is updated when you update the configuration. From time to time, updates are required to the schema of other data stores, such as the identity store, or the CTS store. These updates must be made manually.
Refer to Update the schema for more information.
- Tools and scripts
-
Read the Release notes to understand the changes introduced in each version before you upgrade AM tools and scripts.
The embedded ForgeRock Directory Services (DS) server is not supported in production from AM 7 onwards. If you have an existing site that uses an embedded DS, you must migrate it to an external DS store before you upgrade to AM 7.x. The embedded DS was deprecated in AM 7 and will be removed in a future release. How do I know if my deployment uses the embedded DS?
Use either of the following methods to migrate an embedded DS to an external DS before you upgrade AM:
|
Before you upgrade
You must follow these steps before you start an upgrade.
-
Route client application traffic to another site during the upgrade.
-
Make the secure state encryption key available to all instances in the site.
An AES 256-bit key called
directenctest
must be available to all instances in the site. This might mean, for example, copying the keystore across the site.This key does not need to be the same key that AM provides in the default keystore.
If you don’t provide this key, AM will not start up after the upgrade.
What is the
directenctest
key for?AM uses the
directenctest
key to encrypt information stored in the secure state of authentication trees. This encryption is a mandatory feature of the trees from AM 7 onwards.The upgrade process maps this key to the
am.authn.trees.transientstate.encryption
secret ID.How do I make the
directenctest
key available?-
If you’re upgrading from a version of AM earlier than 6.5:
The key alias must exist in the keystore configured as the AM keystore. Check the path where the keystore and its files are configured by going to Configure > Server Defaults > Security > Key Store.
-
If you’re upgrading from AM 6.5 or later:
The alias must exist in a secret store configured globally, so that all realms can access it. You can configure additional secrets by realm, if required, after the upgrade.
You can create a new secret store to house this secret, or you can add it to one of your existing stores.
The following example creates the key alias in the AM keystore, or in a keystore configured in a secret store:
$ keytool \ -genseckey \ -alias directenctest \ -keyalg AES \ -keysize 256 \ -storetype JCEKS \ -keystore /path/to/keystore.jceks
Where do I find the keystore passwords?
-
(AM versions earlier than 6.5) The passwords are stored in the files configured in Configure > Server Defaults > Security > Key Store.
-
(AM 6.5) The passwords are secrets provided by a different secret store. For example, a file system volume secret store.
After the upgrade, you can rename the key alias or configure a different key in the secret ID mapping. Make sure the secret ID is always mapped to an existing, resolvable secret or key alias.
-
Upgrade the configuration
Use one of the following methods to upgrade the configuration:
amupgrade
The amupgrade
utility converts a set of exported AM configuration files so that the configuration can be used
with the latest AM version. Use this utility with Amster
and to upgrade file-based configurations (from version
7.0 onwards). The utility has the same Java requirements as Amster
. Refer to the
Amster Release notes for more information.
Upgrade paths with amupgrade
You can use amupgrade
to upgrade the following versions of a configuration exported with Amster
:
Upgrade from | Upgrade to |
---|---|
5.0, 5.1 |
5.5 |
5.5 |
6.0 |
6.0.x |
6.5 |
6.5.x |
7.0.x |
7.0.x |
7.1.x, 7.2.x, 7.3.x |
7.1.x |
7.2.x, 7.3.x |
7.2.x |
7.3.x |
You cannot use amupgrade to upgrade a running AM instance.
|
Before you start
-
Download the AM ZIP file from the ForgeRock BackStage download site.
-
Extract the contents of the ZIP file.
-
In the extracted
openam
directory, locate theConfig-Upgrader-7.3.1.zip
file. -
Extract the Config-Upgrader ZIP file.
Upgrade from an Amster
configuration export
-
Follow the Amster documentation to export your configuration.
-
Upgrade the exported configuration to the new version:
$ amupgrade \ -i exported configuration \ -o output directory \ -a amster version \ rules/amster/from-to-to.groovy
Where:
-
exported configuration is the path to the configuration directory you generated in step 1
-
output directory is the directory in which the updated configuration should be saved
-
amster version is the version of Amster you’ll use to import the configuration
-
from is the AM version from which you’re upgrading
-
to is the AM version to which you’re upgrading
-
rules specifies the path to a configuration rules file in the
/path/to/amupgrade/rules
directory
For example:
$ amupgrade \ -i /path/to/AM7Config/ \ -o /path/to/AM7.3Config \ -a 7.2 \ rules/amster/7.2.x-to-7.3.x.groovy Reading existing configuration from files in /path/to/AM72-config/… Modifying configuration based on rules in [rules/amster/7.2.x-to-7.3.x.groovy]… reading configuration from Amster json files Writing configuration to new location at /path/to/AM7.3Config… Upgrade Completed, modified configuration saved to /path/to/AM7.3Config
If you are upgrading a file-based configuration, rather than a configuration exported with Amster, use the --fileBasedMode
option instead of the-i
and-o
options. -
-
Follow the Amster documentation to import the upgraded configuration.
Upgrade wizard
The upgrade wizard brings the AM configuration, including the version number, up to date with the new version.
-
Stop AM or the container where it runs.
-
Deploy your customized AM
.war
file.When you deploy the new
.war
file, you might need to delete working files left by the old deployment.For example, if you deploy on Apache Tomcat, replace
/path/to/tomcat/webapps/openam.war
with the customized.war
file, then recursively delete the/path/to/tomcat/webapps/openam/
and/path/to/tomcat/work/Catalina/localhost/openam/
directories before restarting the server. -
Restart AM or the container where it runs.
-
After deploying AM, but before upgrading, your application container serves AM’s upgrader user interface.
Suspend any external network access to the application container until the upgrade is complete. After the upgrade is complete, AM prevents access to the upgrader UI.
-
Go to the deployment URL and follow the prompts to upgrade.
-
Restart AM or the container where it runs.
-
Update the identity store schema:
-
Log into AM.
-
Go to Realms > Realm Name > Datastores > External User Store.
-
Click Load Schema then click Save to apply your changes.
-
If you have additional identity stores, repeat the previous steps for each store.
-
|
openam-upgrade-tool
The openam-upgrade-tool
lets you upgrade the configuration without user intervention.
-
Set up the configuration tools to install the
openam-upgrade-tool-14.1.3.21.jar
.A
sampleupgrade
file is expanded in the directory where you install the tool. -
Create a configuration file, for example
upgrade.properties
.You can use the
sampleupgrade
file as a template.The upgrade configuration file should resemble the following:
$ grep -v "^#" upgrade.properties SERVER_URL=https://openam.example.com:8443 DEPLOYMENT_URI=/openam ACCEPT_LICENSES=true
-
Run the upgrade tool, specifying the
upgrade.properties
file you created:$ java -jar openam-upgrade-tool-14.1.3.21.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 more information about
openam-upgrade-tool-14.1.3.21.jar
, refer to the reference documentation.
Update tools, scripts, and components
-
Update the AM tools.
Follow Set up administration tools and the Amster User Guide to install an updated version of the tools.
When you have confirmed that the new tools are working, delete the old tools.
-
Ensure that the AM scripts are current, and that they contain the modifications that your environment requires.
To avoid overwriting changes made in customized scripts, the upgrade process does not update scripts from earlier versions of AM.
Check that the scripts in your environment are compatible with the version of AM you’re upgrading to by following these steps:
-
Read the Release notes for information about possible changes.
-
Install an AM 7.3.1 test environment, and compare the scripts.
New installations always have the current scripts.
-
-
Review the information in Upgrade components and services and decide if you need to reconfigure any of AM’s services or features.
Reconfigure any custom advanced properties if necessary. These properties are lost during the upgrade, and you will need to add them again in the AM admin UI.
How do I configure advanced server properties?
-
To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI.
-
To configure advanced server properties for a particular instance, go to Deployment > Servers > Server Name > Advanced.
If the property you want to add or edit is already configured, click on the pencil () button to edit it. When you are finished, click on the tick () button.
Click Save Changes.
-
Update the schema
You might need to update the schema for specific data stores, depending on the version from which you are upgrading and the data store type.
Configuration store
Generally, updating your configuration will also make the required schema updates to the configuration store.
After you have updated the configuration, add an access control instruction (ACI) to the configuration store directory to give the AM 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");)
Refer to Prepare configuration stores for more information about configuring AM configuration stores.
Identity store
Depending on the version you are upgrading from, and the features you have configured, you might need to update your identity store schema manually.
- Upgrade from a version prior to 6.0 with knowledge-based (KBA) user self-service questions
-
You must apply this update if you added the
user_store_type_kba.ldif
schema to your external user data store, even if you did not configure user self-service.-
In the path where you deployed the
openam.war
file (for example,/path/to/tomcat/webapps/openam
) locate the following files in theWEB-INF/template/ldif/opendj
directory:-
opendj_add_kba_attempts.ldif
-
opendj_update_aci_kba_attempts.ldif
If your user data store is not ForgeRock Directory Services, use these files as examples to create LDIF files suitable for your environment. -
-
In the
opendj_update_aci_kba_attempts.ldif
file, replace@SM_CONFIG_ROOT_SUFFIX
with the base DN you defined when you installed DS (for example,dc=userstore,dc=example,dc=com
). -
Apply the two LDIF files to the user data store schema.
For example, to update a DS instance, run the following command:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'id.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_add_kba_attempts.ldif \ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_update_aci_kba_attempts.ldif # Processing MODIFY request for cn=schema # MODIFY operation successful for DN cn=schema # Processing MODIFY request for dc=userstore,dc=example,dc=com # MODIFY operation successful for DN dc=userstore,dc=example,dc=com
-
- Upgrade from a version prior to 7.1 with a ForgeRock Directory Services identity store
-
-
In the path where you deployed the
openam.war
file (for example,/path/to/tomcat/webapps/openam
) locate the following file in theWEB-INF/template/ldif/opendj
directory:opendj_retry_limit_node_count.ldif
-
Update the identity store schema as follows:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'id.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --continueOnError \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_retry_limit_node_count.ldif
This schema update is required for the Save Retry Limit to User feature in the Retry Limit Decision node. The feature is enabled by default.
Even if you are not currently using the Retry Limit Decision node, you should make this schema update, in case you decide to use the node in the future. If you cannot update the identity store schema at this point, you must disable the feature.
-
- Using push or web authentication, or using the ForgeRock SDK for device profiling
-
Apply the following LDIF files:
-
/path/to/openam/WEB-INF/template/ldif/opendj/push_2fa.ldif
-
/path/to/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif
-
/path/to/openam/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif
For example:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'id.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --continueOnError \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif\ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif
If you do not make this schema change, you must remove the
webauthnDeviceProfilesContainer
object class from the user configuration after the upgrade:-
In the AM admin UI, go to Realms > Realm Name > Identity Stores > Identity Store Name.
-
On the User Configuration tab, remove
webauthnDeviceProfilesContainer
from the LDAP User Object Class. -
Save your changes.
Make the same change for each identity store that does not have the schema change, and in each realm that uses the identity store.
-
Core Token Service (CTS) store
If you are updating from a version prior to AM 6.5, apply the following LDIF file to update the CTS schema:
-
cts-add-ttlexpire.ldif
If you are updating from a version prior to AM 6, also apply the following LDIF files:
-
cts-add-multivalue.ldif
-
cts-add-multivalue-indices.ldif
Replace the @DB_NAME@ variable inside the cts-add-multivalue-indices.ldif file with the CTS backend name.
For example, replace occurrences of @DB_NAME@ with ctsStore .
|
Apply the schema updates:
$ /path/to/opendj/bin/ldapmodify \
--hostname 'cts.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-multivalue.ldif \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-multivalue-indices.ldif \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-ttlexpire.ldif
Upgrade components and services
As part of planning your upgrade, consider that some changes in later AM versions will have an impact on your environment. Usually, these changes are driven by changes in specification, security policies, or performance.
When possible, the upgrade process makes the appropriate changes on AM configuration. However, sometimes you will need to perform additional configuration based on your environment needs.
In addition to the mandatory upgrade steps outlined in Upgrade AM instances, if you are using features described in these lists, you will need to perform additional upgrade tasks:
Changes in AM 7.2
- Changes to the OIDC claim classes
-
-
The
org.forgerock.openidconnect.Claim
class has been deprecated. The neworg.forgerock.oauth.clients.oidc.Claim
class, in the ForgeRock commons library, replaces its functionality.This new class has a
getNameWithLocale()
method that returns a string of claim names, appended with#
and the locale, in line with the OIDC specification.A new
getJavaLocale()
method has been added to theClaim
class, and lets a caller get theLocale
object associated with the claim. The existinggetLocale()
method remains unchanged, and is equivalent to callinggetJavaLocale().toLanguageTag()
. -
The new
Claim
class contains aClaimBuilder
class, that you should use to create instances of the Claim. TheClaim
class is immutable and should not be extended. (It cannot be marked asfinal
, for compatibility reasons.) -
The
ClaimBuilder
class no longer contains awithValues
method. This method has been split into the following, more granular methods (with corresponding new methods for single items):-
withBooleanValues
andwithBooleanValue
-
withNumericalValues
andwithNumericalValue
-
withJsonValues
andwithJsonValue
-
withStringValues
andwithStringValue
-
-
The new
ClaimsMapper class separates and encapsulates the functionality for converting claims to and from JSON. The `asMap
method has therefore been removed from theClaim
class.
-
- Anonymous user inactive by default
-
The default
anonymous
user, used, for example, by the Anonymous User Mapping node, is nowInactive
by default. If you have existing nodes, modules, or other clients that reference this user, you must explicitly set the user status toActive
. normalized-profile-to-managed-user
scripts-
For Apple SSO configurations that use the Request Native App for UserInfo property, the normalized-profile-to-managed-user.groovy and normalized-profile-to-managed-user.js scripts have been updated to set a flag that specifies how
userinfo
objects should be patched.
If you use these scripts, or a custom variation of these scripts, in your Apple SSO authentication tree, you should update your scripts to set the flag. You should also update your social provider journey to add a Scripted Decision node, as described in Request Native App for UserInfo.
- Connections made by the CTS
-
OPENAM-13855 corrected an issue where the CTS was creating too many connections to the Directory Services. This fix might imply that the number of connections created is now different in your deployment, corrected to be the expected number of connections. Monitor your environments to ensure that this corrected number of connections is sufficient, and increase it if necessary.
- Script content stored in clear text
-
In file-based configurations, script content is now stored in cleartext, rather than as a base64-encoded string. This makes it easier to find differences between old and new configurations. If you are upgrading AM from a previous version, existing scripts will still appear as base64-encoded strings in their corresponding configuration files. These scripts must be saved again in order for the cleartext script content to be stored in the configuration file. Note that script content is still base64-encoded in REST requests and responses.
- OAuth 2.0 token introspection
-
-
The
/oauth2/introspect
endpoint now returns an additional member,username
, which specifies the user that authorized the introspected token.As part of this change, the
user_id
member, which was used by earlier versions of the specification, is deprecated. It will be removed in a future version of AM.This change aligns the endpoint’s response with the OAuth 2.0 Token Introspection specification.
-
HTTP GET requests are now disallowed on the
/oauth2/introspect
endpoint by default. Usingtoken
as a query parameter on this endpoint is also disallowed. To change this behavior to suit existing clients, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.
-
-
AM 7.2 changes the way the
/oauth2/introspect
and the/oauth2/tokeninfo
endpoints return the value of theexpires_in
object.The
expires_in
object specifies the time, in seconds, that a token is valid for. For example, 3600 seconds. This value is set at token creation time, and it depends on the configuration of the OAuth2 Provider Service.When providing a token introspection or token information response, earlier versions of AM returned the value of the
expires_in
object as it was stored in the token. This means that any call to the endpoints while the token is valid returned the same value for theexpires_in
object.AM 7.2 calculates the amount of seconds the token is still valid for and returns this value in the
expires_in
object. Therefore, repeated calls to the endpoints return different values for the object.However, the actual value of the
expires_in
object in the token does not change. Inspecting the token without using AM will show the value set at token creation time.The
expires_in
object is not always present in the endpoint response:-
Introspection endpoint: AM only returns the
expires_in
object for client-side tokens issued to a client configured in the same realm as the resource owner’s. -
Token information endpoint: AM does not return the
expires_in
object for client-side tokens issued to a client configured in a different realm than the resource owner’s.
-
- OpenID Connect
userinfo
endpoint -
AM 7.2 changes when the
aud
andiss
objects are returned in the JWT response of the/oauth2/userinfo
endpoint.
Earlier versions of AM returned the iss
object when the
user information response was a signed, encrypted, or a signed and
encrypted JWT. The aud
object was never returned.
AM 7.2 now returns both the aud
and iss
objects when response is a signed, or a signed and encrypted JWT, according to the OpenID Connect Core 1.0 incorporating errata set 1 specification.
The iss
object is no longer returned when the response is an encrypted JWT.
- Web and Java agent properties in AM admin UI
-
-
Web agent properties added
-
Use Built-in Apache HTTPD Authentication Directives (
com.forgerock.agents.no.remoteuser.module.compatibility
) -
Hostname to IP Address Map (
com.forgerock.agents.config.hostmap
) -
Retain Session Cache After Configuration Change (
com.forgerock.agents.session.cache.eventually.consistent
)
-
-
Java agent properties added
-
Recheck availability of AM (
org.forgerock.agents.am.unavailability.recheck.window.in.seconds
) -
Enable Notification of Session Logout (
org.forgerock.agents.session.change.notifications.enabled
)
-
-
Deprecated Java agent properties removed
-
Fall-Forward Mode (
org.forgerock.agents.fallforward.mode.enabled
) -
PDP Cache TTL in Milliseconds (
com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl
)
-
-
-
Java agent property name changes
The Java Agent property names have changed in AM admin UI. The new names reflect the names now used in the Java Agent documentation.
Summary of new names
Old Name New Name Accept SSO Tokens
Enable SSO Token Acceptance
Agent Configuration Change Notification
Enable Notifications of Agent Configuration Change
Agent Filter Mode
Agent Filter Mode Map
Allow Custom Login Mode
Enable Custom Login Mode
AM Conditional Login URL
OAuth Login URL List
AM Conditional Logout URL
Conditional Logout URL List
AM Login URL
AM Login URL List
Application Logout URI
Logout URI Map
Attribute Cookie Encode
Enable Attribute Encoding
Authentication Fail Reason Url
Authentication Fail URL
CDSSO Domain List
JWT Cookie Domain List
CDSSO Redirect URI
Authentication Redirect URI
Continuous Security Cookies
Continuous Security Cookie Map
Continuous Security Headers
Continuous Security Header Map
Convert SSO Tokens into OpenID Connect JWTs
Convert SSO Tokens Into OIDC JWTs
Cookies Reset Domain Map
Reset Cookie Domain Map
Cookies Reset Name List
Reset Cookie List
Cookies Reset Path Map
Reset Cookie Path Map
Custom Conditional Login URL
Legacy Login URL List
Custom Response Header
Custom Response Header Map
Encode Cookies
Enable Encoded Cookies
Exchanged SSO Token Cache Size
Max Entries in SSO Exchange Cache
Exchanged SSO Token Cache Time to Live
Exchanged SSO Token Cache TTL
Expired Session Cache Max Records
Max Entries in Expired Session Cache
FQDN Check
Enable FQDN Checking
FQDN Default
Default FQDN
HTTP 302 Redirect Not Enforced List
HTTP 302 Redirect Not-Enforced List
HTTP 302 Redirect Replacement HTTP Code
HTTP 302 Redirect Replacement HTTP Status Code
HTTP 302 Redirects Enabled
Enable HTTP 302 Redirects
Http Only
Enable HTTP Only Cookies
Invert Not Enforced IPs
Invert Not-Enforced IPs
Invert Not Enforced URIs
Invert Not-Enforced URIs
JWT Cache Size
Max Entries in JWT Cache
Legacy User Agent Support Enable
Enable Legacy Support Handlers
Load Balancer Cookie Enabled
Enable Load Balancer Cookies
Login Form URI
Login Form URI List
Logout Entry URI
Logout Entry URI Map
Logout Introspect Enabled
Enable Logout Introspection
Logout Request Parameter
Logout Request Parameter Map
Missing PDP entry URI
Missing POST Data Preservation Entry URI Map
Not Enforced Client IP List
Not-Enforced Client IP List
Not Enforced Favicon
Not-Enforced Favicon
Not Enforced IP Cache Flag
Enable Not-Enforced IP Cache
Not Enforced IP Cache Size
Max Entries in Not-Enforced IP Cache
Not Enforced URIs Cache Enabled
Enable Not-Enforced URIs Cache
Not Enforced URIs Cache Size
Max Entries in Not-Enforced URI Cache
Not Enforced URIs
Not-Enforced URIs
PDP Cache TTL in Minutes
POST Data Preservation Cache TTL
PDP Maximum Cache Size
POST Data Preservation Cache Size
PDP Maximum Number of Cache Entries
Max Entries in POST Data Preservation Cache
PDP Stickysession key-value
POST Data Preservation Sticky Session Key Value
PDP Stickysession mode
POST Data Preservation Sticky Session Mode
Perform Policy Evaluation in User Authenticated Realm
Enable Policy Evaluation in User Authentication Realm
Policy Cache Per User
Max Entries in Policy Cache per Session
Policy Cache Size
Max Sessions in Policy Cache
Policy Evaluation Realm
Policy Evaluation Realm Map
Policy Set
Policy Set Map
Port Check Enable
Enable Port Checking
Port Check File
Port Check Filename
Port Check Setting
Port Check Protocol Map
Possible XSS code elements
XSS Code Element List
Post Data Preservation enabled
Enable POST Data Preservation
Pre-Authenticated Cookie Max Age
Max Age of Pre-Authentication Cookie
Pre-Authenticated Cookie Name
Pre-Authentication Cookie Name
Profile Attribute Mapping
Profile Attribute Map
Regular Expression Remove Query Parameters
Regex Remove Query Parameters List for Policy Evaluation
Remove Query Parameters
Remove Query Parameters List for Policy Evaluation
Resource Access Denied URI
Access Denied URI Map
Response Attribute Mapping
Response Attribute Map
Restrict To Realm
Restrict to Realm Map
Retain Query Parameters
Query Parameter List for Policy Evaluation
Rotate Local Audit Log
Enable Local Audit Log Rotation
Samesite Cookie Attributes Excluded User Agents Pattern List
Exclude Agents From Samesite Cookie Attributes
Session Attribute Mapping
Session Attribute Map
URL Policy Env GET Parameters
GET Parameter List for URL Policy Env
URL Policy Env jsession Parameters
JSession Parameter List for URL Policy Env
URL Policy Env POST Parameters
POST Parameter List for URL Policy Env
User Principal Flag
Enable User Principal Flag
User Token Name
User Session Name
XSS detection redirect URI
XSS Redirect URI Map
- Session and OAuth 2.0 token terminology
-
Sessions and OAuth 2.0 (or Open ID Connect) tokens that are stored in the CTS token store were previously referred to as CTS-based, and sessions/tokens that are returned to the client were referred to as client-based.
This release introduces new terminology to clarify and simplify the distinction between the two types of sessions and tokens, moving away from low-level descriptions to the following terms:
-
Server-side (previously called CTS-based)
-
Client-side (previously called client-based)
This change is reflected in both the documentation and the configuration settings that you see in the user interface.
- Terminology for denying or allowing access
-
The AM 7.2 release initiates the move towards more descriptive and inclusive terminology for the concept of allowing or denying access to components or services.
Where you might previously configure a whitelist or a blacklist, you now configure an allowlist or a denylist. This renaming task is ongoing throughout the ForgeRock documentation and user interfaces.
- Change in behavior when deleting UMA policies
-
In previous AM releases, deleting an UMA policy did not impact any nested UMA policies. In AM 7.2.0, if you delete an UMA policy, any nested UMA policies are deactivated.
For details, see Delete an UMA policy (REST).
Changes in AM 7.1
- Decompressed JWTs
-
By default, AM rejects any JWT that expands to more than 32 KiB (32768 bytes) when decompressed. For more information about changing this default value, see Control the size of compressed JWTs.
- Request Body Size
-
By default, AM rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size. For more information about changing this default value, see Limit the size of the request body.
- Pre-Approval for Redirection URIs Enforced
-
This change affects AM when acting as an OAuth 2.0 and OpenID Connect client.
If a redirection URI uses a scheme, host, or port that differs from that of AM, you must now add it to the global validation service to ensure that it is pre-approved. This is described in Success and failure redirection URLs.
Otherwise, AM rejects the URI, and redirection fails.
- Subject Claim in Access and ID Tokens
-
The subject claim of access tokens and ID tokens has changed formats to ensure that it is locally unique. The new format is not enforced after upgrading to AM 7.1, but new installations default to it.
The
org.forgerock.security.oauth2.enforce.sub.claim.uniqueness
advanced server property controls the format of thesub
claim.Before enabling it, ensure that your clients can use the new
sub
claim format, or a combination of thesub
and thesubname
claims. - The Retry Limit Decision node
-
The new Save Retry Limit to User feature in this node is enabled by default after upgrade and requires upgrading the identity store schema.
Ensure you update the schema following the instructions in Upgrade AM instances, or disable the feature. ForgeRock recommends keeping it enabled for security reasons.
Failure to take any of the actions will break the authentication journey for trees using this node.
- One-Time Passwords in Authentication Nodes
-
One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient state.
Modify any custom authentication nodes or scripts used by the Scripted Decision node to retrieve the one-time passwords from the transient state after upgrading to AM 7.1.
Changes in AM 7
- User Profile Whitelist
-
The profile attribute allowlist controls the information returned to non-administrative users when accessing
json/user
endpoints.Common profile attributes are allowlisted by default, but you need to add any custom attribute you want your non-administrative users to see. For more information, see Configure the user profile allowlist.
/json/authenticate
Endpoint-
When a client makes a call to the
/json/authenticate
endpoint appending a valid SSO token, AM returns thetokenId
field empty ifHttpOnly
cookies are enabled. For example:
[/mnt/scratch/workspaces/workspace/am-docs-release_7.3.x/target/asciidoc/modules/ROOT/attachments/endpoints/authenticate.bash:#authenticate-expected-when-session-exists]
- Secure Authentication Tree State Secret ID
-
An AES 256-bit key called
directenctest
must be available in the environment during upgrade, but it does not need to be the same key that AM provides on the default keystore.After upgrade, ensure that the
am.authn.trees.transientstate.encryption
secret ID is always mapped to an existing, resolvable secret or key alias. Failure to do so may result in trees not working as expected. - The Embedded DS
-
The embedded DS can only be used for single AM instances, for test and demo purposes. Sites are not supported.
Sites using embedded DS servers must be migrated to external DS servers before upgrading.
- SAML v2.0 Secrets
-
AM 7 migrated SAML v2.0 to use secret stores. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see Configure secret stores after upgrade.
goto
andgotoOnFail
Query Parameter Redirection-
Redirection URLs for authentication services, agents, and SAML v.2.0 must be configured in Success and failure redirection URLs if they are not in the same scheme, FQDN, and port as AM, or are not relative to AM’s URL.
- Web Agents of a Version Earlier than 5.6.3
-
Several properties that used to be configured as custom properties (
com.sun.identity.agents.config.freeformproperties
) have been added as regular properties. Due to this change, upgrading to AM 7 will overwrite the value of the original custom properties with the default value of the new UI properties.To work around this issue, perform one of the following actions:
-
Upgrade to Web Agents 5.6.3 or later before upgrading to AM 7.
-
After upgrading to AM 7, reconfigure the properties that you configured as custom properties in their new UI counterparts.
-
- Changes on the CTS Reaper Tuning Properties
-
AM 7 changes the way the CTS reaper searches for expired tokens.
After upgrading, retune the CTS Reaper using the information in Reaper Search Size.
- OpenID Connect Clients Authenticating with JWTs
-
OpenID Connect clients authenticating with JWTs must include in the JWT a
jti
claim containing a unique identifier, in line with OpenID Connect Core 1.0 incorporating errata set 1. - Cookie Filter
-
AM flags cookies as secure if they come through a connection marked as secure, or if they come through HTTPS. See Secure cookie filter.
Changes in AM 6.5.0.2 and 6.5.1
- OAuth 2.0 Refresh Tokens
-
AM only issues refresh tokens to clients that have the
refresh token
grant type configured in their client profile.After an upgrade to 6.5 or later using the UI or the
openam-upgrade-tool
.jar file, existing OAuth 2.0 clients are configured to use all grant flows, including the Refresh Token Grant flow.To configure the
refresh token
grant type manually, see To Configure AM to Issue Refresh Tokens.
Changes in AM 6.5
- Recovery Codes
-
Recovery Codes are encrypted, and existing codes are no longer displayed to the user. For more information, see Upgrade device recovery codes.
- Secret Stores
-
AM 6.5 introduced secret stores for OAuth 2.0 and the persistent cookie module. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see Configure secret stores after upgrade.
- External Configuration Store
-
DS 6.5 introduced setup profiles, which pre-configure instances for different usages, such as CTS or configuration data. The default base DN for a DS configuration store instance (
ou=am-config
) is different to the default used by previous versions of AM (dc=openam,dc=forgerock,dc=org
).Do not run multiple instances of AM where the configuration store base DNs do not match. Use the same configuration store base DNs when configuring external DS 6.5+ instances that will be used simultaneously alongside existing DS 6 or earlier configuration store instances.
For more information, see Prepare a configuration store.
Changes in AM 6
json/
Endpoints-
AM’s CSRF protection filter requires that either the
X-Requested-With
or theAccept-API-Version
headers are included on requests to endpoints under thejson
root. For more information, see Reviewing REST API Versions Before Upgrading.
For information on the endpoints deprecated or removed in previous versions, and their current equivalents, see the following Knowledge Base article. |
Configure the user profile allowlist
AM 7 introduced a profile attribute allowlist.
The profile attribute allowlist controls the information returned to non-administrative users when they access json/user
endpoints. For example, the allowlist controls the attributes shown in the user profile page.
Common profile attributes are allowlisted by default. You must add any custom attributes that you want non-administrative users to see.
The allowlist can be set globally, or per realm, in the user self-service service. To modify the list:
-
Globally: Go to Configure > Global Services > User Self-Service > Profile Management, and edit the Self readable attributes field.
-
By realm: Go to Realms > Realm Name > Services > User Self-Service > Profile Management, and edit the Self readable attributes field.
Note that you need to add the user self-service service to the realm if you have not done so already, but you do not need to configure anything other than the allowlist.
Note that the kbainfo
attribute is required to be allow-listed for users
to manage their KB questions and answers on user self-service flows.
Configure secret stores after upgrade
AM 6.5 introduced secret stores, which are repositories of cryptographic keys, key pairs, and credentials.
|
Follow these steps to make the secret stores available to other servers in the site:
Redeploy secret stores to a site after upgrade
You can reconfigure the secret stores and their mappings after upgrade. However, we recommend that you follow the steps in this procedure to ensure all secrets are available to all the instances in the site, and later on, you make additional changes to your environment.
The upgrade process creates several secret stores, globally and by realm, depending on the features configured in AM, and depending on the version you are upgrading from:
-
Go to Configuration > Secret Stores, and review the global secret stores created for your environment.
Reference: Global secret stores created after upgrade
- Upgrade from AM 6 or earlier
-
-
default-keystore
: a keystore-type secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process. -
default-passwords-store
: A filesystem secret store configured as the/path/to/openam/security/secrets/encrypted
directory.This directory contains the secrets to open the keystore configured in the
default-keystore
, and its keys. -
UpgradeGlobalSecrets
: A filesystem secret store configured as the/path/to/openam/security/secrets/encrypted/encrypted_hmac_key
directory.This directory contains the secrets used for the OAuth 2.0 server and the Persistent Cookie module.
-
- Upgrade from AM 6.5 or earlier
-
-
default-keystore
: a keystore-type secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process. -
saml2-metadata-signing-keystore
: A keystore secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process. -
default-encrypted_base64-store
: A file system volume secret store that contains SAML v2.0 secrets that are base64-encrypted. -
default-encrypted_plain-store
: A file system volume secret store configured as the directory containing secrets related to thesaml2-metadata-signing-keystore
store.The directory contains the password that was configured in the Metadata signing key password field of the global SAML v2.0 Service Configurations service.
It also contains the password files related to the
default-keystore
store if thedefault-passwords-store
store does not exist.
-
-
Ensure that the keystores configured exist on the other servers within the site. You may need to copy the keystores across or make them available in some other way.
-
Ensure that directories configured in file system secret stores and their content exist on the other servers within the site. You may need to copy the directories across or make them available in some other way.
-
Go to Realms > Realm Name > Secret Stores, and perform the same actions you took for the global secret stores.
Reference: Realm-based secret stores created after upgrade
Realm-based secret stores are created for those features that supported different keystore configurations by realm; for example, SAML v2.0, or the persistent cookie module.
To find the realm-based secret stores, go to Realms > Realm Name > Secret Stores. The secrets themselves are stored in the
/path/to/openam/security/secrets/realms/root/realm-name/secret-store-name
directory.If you have upgraded from a version which had SAML v2.0 Service Configurations at realm level, the upgrade process creates realm-level secret stores for the Metadata signing key alias field and its key, if they were configured.
Repeat this step for each of the realms you have configured.
-
Deploy the new AM
.war
file on the rest of the AM servers. -
Once the site is up, and before opening the service to the end users, review the secret ID mappings of the new secret stores and make changes to them as you see fit.
For example, the upgrade process may have created stores for features you are not using. Those may have mappings to secrets that do not exist, and you may want to remove them in production environments.
For more information about the available secret IDs, see Secret ID Default Mappings.
Reference: SAML v2.0 mappings after upgrade
AM has always been very flexible regarding the configuration of secrets for SAML v2.0; this is why migrating the different combinations may create a high number of secret IDs in your environment.
As a rule of thumb, AM configures providers that were using the same key aliases in the same order, to use the same secret IDs. If this rule cannot be satisfied, the upgrade process creates new secretIDs for the provider by assigning it a secret ID identifier.
If you have upgraded from a version which had SAML v2.0 Service Configurations, AM maps the
am.services.saml2.metadata.signing.RSA
secret ID to the alias taken from the relevant Metadata signing key alias property of the service, either from the global service, or the realm-level services.
Upgrade device recovery codes
This section explains how to upgrade to AM 6.5 and later if you are providing the ability for ForgeRock Authenticator users to access and view device recovery codes.
AM versions earlier than 6.5 do not encrypt the recovery codes stored alongside registered push and OATH devices. This allows the codes to be viewed by users at any time in their dashboard page. However storing credentials in plain text is considered a potential security risk, and from AM 6.5 onwards the recovery codes are displayed once, and then stored in a one-way encryption format, meaning they can never be viewed after their initial display.
After upgrading to AM 6.5 or later, when a user accesses their dashboard page, the stored recovery codes for each registered device will be one-way encrypted, meaning existing codes can no longer be displayed to the user.
This DOES NOT affect the ability to use the existing recovery codes, only the ability to display them in plain text to the user.
If you do not want to encrypt the recovery codes, and therefore retain the ability to show the codes to the user when requested, you can start AM with a Java property, as follows:
Prevent AM from encrypting device recovery codes
Perform these steps to prevent AM 6.5 and later from encrypting device recovery codes.
It is STRONGLY recommended that you encrypt recovery codes. |
-
Locate or create the environment settings script for the container in which AM will run.
For example, the environment settings script for Apache Tomcat is located in
/path/to/tomcat/bin/
, and should be namedsetenv.bat
(Windows) orsetenv.sh
(Unix). -
In the relevant environment settings script, add the
org.forgerock.openam.devices.recovery.use_insecure_storage=true
property to theCATALINA_OPTS
variable.For example:
export CATALINA_OPTS="$CATALINA_OPTS -Dorg.forgerock.openam.devices.recovery.use_insecure_storage=true"
For containers other than Apache Tomcat, perform an analogous step to add the Java option to the scripts used to startup the AM instance.
-
Start the container in the usual manner.
For example,
./startup.sh
.AM will not encrypt device recovery codes when created, or when first accessed. When preventing AM from encrypting the stored recovery codes, be aware of the following points:
-
Users will only see registered devices on their dashboard that are of the same type that they have used to authenticate.
For example, if they authenticated using a registered OATH device, they will not see any registered push or WebAuthn devices on their dashboard. This is to prevent users being able to see recovery codes for devices that they did not authenticate with.
-
The option to view the recovery codes for a device has been removed from the user interface.
However, the recovery codes are returned in the JSON response when querying the
/devices/2fa/
endpoint. You will need to provide a customized user interface to display these codes. -
If the container in which AM is running is ever started without the
org.forgerock.openam.devices.recovery.use_insecure_storage=true
property, a query to any of the/devices/2fa/
endpoints will cause AM to one-way encrypt the recovery codes.
-
Upgrade JDBC audit event handlers
If you had configured one or more JDBC audit event handlers, make the following changes to the audit tables' schema:
-
Run the following command on Oracle databases that support AM audit event handlers:
ALTER TABLE am_auditaccess ADD (response_detail CLOB NULL);
This command adds the
response_detail
column to theam_auditaccess
table. -
Run the following commands on MySQL databases that support AM 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 theam_auditconfig
table toobjectid
and add theresponse_detail
column to theam_auditaccess
table. -
If you use databases other than Oracle or MySQL to support AM audit event handlers, review their schema.
If the
am_auditconfig
table has a column namedconfigobjectid
, change that column’s name toobjectid
.If the
am_auditaccess
table does not have a column namedresponse_detail
, add that column to the table’s schema.
Migrate legacy instances
Rather than upgrade legacy instances (running OpenSSO or Sun Access Manager, or an OpenAM or AM version that is no longer supported), you instead manually migrate from your existing deployment to a new deployment.
For complex legacy deployments, ForgeRock can assist you in the migration process.
Upgrade a legacy deployment
-
Prepare your customized AM WAR file.
-
Prepare a new deployment, installing servers from the new, customized WAR file, starting with the instructions in Install AM.
-
After installation, configure the new servers in the same way as the old servers, adapting as necessary.
You can use the
ssoadm do-batch
command to apply multiple changes with one command. -
Validate that the new service is performing as expected.
-
Redirect client application traffic from the old deployment to the new deployment.