3.2 Running the NrfCaseUpdate Utility

This section provides details about the NrfCaseUpdate utility. Topics include:

3.2.1 Overview of NrfCaseUpdate

The NrfCaseUpdate procedure is necessary to provide support for mixed-case searching on roles and resources. This procedure updates the schema by modifying the nrfLocalizedDescrs and nrfLocalizedNames attributes, which are used by User Application drivers. The procedure is required before installing RBPM 4.0.1 and before migrating existing drivers in Designer 4.0.1, if your eDirectory tree was created with 3.6.1 or an earlier release of the RBPM. This step is not required if you are doing a new installation of version 4.0.1 or are upgrading from 3.7.

3.2.2 Installation Overview

This section provides an overview of the steps for upgrading and migrating your existing RBPM environment. This overview emphasizes use of Designer 4.0.1 to create backups of User Application drivers before proceeding with any upgrade.

  1. Install Designer 4.0.1.

  2. Run a health check of the Identity Vault to make sure the schema extends properly. Use TID 3564075 to complete the health check.

  3. Import existing User Application drivers into Designer 4.0.1.

  4. Archive the Designer project. It represents the pre-RBPM 4.0.1 state of the driver.

  5. Run the NrfCaseUpdate process.

  6. Create a new Designer 4.0.1 project and import the User Application driver to prepare for migration.

  7. Install RBPM 4.0.1.

  8. Migrate the driver using Designer 4.0.1.

  9. Deploy the migrated driver.

3.2.3 How NrfCaseUpdate Affects the Schema

When the NrfCaseUpdate utility updates existing attributes in the eDirectory schema, any existing instances of those attributes are effectively deleted. User Application drivers use these attributes and thus will be affected by this schema update, specifically roles and separation of duties names and descriptions, custom attestation requests, and reports.

The NrfCaseUpdate procedure updates existing User Application drivers by providing a utility for exporting existing User Application drivers to an LDIF file before running the schema update. Importing the LDIF files after the schema update effectively recreates any objects deleted during the schema update.

As always, it is important that you back up any existing User Application drivers as a precaution. Remember that schema updates will affect all Identity Manager partitions, so it is very important to use NrfCaseUpdate to export any User Application drivers in the tree.

3.2.4 Creating a Backup of the User Application Drivers

It is recommended that you use Designer to create a backup of your User Application drivers. Before running the NrfCaseUpdate procedure, you should follow this procedure to back up your existing User Application drivers:

  1. Install Designer 4.0.1, which ships with RBPM 4.0.1.

  2. Create an Identity Vault and map it to your Identity Manager server containing your User Application drivers.

  3. Use the Live->Import command to import your Driver Set and User Application drivers.

  4. Save and archive this Designer project.

3.2.5 Using NrfCaseUpdate

NrfCaseUpdate will prompt you to export each driver and then will perform the schema update. If you are unsure about the existence or location of any existing User Application drivers, you should not proceed, as the schema update may invalidate any existing User Application drivers.

The JRE provided under the Identity Manager installation directory, typically /root/idm/jre, can be used to run NrfCaseUpdate. If you require SSL connections to eDirectory, you will need to enable your JRE for SSL connections by following the instructions in Section 3.2.7, Enabling the JRE for SSL Connections.

Alternatively, you may run the NrfCaseUpdate utility remotely from a host with a JRE that contains the eDirectory certificate, such as the User Application server host. In this case, you will need to exit the NrfCaseUpdate utility using CTRL-C after exporting all drivers to LDIF and before the schema update. Then, you can manually update the schema on the eDirectory host using the ndssch command, as shown below:

ndssch -h hostname adminDN update-nrf-case.sch

NOTE:NrfCaseUpdate can accept several arguments to the command line. Pass -help or -? for more information.

Follow these steps to run NrfCaseUpdate:

  1. Verify that you have completed a health check of the Identity Vault before running the NrfCaseUpdate utility. Use TID 3564075 to complete the health check.

  2. Identify all the DNs of any existing User Application drivers before you start the utility. You will need authentication credentials to export these drivers to LDIF.

  3. Run the NrfCaseUpdate utility. You may optionally pass the -v option to obtain more verbose output:

    /root/idm/jre/bin/java -jar NrfCaseUpdate.jar -v

  4. You will be asked if you have an existing User Application driver. Answer true if you have an existing User Application driver. Otherwise, answer false and skip to Step 15.

    Do you currently have a User Application Driver configured [DEFAULT true] :

  5. Next, the utility asks if you have more than one User Application driver. Answer true if you have more than one User Application driver:

    Do you currently have more than one (1) User Application Driver configured [DEFAULT false] :

  6. Specify the DN of the administrator with proper credentials for exporting the User Application driver:

    Specify the DN of the Identity Vault administrator user.
This user must have inherited supervisor rights to the user application driver specified above.
(e.g. cn=admin,o=acme):

  7. Enter the password for this administrator:

    Specify the Identity Vault administrator password:

  8. Enter the host name or IP address of the Identity Manager server hosting the User Application driver:

    Specify the DNS address of the Identity Vault (e.g acme.com):

  9. Specify the port to be used for the connection:

    Specify the Identity Vault port [DEFAULT 389]:

  10. The next question asks if you will use SSL for the connection. If you want to use SSL, the JRE requires the eDirectory certificate to be in the trusted store. To persist the certificate, follow the instructions in Section 3.2.7, Enabling the JRE for SSL Connections.

    Use SSL to connect to Identity Vault: [DEFAULT false] :

  11. Specify the fully qualified distinguished name of the User Application driver that will be exported:

    Specify the fully qualified LDAP DN of the User Application driver located in the Identity Vault
(e.g. cn=UserApplication,cn=driverset,o=acme):

    If the DN includes a space, it has to be included in single quotes, as shown below:

    'cn=UserApplication driver,cn=driverset,o=acme'

  12. Specify a name for the LDIF file where the User Application will be exported:

    Specify the LDIF file name where the restore data will be written (enter defaults to nrf-case-restore-data.ldif):

  13. The utility will post information about the objects saved to the LDIF.

  14. If you indicated you have multiple drivers, you will see the following prompt:

    You indicated you have more than one (1) User Application Driver to configure.
Do you have another driver to export? [DEFAULT false] :

If you have another driver to export then specify true. The utility will repeat Steps 5 through 12 for each driver. 

If you do not have another driver to export then specify false. Ensure that you have exported all existing drivers before proceeding as the utility will proceed with the schema update.

  15. You will be prompted for the location of your ndssch utility, along with the typical locations. The ndssch utility is used for updating the schema.

    Please enter the path to the schema utility:
For Unix/Linux typically /opt/novell/eDirectory/bin/ndssch
For Windows C:\Novell\NDS\schemaStart.bat:

  16. The utility will post the status message for the schema update:

    Schema has successfully been updated for mixed case compliance!

    NOTE:Be sure to give eDirectory enough time to synchronize the schema changes. If you don’t allow enough time, the import of the LDIF file fail.

  17. Run another health check on the Identity Vault to verify that the schema was extended properly before importing the LDIF file. Use TID 3564075 to complete the health check.

  18. After all drivers have been exported and the schema update has been applied successfully, you need to import each LDIF file. You should indicate to allow forward references in your ice command. A suggested command line is shown below:

    ice -l [mylogfile.log] -v -SLDIF -f [your_created_ldif] -c -DLDAP -s [hostname] -p [389/636] -d [cn=myadmin,o=mycompany] -w [MYPASSWORD] -F -B

  19. After all drivers have been re-imported, verify that the NrfCaseUpdate process was successful. See Section 3.2.6, Verification of the NrfCaseUpdate Process for more information.

  20. After you have verified that the NrfCaseUpdate process was successful, you may continue with the RBPM 4.0.1 installation.

3.2.6 Verification of the NrfCaseUpdate Process

After all drivers have been re-imported, verify that the restoration was successful by reviewing the following items in the User Application:

  • Role names and descriptions

  • Separation of duties names and descriptions

  • Attestation requests, including custom requests

  • Reporting

After you complete the verification, you can continue with installation and upgrade to RBPM 4.0.1.

3.2.7 Enabling the JRE for SSL Connections

This section explains how to configure the JRE to use an SSL connection.

First, export a self-signed certificate from the certificate authority in the Identity Vault:

  1. From iManager, in the Roles and Tasks view, click Directory Administration > Modify Object.

  2. Select the certificate authority object for the Identity Vault, then click OK. It is usually found in the Security container and named as TREENAME CA.Security.

  3. Click Certificate > Self Signed Certificate.

  4. Click Export.

  5. When you are asked if you want to export the private key with the certificate, click No, then click Next.

  6. Select binary DER format.

  7. Click the link Save the exported certificate.

  8. Browse to a location on your computer where you want to save the file, then click Save.

  9. Click Close.

Next, import the self-signed certificate into the JRE's trusted store.

  1. Use the keytool utility that is included in the JRE.

  2. Import the certificate into the Role Mapping Administrator’s trust store by entering the following command at a command prompt:

    keytool -import -file name_of_cert_file -trustcacerts -noprompt -keystore filename -storepass password

    For example:

    keytool -import -file tree_ca_root.b64 -trustcacerts -noprompt -keystore cacerts -storepass changeit

3.2.8 Restoring Invalidated User Application Drivers

If the schema update is applied to an existing User Application driver before that driver has been processed using NrfCaseUpdate, it will be invalidated and you will need to restore that driver using a backup.

IMPORTANT:It is essential that you do not delete or rename the invalidated User Application driver, since doing so will also invalidate all the driver's associations. Additionally, if the Role and Resource Service driver is running, and you delete the User Application driver, the Role and Resource Service driver will detect the role deletions and remove the roles from the assigned users.

Additionally, it is not sufficient to redeploy the backed up driver to Identity Manager as the schema change cannot be reconciled in this manner. The following procedure performs the restoration by deploying a renamed copy of the driver in order to generate the data to be restored.

The following procedure outlines the process for restoring the User Application driver backup using Designer 4.0.1:

  1. Restart the eDirectory server to ensure that the schema modification has taken effect.

  2. Open a copy of the Designer 4.0.1 project containing the backup of the User Application driver, UserAppDriver. Since this procedure modifies the driver name so it is important to use a copy of the project.

  3. Select the connector between the User Application driver and the Identity Vault, right-click and choose Properties.

  4. Specify a new name such as UserAppDriver_restore. Select Apply and OK.

  5. Click Save to save the project.

  6. Synchronize the ID Vault schema by selecting the ID Vault and choosing Live->Schema->Compare and choose to Update Designer for the Reconcile Action.

  7. Save the project.

  8. the renamed driver by selecting the driver and choosing Driver->.

  9. Run NrfCaseUpdate and export the newly named driver to an LDIF file.

  10. Make a copy of the LDIF file for editing.

  11. Edit the LDIF file and rename all the driver references to reflect the User Application driver that you are restoring. For example, if your original User Application driver is cn=UserAppDriver then you would rename cn=UserAppDriver_restore to cn=UserAppDriver. This step effectively builds an LDIF file reflecting the real User Application driver.

  12. Import the modified LDIF file using ice:

    ice -l[mylogfile.log] -v -SLDIF -f[your_created_ldif] -c -DLDAP -s[hostname] -p[389/636] -d[cn=myadmin,o=mycompany] -w[MYPASSWORD] -F -B

  13. Note the status of the import using ice to ensure it was successful.

  14. Follow the instructions under Section 3.2.6, Verification of the NrfCaseUpdate Process to verify the restoration of the driver.

  15. Delete the renamed driver from the Driver Set.