20.2 Installation Procedure

This section provides step-by-step instructions of installing a new instance of the identity applications on Tomcat and then configuring it for clustering.

  1. Install the Identity Manager engine. For step-by-step instructions, see Installation Procedures. For a production-level deployment, it is recommended to install Identity Manager engine on a separate server.

  2. Create and deploy the following drivers for the Identity Applications:

    • User Application driver

    • Roles and Resource Service driver

  3. On Node1, install the following Identity Manager components:

    1. User Application

      During the installation process, configure the following settings:

      1. Select Tomcat as the application server.

      2. Select PostgreSQL as the database platform.

        NOTE:You can use any of the Identity Manager 4.8 supported databases.

      3. Provide the required database details in the subsequent pages.

      4. Copy the database driver jar file postgresql-9.4.1212.jar from the PostgreSQL server to all the User application nodes in the cluster.

        NOTE:If you are using other Identity Manager 4.8 supported databases, such as Oracle or SQL Server, ensure that you copy the respective driver jar files from the server where the database is installed to all the User Application nodes in the cluster. For more information, see Configuring the Database for the Identity Applications.

      5. Browse and select the copied database driver jar file.

      6. In the New Database or Existing Database details page, select the New Database option.

      7. In the Identity Manager Configuration page, provide a unique name in the Workflow Engine ID field. For example, you can use the unique name as Engine1 for Node1.

      8. To create a new master key, select No in the Security – Master Key page.

        The identity applications encrypt sensitive data using a master key. As this is the first instance of the identity applications in a cluster; therefore, you must instruct the installation program to create a new master key by selecting No. In a cluster, the User Application clustering requires every instance of the User Application to use the same master key. To ensure that the same master key is used, import the existing key by selecting Yes while configuring these instances.

  4. On Node2, perform the following actions:

    1. Install Tomcat by using the convenience installer (select only Tomcat during the installation process).

    2. Install OSP.

      During the installation process, provide the IP address and port number of the Identity Manager engine (eDirectory) server in the Authentication details page.

    3. Install the User Application.

      During the installation process, configure the following settings:

      1. Select Tomcat as the application server.

      2. Select PostgreSQL as the database platform.

        NOTE:You can use any of the Identity Manager 4.8 supported databases.

      3. Provide the required database details in the subsequent pages of the installation procedure.

      4. Copy the database driver jar file postgresql-9.4.1212.jar from the PostgreSQL server to Node2.

        NOTE:If you are using any other Identity Manager 4.8 supported databases, such as Oracle or SQL Server, ensure that you copy the respective driver jar files from the server where the database is installed to all the User application nodes in the cluster.

      5. Browse and select the copied database driver jar file.

      6. In the New Database or Existing Database details page, select the Existing Database option.

      7. In the Identity Manager Configuration page, provide a unique name in the Workflow Engine ID field. For example, you can use the unique name as Engine2 for Node2.

      8. To create a new Master key in the Security – Master Key page, select Yes.

        The User Application clustering requires every instance of the User Application to use the same master key. To ensure that the same master key is used, import the existing key by selecting Yes. This key is created when you installed the first instance of the User Application in Node1.

        You can obtain the master key from the ism-configuration properties file located in C:\NetIQ\IDM\apps\tomcat\conf on Node1. The parameter that contains the master key is com.novell.idm.masterkey.

      9. Click Install to complete the installation.

    NOTE:For detailed information about installing the Identity Applications, see Installation Procedures.

  5. In load balancer server, start an instance of load balancer with Identity Applications port number and another instance of load balancer with form renderer port number for all clustered nodes. For example,

    • ./balance 8543 apps1-au.edu.in:8543 ! apps2-au.edu.in:8543

    • ./balance 8600 apps1-au.edu.in:8600 ! apps2-au.edu.in:8600

  6. Install SSPR on a separate computer.

    Before installing, make a note of the following settings and specify them during installation process:

    1. Install Tomcat. For installation instructions, see Step 4a.

    2. Install SSPR.

      During the SSPR installation, perform the following actions:

      1. In the Application Server connection page, select Connect to external authentication server and provide the DNS name of the server where the load balancer is installed.

      2. In the Authentication details page, provide the IP address and the port of the Identity Manager engine server. The password for the CA certificates is changeit.

    3. After completing the SSPR installation, launch SSPR (https://<IP>:<port>/sspr/private/config/ConfigEditor) and log in. Click Configuration Editor > Settings > Security > Redirect Whitelist.

      1. Click Add value and specify the following URL:

        https:<dns of the failover><port>/osp

      2. Save the changes.

      3. In the SSPR Configuration page, click Settings > OAuth SSO and modify the OSP links by replacing the IP addresses with the DNS name of the server where the load balancer software is installed.

      4. Click Settings > Application and update the forward and logout URLs by replacing the IP addresses with the DNS name of the server where the load balancer software is installed.

    4. To update the SSPR information on Node1, launch the Configuration utility located at C:\NetIQ\idm\apps\UserApplication\configupdate.bat.

      In the window that opens, click SSO clients > Self Service Password Reset and enter values for Client ID, Password, and OSP Auth redirect URL parameters.

    NOTE:Verify that the values for these parameters are updated in Node2.

  7. Perform the following configuration tasks on the cluster nodes:

    1. Restart Tomcat on all the cluster nodes.

    2. To change the Change my password link, see Updating SSPR Links in the Dashboard for a Distributed or Clustered Environment.

    3. Verify that the Forgot Password link and Change my password links are updated with the SSPR IP address on Node2.

      NOTE:If the Change Password and Forgot Password links are already updated with the SSPR IP address, no changes are required.

  8. In Node1, stop Tomcat and generate a new osp.jks file by specifying the DNS name of the load balancer server by using the following command:

    C:\NetIQ\Common\JRE\bin\keytool -genkey -keyalg RSA -keysize 2048 -keystore osp.jks -storepass <password> -keypass <password> -alias osp -validity 1800 -dname "cn=<loadbalancer IP/DNS>"

    For example: C:\NetIQ\idm\apps\jre\bin\ -genkey -keyalg RSA -keysize 2048 -keystore osp.jks -storepass changeit -keypass changeit -alias osp -validity 1800 -dname "cn=mydnsname"

    NOTE:Ensure that the key password is the same as the one provided during OSP installation. Alternatively, this can also be changed using Configuration Update utility including the keystore password.

  9. (Conditional) To verify if the osp.jks file is updated with the changes, run the following command:

    C:\NetIQ\Common\JRE\bin\keytool -list -v -keystore osp.jks -storepass changeit

  10. Take backup of the original osp.jks file located at C:\NetIQ\idm\apps\osp\ and copy the new osp.jks file to this location. The new osp.jks file was created in Step 8.

  11. Copy the new osp.jks file located at from Node1 to other User Application nodes in the cluster.

  12. On each clustered node,

    1. Navigate to the C:\netiq\idm\apps\sites directory and edit the ServiceRegistry.json file to add the load balancer details.

      {"serviceRegisteries":[{"serviceID":"IDM","restUrl":"https://<DNS of the load balancer>:8543/IDMProv"}]} 
    2. Navigate to the C:\netiq\idm\apps\sites\ directory and edit the config.ini file to add the load balancer DNS and port number.

      OSPIssuerUrl=https://<DNS of the load balancer>:8543/osp/a/idm/auth/oauth2
      OSPRedirectUrl=https://<DNS of the load balancer>:8600/forms/oauth.html
      ClientID=forms
      OSPLogoutUrl=https://<DNS of the load balancer>:8543/osp/a/idm/auth/app/logout
  13. Launch the Configuration utility in Node1 and change all of the URL settings, such as URL link to landing page and OAuth redirect URL to the load balancer DNS name under the SSO Client tab.

    1. Save the changes in the Configuration utility. Check the ism-configuration properties file for the changes and modify if any URLs are still pointing to Node 1 DNS and port.

    2. To reflect this change in all other nodes of the cluster, copy the ism-configuration properties file located in C:\NetIQ\IDM\apps\tomcat\conf from Node1 to other User Application nodes in the cluster.

      NOTE:You copied the ism.properties file from Node1 to the other nodes in the cluster. If you specified custom installation paths during the User Application installation, ensure that referential paths are corrected by using Configuration update utility in the cluster nodes.

      In this scenario, both OSP and User Application are installed on the same server; therefore, the same DNS name is used for redirect URLs.

      If OSP and User Application are installed on separate servers, change the OSP URLs to a different DNS name pointing to the load balancer. Do this for all the servers where OSP is installed. Doing this ensures that all OSP requests are dispatched through load balancer to the OSP cluster DNS name. This involves having a separate cluster for OSP nodes.

  14. Perform the following actions in the setevn.sh file located at /TOMCAT_INSTALLED_HOME/bin/ directory:

    1. To ensure that the mcast_addr binding is successful, JGroups requires that the preferIPv4Stack property be set to true. To do so, add the JVM property “-Djava.net.preferIPv4Stack=true” in the setenv.sh file in all nodes.

    2. Add “-Dcom.novell.afw.wf.Engine-id=Engine1” in the setenv.sh file on Node1. Similarly, add a unique engine name for each node of the cluster. For example, for Node2, you can add the engine name as Engine2.

  15. Enable clustering in the User Application.

    1. Start Tomcat on Node1.

      Do not start any other servers.

    2. Log in to the User Application as a User Application administrator.

    3. Click the Configuration > Caching and Cluster option.

      The User Application displays the Caching Management page.

    4. Click Cluster Cache Configuration and select True for the Cluster Enabled property.

    5. Click Save.

    6. Restart Tomcat.

    NOTE:If you have selected Enable Local settings, repeat this procedure for each server in the cluster.

    The User Application cluster uses JGroups for cache synchronization across nodes using default UDP. In case you want to change this protocol to use TCP, see Configuring User Application to use TCP.

  16. Enable the permission index for clustering. For more information see Enabling the Permission Index for Clustering.

  17. Enable Tomcat cluster.

    Open the Tomcat server.xml file from /TOMCAT_INSTALLED_HOME/conf/ and uncomment this line in this file on all the cluster nodes:

    <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>

    For advanced Tomcat clustering configuration, follow the steps from the Apache documentation website.

  18. Restart Tomcat on all the nodes.

  19. Configure the User Application Driver for clustering.

    In a clustered environment, you can use a single User Application driver with multiple instances of the User Application. The driver stores various kinds of information (such as workflow configuration and cluster information) that is application-specific. You must configure the driver to use the host name or IP address of the dispatcher or load balancer for the cluster.

    1. Log in to the instance of iManager that manages your Identity Vault.

    2. In the navigation frame, select Identity Manager.

    3. Select Identity Manager Overview.

    4. Use the search page to display the Identity Manager Overview for the driver set that contains your User Application driver.

    5. Click the round status indicator in the upper right corner of the driver icon:

    6. Select Edit Properties.

    7. For Driver Parameters, change Host to the host name or IP address of the Load Balancer.

    8. Click OK.

    9. Restart the driver.

  20. To change the URL of Roles and Resource Service Driver, repeat steps from 19a to 19f and click Driver Configuration and update the User application URL with the load balancer DNS name.

  21. Ensure session stickiness is enabled for the cluster created in the load balancer software for the User Application nodes.

Most loadbalancers provide a healthcheck feature for determining whether an HTTP server is up and listening. The User Application contains a URL that can be used for configuring HTTP healthchecks on your loadbalancer. The URL is:

http://<NodeIP>:port/IDMProv/jsps/healthcheck.jsp