Skip Headers

Oracle® Application Server Containers for J2EE Security Guide 10g Release 2 (10.1.2) B14013-02 |
| Library | Product | Contents | Index

Previous | Next |

# 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.

## Ins tance-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.

### Cho osing 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>