Installation

The following chapter provides details about the Identity Governance installation.

Provided Files

The installer is provided in the identity-governance-winter-2021.zip archive. The top-level directory contains the following files and directories:

  • install.sh. Linux installer.

  • install.bat: Windows installer.

  • governance.groovy: Common installer, invoked by both Linux and Windows installers.

  • governance.properties: Properties file that can be used in place of interactive input with the installers.

  • legal-notices: Contains the Forgerock license agreement and any third party licensing agreements.

  • openidm: Files to be installed in the IDM home directory. These files include configuration files, scripts, workflows, CLI tools, user interface configuration and file fragments that will be injected into existing files.

  • integrations: Files and scripts used to make adjustments to out of the box ForgeRock IDM configuration files.

Installation Instructions

  1. Unzip the identity-governance-winter-2021.zip to a temporary directory then navigate to the directory that was unzipped.

  2. Run the following command to initiate the installer:

    For Windows:
    install.bat [--properties filename | -p filename]
    
    For Linux:
    ./install.sh [--properties filename | -p filename]

    The installer prints updates to the console until successful completion.

The command can be run with the following optional argument: * --properties or –p <location/of/properties/file>: Provides a properties file for script input. If no properties file is specified, the user must input the following properties at run time.

The following input is used for the installer: * openidm_location: File location of IDM home directory.

  • project_location: File location of IDM project directory, if used. This is an optional property that will default to the openidm_location if left blank.

  • identity_governance_installer_location: Location where the installer is being run from

  • openidm_version: The version of IDM. This will either be 6.5 or 7.0.

  • initial_install: If this is the first install in a cluster of installs

Names are those found in the properties file. If a properties file is not used, equivalent input will be gathered directly from the installer.
  1. After installation completes, the IDM server must be restarted.

Clustered Environment

Currently, the installer script can only be run once per environment. In a clustered environment, manual steps will need to be taken to copy over artifacts to subsequent nodes once the installer has run on the initial node. The following requires replication on each node after the first:

  1. Copy the following files from the installer zip into the IDM installation directory:

    1. Everything in the ./openidm/script directory, copied into the script directory of the installation.

    2. Everything in the ./openidm/conf directory, copied into the conf directory of the installation.

    3. Everything in the ./openidm/workflow directory, copied into the workflow directory of the installation.

    4. Everything in the ./openidm/tools directory, copied into the tools directory of the installation.

    5. The entire ./openidm/governance directory, copied into the openidm installation directory.

    6. The entire ./legal-notices directory, copied into the openidm installation directoryl

  2. Copy the following files from the first node’s IDM installation directory:

    • openidm/script/access.js

    • openidm/conf/managed.json

    • openidm/conf/policy.json

Post-Installation Instructions

The UI context for Identity Governance can be found by navigating to /governance from your IDM server URL.

Additional configuration is needed on each node as described below:

  • Administrator Roles. For a user to access the administrator functionality of Identity Governance, they must be assigned the intended internal authorization role (governance-administrator, access-request-admin, or glossary-admin) that was created during installation. Note that if you are assigning the role to the currently logged in user you must log out and back in again for the role to take effect, and internal users (e.g., openidm-admin) are not supported by Identity Governance}.

  • Enable Workflow. If planning to use the IDM workflow functionality for certification remediation or custom request flows, Identity Governance requires workflow to be enabled in the IDM administrator configuration. To do so, navigate to Configuration > System Preferences > Workflow and toggle the Enable setting.

  • Setting the membershipProperties configuration. Administrators have the ability to determine which default managed user property will be used to determine membership for group assigned approvals, either roles or authzRoles. If ‘roles’ is selected, users that are assigned a managed role to their Provisioning Roles attribute (‘roles’ in the schema) will be eligible to approve tasks assigned to that managed role. If ‘authzRoles’ is selected, users that are assigned a role to their Authorization Roles attribute (‘authzRoles’) will be eligible to approve tasks assigned to that role. In previous versions of Access Request this was always determined by the Authorization Roles property.

    To edit this configuration, open the file found at openidm/conf/commons.json and edit the membershipProperties array value. By default the configuration contains both ‘authzRoles’ and ‘roles’ as options; however, it is recommended that only one is chosen. Note that only those two properties are currently supported as options for determining group membership.

  • Event-Driven Certifications. In order to enable event based certifications for managed users or other managed objects, the following snippet of code (in JavaScript) must be added to the onUpdate hook for each individual object that you want to create certifications for:

    require('script/idg/onUpdateManagedObject.js').triggerCerts(oldObject,newObject, 'user');

    where ‘user’ should correspond to the managed object you are editing (e.g., ‘role’, ‘assignment’, etc.)

  • Reactive Policy Scans. In order to enable reactive policy scans on managed users, the following snippet of code (in JavaScript) must be added to the postUpdate hook for the managed user object:

    if(request.method.equals('update') || request.method.equals('patch'))
      openidm.action('governance/policyScan', 'reactive', { userId: object._id });
    After installation steps are complete, it is recommended that the installer ZIP and the created installation folders and files be removed from the server.

Installer Backups

As part of the installation process, backups of any IDM files that are changed or edited are created within the openidm/backup folder. The file names follow the pattern of <original file name>.pre-accessreview-install-<timestamp>`, and are located within the same subdirectories of the backup folder as they would be in the original openidm directory.

IDM/AM Integration for 7.0

If installing Identity Governance into an IDM environment that is configured to authenticate through Access Management, you must configure an OAuth client in AM for the Governance context.

To start, refer to section 2.4.2 of the ForgeRock Platform Setup Guide found at the following url: https://backstage.forgerock.com/docs/platform/7/platform-setup-guide/#proc-auth-clients

In step 5 of the section, instructions are given to configure a client for the end-user-ui. For Identity Governance, please repeat those steps with the following adjustments:

  • Client ID: identity-governance-ui

  • Core:

    • Redirect URIs: <IDM domain>/governance/appAuthHelperRedirect.html

  • Advanced:

    • Subject Type: Public

In the ForgeRock Platform admin interface, click on Applications and then Add Application. The data entered in this form should match the configurations included in the AM client.

Patching/Updating Process

If installing a patch update to the current installation the following steps are recommended to ensure proper installation of the update. For updating a major version of the product (e.g. 2.5 > 3.0), consult the release notes for any instructions on the upgrade process.

  1. Check the patch/update zip for a README file and confirm if there are any additional actions that need to be taken for the specific patch or update. Any steps found within this file should take precedence over the steps found below.

  2. Manually create a backup of the following directories with the openidm installation: /conf, /script/idg, /script/commons, /governance, and /workflow.

  3. Unzip the provided patch/update into the openidm directory

  4. Restart the IDM server.

In the event the update needs to be backed out and reverted, simply copy the backup directories back into the openidm directory to overwrite the new changes and restart the server once again.