4 Overall Security Configuration

Choosing the XML-Based or LDAP-Based Provider

As part of installing OC4J, you determine whether to use the LDAP-based or XML-based provider. This section gives guidelines on how to make that choice.

• XML-based provider: Use the XML-based provider in development environments and in deployed applications with a small user population.

• LDAP-based provider: Use the LDAP-based provider in production environments.

  Compared to the XML-based provider, the LDAP-based provider offers better security and performance. The centralized Oracle Internet Directory server scales gracefully as the number of applications and users grows. We recommend you take advantage of a centralized Oracle Internet Directory server in your production deployments, both for better performance and to take advantage of such features as centralized account creation and management, single passwords, and credential management.

  The LDAP-based provider enables you to configure cache parameters to improve overall performance of authentication and authorization. If secure communications are needed between the Oracle Internet Directory server and OC4J, configure the system to use the level of security required.

When you install infrastructure, then associate the OC4J instance with a mid-tier Oracle Internet Directory or Oracle Application Server Single Sign-On instance, the installer automatically selects the LDAP-based provider. For details, see the Oracle Application Server Installation Guide . If you need to configure OC4J to use the LDAP-based provider, see the instructions in the Oracle Application Server Administrator's Guide.

Locating jazn.xml, jazn-data.xml, and the <jazn> Element

To configure the OracleAS JAAS Provider, you must sometimes edit various configuration files using text editors. This section discusses how to locate the configuration files and the <jazn> element.

<jazn provider="xml" location="pathname">
   ...
</jazn>

Admintool Overview

This section discusses basic information needed to understand and use the JAZN Admintool. The JAZN Admintool is a lightweight tool used to manage user accounts stored in jazn-data.xml. To manage accounts in the LDAP-based provider, use the tools provided in the Oracle Delegated Administration Services.

java -jar jazn.jar -listrealms 
>RealmLoginModule username: martha
>RealmLoginModule password: mypass

-clustersupport oracle_home

java -jar jazn.jar -clustersupport /oracle_home -shell

<application> 
  <name>oracle.security.jazn.tools.Admintool</name>
  <login-modules> 
    <login-module> 
     <class>oracle.security.jazn.realm.RealmLoginModule</class>
      <control-flag>required</control-flag> 
      <options> 
         <option> 
            <name>debug</name> 
            <value>false</value> 
         </option> 
         <option> 
            <name>addAllRoles</name> 
            <value>true</value> 
         </option> 
      </options> 
    </login-module> 
  </login-modules> 
</application> 

Specifying an Alternate Policy Provider (Optional)

If you use the Java Virtual Machine shipped with Oracle Application Server, the OracleAS JAAS Provider is automatically specified as the JAAS policy provider. If you use another JVM, you must explicitly specify oracle.security.jazn.spi.PolicyProvider as the policy provider, because by default, the JVM uses the Sun JAAS provider.

You can specifying Oracle-specific JAAS properties in a separate file and passing them to the JVM on the command line. Oracle supplies a default file (ORACLE_HOME/j2ee/home/config/jazn.security.props) that specifies the OracleAS JAAS provider.

• To replace all security properties with the Oracle properties:

  java -Djava.security.properties==propfile
  
  

• To append the Oracle-specific properties to the other properties:

  java -Djava.security.properties=propfile
  

Specifying OracleAS JAAS Provider Settings

The home instance jazn.xml file is in the ORACLE_HOME/j2ee/home/config directory. The OracleAS JAAS Provider reads the information in this file before OC4J is started up, and certain settings can be made only in this file. If changes are read after OC4J starts up, they have no effect on the OracleAS JAAS Provider. These properties are discussed in detail in Chapter 5, "Configuring the OC4J Instance".

Enabling Debug Logging

To enable OracleAS JAAS Provider debug logging, set the system property jazn.debug.log.enable to true during Java Virtual Machine (JVM) startup.

You do this by modifying the JVM startup settings for your OC4J instance. In Oracle Application Server, you normally manage JVM settings with Oracle Enterprise Manager, using the Java Options textbox on the Server Properties page.

In standalone mode, you set this property using JVM command-line options. For example, you might start OC4J standalone with a command line such as:

java -Djazn.debug.log.enable=true -jar oc4j.jar 

Or you can start the Admintool shell in debug mode with the command:

java -Djazn.debug.log.enable=true -jar jazn.jar -shell

In Oracle Application Server, the debug output is captured by OPMN and written to log files associated with each OC4J instance in the ORACLE_HOME/opmn/logs directory.

Specifying User Managers

The user manager, employing the user name and password, verifies the user's identity using information in the user repository. The user manager contains your definitions for users, groups, or roles. The default user manager is the JAZNUserManager.

You can define a user manager for all applications or for specific applications.

• Global user manager: The global (default) user manager is inherited by all applications within an instance that has not defined a specific user manager. The instance UserManager is defined in the application.xml file.

• Specific user manager: This user manager is defined in orion_application.xml solely for a single application. It is not used by any other application.

  
  

  Note: Within a single OC4J instance you can specify different values for the application-specific UserManager instance and the global UserManager instance. When you do this, we recommend that you not mix custom UserManager instances and Oracle-supplied UserManager instances. You can use different custom UserManager instances for the application and the global instance, and you can use different Oracle-supplied UserManager instances for the application and the global instance, but you should avoid using a custom UserManager for the one instance and an Oracle-supplied UserManager for the other.

  
  

• In some cases, if an application inherits from another application instead of inheriting from the global application, then the parent user manager of the application will be the global UserManager instance instead of the UserManager instance specified in the parent application.

Customizing RealmLoginModule

The RealmLoginModule class is the default LoginModule that is configured through the jazn-data.xml file. The RealmLoginModule class authenticates user login credentials before the user can access J2EE applications. Authentication is performed using OC4J container-based authentication (HTTP BASIC, FORM, and so on). You do not need to enable the RealmLoginModule class if your application uses OracleAS Single Sign-On authentication.

You can configure RealmLoginModule either using the JAZN Admintool or by editing jazn-data.xml. For details on using the Admintool, see "Adding and Removing Login Modules" .

The <login-module> element supports the following <option> values:

<!DOCTYPE jazn-data (View Source for full doctype...)>
<jazn-data>
    ...
<!--  Login Module Data -->
 <jazn-loginconfig>
   <application>
     <name>oracle.security.jazn.oc4j.JAZNUserManager</name>
     <login-modules>
       <login-module>
          <class>oracle.security.jazn.realm.RealmLoginModule</class>
          <control-flag>required</control-flag>
          <options>
             <option>
               <name>addRoles</name>
               <value>true</value>
             </option>
         </options>
       </login-module>
     </login-modules>
   </application>
  </jazn-loginconfig>
</jazn-data>

Specifying Authentication (auth-method)

You specify the authentication method (auth-method) in one of several configuration files, using either the <jazn-web-app> or <login-config> elements. You must edit the configuration files by hand.

<web-app>
   ...
   <login-config>
      <auth-method>BASIC</auth-method>
   </login-config>
   ...
</web-app>

<web-app>
   ...
   <login-config>
      <auth-method>BASIC</auth-method>
   </login-config>
   ...
</web-app>

<jazn provider="LDAP">
   ...
   <jazn-web-app auth-method="SSO"/>
   ...
</jazn>

<web-app>
   ...
   <login-config>
      <auth-method>BASIC</auth-method>
   </login-config>
   ...
</web-app>

<jazn>
   ...
   <jazn-web-app auth-method="DIGEST" />
   ...
</jazn>

Configuring J2EE Authorization

J2EE defines a declarative authorization model that decouples applications from the underlying security infrastructure. This model allows the authorization policy of an application to be expressed in a portable manner in the application deployment descriptors. This model has proven to be hugely successful and suffices for most application needs.

In some advanced scenarios, however, the J2EE authorization model may seem too static and coarse-grained. In these cases, the JAAS authorization model can be used instead of (or in addition to) the J2EE security model. When compared to the J2EE authorization model, the JAAS authorization model is more powerful (fine-grained and dynamic) and more flexible (custom permission types supported). Such power and flexibility come at a cost, however, the JAAS authorization model is more complex to understand, deploy and administer than the J2EE authorization model.

Both models are fully supported in OC4J.

<jazn-web-app 
    auth-method="SSO"
    runas-mode="true" 
    doasprivileged-mode="true" />

<security-role-ref>
  <role-name>mgmt</role-name>
  <role-link>corpmanagers</role-link>
</security-role-ref>

Removing Realm Names from Authentication Principals

It is often desirable to avoid parsing the principal returned by various method calls. You can configure OracleAS JAAS Provider so that the returned principal contains no realm name. To do this, you add a jaas.username.simple property to the <jazn> element in the instance-level jazn.xml file, ORACLE_HOME/j2ee/instance_name/config/jazn.xml. If this property is set to true, returned principals contain no realm name; if it is set to false, the default, returned principals contain the complete realm name.

The jaas.username.simple property affects only the specified OC4J instance. Setting this property in orion-application.xml has no effect.

This property affects the return values of the following methods:

• javax.servlet.http.HTTPServletRequest: getRemoteUser() and getUserPrincipal() methods

• javax.ejb.EJBContext: getCallerIdentity() and getCallerPrincipal() methods

By default, the principal returned by these methods is in the format realm_name/simple_name, such as jazn.com/john. When you set jaas.username.simple to true, the returned principal is in the format simple_name, such as john.

You set jaas.username.simple as follows:

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

2. Search for a <property> subelement with name="jaas.username.simple" within the <jazn> element.

3. If the subelement exists, change value to true or false; if the subelement does not exist, create one. In either case, you should have a subelement that looks like this:

   <jazn provider="XML" location="./jazn-data.xml">
      <property name="jaas.username.simple" value="true" /> 
   </jazn>
   

   
   

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

   
   

Configuring Third-Party LDAP Providers

See Chapter 9, "Configuring External LDAP Providers".

Permitting EJB RMI Client Access

To enable fat client access to EJBs using RMI, you must grant the correct permissions using the JAZN Admintool. (For general information on using the Admintool, see "Admintool Overview" .) You must grant RMIPermission of login to your user, role, or group.

java -jar jazn.jar -grantperm myrealm -role administrators \
  oracle.j2ee.server.rmi.RMIPermission login

Creating a Java 2 Policy File

The Java 2 policy file grants permissions to trusted code or applications that you run. This enables code or applications to access Oracle support for JAAS or JDK APIs requiring specific access privileges.

A preconfigured Java 2 policy (java2.policy) is provided in ORACLE_HOME/j2ee/home/config.

You need to modify the Java 2 policy file to grant permissions to trusted code or applications.

For example, the following section of a java2.policy file grants java.security.AllPermission to the trusted jazn.jar.

/* grant the JAZN library AllPermission */ 
grant codebase "file:${oracle.home}/j2ee/home/jazn.jar" { 
    permission java.security.AllPermission; 
}; 

The following example grants specific permissions to all applications running in the ORACLE_HOME/appdemo directory.

/* Assuming you are running your application demo in $ORACLE_HOME/appdemo/, */ 
/* Grant JAZN permissions to the demo to run JAZN APIs*/ 
grant codebase "file:/${oracle.ons.oraclehome}/appdemo/-" {  
   permission oracle.security.jazn.JAZNPermission "getPolicy"; 
   permission oracle.security.jazn.JAZNPermission "getRealmManager"; 
   permission oracle.security.jazn.policy.AdminPermission
     "oracle.security.jazn.realm.RealmPermission$*$createRealm,dropRealm,
     createRole, dropRole,modifyRealmMetaData"; 

Using the <principals> Element and principals.xml

The <principals> element tells OC4J to use the UserManager described in a principals file, normally principals.xml. A <principals> element has one attribute, <path>, which specifies a path for the principals file, normally principals.xml.

For example:

<principals path="myprincipals.xml" />

A principals.xml file also contains a <principals> element; this contains two subelements, <groups> and <users>. The <groups> element contains one or more <group> elements, and the <users> element contains one or more <user> elements.

Groups in principals.xml correspond to roles in the OracleAS JAAS Provider. The principals.xml file does not support any equivalent of the OracleAS JAAS Provider concept of realms. Permissions granted to groups may be checked explicitly, and OC4J does check for the special permissions listed above. However, group permissions are not integrated with the usual Permission checking performed by a SecurityManager.

The following is a sample principals.xml file.

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE principals PUBLIC "//Evermind - Orion Principals//"
 "http://xmlns.oracle.com/ias/dtds/principals.dtd">

<principals>
  <groups>
<group name="guests">
    <description>users</description>
  </group>
  <group name="administrators">
    <description>administrators</description>
    <permission name="administration" />
  </group>
  </groups>
  <users>
  <user username="SCOTT" password="TIGER">
  <group-membership group="guests" />
  </user>
  <user username="anonymous" password="">
    <description>The default guest/anonymous user</description>
    <group-membership group="guests" />
  </user>
  <user username="admin" password=""  deactivated="true">
    <description>The default administrator</description>
    <group-membership group="users" />
    <group-membership group="administrators" />
  </user>
  </users>
</principals>