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 (JSR-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 (JSR-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"

Overview 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:

• Deploying 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.

Overview 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

Overview 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 persistence 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

Predefined 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 user, 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
  

Configuring 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