2.1 Setting Up a Provisioning Project

The Provisioning view is only available for Designer projects that contain a User Application driver. After you set up an Identity Manager project and configure an Identity Vault and driver set for the project, you add and configure a User Application driver.

To use Designer to configure the Roles tab of the User Application, you must additionally add a Role Service driver to your project.

2.1.1 Adding a User Application Driver to the Project

To add the User Application driver to a project, the driver must be installed and deployed in your environment. For more information, see NetIQ Identity Manager Setup Guide for Linux or NetIQ Identity Manager Setup Guide for Windows.

  1. In an open Designer project, create a new driver by using one of these methods:

    • Click Provisioning in the Palette, then drag the User Application icon onto the modeler.

    • Right-click the driver set for your project, then select New > Driver.

    • Click the driver set for your project, then select Model > Driver > New.

  2. Select User Application Base from the list of driver base packages in the Driver Configuration Wizard, then click Next.

  3. Specify the properties you want to use for the driver:

    Driver Name

    Specifies the either the User Application driver created when you installed Identity Manager or a new User Application driver.

    Authentication ID

    Specifies the DN of the User Application Administrator.

    Application Password

    Specifies the password for the User Application Administrator.

    Host

    Specifies the name or IP address of the application server where you deployed the User Application.

    Identity Manager uses this information to perform the following actions:

    • Trigger workflows on the application server to connect to access workflows, such terminate and retract

    • Update cached data definitions

    Port

    Specifies the port for the host server.

    Application Context

    Specifies context of the User Application. For example, IDMProv.

    Allow Initiator Override

    Applies to workflows that start automatically

    Specifies whether you want to use an identity other than the User Application Administrator to start workflows. To use an alternate identity, select Yes.

    For more information, see the Identity Manager User Application: Administration Guide.

  4. Click Next, then Finish.

  5. (Optional) Deploy the email templates to support email notifications in your workflows.

    When you add a User Application driver, Identity Manager adds email templates to the Default Notification Collection. You must explicitly deploy the templates. They are not deployed by default when you deploy the driver. For more information about deploying the templates, see Setting Up E-Mail Notification Templates in the NetIQ Analyzer for Identity Manager Administration Guide.

2.1.2 Modifying the User Application Driver Properties

After creating the User Application driver, you can optionally modify some of the driver configuration settings described in Table 2-1.

To customize the driver configuration settings:

  1. In the Modeler, right-click the User Application driver and select Driver > Properties.

  2. Select Driver Configuration (in the left pane).

  3. Click the Driver Parameters tab.

  4. Click the Driver Options tab. You can modify the driver properties as desired. For more information, refer to the Table 2-1.

    Table 2-1 Additional Settings for Customizing the User Application Driver

    Field

    Description

    Enable oidpInstanceData attribute clean-up

    The driver will automatically remove the login entry from the logged-in user’s oidpInstanceData attribute when the attribute size exceeds 16 KB. By default, the value is set to true. This setting takes effect when the value specified in the Specify the token entry expiration time in hours reaches the threshold value.

    From Identity Manager 4.8.5 onward, the Enable oidpInstanceData attribute clean-up property also handles the DirXML-EntitlementResult attribute cleanup. After notifying the User Application driver, the entitlement result that caused an event is purged by default. However, if the entitlement results are not purged and continue to increase in number, the driver will delete them from the DirXML-EntitlementResult attribute when its value reaches 5000 or greater.

    Client ID

    Specifies the name that you want to use to identify the single sign-on client for Identity Applications to the authentication server. Out of the box, Client ID is rbpmrest.

    Client Password

    Specifies the password for the single sign-on client for the Identity Applications client. By default, the driver uses the password set by the administrator during install.

    OAuth Issuer URL

    Specifies the absolute URL to the authorization server that issues the access token.

    For example, https://<https://<hostname or IP address of the Identity Applications server>:<port>/osp/a/idm/auth/oauth2

    Specify the token entry expiration time in hours

    Specifies the number of hours after which the User Application driver can remove the login entry from the logged-in user’s oidpInstanceData attribute. By default, the value is set to 24 hours. This setting applies based on the following conditions:

    • When the size of the oidpInstanceData attribute size exceeds 16 KB.

    • When the value of the Enable oidpInstanceData attribute clean-up parameter is set to True.

  5. Click OK to save the changes.

2.1.3 Adding a Role Service Driver to the Project

  1. In the same project where you created a User Application driver, click Provisioning in the Palette, then drag and drop the Role Service icon onto the Modeler.

  2. Select Role and Resource Service Base from the list of driver base packages in the Driver Configuration Wizard, then click Next.

  3. Specify the name you want to use for the driver and click Next.

  4. Specify the properties you want to use for connecting the driver to the User Application. If you have already configured the User Application driver, the Driver Configuration Wizard should prepopulate the fields with the correct information, but we recommend you double-check the specified properties. Use the following information to configure the driver:

    Field

    Description

    User-Group base container DN

    Specify the DN of the root container that the Role Service driver services.

    User Application Driver DN

    Specify the DN of the User Application Driver object that hosts the role system. For example, system\driverset1\UserApplication.

    User Application URL

    Specify the URL used to connect to the User Application. The default URL is http://127.0.0.1:8180/IDMProv.

    User Application Identity

    Specify the DN of the User Application Administrator. For example, cn=admin,ou=sa,o=data.

    User Application Password

    Specify the Application Password you specified for the User Application driver.

  5. Click Next.

  6. Click Finish.

2.1.4 Modifying the Role Service Driver Properties

After creating the Role Service driver, you can optionally modify some of the driver configuration settings and modify the additional settings described in Table 2-2. To customize the additional settings:

  1. In the Modeler, right-click the Role Service driver and select Driver > Properties.

  2. Select Driver Configuration (in the left pane).

  3. Click the Driver Parameters tab.

  4. Click the Driver Options tab. You can modify the driver properties as desired. For more information, refer to the Table 2-2.

    Table 2-2 Additional Settings for Customizing the Role Service Driver

    Field

    Description

    Number of days before processing removed request objects

    The number of days the driver should wait before cleaning up request objects that have finished processing. This value determines how long you are able to track the status of requests that have been fulfilled.

    Frequency of reevaluation of dynamic and nested groups (in minutes)

    The number of minutes the driver should wait before reevaluating dynamic and nested groups. This value determines the timeliness of updates to dynamic and nested groups used by the User Application. In addition, this value can have an impact on performance. Therefore, before specifying a value for this option, you need to weigh the performance cost against the benefit of having up-to-date information in the User Application.

    Expiration Interval*

    Determines how often the driver evaluates the roles and resources for expiration. The default time interval is 60 minutes, the duration for which the driver waits before reevaluating the expiry of roles and resources.

    Enable Resynchronization of assigned static resources

    When set to true, the driver will synchronize the users and restore the entitlement values <ent-ref> and <ent-dn> for the static resources that are already assigned to the users.

    This setting has been added in Identity Manager 4.8.2 version.

    Update Entitlement param from resource form

    While requesting a resource, users can provide values for added form fields on a resource request form. However, these values are not mapped to the entitlement parameters on the driver when the Update Entitlement param from resource form is set to false. You can set the value as true if you want values from the added form fields on the resource request form to map to the entitlement.

    This setting has been added in Identity Manager 4.8.2 version.

    Generate audit events

    Determines whether audit events are generated by the driver.

    Disable Dynamic Group evaluation in a single MOT transaction

    When a role is assigned to a dynamic group, the driver performs the dynamic group evaluation on a single thread. The driver uses Multi Object Transaction (MOT) to update multiple attributes of the user and group entities that are part of a dynamic group. This is the default behavior. To enable parallel processing of multiple threads at the same time, set the value of this property to true.

    This setting has been added in Identity Manager 4.8.5 version.

    Enable Parallelization of resource requests on role assignment

    When set to true, the driver uses multiple threads to process the resource requests in parallel. This setting is specifically applicable to role assignments for groups, where resources mapped to the role can be simultaneously processed and assigned to the users within the group. By default, the value is set to false.

    Enable parallelization of role recalculation for user entities when an inherited role is added or removed from the parent role

    Whenever a child role is added to or removed from the parent role, the driver recalculates the role assignment for all the user entities. This driver setting is set to false by default. If you want to enable parallel processing of multiple threads at one time, set the value to true.

    This setting has been added in Identity Manager 4.8.3 version.

    Enable multi-threaded Role and Resource driver

    Sets the Role and Resource Service driver for multi-threaded services to achieve parallel processing of requests. The value is set to true by default.

    Allow driver to start if reading unprocessed events fails

    This setting allows you to specify whether the driver should start or stop when it encounters an exception while reading unprocessed requests. By default, the value is set to false, which prevents the driver from reading the unprocessed requests. If you set it to true, the driver will restart and process the unprocessed request again.

    Maximum number of command’s allowed in the driver storage

    Specify the number of requests that the driver storage can accommodate. The default value is 500 requests. It is recommended to use a value less than the default value to avoid any memory issues.

    Store resource history for days

    The number of days that the driver stores the resource history information before cleaning up the data from the storage.

    * The Expiration Interval parameter label is changed to Specify the time interval (in minutes) at which the role and resource expiry is evaluated in Identity Manager 4.8.3 version.

  5. Click OK to save the changes.

2.1.5 About Email Notification Templates

Identity Manager includes a standard set of email notification templates.

When you create a User Application driver, any email notification templates that are missing from the standard set are replaced. However, existing email notification templates, which might come from an earlier version of Identity Manager, are not updated. To replace existing templates with new templates:

  1. Expand the Outline view.

  2. In the Default Notification Collection, delete the email notification templates that you want to replace.

  3. Right-click Default Notification Collection and select Add Default Templates or Add All Templates.

    You can also use this command at any time to update email notification templates without creating a new User Application driver.

  4. To deploy the email notification templates to the Identity Vault, right-click Default Notification Collection and select Live > Deploy.

2.1.6 Email Based Approval

You can allow request reviewers to approve or deny a request using e-mail. The e-mail notification can include links that can be used for approving or rejecting requests to help you easily respond to the request without logging in to the identity applications.

IMPORTANT:If request reviewer forwards the mail to another user, action links for approval or rejection action do not work.

A request reviewer can respond to the notification email in the following two ways:

  • When the request reviewer clicks Approve or Deny link in the e-mail, the identity applications composes a new email with the required subject and content. The request reviewer can enter comments in the e-mail send it after adding the comments.

  • Before replying to a notification, a request reviewer can modify the subject line of the e-mail. However, ensure that the keyword (Approve or Deny) along with the alpha-numeric unique code is not changed.

    IMPORTANT:To reply to the notification e-mail, set the ‘from’ address of the request reviewer mail server as same as the incoming mail server.

Checklist to Setup Email Based Approval

Before setting up the Email Based Approval, review the following checklist:

Checklist Items

  1. Ensure that the outgoing mail server is configured using Configuration Update Utility or iManager and verify whether outgoing mail is working. To configure the outgoing mail server using Configuration Update Utility, see User Application Parameters in the NetIQ Identity Manager Setup Guide for Linux or User Application Parameters in the NetIQ Identity Manager Setup Guide for Windows. If you are using iManager, see E-Mail Notification in the NetIQ iManager Administration Guide.

  1. Install Email Based Approval package in Designer. For more information, see Installing Email Based Approval Package.

  1. Choose the Email Based Approval Templates for workflows. For more information, see Using Email Based Approval Templates for Workflow.

  1. For receiving emails, set up an account on an email server that supports POP3 or IMAP protocol. If you are using a POP3 type of server, the received emails are not marked as ‘read’ in the incoming mailbox. For more information, see Help in the Identity Manager Dashboard.

  1. Enable Email Based Approval and configure incoming Mail server properties from the User Application, see Enabling Email Approval and Configuring Incoming Mail Server Properties from User Application.

  1. (Conditional) To enable Email Based Approval on Cluster Environment, see Enabling Email Based Approval on Cluster Environment.

Installing Email Based Approval Package

In Designer, open the project where you want to install Email Based Approval package and perform the following steps:

  1. Right-click on the Identity Manager engine and select Properties > Packages.

  2. Click icon to add new package and select Email Based Approval Templates package.

  3. Install the package and click OK.

  4. Expand Default Notification Collection and select all the Email Based Approval templates.

  5. Deploy the selected templates on to your Identity Vault.

Using Email Based Approval Templates for Workflow

In Designer, select the required Email Based Approval templates to deploy the workflow:

  1. Create a PRD workflow, select the Notify participants by E-mail check box.

  2. Right-click on the Approver icon, and select Show E-mail Notification.

  3. Select one of the following e-mail options as:

    • Notify,

    • Reminder

    • Escalation Reminder

  4. From E-mail Template drop-down list, select Email Based Approval Provisioning Notification template.

  5. Repeat Step 1 through Step 4 for the workflows that requires approval.

    NOTE:Email Based Approval allows request reviewers to process the requests which is not associated with complex forms.

  6. Add the source ECMA script for the required field based on the selected template.

  7. After creating a PRD, deploy the workflow.

Enabling Email Approval and Configuring Incoming Mail Server Properties from User Application

To allow users to approve or reject requests from an email:

  1. Log in to the Identity Manager Dashboard.

  2. Select Administration > Email-based approval.

For more information, see the Help in the Dashboard.

Enabling Email Based Approval on Cluster Environment

Ensure that the outgoing mail server is configured on each nodes of the cluster, you can configure this mail server using Configuration update Utility. For more information, see Email Server Configuration in the NetIQ Identity Manager Setup Guide for Linux or Email Server Configuration in the NetIQ Identity Manager Setup Guide for Windows.

On cluster environment, you must specify the IP address of the ActiveMQ server in server.xml file of the other nodes in the cluster, which is set to localhost by default. Look for the brokerURL attribute for the AcitveMQ server in the server.xml and replace the localhost with the ActiveMQ server IP address.

If you enable or disable the Email Based Approval (Off/On) or change the incoming mailbox properties, then restart all the cluster nodes for the change to take effect. You must also verify the connection between the mailbox host and other servers.

Adding Dashboard URL to the config.ini File

(Optional) Applies only when you use Identity Manager 4.8.3 or later versions.

When the request reviewer opens an approval form through the e-mail link and acts on the request, the approval form does not close by default after the form is submitted. To redirect the reviewer to the Dashboard page upon submitting the approval form, perform the following steps:

  1. Navigate to the config.ini file on the identity applications server.

    Linux: /opt/netiq/idm/apps/sites

    Windows: C:\netiq\idm\apps\sites\

  2. Edit the config.ini file to add the Identity Manager Dashboard page URL.

    IDMDashboardURL=https://<server_IP>:<port>/idmdash

  3. Restart the NGINX service.

    systemctl restart netiq-nginx.service

Troubleshooting Tips

This section helps you to troubleshoot the general issues while configuring Email Based Approval.

  • In provisioning request e-mail, if recipient’s mail address, or Approval or Deny Tokens are missing, enable the Email Based Approval option.

  • If a request reviewer cannot find the Approve or Deny link in the e-mail, review the Email Based Approval settings.

  • If a request reviewer cannot compose an e-mail after clicking the Approve or Deny link, verify whether the default e-mail client is configured. (For example: Microsoft Outlook)

You can verify the Email Based Approval settings using the catalina.out events logs.

For example, if you want to verify the status of Email Based Approval, look for the following entries in the catalina.out property file:

INFO  com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Email based approval feature is turned on. Starting the incoming mailbox service soon..
INFO  com.novell.soa.notification.impl.jms.JMSConnectionMediator- [RBPM] Starting JMS notification system
INFO  com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Successfully started persistent JMS notification system for email based approval
INFO  com.novell.soa.notification.impl.EmailReceiverThread- [RBPM] Starting asynchronous notification system
INFO  com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Mailbox service for incoming mail started successfully without any warning
INFO  com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Email based approval token cleanup service started successfully.

2.1.7 Preparing Drivers to Use CPRS

NOTE:This section is applicable only for Identity Applications 4.7.1.

Controlled Permission Reconciliation Services (CPRS) currently supports Active Directory, Multi-Domain Active Directory (MDAD), LDAP, Loopback, Delimited, and REST drivers.

Deploying Custom Entitlement Package for Identity Application Catalog

Perform the following tasks to make custom entitlement available for Identity Applications using Designer:

  1. Install custom entitlement package which by default installs cprs common package.

  2. Create an entitlement (DirXML-Entitlement) object for the driver. For example: Cubicle

    For more information, see Creating Entitlements through the Entitlement Wizard in theNetIQ Designer for Identity Manager Administration Guide.

  3. To make the new entitlement available for Identity Applications Resources perform the following tasks:

    NOTE:To access Identity Applications Resource Catalog, navigate to Administration > Resources in Identity Manager Dashboard. For more information, see Listing Resources in NetIQ Identity Manager - Administrator’s Guide to the Identity Applications.

    1. Right-click on the specific driver and click Properties. Navigate to GCVs > Custom Entitlements tab.

    2. In List of Custom Entitlements, add the entitlement object names that needs to be listed in the Identity Applications user interface.

      NOTE:

      • These entries are case sensitive.

      • CPRS supports only the Identity Manager 4.0 and later entitlement format.For more information, see Entitlements Formats in NetIQ Identity Manager Entitlements Guide.

      • By default, the cprs-supported, role-mapping, and resource-mapping flags are set to True and the data-collection flag is set to False.

    3. (Conditional) If you wish to configure the flags, create a boolean GCV in the following format:

      drv.cprssupported.<entitlement-name>, drv.datacollection.<entitlement-name>, drv.rolemapping.<entitlement-name>, drv.resourcemapping.<entitlement-name> respectively.

    4. To include an additional XML to an entitlement:

      1. Specify the Name as drv.entitlement.extensions.<entitlement-name>.

      2. Select the Type as String.

      3. Select the Multi-line option.

      You should add the additional entitlement extensions between <entitlement-extensions></entitlement-extensions> XML node. For more information, see Modifying Entitlement Extension.

    5. (Conditional) For localization of entitlement, add the localization values for the entitlement in the L10N_<locale> mapping tables.

  4. Deploy and start the driver for the changes to take effect.

Modifying Entitlement Extension

If Identity Manager is of Style4 entitlement, then you need to define the parameter tag.

Ensure that the entitlement extension XML contains the following information:

  • Parameter node for building codemap values.

    The <parameters> node defines the list of parameters.For more information, see DTD.

  • (Conditional) If the entitlement is dealing with accounts, then the <account> node provides information about the account status (such as status, attribute name, active and inactive values). For more information, see DTD.

  • (Conditional) If you want to run a different query to fetch permission from the connected application, then provide the specific query in the <member-assignment-query> node. This node is applicable only for <entitlement> type account. For more information, see DTD.

  • (Conditional) In case of multi-valued entitlement, if the permission information needs to be retrieved from a specific attribute of the connected application, then provide the specific information in the <member-assignment-extension> node. Member assignment information are available on both account and group entitlements, however they are retrieved differently. For more information, see DTD.

The following is a sample of entitlement extension XML for two different entitlements:

Example 1:

To manage custom entitlement in the connected application such as Cubicle, where the permission value is stored in the AssignedTo attribute.

<entitlement-extensions>
  <parameters>
      <parameter mandatory="true" name="ID" source="association" />
            <parameter mandatory="true" name="ID2" source="association" />
  </parameters>
      <native-value source="src-dn" />
  <member-assignment-extensions>
            <query-xml>
        <read-attr attr-name="AssignedTo" />
            </query-xml>
  </member-assignment-extensions>
  </entitlement-extensions>

Example 2:

This example shows how account node and member-assignment-query node needs to be defined.

<entitlement-extensions>
      <account>
      <account-id source="src-dn" />
            <account-status active="FALSE" inactive="TRUE" source="read-attr" source-name="Account_STATUS" />
      </account>
  <parameters>
           <parameter mandatory="true" name="ID" source="read-attr" source-name="RESTACCOUNT" />
      </parameters>
  <member-assignment-query>
           <query-xml>
        <nds dtdversion="2.0">
                     <input>
             <query class-name="User" scope="subtree">
                              <search-class class-name="USer" />
             </query>
                     </input>
        </nds>
            </query-xml>
  </member-assignment-query>
  </entitlement-extensions>