Skip Headers

Oracle® Containers for J2EE Security Guide 10g Release 3 (10.1.3) B14429-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 3 Overview of Security Administration and Configuration

This section provides an overview of features and tools for security administration and configuration in OC4J and Oracle Application Server, covering the following topics:

- General OC4J Deployment and Configuration Features

- Tools for Oracle Application Server and OracleAS JAAS Provider

- JMX and MBeans Administration

- Overview of Configuration Files and Key Elements

- OC4J System Application

- Summary of OC4J Accounts

- Summary of Configuration Repositories and Security Management Tools

## General OC4J Deployment and Configuration Features

OC4J supports the following standards for deploying and managing applications in a J2EE environment:

- Java Management Extensions (JMX) 1.2 specification allows standard interfaces to be created for managing resources, such as services and applications, in a J2EE environment. The OC4J implementation of JMX provides a user interface that you can use to completely manage an OC4J server and applications running within it.

- Java 2 Platform, Enterprise Edition Management Specification (JS R-77) allows objects known as MBeans (managed beans) to be created for runtime management of applications in a J2EE environment. In OC4J, you can directly access MBeans through the System MBean Browser in Oracle Enterprise Manager 10g, but many of their properties are exposed in a more user-friendly way through other features of Enterprise Manager.

- Java 2 Enterprise Edition Deployment API Specification (JS R-88) defines a standard API for configuring and deploying J2EE applications and modules into a J2EE-compatible environment. The OC4J implementation includes the ability to create or edit a deployment plan containing the OC4J-specific configuration data needed to deploy a component into OC4J.

See Also: Oracle Containers for J2EE Deployment Guide and Oracle Containers for J2EE Configuration and Administration Guide for general information about OC4J deployment, configuration, and administration

## Tools for Oracle Application Server and OracleAS JAAS Provider

Managing security in the J2SE and J2EE environments involves creating and managing realms, users, roles, permissions, and policy. The following Oracle tools are involved in managing security configuration:

- Oracle Enterprise Manager 10g Application Server Control is used for overall security administration and configuration during and after deployment, and to manage the file-based provider.

- OracleAS JAAS Provider Admintool is used to manage the file-based provider, and also to manage policies and login modules for any security provider.

- Oracle Identity Management and Oracle Internet Directory tools: Oracle Delegated Administration Services (DAS) and Oracle Directory Manager (`oidadmin`) are used to manage users and roles in Oracle Internet Directory for Oracle Identity Management.

These tools will be summarized more thoroughly in the subsections that follow.

Note: Wherever possible, Oracle Enterprise Manager 10g Application Server Control should be your first-choice tool to administer OC4J, including OC4J security. For features that the Application Server Control does not support, you can, as applicable, use the OracleAS JAAS Provider Admintool. Occasionally, you will have to directly manipulate a configuration file, particularly the instance-level `jazn.xml` file (discussed in "The jazn.xml File").

See Also: "Summary of Configuration Repositories and Security Management Tools"

### Ove rview of Enterprise Manager

Typically, you should use Oracle Enterprise Manager 10g Application Server Control to deploy and administer your applications. The user interface for this is the Application Server Control Console. Application Server Control includes features for the following:

- Deploy ing an application to OC4J. This includes a deployment plan editor. For security, this also includes features to specify the security provider and security role mapping during deployment.

- Using the System MBean Browser for MBean configuration and operations (further discussed in "JMX and MBeans Administration"). Also be aware, however, that many parameters corresponding to MBeans properties are exposed through other pages of the Application Server Control Console. Avoid direct manipulation of OC4J MBeans whenever possible.

- Changing to a different security provider after deployment, or updating security provider settings.

- Performing OC4J runtime administration and configuration.

OC4J-specific XML configuration files are updated automatically by OC4J when you use the Application Server Control Console.

Notes: In standalone OC4J you also have the option of using the command-line OC4J `admin_client.jar` tool, which operates through the OC4J `system` application, to deploy and bind your J2EE applications. Alternatively, if you use the Oracle JDeveloper tool to develop your application, you can use it to deploy the application and any resource adapters as well. Whenever a configuration change is made using Application Server Control or the OC4J security provider MBean, the application must be restarted. Until the application is restarted, all other operations of the security provider MBean are invalidated and will return an error message.

See Also: Oracle Application Server Administrator's Guide for more information about Application Server Control Oracle Containers for J2EE Configuration and Administration Guide for information about the admin_client.jar utility "OC4J System Application"

### Overview of the OracleAS JAAS Provider Admintool

The OracleAS JAAS Provider Admintool, for use during development, is a lightweight Java application with the following management features:

- For the file-based provider: administration for users, roles, policies, and login modules

- For Oracle Identity Management: administration for policies and login modules, plus read-only access to users and roles

- For external LDAP providers: administration for policies and login modules

- For custom security providers: administration for policies and login modules

Admintool functions can be called directly from a command line or through an interactive shell. The Admintool is located in `ORACLE_HOME``/j2ee/home/jazn.jar`.

The general command-line syntax is as follows:

    % java -jar jazn.jar [-user username -password pwd] [option1 option2 ... ]

When you use the Admintool for the file-based provider, by default it updates the `system-jazn-data.xml` file in the `ORACLE_HOME``/j2ee/home/config` directory.

Note: In general, changes made by the Admintool are not effective until you restart OC4J.

See Also: Appendix C, "OracleAS JAAS Provider Admintool Reference"

### Overview of Oracle Identity Management and Oracle Internet Directory Tools

This section provides an overview of tools to manage Oracle Internet Directory, when using Oracle Identity Management as your security provider.

#### Ove rview of Delegated Administration Services

Delegated administration is an important feature of the Oracle Identity Management infrastructure. It enables you to store all data for users, groups, and services in a central directory, while distributing the administration of that data to various administrators and end users. It does this in a way that respects the various security requirements in your environment.

Suppose, for example, that your enterprise stores all user, group, and services data in a central directory, and requires one administrator for user data, and another for the e-mail service. Delegated administration as provided by the Oracle Identity Management infrastructure enables different administrators with different security requirements to administer centralized data in a way that is both secure and scalable. Privileges can be delegated with Oracle Delegated Administration Services to (among other things) create, edit, and delete users and groups; assign privileges to users and groups; and manage services and accounts.

Oracle Delegated Administration Services is a set of pre-defined, Web-based units for performing directory operations on behalf of a user. It frees directory administrators from the more routine directory management tasks by enabling them to delegate specific functions to other administrators and to end users. It provides most of the functionality that directory-enabled applications require, such as creating a user entry, creating a group entry, searching for entries, and changing user passwords.

You can use Oracle Delegated Administration Services to develop your own tools for administering application data in the directory. Alternatively, you can use the Oracle Internet Directory Self-Service Console, a tool based on Delegated Administration Services. This tool comes ready to use with Oracle Internet Directory.

See Also: Oracle Identity Management Guide to Delegated Administration

#### Ov erview of Oracle Directory Manager

Oracle Directory Manager is an online administration tool with a Java-based graphical user interface that you can use to administer Oracle Internet Directory. The executable file is located in the `ORACLE_HOME``/bin` directory, and you can run it from the command line as follows:

    % oidadmin

In general, any directory-specific configuration or maintenance task not available through Application Server Control can be accomplished through Oracle Directory Manager (as well as various command-line interfaces supplied with Oracle Internet Directory).

You can use Oracle Directory Manager for tasks such as the following:

- Configuring realms

- Specifying password policies

- Configuring the Oracle Directory Synchronization Service and Oracle Internet Directory connectors and agents

You can also manage features such as attribute uniqueness, plug-ins, garbage collection, change logs, replication, query optimization, debug logging, and access control lists.

See Also: Oracle Internet Directory Administrator's Guide for general information about Oracle Directory Manager

## JMX and MBeans Administration

OC4J support for the JMX specification allows standard interfaces to be created for managing resources dynamically in a J2EE environment. The OC4J implementation of JMX provides a JMX client, the System MBean Browser, that you can use to manage an OC4J instance through MBeans that are provided with OC4J.

An MBean is a Java object that represents a JMX manageable resource. Each manageable resource within OC4J is managed through an instance of the appropriate MBean. Each MBean provided with OC4J exposes a management interface that is accessible through the System MBean Browser in the Application Server Control Console. You can set MBean attributes, execute operations to call methods on an MBean, subscribe to notifications of errors or specific events, and display execution statistics.

To access the browser from the OC4J Home page, select the Administration tab and then, under the list of tasks, go to the JMX task "System MBean Browser". From the browser, you can do the following:

- Select the MBean of interest in the left-hand frame.

- Use the Attributes tab in the right-hand frame to view or change attributes. A settable attribute has a field where you can type in a new value. Then apply the change.

- Use the Operations tab in the right-hand frame to invoke methods on the MBean. Select the operation of interest. In the Operation window, you can invoke it with specified parameter settings.

- Use the Notifications tab (where applicable) in the right-hand frame to subscribe to notifications. You can select each item for which you want notification, and then apply the changes.

- Use the Statistics tab (where applicable) in the right-hand frame to display execution statistics.

Be aware that MBeans and their attributes vary regarding when changes take effect. In the runtime model, changes take effect immediately. In the configuration model, some changes take effect when the resource is restarted, others when the application is restarted, and still others when OC4J is restarted. There is also variation in whether changes are persisted.

## Overview of Configuration Files and Key Elements

This section provides an overview of the following key XML files and elements for security configuration:

- The orion-application.xml File (<jazn> and <jazn-web-app> Elements)

- The system-application.xml File

- The system-jazn-data.xml File

- Application-Specific jazn-data.xml File (Optional)

- The jazn.xml File

Note: In general, you should use the Application Server Control Console or OracleAS JAAS Provider Admintool (both discussed earlier in this chapter) for configuration and administration, instead of manipulating configuration files directly. Using these tools results in the appropriate entries automatically being made in the configuration files.

See Also: "Summary of Configuration Repositories and Security Management Tools"

### The orion-application.xml File (<jazn> and <jazn-web-app> Elements)

The OC4J `orion-application.xml` file is for general (not just security-related) application-level configuration. Settings in this file apply across a single J2EE application (EAR file).

For security settings in `orion-application.xml`, there is the `<jazn>` element. In particular, this element can specify the security provider, the user and role repository location, and the default realm for the application, as in the following example to use the file-based provider:

    <jazn provider="XML" location="./system-jazn-data.xml" default-realm="jazn.com" >
       ...
    </jazn>

(The `system-jazn-data.xml` file, discussed in "The system-jazn-data.xml File", would actually be the repository by default, but is specified here for illustrative purposes.)

A subelement of `<jazn>` in `orion-application.xml` is the `<jazn-web-app>` element, which is where you specify OC4J-specific authentication methods (using the `auth-method` attribute) for Web applications.

Note: If there is no `<jazn>` element in `orion-application.xml`, the security provider settings defer to those of the instance-level `jazn.xml` file (where the file-based provider with the `system-jazn-data.xml` repository and `jazn.com` default realm are the default settings).

### The system-application.xml File

The OC4J configuration file is associated with the OC4J `system` application, which is described in "OC4J System Application". For the `system` application, `system-application.xml` is equivalent to the `orion-application.xml` file for a deployed application.

The `system-application.xml` file, through its `<jazn>` element, specifies the file-based security provider for OC4J instance-level user and role settings (including some used for special OC4J functionality). The `system-application.xml` file points to the `system-jazn-data.xml` file (described in the next section), which is also instance-level, as the repository for these settings, which are located under the `<jazn-realm>` element.

By default, OC4J expects the `system-application.xml` to be in the `ORACLE_HOME``/j2ee/``instance_name``/config` directory.

### The system-jazn-data.xml File

The `system-jazn-data.xml` file is a new file in the OC4J 10.1.3 implementation. This file (as well as `system-application.xml`) is associated with the OC4J `system` application, which is described in "OC4J System Application".

The `system-application.xml` file points to the `system-jazn-data.xml` file as the repository for OC4J instance-level user and role settings (located under the `<jazn-realm>` element) for the file-based provider, which uses `system-jazn-data.xml` for authentication and authorization. (Note that the file-based provider is the default security provider.)

The `system-jazn-data.xml` file also stores JAAS login module configuration (under the `<jazn-loginconfig>` element). In addition, by default, it stores instance-level policy and permission configuration (under the `<jazn-policy>` and `<jazn-permission-classes>` elements).

By default, OC4J expects the `system-jazn-data.xml` file to be in the `ORACLE_HOME``/j2ee/``instance_name``/config` directory.

There is a persist ence mode that governs how often changes are written to the `system-jazn-data.xml` file and, if applicable (for the file-based provider), to an application-level `jazn-data.xml` file There are three possible values for persistence, according to the `<jazn>` element `persistence` attribute in either the instance-level `jazn.xml` file or application-level `orion-application.xml` file:

- "`NONE`": Do not write changes to `system-jazn-data.xml`.

- "`ALL`": Write changes after every modification.

- "`VM_EXIT`" (default): Write changes when the Java Virtual Machine exits.

Here is an example:

    <jazn provider="XML" persistence="ALL" ... >
       ...
    </jazn>

- Notes: In previous releases, `system-jazn-data.xml` was named `jazn-data.xml`. For the file-based provider, you can still use a file named `jazn-data.xml` to store user and role information, but this file would be application-specific. See the next section, "Application-Specific jazn-data.xml File (Optional)". Settings in the `system-jazn-data.xml` file can be manipulated using Application Server Control or the OracleAS JAAS Provider Admintool. Changes made to the `system-jazn-data.xml` file are visible to all applications that use it. The `system-jazn-data.xml` file contains accounts for predefined OC4J users and roles. See "Predefined OC4J Accounts in system-jazn-data.xml". White space in element settings is significant, such as the differences between the following:
      <name>scott</name>
      <name>scott </name>
      <name> scott</name>
      <name> scott </name>

### Application-Specific jazn-data.xml File (Optional)

When you use the file-based provider, you can optionally still use a `jazn-data.xml` file as the user and role repository, but this file is application-specific. You can specify its location in the `<jazn>` element of the `orion-application.xml` file:

    <jazn provider="XML" location="path/jazn-data.xml">
       ...
    </jazn>

Here is the default location:

    ORACLE_HOME/j2ee/instance_name/application-deployments/app_name

Note that if `orion-application.xml` is configured exactly as follows, but the `jazn-data.xml` file is not packaged with the application, then one will be created during deployment:

    <jazn provider="XML" location="./jazn-data.xml" />

Persistence mode for changes to the repository, described in the preceding section for `system-jazn-data.xml`, also affects `jazn-data.xml`.

- Notes: Think of the application-specific `jazn-data.xml` file as a repository, not as a configuration file. White space in element settings is significant, such as the differences between the following:
      <name>scott</name>
      <name>scott </name>
      <name> scott</name>
      <name> scott </name>

### The jazn.xml File

The `jazn.xml` file, located in the `ORACLE_HOME``/j2ee/``instance_name``/config` directory, is an OC4J instance-level configuration file for the OracleAS JAAS Provider. It specifies the instance-level security provider and repository for policy and permission settings. The main element of the `jazn.xml` file is the `<jazn>` element, with largely the same functionality as discussed earlier for the `orion-application.xml` file for application-level settings.

By default, `jazn.xml` specifies the file-based provider, with `system-jazn-data.xml` as the repository and `jazn.com` as the default realm:

    <jazn provider="XML" location="./system-jazn-data.xml" default-realm="jazn.com">
       ...
    </jazn>

The `jazn.xml` file for the OC4J `home` instance, referred to as the bootstrap `jazn.xml` file, is typically located in the `ORACLE_HOME``/j2ee/home/config` directory. It is read at OC4J startup and used by the OracleAS JAAS Provider runtime. Without a valid `jazn.xml` file, the OracleAS JAAS Provider cannot begin running.

If you use Application Server Control to associate OC4J with an Oracle Internet Directory instance in order to use the Oracle Identity Management security provider, then the `<jazn>` element of the bootstrap `jazn.xml` file is updated appropriately for the Oracle Internet Directory instance. For example:

    <jazn provider="LDAP" location="ldap://myoid.oracle.com:389" default-realm="us" >
       ...
    </jazn>

Note: If changes are made to `jazn.xml` after OC4J starts up, they have no effect on the OracleAS JAAS Provider.

You can optionally use a system property to specify an alternative location for the bootstrap `jazn.xml` file. When the OracleAS JAAS Provider starts, it searches for `jazn.xml` in the following order, stopping the search as soon as it finds one:

1. Location specified by the system property `oracle.security.jazn.config`

2. Location specified by the system property `java.security.auth.policy`

3. `J2EE_HOME``/config`, where `J2EE_HOME` is specified by the system property `oracle.j2ee.home`

4. `ORACLE_HOME``/j2ee/home/config`, where `ORACLE_HOME` is specified by the system property `oracle.home` (this is generally the same location as `J2EE_HOME``/config`)

5. `./config`

Sample jazn.xml Files

Here are sample `jazn.xml` files, first with the default configuration for the file-based provider:

    <?xml version="1.0" encoding="UTF-8" standalone='yes'?>
    <jazn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation=
                    "http://xmlns.oracle.com/oracleas/schema/jazn-10_0.xsd"
     schema-major-version="10"
     schema-minor-version="0"
     provider="XML"
     location="./system-jazn-data.xml"
     default-realm="jazn.com"
    />

And for the LDAP-based provider:

    <?xml version="1.0" encoding="UTF-8" standalone='yes'?>
    <jazn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation=
                    "http://xmlns.oracle.com/oracleas/schema/jazn-10_0.xsd"
     schema-major-version="10"
     schema-minor-version="0"
     provider="LDAP"
     location="ldap://myoid.us.oracle.com:389"
    />

## OC4J System Application

Be aware that the OC4J `system` application is a new internal component in the OC4J 10.1.3 implementation. It is auto-deployed to the OC4J instance the first time OC4J is started. This application was added primarily to address issues related to deploying or redeploying applications to OC4J.

The `system` application is at the root of the application hierarchy, and provides classes and configuration required at OC4J startup, including shared libraries imported by default by all other deployed applications. It is an OC4J internal component only. Applications cannot be deployed to it, nor can it be declared the parent of another application. The OC4J `default` application continues to serve as the default parent of all deployed applications.

The `system` application is configured to use the file-based provider for user and role settings, using `system-jazn-data.xml` for the repository. These settings should not be altered.

The OC4J-specific application descriptor for the `system` application is `system-application.xml`, with the same functionality as `orion-application.xml` for a deployed application. (For the `default` application, the OC4J-specific application descriptor is `application.xml`, not to be confused with the J2EE standard `application.xml` file for deployed applications.) These files are located in the `ORACLE_HOME``/j2ee/``instance_name``/config` directory.

Note: By default, the OC4J `default` application also uses `system-jazn-data.xml`.

See Also: Oracle Containers for J2EE Configuration and Administration Guide for information about the OC4J `system` and `default` applications

## Summary of OC4J Accounts

This section provides a summary of key OC4J accounts, covering the following topics:

- Predefined OC4J Accounts

- Activation of the oc4jadmin Account

- Configuring a New Administration Account

- Configuring an Anonymous User

### Pred efined OC4J Accounts

The OC4J 10.1.3 implementation includes predefined "bootstrap" users and roles for Oracle Internet Directory (when you use Oracle Identity Management) or the file-based provider.

For the file-based provider, the accounts are predefined in the `system-jazn-data.xml` file. For Oracle Internet Directory, they are created automatically as default accounts as part of the OC4J-OID association process.

The following predefined accounts are common to both providers:

- `oc4jadmin` user (formerly `admin`)

- `oc4j-administrators` role (formerly `administrators`), with member `oc4jadmin`, RMI permission "login" granted, and administration permission "administration" granted

- `oc4j-app-administrators` role (formerly `jmx-users`), with RMI permission "login" granted, to allow access to JMX application-level connectors

The following additional accounts are predefined for the file-based provider:

- `anonymous` us er, initially deactivated

  Activate `anonymous` directly in the `system-jazn-data.xml` file, by changing the `deactivated` attribute of the `<user>` element from "`true`" to "`false`". Unlike for `oc4jadmin`, there is no support in the OracleAS JAAS Provider Admintool for activating `anonymous`.

- `users` role, for RMI/EJB access

- `jtaadmin` user, to allow transaction propagation over ORMI

Do not remove any of these accounts, or the administrative functions of the OracleAS JAAS Provider will not work.

See Also: The next section, "Activation of the oc4jadmin Account"

### Activation of the oc4jadmin Account

The `oc4jadmin` account (formerly the `admin` account) is activated during Oracle Application Server installation, but is initially deactivated for the file-based provider in standalone OC4J. It is activated under the following circumstances:

- When standalone OC4J is first started (and you are prompted for a password)

- When you run the OracleAS JAAS Provider Admintool with the `-activateadmin` option

  You also specify the password as part of this command:

      % java -jar jazn.jar -activateadmin password

### Co nfiguring a New Administration Account

By default, `oc4jadmin` is the administration account for OC4J. When using either the file-based provider or Oracle Identity Management, you can specify a different administration account by setting the `admin.user` property in the instance-level `jazn.xml` file, as follows:

    <jazn ... >
       ...
       <property name="admin.user" value="desired_admin_user_name" />
       ...
    </jazn>

Then configure the account in the user repository with correct group membership and privileges, as appropriate. In Oracle Internet Directory, you can use DAS to create users and roles grant roles to users. To assign permissions, you can use the OracleAS JAAS Provider Admintool (or the OracleAS JAAS Provider MBean).

### Configuring an Anonymous User

When using either the file-based provider or Oracle Identity Management, you can map an anonymous user to an existing user by setting the `anonymous.user` property in the instance-level `jazn.xml` file. For example, assuming there is a user `PUBLIC` in Oracle Internet Directory:

    <jazn ... >
       ...
       <property name="anonymous.user" value="PUBLIC" />
       ...
    </jazn>

## Summary of Configuration Repositories and Security Management Tools

Management tools and configuration repositories have been discussed previously, but Table 3-1 summarizes the configuration repositories and the preferred management tools to use for the various types of configuration for each security provider.

Where applicable, Application Server Control is the preferred tool.

Table 3-1 Configuration Repositories and Preferred Management Tools

Security Provider | Repository and Management Tool for Users and Roles | Repository and Management Tool for Policies | Repository and Management Tool for JAAS Login Modules
--- | --- | --- | ---
File-based | system-jazn-data.xml (or application-specific jazn-data.xml) Use Application Server Control Console. | system-jazn-data.xml Use OracleAS JAAS Provider Admintool. | n/a
Oracle Identity Management | Oracle Internet Directory Use DAS (or OracleAS JAAS Provider Admintool for read-only). | Oracle Internet Directory Use OracleAS JAAS Provider Admintool. | n/a
External LDAP | External (third-party) LDAP server Use tool supplied by provider. | system-jazn-data.xml Use OracleAS JAAS Provider Admintool. | system-jazn-data.xml Use Application Server Control Console or OracleAS JAAS Provider Admintool.
Custom security provider | Custom security repository Use tool supplied by provider. | system-jazn-data.xml Use OracleAS JAAS Provider Admintool. | system-jazn-data.xml Use Application Server Control Console or OracleAS JAAS Provider Admintool.
COREid Access | Oracle COREid Access and Identity Use COREid Access Manager. | system-jazn-data.xml Use OracleAS JAAS Provider Admintool. | n/a