2 Component Configuration

This chapter includes information about the default configuration of the Oracle Role Manager server and how to modify these defaults.

This chapter includes the following sections:

• Understanding Default Server Configuration

• Default Configuration Files

• Deploying Customizations

2.1 Understanding Default Server Configuration

This section shows the default values that are set during initial deployment of Oracle Role Manager to help you determine whether you need to use different values for your installation.

Each configurable component of the Oracle Role Manager server has a corresponding XML file to use as a starting place, should you find that you need to modify the configuration. The configurable components in Oracle Role Manager are:

• Authentication

• Bootstrap

• Business Logic Plug-ins

• Cache

• Deployment

• Finalization

• Internationalization

• Timers

2.1.1 Authentication

Oracle Role Manager authentication configuration controls the form of accepted SSO tokens, encryption algorithm, System Identity credentials, and person credentials for direct access to the Oracle Role Manager Web UI. For more information about authentication, refer "About the Single Sign-On Configuration with Oracle Role Manager".

Table 2-1 shows the default configuration for the Authentication component of Oracle Role Manager.

Table 2-1 Authentication Configuration Values

Element	Default Value
sso-token	Mapping between the person entity class and the userID attribute.
encryption-algorithm	oracle.iam.rm.authentication.util.SHAEncryption
system-credentials-mapping	Mapping between the systemIdentity entity class and the userID attribute for username, and between the systemIdentity entity class and the userPassword attribute for password.
user-credentials-mapping	Mapping between the person entity class and the userID attribute for username, and between the person entity class and the userPassword attribute for password
failure-policy	Defines the lockout attempt threshold, which is the maximum number of attempts a user can attempt for logging in.
lockout-attempt-threshold	The maximum number of attempts a user can attempt for logging in. The standard default value is 5.

2.1.2 Bootstrap

The Bootstrap configuration is used to initialize the core System Identities and the System Administrator role during initial deployment.

The entitlements for the roles set in this configuration are the minimum required to allow loading of other system roles and mappings to system entitlements. The bootstrap configuration defines two system identities: the System Administrator (the user that can log in to the system via the Web UI and command-line tools), and the System User (the identity of the Role Manager Server itself, which is used to perform system level background tasks, for example, Batch Role Resolution).

Note:

In the event where the initial state for these System Identities has been locked out, it can be recovered using the Rebootstrap tool. Refer to Section 4.5 for more information.

Table 2-2 shows the default configuration for the Bootstrap component of Oracle Role Manager.

Table 2-2 Bootstrap Configuration Values

Element	Default Value
system-admin
display-name	System Administrator
unique-name	System Administrator
admin-role display-name	System Administrator
admin-role unique-name	System Administrator
admin-role delegatable	false
admin-role privileges	systemRole with all permission and sysRolePrivilege with all permission.
system-user
display-name	System User
unique-name	System User

2.1.3 Business Logic Plug-ins

The configuration settings for Business Logic (BL) determine the cache size limit of plug-in packs and the time out value. You may need to increase the size limit of additional plug-in packs, which you have added.

The time out setting specifies the amount of time (in seconds) between submitting a business transaction for finalization and returning control to the user if the process is taking too long. You may want to shorten the value if you want the system to "fail" faster, or lengthen the value if time outs occur too frequently.

Table 2-3 shows the default configuration for the Business Logic Plug-in component of Oracle Role Manager.

Table 2-3 Business Logic Plug-in Configuration Values

Element	Default Value
plugin-cache-config size-limit	20 (number of cached plugin-pack objects)
finisher-config default-timeout-sec	60 seconds

2.1.4 Cache

You may want to reduce the heartbeat period (in milliseconds) for more frequent cleaning of the cache or increase the heartbeat period to handle a larger window when the cache is larger than configured.

Table 2-4 shows the default configuration for the cache component of Oracle Role Manager.

Table 2-4 Cache Configuration Values

Element	Default Value
heartbeat-period	5000 milliseconds

2.1.5 Deployment

The deployment configuration provides the information about which tablespaces must be used to deploy tables and indexes. By default tables and indexes are deployed to the database user's default tablespace. This configuration allows:

• the installer to define which tablespaces must be used

• the ModelManager to distribute the tables and indexes

Table 2-5 shows the default configuration values for the tablespace names used during deployment.

Table 2-5 Default Tablespace Configuration

Tablespace	Default Value
Data tables	ORM_DATA
Indexes	ORM_INDEX

2.1.6 Finalization

The Finalization configuration settings determine the expiration period and renewal period of the finalization lease. The expiration period is the amount of time (in milliseconds) a finalization node will be down before another node attempts to take its place; the smaller it is, the faster fail over will occur.

The renewal period is the amount of time (in milliseconds) between lease renewals; the smaller it is, the more "up to date" the lease is, however, this can cause more database traffic. The renewal period must be shorter than expiration period. If it is not shorter than expiration period, the lease can expire, causing fail over when the finalization server is still running, which will affect performance.

Table 2-6 shows the default configuration for the Finalization component of Oracle Role Manager.

Table 2-6 Finalization Configuration Values

Element	Default Value
lease-config expiration-period	15000
lease-config renewal-period	5000

2.1.6.1 Troubleshooting Finalization Lease Error

In the rare case when the application server crashes, it would not get a chance to cancel its finalization lease stored in the database.

Normally, the finalization lease expires after the lease-configuration period is over and the application server, when started is able to obtain a new finalization lease. However if the application server JVM crashes and if the database time is ahead of the application server, the finalization lease expires only after the time difference plus the lease configuration expiration period. This results in a pending state, where no transactions will get finalized in the database.

This pending state causes the deployment command ORM_HOME/bin/deploy.sh or deploy.bat to fail with the error message, "Could not obtain finalization lease: ensure that the server is down." This error condition persists even if you reboot all application servers and database systems. It is irrecoverable for the time difference period (a maximum period of one day) and recovers automatically after the time difference period is over.

To recover from this error condition, you need to direct the application server to obtain the lease by force:

Note:

You must perform this procedure only if the error condition persists even after rebooting all application servers and database systems.

Depending on the application server you are using, perform the following steps:

1. For JBoss:

   Edit the following file:

   JBOSS_HOME/bin/run.bat or run.sh

   Add the following:

   -Doracle.iam.rm.finalization_lease.obtain_by_force=true JVM property to JAVA_OPTS

2. For WebLogic:

   Edit the following file:

   WEBLOGIC_ORM_DOMAIN_HOME/bin/startWebLogic.cmd or startWebLogic.sh

   Add the following:

   -Doracle.iam.rm.finalization_lease.obtain_by_force=true JVM property to JAVA_OPTIONS

Note:

• This error does not occur for Oracle Role Manager on WebSphere, because the finalization lease is managed by WebSphere application server and not by the Oracle Role Manager database.

• After the lease is obtained by force, you may see JTA transaction abort warnings on server startup: "javax.transaction.RollbackException: Can't commit because the transaction is in aborted state."

  This is a benign message. The business transaction is not lost and it is processed when the lease is obtained.

• You must remove the JVM property from the application servers after the successful startup of the server.

2.1.7 Internationalization

The i18n configuration file provides the default information about cache configuration size limit and age-limit for the i18n configuration. You can use this file to change the default values.

By default there is only one i18n file bundled with Oracle Role Manager. If you add any i18n files, increase the size-limit to the number of i18n files. The age-limit controls the time interval, after which the cache will be refreshed. Table 2-6 shows the default values for the i18n configuration.

Table 2-7 Internationalization Default Configuration Values

Element	Default Value
cache-config size-limit	10 (number of 18n files in cache)
age-limit	18000 milliseconds

2.1.8 Timers

There are two configurable timer components in Oracle Role Manager, one for the main server, a singleton configuration for the timer subsystem as a whole. The second timer, for batch resolution can have several configurations, one per timer (identified by the job ID), used for integrations with external systems.

The main Timer configuration sets the thread pool property (refer to Table 2-8). Oracle recommends that this default value not be changed.

Table 2-8 Timer Configuration Values

Element	Default Value
thread-pool-property	5

The batch resolution job updates the user-to-role assignments calculated for complex dynamic roles (roles having complex rules that dynamically determine membership). The batch resolution timer can have multiple jobs configured (identified by the job ID).

The Batch Resolution Timer configuration sets preferences for the batch resolution job. Table 2-9 shows the default configuration values for setting the implementing Java class and whether the timer type is simple (defining a repeat interval of n milliseconds between invocations) or a cron timer (defining a UNIX-style cron timer). The default is the simple timer type. (Refer to Section 2.1.8.1 for more information about cron expressions.)

Table 2-9 Batch Resolution Timer Configuration Values

Element	Default Value
factory-classname	oracle.iam.rm.resolution.impl.BatchResolutionTimerFactory
job-id	BatchResolutionJob
singleton	true
simple repeat-interval	14400000
cron cron-expression	N/A

2.1.8.1 Cron Expressions

A cron expression is a string comprised of six or seven fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. The fields in the expected order is shown in Table 2-10.

Table 2-10 Cron Expressions Allowed Fields and Values

Name	Required	Allowed Values	Allowed Special Characters
Seconds	Y	0-59	, - * /
Minutes	Y	0-59	, - * /
Hours	Y	0-23	, - * /
Day of month	Y	1-31	, - * ? / L W C
Month	Y	0-11 or JAN-DEC	, - * /
Day of week	Y	1-7 or SUN-SAT	, - * ? / L C #
Year	N	empty or 1970-2099	, - * /

Example 2-1 Cron Expressions

Cron expressions can be as simple as * * * * ? * or as complex as 0 0/5 14,18,3-39,52 ? JAN,MAR,SEP MON-FRI 2002-2010.

Here are some more examples:

Expression	Means
0 0 12 * * ?	Fire at 12:00 PM (noon) every day
0 15 10 ? * *	Fire at 10:15 AM every day
0 15 10 * * ?	Fire at 10:15 AM every day
0 15 10 * * ? *	Fire at 10:15 AM every day
0 15 10 * * ? 2005	Fire at 10:15 AM every day during the year 2005
0 * 14 * * ?	Fire every minute starting at 2:00 PM and ending at 2:59 PM, every day
0 0/5 14 * * ?	Fire every 5 minutes starting at 2:00 PM and ending at 2:55 PM, every day
0 0/5 14,18 * * ?	Fire every 5 minutes starting at 2:00 PM and ending at 2:55 PM, AND fire every 5 minutes starting at 6:00 PM and ending at 6:55 PM, every day
0 0-5 14 * * ?	Fire every minute starting at 2:00 PM and ending at 2:05 PM, every day
0 10,44 14 ? 3 WED	Fire at 2:10 PM and at 2:44 PM every Wednesday in the month of March
0 15 10 ? * MON-FRI	Fire at 10:15 AM every Monday, Tuesday, Wednesday, Thursday and Friday
0 15 10 15 * ?	Fire at 10:15 AM on the 15th day of every month
0 15 10 L * ?	Fire at 10:15 AM on the last day of every month
0 15 10 ? * 6L	Fire at 10:15 AM on the last Friday of every month
0 15 10 ? * 6L	Fire at 10:15 AM on the last Friday of every month
0 15 10 ? * 6L 2002-2005	Fire at 10:15 AM on every last friday of every month during the years 2002, 2003, 2004, and 2005
0 15 10 ? * 6#3	Fire at 10:15 AM on the third Friday of every month
0 0 12 1/5 * ?	Fire at 12 PM (noon) every 5 days every month, starting on the first day of the month
0 11 11 11 11 ?	Fire every November 11 at 11:11 AM

2.2 Default Configuration Files

To view the default configuration XML files, you will need to extract them from an archive file. You may want to use these files for convenience as a starting place for your configuration changes.

To get the default configuration files:

1. If you have not already extracted the default configuration files, extract them as follows:

   1. On the Oracle Role Manager installation host, navigate to ORM_HOME/config.

   2. Using an utility like WinZip or gunzip, extract the entire contents of configurations.car into a temporary location.

2. From the temporary location used to extract the files, navigate to configurations/config.

   This directory contains subdirectories for all the configurable Oracle Role Manager server components.

These can be modified and used as a starting place for customizing your configuration.

Note:

The only difference between configurations.car and configurations_hardened.car is in the config/oracle.iam.rm.bootstrap/default.xml file, between system privileges assigned to the System Administrator.

2.3 Deploying Customizations

Oracle Role Manager configuration is stored in the database and must be deployed (copied into the database) before any data is loaded into the system.

If you need to alter the standard configuration or standard data model, you will need to run a command to deploy your customizations to the database.

Note:

For information on how to upgrade the data model and configurations from an existing installation of Oracle Role Manager to the latest release, refer Oracle Role Manager Installation Guide.

This procedure assumes you have already completed the following steps:

• A database instance has been created for Oracle Role Manager with the appropriate tablespaces.

• The Oracle Role Manager database owner and application user schemas have been created.

• The service on which Oracle Role Manager is installed is started and the database is accessible.

Refer to the Oracle Role Manager Installation Guide for more information about these assumptions.

To deploy model and configuration customizations:

1. Create an archive file containing your customizations and append the file name with .car.

2. In ORM_HOME/config, edit the following two lines in the db.properties file to match your environment:

   db.driverClass=oracle.jdbc.driver.OracleDriver
   db.connection_string=jdbc:oracle:thin:@//$HOST$:$PORT$/$SERVICE_NAME$
   

   where $HOST$ is the database host name, $PORT$ is the database listener port, and $SERVICE_NAME$ is the database service name on which the Oracle Role Manager users/schemas were created.

3. In a command window, navigate to ORM_HOME/bin.

4. Run the following command to deploy the configuration and data model and create the root entities.

   deploy "<collection_of_cars>" <orm-owner> <ormapp-user> <admin-user>
   

   where:

   <collection_of_cars> contains the relative paths and file names of all CAR files to deploy, for example, in a customized deployment, on a UNIX-based system:

   ../config/configurations_custom.car:../config/oim_integration_custom.car
   

   This collection must be within quotes with delimiters appropriate to the platform (a semicolon (;) for Windows, otherwise a colon (:)).

   <orm-owner> is the username of the Oracle Role Manager database owner user/schema.

   <ormapp-user> is the username of the Oracle Role Manager application user/schema.

   <admin-user> is the username of the Oracle Role Manager System Administrator to create.

5. At the prompts, type the passwords of the Oracle Role Manager database owner, Oracle Role Manager application user, and Oracle Role Manager Administrator account.

2.4 Logging Configuration

The logging.properties file determines the logging messages of the command-line tools. It provides the information about logging level, filename, and location.

To configure logging, reset the following default configuration values:

• Set the global logging level using the following syntax:

  .level = INFO

• Set the logging level for messages that are printed on the console to FINE and above:

  java.util.logging.ConsoleHandler.level = FINE

• Set the logging level for messages that are printed in the file to FINE and above:

  java.util.logging.FileHandler.level = FINE

• Set the file size limit (in bytes) and the number of most recent log files to be retained. The product of these two parameters (limit * count) must be less than your free disk space.

  java.util.logging.FileHandler.limit = 100000

  java.util.logging.FileHandler.count = 10

  Note:

  A reasonable file size limit is 5000000 (~5MB) with a count of 200, which makes a total of about 1 GB.

• Set the hierarchy indexing manager logger to log FINE messages, for example:

  oracle.iam.rm.hierarchy.level = FINE

For more information about logging configuration, visit the Java Web site at

http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html.

2.5 Abandoned Transaction Cleanup

Abandoned transactions are those pending transactions which have seen no activity in a configurable time-to-live period. The transactions are abandoned either because of a network problem between Role Manager client and server or the user of Role Manager navigates away from the transaction page without completing the transaction. Role Manager uses a configurable scheduled task to cleanup such abandoned transactions. The following factors are considered to cleanup the abandoned transactions:

• Any pending transaction that has no activity within the time-to-live window is eligible for cleanup. However, the actual cleanup only occurs when the scheduled task for cleanup is run.

• An excessively short time-to-live window will interfere with normal user activities. Therefore Oracle recommends a time-to-live value of at least 1 hour.

You can consider these two factors to configure the scheduled task. The default time at which the scheduled task is set to run is 1 a.m. and time-to-live value is 1 hour. These values can be set by unpacking the configurations.car file and editing the oracle.iam.rm.timer.abandonedTransactionCleanupTimer.xml file. The following is the default configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<timer-config xmlns="http://xmlns.oracle.com/iam/rm/timer/config/1_0">
    <job-configs>
        <job-config>
<factory-classname>oracle.iam.rm.bizxact.impl.AbandonedTransactionCleanupFactory</factory-classname>
            <job-id>AbandonedTransactionCleanupJob</job-id>
            <group-id>TransactionGroup</group-id>
            <parameters>
                <parameter>
                    <id>timeToLive</id>
                    <integer>60</integer>  <!-- hourly, represented by minute-granularity -->
                </parameter>
            </parameters>
            <singleton>true</singleton>
            <!--
            The default invocation interval is 0 0 1 * * ?
            This cron-style expression translates to 1:00 AM every day.
            Refer to the Oracle Role Manager Administrator's Guide for more information.
            -->
            <cron>
                <cron-expression>0 0 1 * * ?</cron-expression>
            </cron>
        </job-config>
    </job-configs>
</timer-config>