5 Configuring the OC4J Instance

This chapter discusses instance-level OC4J configuration. All tasks in this chapter affect an entire OC4J instance and all applications running under that instance. This chapter contains the following sections:

• The admin Account

• Instance-Level jazn.xml File

• Specifying LDAP Connection Properties

• Specifying LDAP JNDI Connection Pool Size

• Configuring LDAP Caching

• Configuring LDAP SSL Properties

• Configuring LDAP Default Realm

The admin Account

Whenever you create a new OC4J instance, that instance is given an administrator account admin with password welcome. You should change this password immediately using Oracle Enterprise Manager 10g Application Server Control Console.

Here are the steps to change the password:

1. From the Application Server Home page, select the OC4J instance.

2. From the home page of the OC4J instance, choose Administration.

3. From the OC4J Administration page, choose Security.

4. From the Security page, choose jazn.com/admin (under Users) to edit the administrative user properties.

Instance-Level jazn.xml File

All of the tasks in this chapter rely on editing the OC4J instance-level jazn.xml file, which is read at instance startup. The instance-level jazn.xml file is ORACLE_HOME/j2ee/instance_name/config/jazn.xml. All changes to this file affect the entire OC4J instance. The properties listed in this section can be changed only in the instance-level jazn.xml file.

Note: You cannot change the jazn.xml file with Application Server Control Console; you must edit it using a text editor.

Specifying LDAP Connection Properties

There are two properties that change LDAP connection properties. They are listed in Table 5-1.

Table 5-1 LDAP Connection Properties

Property Name	Meaning	Default Value
ldap.connect.max.retry	Number of times the OracleAS JAAS Provider attempts to create an LDAP connection before giving up	5
ldap.connect.sleep	Number of milliseconds the OracleAS JAAS Provider waits before retrying a failed LDAP connection attempt	5000

To configure LDAP connection properties, use the following steps:

1. Open the jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml, in a text editor and go to the <jazn> element within the file.

2. Locate the <property> subelement within the <jazn> element. The syntax of the <property> subelement is:

   <property name="propname" value="propvalue"/>
   
   

   If there is no <property> subelement corresponding to the property you want to change, create one.

3. Restart OC4J.

Specifying LDAP JNDI Connection Pool Size

There are two properties that change LDAP connection pool properties. They are listed in Table 5-2.

Table 5-2 LDAP JNDI Connection Pool Properties

Property Name	Meaning	Default Value
jndi.ctx_pool.init_size	Initial size for JNDI/LDAP connection pool	5
jndi.ctx_pool.inc_size	Pool increment size for JNDI/LDAP connection pool—number of connections added to pool whenever the supply of connections in the pool is exhausted	10

To specify the size of the connection pool used by JNDI:

1. Open the jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml, in a text editor and go to the <jazn> element within the file.

2. Locate the <property> subelement within the <jazn> element. The syntax of the <property> subelement is:

   <property name="propname" value="propvalue"/>
   
   

   If there is no <property> subelement corresponding to the property you wish to change, create one. For example, a <property> subelement setting the initial size to 20 would look like:

   <property name="jndi.ctx_pool.init_size" value="20">
   

   
   

   Note: Do not edit any <jazn> properties except as specified in this documentation.

   
   

3. Restart OC4J.

Configuring LDAP Caching

The LDAP-based OracleAS JAAS Provider supports caching, providing improved performance and scalability. There are three separate caches:

• Policy cache, which stores grantees and permissions

• Realm cache, which stores realms, users and roles, and a role graph

• Session cache, which stores users and role graphs in an HTTP session object (available only to Web-based clients with cookies enabled)

The caching service maintains a global HashMap, which is used to store and retrieve cached objects. A daemon thread runs periodically in the background to invalidate and clean up expired objects in the HashMap. Objects in the cache expire based on a time-to-live algorithm; expiration time can be set with the cache properties, described in Table 5-3.

Note: Only the LDAP-based provider provides these caches. The XML-based provider defaults to caching the entire XML document.

Changing Session Cache Details

HttpSession objects persist for the duration of the server-side session. An application can terminate a session explicitly, by invoking HttpSession.invalidate(); a container can terminate a session based on the <session-timeout> value.

Note: Objects stored in an HttpSession instance must implement the java.io.Serializable interface in order to be deployed with the <distributable /> flag in web.xml.

See Also: The Oracle HTTP Server Administrator's Guide for more information about session support in OC4J

Disabling LDAP Caching

Caching is enabled by default. You should disable the caches when performing management and administrative tasks programmatically. In particular:

• Disable the policy cache when managing policy. If the policy cache is enabled, calling Policy.grant() or Policy.revoke() causes an UnsupportedOperationException.

• Disable the realm cache when managing realms. This includes adding realms, dropping realms, granting roles, and revoking roles.

• Disable the session cache when you disable HTTP session cookies.

  
  

  Note: The JAZN Admintool automatically disables caching while it is in operation, then reenables caching when it finishes.

  
  

To disable the LDAP cache, use the following steps:

1. Open the jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml, in a text editor and go to the <jazn> element within the file.

2. Edit the <jazn> element to appear as follows:

   <jazn provider="LDAP">
      <property name="ldap.user"
                value="orclApplicationCommonName=jaznadmin1,cn=JAZNContext,
                       cn=products,cn=OracleContext"/>
      <property name="ldap.password" 
                value="{903}3o4PTHbgMzVlzbVfKITIO5Bgio6KK9kD"/>
      <property name="ldap.cache.session.enable" 
                value="false" />
      <property name="ldap.cache.realm.enable" 
                value="false" />
      <property name="ldap.cache.policy.enable" 
                value="false" />
   </jazn>
   
   

3. Restart OC4J.

LDAP Cache Configuration

The properties that affect the LDAP cache are controlled by <property> subelements within the <jazn> element. To change these properties, you must edit the jazn.xml file and change the <jazn> element.

To configure LDAP cache properties, use the following steps:

1. Open the jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml, in a text editor and go to the <jazn> element within the file.

2. Locate the <property> subelement within the <jazn> element. The syntax of the <property> subelement is:

   <property name="propname" value="propvalue"/>
   
   

   If there is no <property> subelement corresponding to the property you wish to change, create one.

3. Restart OC4J.

Table 5-3 describes the LDAP cache properties and their default values. You can set these properties only at the instance level, in the <jazn> element in the jazn.xml.

Table 5-3 LDAP Cache Properties

Property	Description	Default
ldap.cache.policy.enable (see Notes)	If set to true, enables cache; if set to false, disables cache.	true
ldap.cache.realm.enable	If set to true, enables cache; if set to false, disables cache.	true
ldap.cache.session.enable	If set to true, enables cache; if set to false, disables cache.	true
ldap.cache.initial.capacity	Initial capacity for the HashMap.	20
ldap.cache.load.factor	Load factor for the HashMap.	0.7
ldap.cache.purge.initial.delay	String containing an integer that represents the number of milliseconds the daemon thread waits before starts checking for expired objects.	3600000
ldap.cache.purge.timeout	The string representation of an integer that represents the number of milliseconds an object remains in cache before being invalidated and removed. It is also the sleep time for the daemon thread between each run looking for expired objects.	3600000

Notes: Do not edit any <jazn> properties except as specified in this documentation. The ldap.cache.policy.enable property replaces the deprecated ldap.cache.enable property.

A jazn element with all caches enabled, a cache size of 100, and a 10000-millisecond timeout would look like:

< jazn provider="LDAP" location="ldap://example.com:389" >
   < property name="ldap.cache.initial capacity" value="100" />
   < property name="ldap.cache.purget.timeout" value="10000" /> 
</jazn> 

Configuring LDAP SSL Properties

The properties that affect SSL are controlled by <property> subelements within the <jazn> element. To change these properties, you must edit the file containing the <jazn> element.

To configure LDAP SSL properties, use the following steps:

1. Open the jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml, in a text editor and go to the <jazn> element within the file.

2. Locate the <property> subelement within the <jazn> element. The syntax of the <property> subelement is:

   <property name="propname" value="propvalue"/>
   
   

   If there is no <property> subelement corresponding to the property you wish to change, create one.

3. Restart OC4J.

Table 5-4 lists the SSL properties.

Table 5-4 Values for <property> Subelement of <jazn> Element

Property Name	Value
ldap.password	Obfuscated password for the LDAP user name. For example: {903}oZZYqmGc/iyCaDrD4qs2FHbXf3LAWtMN See "Password Obfuscation in jazn-data.xml and jazn.xml" for details on obfuscation.
ldap.protocol	The protocol to be used when communicating with LDAP using SSL.
ldap.user	LDAP user name or DN. This element is populated automatically; you should not change the contents. For example: orclApplicationCommonName=jaznadmin1,cn=JAZNContext, cn=products,cn=OracleContext

Note: Do not edit any <jazn> properties except as specified in this document.

Choosing SSL Authentication

This section discusses configuring the OracleAS JAAS Provider to use SSL with Oracle Internet Directory. For information on how to configure Oracle Internet Directory to use SSL, see the Oracle Internet Directory Administrator's Guide and Oracle Application Server Containers for J2EE Servlet Developer's Guide .

At 10g Release 2 (10.1.2), you must use NULL authentication when communicating with Oracle Internet Directory. NULL authentication means that data are encrypted with the Anonymous Diffie-Hellman cipher suite, but no certificates are used for authentication.

If you choose SSL at install time, SSL is enabled with NULL authentication in place. You must manually enable SSL only if you did not choose SSL as part of your installation. In that case, for NULL authentication, add a <property> element to the <jazn> element in jazn.xml to specify a protocol. (Note that you do not specify a wallet location or password, because NULL authentication does not use certificates.)

<jazn provider="LDAP" location="ldap://example.com:5000" default-realm="us">
   ...
   <property name="ldap.protocol" value="ssl"/>  
   ...
</jazn>

Configuring LDAP Default Realm

The default realm is the realm used whenever an authentication or authorization request does not specify a realm explicitly. This attribute is automatically populated with the default Oracle Identity Management realm; you need to edit the attribute only if the default is incorrect for your application. To configure the LDAP default realm, use the following steps:

1. Open the jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml, in a text editor and go to the <jazn> element within the file.

2. Edit the default-realm attribute of the <jazn> element. The syntax is:

   <jazn provider="LDAP" default-realm="myrealm">
      ...
   </jazn>
   
   

3. Restart OC4J.

   
   

   Note: Do not edit any <jazn> properties except as specified in this documentation.

   
   

For example, a <jazn> element that set the default-realm to "Sales" would look like:

<jazn provider="LDAP" default-realm="Sales" ... more attributes ... >
   ...
</jazn>