21.1 Portal Configuration Tasks

NOTE:The portal functionality within the User Application has been deprecated in Identity Manager 4.0.2.

21.1.1 Caching Management

You can use the Caching page to manage various caches maintained by the Identity Manager User Application. The User Application employs these caches to store reusable, temporary data on the application server so it can optimize performance.

You have the ability to control these caches when necessary by flushing their contents and changing their configuration settings.

Flushing caches

The caches are named according to the subsystems that use them in the Identity Manager User Application. Normally, you don’t need to flush them yourself, because the User Application does that automatically based on how frequently their data is used or when the source data changes. However, if you have a specific need, you can manually flush selected caches or all caches.

  1. Go to the Caching page.

  2. In the Flush Cache section of the page, use the drop-down list to select a particular cache to flush (or select Flush all).

    The list of available caches is dynamic; it changes depending on what data is cached at the moment.

  3. Click Flush Cache.

Flushing the Directory Abstraction Layer Cache

The User Application’s directory abstraction layer also has a cache. The DirectoryAbstractLayerDefinitions cache stores abstraction layer definitions on the application server to optimize performance for all data model operations.

In a typical situation, the User Application automatically keeps the DirectoryAbstractLayerDefinitions cache synchronized with the abstraction layer definitions stored in the Identity Vault. But, if necessary, you can manually flush the DirectoryAbstractLayerDefinitions cache as described in Flushing caches to force the latest definitions to be loaded from the Identity Vault.

For more information on the User Application’s directory abstraction layer, see the Identity Manager User Application: Design Guide.

Flushing Caches in a Cluster

Cache flushing is supported in both clustered and non-clustered application server environments. If your application server is part of a cluster and you manually flush a cache, that cache is automatically flushed on every server in the cluster.

Configuring Cache Settings

You can use the Caching page to display and change cache configuration settings for a clustered or non-clustered application server environment. Your changes are saved immediately, but they don’t take effect until the next User Application restart.

HINT:To restart the User Application, you can reboot the application server; redeploy the application (if the WAR has been changed in some way); or force the application to restart (as described in your application server’s documentation).

How Caching Is Implemented

In the Identity Manager User Application, caching is implemented via JBoss Cache. JBoss Cache is an open source caching architecture that’s included with the JBoss Application Server but also runs on other application servers.

How Cache Settings Are Stored

Two levels of settings are available for controlling cache configuration: global and local. Use these settings to customize the caching behavior of the Identity Manager User Application. Table 21-1 describes the cache configuration settings.

Table 21-1 Cache Configuration Settings

Level

Description

Global settings

Global settings are stored in a central location (the Identity Vault) so that multiple application servers can use the same setting values. For example, someone with a cluster of application servers would typically use global settings for the cluster configuration values.

To find the global settings in your Identity Vault, look for the following object under your User Application driver:

configuration.AppDefs.AppConfig

For example:

configuration.AppDefs.AppConfig.MyUserApplicationDriver.MyDriverSet.MyOrg

The XmlData attribute of the configuration object contains the global settings data.

Local setting

Local settings are stored separately on each application server so that an individual server can override the value of one or more global settings. For example, you might want to specify a local setting to remove an application server from the cluster specified in the global settings, or to reassign a server to a different cluster.

For example: tomcat/server/IDMProv/conf/sys-configuration-xmldata.xml.

If your server has local settings, that data is contained in this file. If no local settings have been specified, the file won’t exist.

You should think of global settings as the default values for every application server that uses a particular instance of the User Application driver. When you change a global setting, you are affecting each of those servers (at the next restart of the identity applications), except for those cases where an individual server specifies a local override.

How Cache Settings Are Displayed

The Caching page displays the current cache settings (from the latest User Application restart). It also displays the corresponding global and local values of those settings, and lets you change them (for use at the next User Application restart).

The global settings always have values. The local settings are optional.

Basic Cache Settings

These cache settings apply to both clustered and non-clustered application servers.

To configure basic cache settings:

  1. Go to the Caching page.

  2. In the Cache Configuration section of the page, specify global or local values for the following settings, as appropriate:

    Setting

    What to do

    Lock Acquisition Timeout

    Specify the time interval (in milliseconds) that the cache waits for a lock to be acquired on an object. You might want to increase this setting if the User Application gets a lot of lock timeout exceptions in the application log. The default is 15000 ms.

    Wake Up Interval Seconds

    Specify the time interval (in seconds) that the cache eviction policy waits before waking up to do the following:

    • Process the evicted node events

    • Clean up the size limit and age-out nodes

    Eviction Policy Class

    Specify the classname for the cache eviction policy that you want to use. The default is the LRU eviction policy that JBoss Cache provides:

    org.jboss.cache.eviction.LRUPolicy

    If appropriate, you can change this to another eviction policy that JBoss Cache supports.

    Max Nodes

    Specify the maximum number of nodes allowed in the cache. For no limit, specify:

    0

    You can customize this setting for some cache holders. See Customizable Cache Holders.

    Time To Live Seconds

    Specify the time to idle (in seconds) before the node is swept away. For no limit, specify:

    0

    You can customize this setting for some cache holders. See Customizable Cache Holders.

    Max Age

    Specifies the number of seconds an entry should be allowed to stay in the cache holder since its creation time. For no time limit, specify:

    0

    This setting is only available for Customizable Cache Holders.

    These settings are required, which means that there must be a global value for each, and optionally a local value too.

    If you want to override the global value of a setting with a local value, select Enable Local for that setting. Then specify the local value. (Make sure that all of your local values are valid. Otherwise, you won’t be able to save your changes.)

    NOTE:For those settings where Enable Local is deselected, any existing local values are deleted when you save.

  3. Click Save.

  4. When you’re ready for your saved settings to take effect, restart the User Application on the applicable application servers.

Customizable Cache Holders

You can customize the Max Nodes, Time To Live, and Max Age settings for some cache holders. The cache holders are listed in Table 21-2.

NOTE:You must restart the Tomcat on each node of the cluster for the changes to take effect.

Table 21-2 Customizable Cache Holders

Cache Holder Name

Description

DirectoryAbstractionLayerDefinitions

Caches the Directory Abstraction Layer definitions to optimize performance for all data model operations. See Flushing the Directory Abstraction Layer Cache.

DirectoryService.ContainerCacheHolder

Caches containers in the directory layer. Containers are shared by many users and groups, and reading them from the directory layer involves both network communication (with the LDAP server) and object creation. By default, the cache is limited to 50 containers, and the LRUs have a default Time To Live (TTL) of 10 minutes. Depending on the directory topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for container objects. Making settings too high in combination with a large number of usable containers can cause unneeded memory consumption and net lower performance from the server.

DirectoryService.DelProxyRuntimeServiceDelegate

Caches delegate assignments.

DirectoryService.DelProxyRuntimeService.Delegation

Caches user availability settings.

DirectoryService.DelProxyRuntimeService.Delegator

Caches the delegator entities.

DirectoryService.DelProxyRuntimeService.Proxy

Caches proxy assignments.

DirectoryService.GroupCacheHolder

Caches groups in the directory layer. Groups are often shared by many users, and reading them from the directory layer involves both network communication (with LDAP server) and object creation. By default, the cache is limited to 500 groups, and the LRUs have a default TTL of 10 minutes. Depending on the user/group topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for groups objects. Settings that are too high, in combination with a large number of usable groups, can cause unneeded memory consumption, and net lower performance from the server.

DirectoryService.MemberhipCacheHolder

Caches the relationship between a user and a set of groups. Querying the set of groups a user belongs to can be a network and CPU intensive operation on the LDAP server, especially if dynamic groups are enabled. For this reason, relationships are cached with an expiration interval so that changes in the criteria for inclusion/exclusion in a group (such as time-based dynamic groups) are reflected. The default Max Age is five minutes. However, if you use dynamic groups which have a requirement for finer grained time control, then you can adjust the Max Age on this cache holder to be just below the minimum time your finest grained time based dynamic group requires. The lower this value is, the more times the user's groups are queried during a session. Setting a value too high keeps the user/group relationships in memory perhaps longer than the user's session needlessly consuming memory.

DirectoryService.RolesMembershipCacheHolder

Caches the application role membership list by role.

DirectoryService.TeamManagerRuntime.Team

Caches the application team instances and team provisioning requests.

DirectoryService.UserCacheHolder

Caches users in the directory layer. Reading users from the directory layer involves both network communication (with LDAP server) and object creation. By default, the cache is limited to 1000 users, and the LRUs have a default TTL of 10 minutes. Depending on the user topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for user objects. Making settings too high combined with a large number of different users logging in can cause unneeded memory consumption, and net lower performance from the server.

GlobalCacheHolder

The general purpose cache holder. This configuration applies to all caches that are not customizable (that is, all cache holders not listed in this table.)

JUICE

Caches the resource bundles used by the user interface controls and DN display expression lookup results. Changing the setting of the cache holder has a performance impact for the DN display expression lookups because they are frequently used in the User Application. The low value should be at least 300 seconds, but a higher value than 900 seconds is ok. A lower value should be used if the customer is frequently changing the attributes that are used in the DN display expression

RoleManager.RolesCacheHolder

Caches user role memberships listed by user.

Workflow.Model.Process

Caches the provisioning process XML object structure.

Workflow.Model.Request

Caches the provisioning request XML object structure.

Workflow.Provisioning

Caches provisioning request instances that have not completed. The default maximum capacity for the LRU cache is 500. The capacity can be modified by clicking the Administration/Provisioning and choosing the Engine and Cluster settings. The Process Cache Maximum Capacity appears on this page. This cache reduces the memory footprint for workflow processing without compromising performance.

Cache Settings for Clusters

This section discusses how to configure caching when you run the Identity Manager User Application across a cluster of application servers.

In the Identity Manager User Application, cluster support for caching is implemented via JGroups. JGroups is an open-source clustering architecture that’s included with the JBoss Application Server but also runs on other application servers.

The User Application’s cluster consists of nodes on a network that run JGroups and use a common Group ID. By default, the Group ID provided for the User Application’s cluster is a UUID that looks like this:

c373e901aba5e8ee9966444553544200

The UUID helps ensure uniqueness, so that the Group ID of the User Application’s cluster doesn’t conflict with the Group IDs of other clusters in your environment. For instance, the JBoss Application Server itself uses several JGroups clusters and reserves associated names including the Group IDs DefaultPartition and Tomcat-Cluster for them.

How Caching Works with a Cluster

When you start the User Application, the application’s cluster configuration settings on the Caching page determine whether to participate in a cluster and invalidates cache changes in the other nodes in that cluster. If clustering is enabled, the User Application accomplishes this by sending cache entry invalidation messages to each node as changes occur.

In most cases, you should use global settings when configuring a cluster. However, global settings might be a problem if you need to use TCP, becasue the IP address of the server must be specified in the JGroups initialization string for each server. You can use local settings to specify a JGroups initialization string. For more information, see Configuring Cache Settings for Clusters.

Preparing to Use a Cluster

To use caching across a cluster:

  1. Set up your JGroups cluster. This involves using the User Application installation program to install the Identity Manager User Application to each application server in the cluster (see High Availability Design).

  2. Enable the use of that cluster in the User Application’s cache configuration settings

    See Configuring Cache Settings for Clusters.

Configuring Cache Settings for Clusters

After you have a cluster ready to use, you can specify settings for the support of caching across that cluster.

  1. Go to the Caching page.

  2. In the Cluster Configuration section of the page, specify global or local values for the following settings, as appropriate:

    Setting

    What to do

    Cluster Enabled

    Select True to invalidate cache changes to the other nodes in the cluster specified by Group ID. If you don’t want to participate in a cluster, select False.

    Group ID

    Specify the Group ID of the JGroups cluster in which you want to participate. There’s no need to change the default Group ID that’s provided for the User Application’s cluster, unless you want to use a different cluster.

    The Group ID must be unique and must not match any of the known JBoss cluster names such as DefaultPartition and Tomcat-Cluster.

    HINT:To see the Group ID in logging messages, make sure that the level of the caching log (com.sssw.fw.cachemgr) is set to Info or higher.

    Cluster Properties

    Specify the JGroups protocol stack for the cluster specified by Group ID. This setting is for experienced administrators who might need to adjust the cluster properties. Otherwise, you should not change the default protocol stack.

    To see the current cluster properties, click view.

    For details on the JGroups protocol stack, go to www.jboss.org/wiki/Wiki.jsp?page=JGroups.

    If you want to override the global value of a setting with a local value, select the Enable Local check box for that setting. Then specify the local value. For those settings where Enable Local is unselected, any existing local values are deleted when you save.

    WARNING:If you specify local settings and enter an incorrect configuration in the JGroups initialization string, the cache cluster function might not start. Unless you know how to configure JGroups correctly and understand the protocol stack, you should not use local settings.

    Make sure that all nodes in your cluster specify the same Group ID and Cluster Properties. To see these settings for a particular node, you must access the Identity Manager user interface running on that node—by browsing to the URL of the user interface on that server—and then display the Caching page there.

    To use the TCP protocol instead of the default UDP protocol, you can add a token to the global settings for the Cluster Properties. For example, IDM_HOST_ADDR. You can then edit the hosts file on each server in the cluster to specify the IP address for that server. For more information, see Configuring User Application Clustering to Use TCP or UDP.

  3. Click Save.

  4. When you’re ready for your saved settings to take effect, restart the User Application on the applicable application servers.

Configuring User Application Clustering to Use TCP or UDP

You can configure the User Application clustering to use TCP or UDP. The configuration process must be completed on each server in the cluster because the local settings are saved on the file system for each server.

To configure the User Application clustering to use TCP or UDP:

  1. Log in as the User Application Administrator and go to Administration > Application Configuration > Caching.

  2. Enable the Enable Local check box in the Cluster Enabled row and set Local to TRUE.

  3. For each individual property, enable the Enable Local check box for the property and specify a value in the corresponding text field in the Local column. This allows the Local value to override the Global value for the property.

  4. Paste one of the following strings into the Cluster Properties field. It is important to paste the content as a single string with no carriage returns embedded:

    To use TCP, specify the following string:

    TCP(start_port=$startport;loopback=true):TCPPING(initial_hosts=$host_details;port_range=3);timeout=3500;num_initial_members=3;up_thread=true;down_thread=true):MERGE2(min_interval=5000;max_interval=10000):FD(shun=true;timeout=2500;max_tries=5;up_thread=true;down_thread=true):VERIFY_SUSPECT(timeout=1500;down_thread=false;up_thread=false):pbcast.NAKACK(down_thread=true;up_thread=true;gc_lag=100;retransmit_timeout=3000):pbcast.STABLE(desired_avg_gossip=20000;down_thread=false;up_thread=false):pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=true;down_thread=true;up_thread=true):pbcast.STATE_TRANSFER(up_thread=true;down_thread=true)

    Specify the values for start_port and initial_hosts. For example:

    TCP(start_port=7815;loopback=true):TCPPING(initial_hosts=192.168.162.10[7815],192.168.162.11[7815];port_range=3;timeout=3500;num_initial_members=3;up_thread=true;down_thread=true):MERGE2(min_interval=5000;max_interval=10000):FD(shun=true;timeout=2500;max_tries=5;up_thread=true;down_thread=true):VERIFY_SUSPECT(timeout=1500;down_thread=false;up_thread=false):pbcast.NAKACK(down_thread=true;up_thread=true;gc_lag=100;retransmit_timeout=3000):pbcast.STABLE(desired_avg_gossip=20000;down_thread=false;up_thread=false):pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=true;down_thread=true;up_thread=true):pbcast.STATE_TRANSFER(up_thread=true;down_thread=true)

    To use UDP, specify the following string:

    UDP(mcast_addr=228.8.8.8;mcast_port=45654):PING(timeout=5000):FD(timeout=10000;max_tries=5):VERIFY_SUSPECT:pbcast.NAKACK:UNICAST:pbcast.STABLE:FRAG:pbcast.GMS

    If you want to use TCP and use an external IP address, specify the bind_addr parameter as described in the below example:

    TCP(bind_addr=192.99.170.20;start_port=7815;loopback=true):TCPPING(initial_hosts=192.99.170.20[7815], 192.99.170.26[7815];port_range=3;timeout=3500;num_initial_members=3;up_thread=true;down_thread=true):MERGE2(min_interval=5000;max_interval=10000):FD(shun=true;timeout=2500;max_tries=5;up_thread=true;down_thread=true):VERIFY_SUSPECT(timeout=1500;down_thread=false;up_thread=false):pbcast.NAKACK(down_thread=true;up_thread=true;gc_lag=100;retransmit_timeout=3000):pbcast.STABLE(desired_avg_gossip=20000;down_thread=false;up_thread=false):pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=true;down_thread=true;up_thread=true):pbcast.STATE_TRANSFER(up_thread=true;down_thread=true)

    The properties in these strings are defined by JBoss. Refer to the JBoss documentation prior to JGroups 4.0.12.

  5. (Conditional) Perform the following actions for using TCP:

    1. Set start_port. This value must take into account the ports that are already in use and the value for port_range to avoid port conflicts. Depending on your configuration you may need to troubleshoot to find an unused port.

    2. Change the IP addresses to include the IP addresses of all the nodes in the cluster and their start_port values. The list should begin with the local IP address.

  6. Save the changes. These changes are written to the local file system for your server. Remember to make these changes for all servers in the cluster. Any server that does not have these changes uses the Global Settings values.

  7. Restart the server.

21.1.2 Driver Status

You can use the Driver Status pane to determine the expiration status of your driver.

The Driver Status pane displays the following two entries:

  • Driver Name

  • Expiration Date

    The Expiration Date displays one of the following values:

    1. Unlimited (if the activation has occurred)

    2. Expiration date of the driver (if the driver is a trial driver)

21.1.3 Identity Vault Settings

You can use the Identity Vault Settings pane to:

  • Change the credentials used by the Identity Manager User Application when connecting to the Identity Vault (LDAP provider)

  • Change the credentials for the guest account, if your system is configured to use a specific guest account, rather than LDAP anonymous account.

  • View other LDAP properties of the Identity Manager User Application. The values of these settings are determined when you install the User Application.

The user interface displays different fields depending on how you configured the guest account during installation. If you specified a guest account, the user interface includes fields that let you update the credentials for that account. If you have configured your system to use the LDAP Public Anonymous account, the user interface displays this message: The application is configured to use public anonymous account. To use a specific guest account, enable the guest account using the ldap configuration tool.

To administer Identity Vault settings:

  1. On the Application Configuration page, select Identity Vault Settings from the navigation menu on the left.

  2. Examine and modify the settings, as appropriate. For details, see:LDAP Settings You Can Change.

  3. If you make changes that you want to apply, click Submit.

LDAP Settings You Can Change

On the Identity Vault Connection Settings panel, you can modify settings for the credentials for:

  • The Identity Manager User Application whenever it connects to the Identity Vault (LDAP provider).

  • The guest account (if configured).

The initial values for the credentials are specified during installation. These installation values are written to the sys-configuration-xmldata file. If you make changes to these credentials via the Administration tab, your changes are saved to the User Application’s database; they are not saved to the sys-configuration-xmldata file. After values are written to the database, the User Application no longer checks the values written to the sys-configuration-xmldata file. This means that you cannot use the configupdate utility to change the credentials because they are ignored. However, you can use configupdate to change the type of guest user (LDAP Guest or Public Anonymous Account).

Table 21-3 LDAP Parameters

Setting

What to do

Identity Vault Administrator

Type the name of a user who has full administrator rights in the Identity Vault. The Identity Manager User Application needs to access the Identity Vault as an administrator in order to function.

It is typical to specify the Identity Vault’s root administrator as the LDAP connection username. The root administrator has full control over the tree, so you need not assign any special trustee rights.

For example:

cn=admin,o=myorg

If you specify some other user, you need to assign inheritable trustee rights to the properties [All Attributes Rights] and [Entry Rights] on your User Application driver.

NOTE:To avoid confusion, it is recommended that you do not specify the User Application’s User Application Administrator as the LDAP connection username. It is best to use separate accounts for these two different purposes.

Identity Vault Administrator Password

and

Confirm Identity Vault Administrator Password

Type the password that is currently set for that username in the Identity Vault.

Guest Username

Type the guest user’s distinguished name

Confirm Guest Password

Type the password for the guest user.

If TLS is enabled for your LDAP server, you might encounter the following error when you update the Admin username and password: Unable to authenticate to LDAP Provider. Disable this error by disabling TLS via iManager.

21.1.4 Logging Configuration

You can use the Logging page to control the levels of logging messages you want the Identity Manager User Application to generate. For information about understanding how logging works in an identity applications environment, see Section 8.0, Setting Up Logging in the Identity Applications.

The Identity Manager User Application implements logging by using a custom-developed logging framework that integrates with log4j, an open-source logging package distributed by The Apache Software Foundation. By default, event messages are logged to both of the following:

  • The system console of the application server where the Identity Manager User Application is deployed

  • A log file on that application server. For example:

    /opt/netiq/idm/apps/tomcat/logs/catalina.out

    This is a rolling log file. After it reaches a certain size, it rolls over to another file.

Logs for all identity applications components including OSP are logged to the catalina.out file. OSP logs are also stored in a separate file, osp-idm-<date of log generation>.log file located in /opt/netiq/idm/apps/tomcat/logs/. Logging is turned off by default and must be enabled in the setenv.sh file in the /TOMCAT_INSTALLED_HOME/bin/ directory. By default, logs for User Application and Role and Resource Service drivers are added to DSTrace.

21.1.5 Portal Settings

You can use the Portal page to view characteristics of the Identity Manager User Application.The settings are for informational purposes and cannot be changed.The values of these settings are set in the User Application WAR. (Default reflects your current choice from the s page.)