Upgrade from AM 6.5 to 6.5.x doesn't start because The entry ou=am-config does not include a subschemaSubentry attribute

Symptoms

The Upgrade to Access Management 6.5.x button on the Upgrade Available page is disabled, which prevents you proceeding with the upgrade.

The following errors are shown in the amUpgrade log when this happens:

• Unable to read directory schema, the schema won't be upgraded: amUpgrade:04/24/2019 12:25:37:515 PM BST: Thread[http-nio-8080-exec-6,5,main]: TransactionId[73cba79a-2539-470f-8c30-6313e6bbbdaf-38] ERROR: Unable to read directory schema, the schema won't be upgraded No Results Returned: The entry ou=am-config does not include a subschemaSubentry attribute at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:246)​ at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:143) at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:112) at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:70) at org.forgerock.opendj.ldap.schema.SchemaBuilder.getSubschemaSubentryDn(SchemaBuilder.java:93) at org.forgerock.opendj.ldap.schema.SchemaBuilder.addSchemaForEntry(SchemaBuilder.java:1714) at org.forgerock.opendj.ldap.schema.Schema.readSchemaForEntry(Schema.java:898) at org.forgerock.openam.upgrade.DirectoryContentUpgrader.<init>(DirectoryContentUpgrader.java:156) at org.forgerock.openam.upgrade.steps.UpgradeDirectoryContentStep.initialize(UpgradeDirectoryContentStep.java:56) at org.forgerock.openam.upgrade.UpgradeServices.<init>(UpgradeServices.java:96) at org.forgerock.openam.upgrade.UpgradeServices.getInstance(UpgradeServices.java:123) at com.sun.identity.config.upgrade.Upgrade.<init>(Upgrade.java:45)
• An error occurred while initializing upgrade steps:
  • AM 6.5.2 and later: ERROR: An error occurred while initializing upgrade steps org.forgerock.openam.upgrade.UpgradeException: Failed to read directory schema at org.forgerock.openam.upgrade.DirectoryContentUpgrader.<init>(DirectoryContentUpgrader.java:160) ... Caused by: org.forgerock.opendj.ldap.EntryNotFoundException: No Results Returned: The entry ou=am-config does not include a subschemaSubentry attribute
  • AM 6.5.0.x and AM 6.5.1: amUpgrade:04/24/2019 12:25:37:536 PM BST: Thread[http-nio-8080-exec-6,5,main]: TransactionId[73cba79a-2539-470f-8c30-6313e6bbbdaf-38] ERROR: An error occurred while initializing upgrade steps java.lang.NullPointerException at org.forgerock.openam.upgrade.DirectoryContentUpgrader$UpgradeCTSToMultiValue.isUpgradeNecessary(DirectoryContentUpgrader.java:369) at org.forgerock.openam.upgrade.DirectoryContentUpgrader.<init>(DirectoryContentUpgrader.java:162) at org.forgerock.openam.upgrade.steps.UpgradeDirectoryContentStep.initialize(UpgradeDirectoryContentStep.java:56) at org.forgerock.openam.upgrade.UpgradeServices.<init>(UpgradeServices.java:96) at org.forgerock.openam.upgrade.UpgradeServices.getInstance(UpgradeServices.java:123) at com.sun.identity.config.upgrade.Upgrade.<init>(Upgrade.java:45)

Recent Changes

Installed the DS configuration store for AM 6.5 using the following setup options:

See To Use DS for AM Configuration Data for further information.

Causes

During the upgrade process, AM tries to read the SubSchemaSubentry operational attribute in order to access the schema, but the am-config profile in productionMode is missing the ACI that grants access to operational attributes.

If you compare the ACIs that the am-config profile needs to perform the upgrade with the ones that are available, you can see that the "Allow CRUDQ operations" ACI does not exactly match what is needed; it is missing the operation attributes (+):

• Needed ACIs: aci: (targetattr="*||+")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");) aci: (targetcontrol="2.16.840.1.113730.3.4.3||1.2.840.113556.1.4.473")(version 3.0;acl "Allow persistent search and server-side sorting controls"; allow (read)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");)
• Available ACIs: aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");) aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;acl "Allow persistent search"; allow (search, read)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");) aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;acl "Allow server-side sorting"; allow (read)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");)

Solution

This issue can be resolved by installing a new DS 6.5.1 or later instance for your configuration store so you can run setup again; this will create the correct ACIs. You can download this from Backstage. Once you have re-installed DS, you can then attempt to upgrade to AM 6.5.x again.

Workaround

You can workaround this issue by modifying the "Allow CRUDQ operations" ACI to include operation attributes:

1. Remove the current "Allow CRUDQ operations" ACI: $ ./ldapmodify --hostname localhost --port 1636 --useSsl --trustAll --bindDN "cn=Directory Manager" --bindPassword password dn: ou=am-config changetype: modify delete: aci aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");)
2. Verify that the "Allow CRUDQ operations" ACI has been removed: $ ./ldapsearch --hostname localhost --port 1636 --useSsl --trustAll --bindDN "cn=Directory Manager" --bindPassword password --baseDn "ou=am-config" "aci=*" aci
3. Add the "Allow CRUDQ operations" ACI with operational attributes: $ ./ldapmodify --hostname localhost --port 1636 --useSsl --trustAll --bindDN "cn=Directory Manager" --bindPassword password dn: ou=am-config changetype: modify add: aci aci: (targetattr="*||+")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,ou=am-config");)
4. Verify that the "Allow CRUDQ operations" ACI with operational attributes has been added: $ ./ldapsearch --hostname localhost --port 1636 --useSsl --trustAll --bindDN "cn=Directory Manager" --bindPassword password --baseDn "ou=am-config" "aci=*" aci

See Also

Upgrading AM

Using Directory Server Setup Profiles

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14565 (AM Upgrade NPE when unable to read operational attrs from directory)

OPENAM-14333 (am-config profile is unable to upgrade in production mode)

OPENDJ-6065 (Backport OPENDJ-6039: AM Config Store Profile doesn't have enough access in ProductionMode when upgrading AM.)

OPENDJ-6039 (AM Config Store Profile doesn't have enough access in ProductionMode when upgrading AM.)