7
Configuring JAAS Support

This chapter describes the configuration tasks you must perform to use JAAS support in a Java2 Platform, Standard Edition (J2SE) or Java2 Platform, Enterprise Edition (J2EE) environment.

This chapter contains these topics:

• What JAAS Components Do You Need to Configure?

• Performing Configuration Tasks Common to J2SE and J2EE Environments

• Performing Configuration Tasks Unique to J2SE Environments

• Performing Configuration Tasks Unique to J2EE Environments

• Differences between <jazn> Tags and the <user-manager> Property

  Note: This chapter does not describe how to configure Oracle9iAS Containers for J2EE (OC4J) with your application. See the Oracle9iAS Containers for J2EE User's Guide in the Oracle9iAS Documentation Libraryfor those instructions.

  See Also: Part 2 of OC4J Services Guide in the Oracle9iAS Documentation Library for information on using JAAS support after completing these configuration tasks.

What JAAS Components Do You Need to Configure?

You must configure the JAAS components after installation and before using your JAAS-based application. The JAAS components that must be configured depend on the environment in which the application runs. Table 7-1 identifies the necessary configuration tasks.

Table 7-1 JAAS Component Configuration Tasks  

For Applications in...	Follow These Configuration Tasks...
J2SE Environments	Performing Configuration Tasks Common to J2SE and J2EE Environments Performing Configuration Tasks Unique to J2SE Environments
J2EE Environments	Performing Configuration Tasks Common to J2SE and J2EE Environments Performing Configuration Tasks Unique to J2EE Environments

Sample Files

Configuration tasks in this chapter require that you either create or edit certain configuration or deployment descriptor files. To make this task easier, sample configuration files are provided. Copy and edit these files as described in this chapter with values appropriate to your development or runtime environment.

These files are located in the $ORACLE_HOME/j2ee/home/config directory.

• jazn.xml

  JAAS property file

• jazn-data.xml

  Default JAAS datafile for using an XML-based provider

• java2.policy

  The Java2 policy file

  The following are application-specific deployment descriptor files you may need to modify:

• orion-application.xml

• orion-web.xml

• web.xml

Performing Configuration Tasks Common to J2SE and J2EE Environments

J2SE and J2EE environments require several similar configuration tasks. Complete these tasks to configure JAAS components for applications developed in J2SE and J2EE environments.

• Task 1: Ensure That You Installed the Correct Components

• Task 2: Load the JAZN Schema and Default Entries into Oracle Internet Directory (Optional)

• Task 3: Specify JAAS as the Policy Provider (optional)

• Task 4: Configure a Java2 Policy File (optional)

• Task 5: Create a LoginModule Configuration File (optional)

  If your application runs in the J2EE environment, then perform this task only if you do not need your application to be SSO-enabled.

• Task 6: Perform Configuration Tasks Unique to Your Java Environment

Task 1: Ensure That You Installed the Correct Components

Table 7-2 identifies required components for J2SE and J2EE environments. Ensure that you have installed the correct components for your environment.

Table 7-2 Components Required for J2SE and J2EE Environments  

Component	Required For J2SE?	Required For J2EE?
Java Authentication and Authorization Service (JAAS)	Yes	Yes
JDK 1.3	Yes	Yes
JAAS support, which includes JAZNUserManagerFoot 1 and a provider for storing realms, users, roles, and policy. Depending on your 9iAS installation type, you have either the default provider type or a choice of two types: XML-based provider type, the default, available with both installation types, Oracle9iAS Infrastructure and Oracle9i Application Server LDAP-based provider type, Oracle Internet Directory, available with Oracle9iAS Infrastructure installation type only. If Oracle Internet Directory is used, this guide assumes that you have already: Installed Oracle Internet Directory Run Oracle Internet Directory Configuration Assistant to load Oracle Internet Directory schema into the directory Created users and roles with the Delegated Administration Service (DAS)	Yes	Yes
Oracle9iAS Containers for J2EE (OC4J)	No	Yes
Oracle9iAS Single Sign-On (for SSO-enabled applications) This guide assumes that you have already: Installed Oracle9iAS Single Sign-On Loaded required database objects into a repository	No	YesFoot 2
RealmLoginModule or other login module Authenticates the user name and password of a client user attempting to access an application. The RealmLoginModule is part of Oracle's proprietary Realm API package (oracle.security.jazn.realm). RealmLoginModule can be used in non-SSO environments.	No	No
Oracle HTTP Server, which includes:	No	Yes
mod_oc4j	No	Yes
mod_osso (for SSO-enabled applications)	No	Yes
mod_ossl (for SSL-enabled applications)	No	Yes

1 JAZNUserManager functionality is provided for J2EE environments only. 2 If you want your applications to be SSO-enabled in J2EE environments, use Oracle9iAS Single Sign-On.

See Also: Oracle9i Application Server Installation Guide in the Oracle9iAS Platform-specific Documentation for installation and postinstallation tasks

Task 2: Load the JAZN Schema and Default Entries into Oracle Internet Directory (Optional)

These configuration steps pertain only to LDAP-based environments. If you decide to use the LDAP-based Oracle Internet Directory as your provider type, then you must run the scripts described in this section. These scripts load the JAZN schema and default entries.

Note: Use JAAS support with the version of Oracle Internet Directory available through the Oracle9iAS Infrastructure installation type of Oracle9i Application Server release 2 (9.0.2). Older versions of Oracle Internet Directory must first be upgraded to this version in order to work with JAAS. If you have installed Oracle9iAS Infrastructure, then the following steps 1 through 4 are unnecessary because these configuration steps are performed when the infrastructure is installed. However, step 5 to load the demo data only is still required. If you have not installed the infrastructure and want to use Oracle Internet Directory as your provider type, then you must perform steps 1 through 5. In this case, use the script in step 5 that loads both the JAZN schema and the demo data.

To load the JAZN schema and default entries into Oracle Internet Directory:

1. Obtain the following information about Oracle Internet Directory:

   Element	Description
   ldaphost	Host name of the computer on which Oracle Internet Directory is installed
   ldapport	Port number for Oracle Internet Directory (default value is 389)
   binddn	Bind distinguished name; the default value is cn=orcladmin
   passwd	Bind password; the default password is welcome
   OracleContextDN	Distinguished name of the Oracle site context

   This information is used to configure JAAS support with Oracle Internet Directory in steps 4 through 5.

2. Go to the computer on which JAAS support is installed.

3. Go to the $ORACLE_HOME/jazn/install directory.

4. Run the generateldif.sh script to generate the .ldif files that are required by JAAS. These LDIF (LDAP Data Interchange Format) files are used to add the JAZN LDAP schema and demo data in the directory. Use the following syntax:

   generateldif.sh -b cn=OracleContextDN
   
   

   where OracleContextDN is the distinguished name of the Oracle site context.

5. If you are running a version of Oracle Internet Directory that is not available with Oracle9iAS Infrastructure release 2 (9.0.2), you must first upgrade Oracle Internet Directory to this version. After that, run the following scripts to load the JAZN schema and demo data using the .ldif files generated in step 4:

   To load the demo data only, run the script with the following arguments:

   postinstall.sh -h ldaphost -p ldapport -D binddn -w password
   
   

   To load everything (the JAZN schema and the demo data), run the script with the following arguments:

   postinstall.sh -h ldaphost -p ldapport -D binddn -w password -load All
   
   

Task 3: Specify JAAS as the Policy Provider (optional)

You must specify JAAS as the policy provider for JAAS if it has not been configured automatically. Configuration is automatic if you use the JVM shipped with Oracle9i Application Server.

To specify JAAS as the policy provider:

1. Add the following information to the end of the $JAVA_HOME/jre/lib/security/java.security file:

   auth.policy.provider=oracle.security.jazn.spi.PolicyProvider
   login.configuration.provider=oracle.security.jazn.spi.LoginConfigProvider
   

Task 4: Configure a Java2 Policy File (optional)

Note: This task is required only when the Java Security Manager is enabled.

The Java2 policy file grants permissions to the trusted codes or applications that you run. This enables these codes or applications to access Oracle support for JAAS, JAAS, or JDK APIs requiring specific access privileges.

A preconfigured Java2 policy (java2.policy) has been provided in $ORACLE_HOME/j2ee/home/config with grants necessary to launch OC4J with SecurityManager enabled.

You need to modify the Java2 policy file to grant permissions to trusted codes or applications.

For example, the following section of a java2.policy file grants java.security.AllPermission to the trusted codes jazn.jar and an application named appdemo_runtime.jar running in the $ORACLE_HOME/appdemo directory:

/* grant the JAZN library AllPermission */ 
grant codebase "file:/Oracle/OraHome/lib/jazn.jar" { 
    permission java.security.AllPermission; 
}; 

/* 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"; 

Task 5: Create a LoginModule Configuration File (optional)

Oracle support for JAAS fully complies with the J2EE JAAS specification so users can plug in any LoginModule implementation, if desired. RealmLoginModule is just one implementation that is included with JAAS for Oracle9iAS.

The jazn-data.xml file enables the RealmLoginModule class. The RealmLoginModule class authenticates user login credentials before the user can access:

• J2SE applications

• J2EE applications that do not use the SSO feature

  If you want to use SSO authentication with your application, do not perform this task. See "Performing Configuration Tasks Unique to J2EE Environments" for SSO configuration tasks.

To enable the RealmLoginModule class, perform the following step:

Use a text editor to modify the login configuration file jazn-data.xml where needed.

The default configuration for the RealmLoginModule class setting in the jazn-data.xml file is as follows:

<!DOCTYPE jazn-data (View Source for full doctype...)>
- <jazn-data>
   .
   .
   .
<!-- Login Module Data -->
- <jazn-loginconfig>
 - <application>
     <name>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>

See Also: The JAAS Provider API Reference (Javadoc) is located in the Oracle9iAS Documentation Library

Task 6: Perform Configuration Tasks Unique to Your Java Environment

The configuration tasks that must be performed next depend on the environment in which the application runs, as indicated in Table 7-3.

Table 7-3 Configuration Tasks Unique to Your Java Environment  

For...	Go To...
J2SE Environments	"Performing Configuration Tasks Unique to J2SE Environments"
J2EE Environments	"Performing Configuration Tasks Unique to J2EE Environments"

Performing Configuration Tasks Unique to J2SE Environments

Perform these configuration tasks after the configuration tasks described in "Performing Configuration Tasks Common to J2SE and J2EE Environments".

Task 1: Configure the JAAS Property File

Configure the JAAS property file, jazn.xml, in the $ORACLE_HOME/j2ee/home/config directory, according to the provider environment type being used:

• Task 1a: Configure the LDAP-Based Provider Type for J2SE

• Task 1b: Configure the XML-Based Provider Type for J2SE

Task 1a: Configure the LDAP-Based Provider Type for J2SE

If you enable Oracle9iAS Single Sign-On by installing the Oracle9iAS Infrastructure, which installs and automatically configures the Single Sign-On server, Oracle Internet Directory, and Oracle Enterprise Manager, then you do not need to perform this task. The following steps for manually configuring the LDAP-based provider type are included in the following section for your reference only. These steps can be performed if you need to configure another LDAP-based provider.

1. Modify the preconfigured jazn.xml file using the following example:

   <jazn provider="LDAP" location="ldap://orclcomp-sun.us.oracle.com:389">  
   </jazn>
   
   

   For this example, orclcomp-sun.us.oracle.com is the LDAP-based URL being used.

   Additional attributes and property names can also be set. jazn.xml permits the following attribute settings:

   Attribute	Status	Value
   provider	Optional	LDAP (default is XML)
   location	Required	An LDAP server. For example: ldap://orclcomp-sun.us.oracle.com:389

   jazn.xml permits the following property name settings. If you want to permit anonymous, read-only logins to the application, do not set and assign values to these property names.

   Property Name	Status	Value
   ldap.user	Optional	A valid LDAP user name or DN. For example: orcladmin or cn=orcladmin
   ldap.password	Optional	An obfuscated password for the LDAP user name. For example: QJ+w7NJUlm=
   ldap.cache.enable	Optional	Setting this property name to "true" enables an LDAP cache feature that is implemented based on a simple TTL (time-to-live) expiration algorithm. When it is enabled, calling Policy.grant/revoke results in an UnsupportedOperationException. If you need to manage the JAZN policy, then you must disable caching (the default setting).

   The following example shows a jazn.xml file with all attributes and property names specified.

   <jazn   provider="LDAP" 
           location="ldap://orclcomp-sun.us.oracle.com:389" >
           <property name="ldap.user" value="orcladmin" />
           <property name="ldap.password" value="QJ+w7NJUlm=" />
   

   <property name="ldap.cache.enable" value="true" />
   

   </jazn>
   
   

   Note: If you do not want to obfuscate the password entry in jazn.xml, place an exclamation point in front of the password value (!). For example: <property name="ldap.password" value="!welcome" />

Task 1b: Configure the XML-Based Provider Type for J2SE

The jazn.xml file is preconfigured as follows:

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

Additional attributes and property names can also be set. jazn.xml permits the following attribute settings:

Attribute	Status	Values
provider	Optional	XML (Default) LDAP
location	Required	Path to file. For example: ./jazn-data.xml This can be an absolute path, or a path relative to the jazn.xml file, where the JAAS provider first looks for the jazn-data.xml in the directory containing the jazn.xml file.
persistence	Optional	NONE Changes do not persist ALL Changes persist after every modification VM_EXIT (Default) Changes persist when VM exits
xml.credentials.auto.obfuscate	Optional	ON OFF

The following example shows a jazn.xml file with all attributes specified.

<jazn   provider="XML" 
        location="./jazn-data.xml" 
        persistence="ALL"
        xml.credentials.auto.obfuscate="ON">
</jazn>

Performing Configuration Tasks Unique to J2EE Environments

Perform these configuration tasks after the configuration tasks described in "Performing Configuration Tasks Common to J2SE and J2EE Environments".

• Task 1: Configure the JAAS Provider and Enable the JAZNUserManager

• Task 2: Configure an Authentication Method and Filter Modes

• Task 3: Configure Your Application for SSL Environments

• Task 4: Configure mod_oc4j to Delegate HTTP Requests to OC4J

• Task 5: Configure the Security Role (run-as)

Task 1: Configure the JAAS Provider and Enable the JAZNUserManager

Configure the JAAS and enable the JAZNUserManager through the OC4J-specific configuration file, orion-application.xml. Indicate the JAAS environment type and related information:

• Task 1a: Configure the LDAP-Based Provider Type for J2EE (Optional)

• Task 1b: Configure the XML-Based Provider Type for J2EE

Task 1a: Configure the LDAP-Based Provider Type for J2EE (Optional)

If you enable Oracle9iAS Single Sign-On by installing the Oracle9iAS Infrastructure, which installs and automatically configures the Single Sign-On server, Oracle Internet Directory, and Oracle Enterprise Manager, then you do not need to perform this task. The following steps for manually configuring the LDAP-based provider type are included in the following section for your reference only. These steps can be performed if you need to configure another LDAP-based provider.

Specifying the default-realm in orion-application.xml is necessary if there is more than one realm registered. In a hosted environment, where Oracle9iAS Single Sign-On and Oracle Internet Directory are enabled, specifying the default realm is optional. In this situation, JAAS reads the subscriber information from the HTTP header (the attributes that are set by mod_osso). These header attributes provide JAAS with the realm information, which represents the subscriber.

Configure the JAAS to use LDAP-based Oracle Internet Directory by adding an entry to the orion-application.xml file similar to the following example:

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

This information identifies the LDAP-based Oracle Internet Directory URL (for this example, orclcomp-sun.us.oracle.com), the default realm (sample_subrealm.

Additional attributes and property names can also be set. The following attributes can be set in orion-application.xml:

Attribute	Status	Value
provider	Required	LDAP
location	Optional if jazn.xml file configured, otherwise Required	An LDAP server. For example: ldap://orclcomp-sun.us.oracle.com:389
default-realm	Optional (unnecessary if only one realm is configured)	A realm name. For example: sample_subrealm

The following property names can be set in orion-application.xml. If you want to permit anonymous, read-only logins to the application, do not set and assign values to these property names.

Property Name	Status	Value
ldap.user	Optional	A valid LDAP user name or DN. For example: orcladmin or cn=orcladmin
ldap.password	Optional	An obfuscated password for the LDAP user name. For example: QJ+w7NJUlm=
ldap.cache.enable	Optional	Setting this property name to "true" enables an LDAP cache feature that is implemented based on a simple TTL (time-to-live) expiration algorithm. When it is enabled, calling Policy.grant/revoke results in an UnsupportedOperationException. If you need to manage the JAZN policy, then you must disable caching (the default setting).

A sample orion-application.xml file with all attributes and property names specified is provided in "orion-application.xml file".

Note: If you do not want to obfuscate the password entry, place an exclamation point (!) in front of the password value: !welcome

See Also: "Task 2: Configure an Authentication Method and Filter Modes" for information on the benefits of setting auth-method, runas-mode, and doasprivileged-mode.

Task 1b: Configure the XML-Based Provider Type for J2EE

Configure the JAAS to use the XML-based provider type by adding the following entry to the orion-application.xml file:

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

Additional attributes and property names can also be set. orion-application.xml permits the following attribute settings:

Attribute	Status	Value
provider	Optional	XML (Default)
location	Optional if jazn.xml file configured, otherwise Required	Path to file. For example: ./jazn-data.xml This can be an absolute path, or a path relative to the jazn.xml file, where the JAAS Provider first looks for the jazn-data.xml in the directory containing the jazn.xml file.
persistence	Optional	NONE Do not persist changes ALL Persist changes after every modification VM_EXIT (Default) Persist changes when VM exits
default-realm	Optional (if only one realm is configured)	A realm name. For example: sample_subrealm

The following property names can be set in orion-application.xml:

Property Name	Status	Value
xml.permclsmgr.enable	Optional	true Enables the JAAS Permission Class Management feature false (Default) Disables the feature
xml.princlsmgr.enable	Optional	true Enables the JAAS Principal Class Management feature false (Default) Disables the feature

A sample orion-application.xml file with all attributes and property names specified is provided in "orion-application.xml file".

See Also: Part 2, Chapter 3 of the OC4J Services Guide in the Oracle9iAS Documentation Library for information on authentication environments "Task 2: Configure an Authentication Method and Filter Modes" for information on the benefits of setting auth-method, runas-mode, and doasprivileged-mode

Task 2: Configure an Authentication Method and Filter Modes

Integrate the JAAS with the type of authentication method you want to use:

• Single sign-on (SSO), with either single or multiple JAAS Web applications

• Secure Socket Layer (SSL)

• Basic Authentication

In addition to the authentication method, you can also use the filter element of JAZNUserManager and configure the optional runas-mode and doasprivileged-mode features. The filter is configured by the <jazn-web-app> element.

runas-mode and doasprivileged-mode include the following range of values for the orion-web.xml and orion-application.xml files:

Table 7-4 runas-mode and doasprivileged-mode Settings  

If runas-mode is Set To...	If doasprivileged-mode Is Set To...	Then...
true	true (default)	Subject.doAsPrivileged in a privilegedExceptionAction block that calls chain.doFilter (myrequest,response)
true	false	Subject.doAs in a privilegedExceptionAction block that calls chain.doFilter (myrequest,response)
false (default)	true	chain.doFilter (myrequest,response)
false	false	chain.doFilter (myrequest,response)

See Also: Part 2, Chapter 3 of the OC4J Services Guide in the Oracle9iAS Documentation Library for information on the following: Authentication environments The filter element of JAZNUserManager Using the JAAS after completing these configuration tasks

The authentication method, as well as the runas-mode, and doasprivileged-mode features are specified in a configuration file. Since it is possible to specify the information in several files, the precedence indicated in Table 7-5 prevails. Specification in the first file overrides specification in the second and so on.

t

Table 7-5 Precedence of Configuration Files for Specifying Authentication Methods

Precedence	Configuration File
1	web.xml
2	orion-application.xml
3	orion-web.xml

orion-web.xml file

Specify your authentication method within the <jazn-web-app> element which enables the filter. In the following example, all three settings are optional:

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

Set auth-method to SSO (single sign-on). If you do not set this parameter, it defaults to null. See Table 7-4 for information on the impact of setting runas-mode and doasprivileged-mode.

orion-application.xml file

Specify your authentication method within the <jazn-web-app> element of the <jazn> element. The <jazn-web-app> element enables the filter. For example:

<jazn provider="XML" 
        location="jazn-data.xml" 
        default-realm="JAZN.com" 
        persistence="ALL">

        <!-- default values for this application -->
        <jazn-web-app
                auth-method="SSO" 
                runas-mode="true"
                doasprivileged-mode="true"
        />
        <property name="xml.princlsmgr.enable" value="true" />
        <property name="xml.permclsmgr.enable" value="true" />
</jazn>

All three settings in bold are optional. Set auth-method to SSO. If you do not set this parameter, it defaults to null. See Table 7-4 for information on the impact of setting runas-mode and doasprivileged-mode.

web.xml

Specify your authentication method within the <login-config> element. For example:

<login-config>
        <auth-method>BASIC</auth-method>
</login-config>

Enter the following:

• BASIC or FORM to use basic authentication

• DIGEST to use digest authentication

• CLIENT-CERT to use SSL authentication

You cannot set runas-mode or doasprivileged-mode in this file. If they are required, configure runas-mode or doasprivileged-mode in the appropriate file: orion-application.xml or orion-web.xml. Be careful to maintain the desired precedence.

Task 3: Configure Your Application for SSL Environments

Note: If you are using basic authentication, then do not perform this configuration task. If you require Oracle9iAS Single Sign-On, then install the Oracle9iAS Infrastructure to automatically perform the necessary configuration tasks to enable single sign-on.

If you require SSL, then perform the following steps:

When you configure an application to run in an SSL environment, you must

• Set the port in the httpd.conf file

• Specify the server wallet directory and password. The server wallet contains the server's certificate, private key, and trusted certificates.

• Set SSL to on in the mod_oc4j.conf file

To configure an application for the SSL environment:

1. Uncomment the following lines in the httpd.conf file. If these lines are not in the httpd.conf file, add them.

   LoadModule ossl_module        libexec/mod_ossl.so 
   

   
   
   <IfDefine SSL>
     Port 80
     Listen 80
     Listen 443
   </IfDefine>  
   
   <VirtualHost _default_:443>  
   
   

   Note: SSL typically uses port 443. If this port is currently being used by a different process, change this port number in both places to one currently not being used.

2. Specify the server wallet file directory:

   SSLWallet file:/wallet_file_directory 
   
   

3. Add $ORACLE_HOME/lib to the LD_LIBRARY_PATH environment parameter.

4. Either use a clear text wallet password or use the iasobf utility to create an encrypted server wallet password. The iasobf utility is located in the Apache/Apache/bin directory.

5. Uncomment the following line and specify the server wallet password created in step 4.

   #SSLWalletPassword password 
   
   

6. Uncomment the following line:

   #SSLOptions +FakeBasicAuth +ExportCertData +CompatEnvVars +StrictRequire
   
   

7. If you also want to use client certificate authentication, uncomment the following line and change SSLVerifyClient from none to require or optional.

   #SSLVerifyClient require
   

   Note: You must also configure your Web browser by adding the client certificate.

8. Go to the mod_oc4j.conf file.

9. Uncomment the following line and set Oc4JExtractSSL to On. If this line is not in mod_oc4j.conf, then add it.

   #Oc4jExtractSSL On
   
   

   See Also: "Using Secure Sockets Layer (SSL) to Authenticate Users" for information about using the Oracle HTTP Server configuration directives for enabling SSL.

Task 4: Configure mod_oc4j to Delegate HTTP Requests to OC4J

To configure mod_oc4j to delegate HTTP requests to OC4J, you must add mount directives to the mod_oc4j.conf file. Use the following steps:

1. Go to $ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf.

2. Add the following lines. For this example, the application starts with the URI "reports."

   Oc4jMount /reports
   Oc4jMount /reports/*
   
   

3. Save your changes and exit mod_oc4j.conf.

Task 5: Configure the Security Role (run-as)

You can map J2EE security roles to JAAS roles by way of OC4J groups. This enables your application to run with the privileges of the security role or specific RealmPrincipal class. The following tasks pertain to both kinds of privileges; additional information appears on "RealmPrincipal Class".

If the run-as element is specified, the <role-name> maps to a security role already defined for the Web application.

The following steps assume that sr_manager has already been defined as a security role in web.xml as follows:

<security-role>
   	<role-name>sr_manager</role-name>
</security-role> 

To map J2EE security roles to JAAS roles:

1. Specify the run-as element within the <servlet> tag to run as the specific J2EE security role or specific RealmPrincipal class in the web.xml file

   For example, to run as the security role sr_manager:

   <servlet> 
     <servlet-name>DevGroup</servlet-name> 
     <servlet-class>DevGroupServlet</servlet-class> 
    <!--  run as security role "sr_manager" --> 
       <run-as> 
         <role-name>sr_manager</role-name> 
       </run-as> 
   </servlet>
    
   

2. Define a JAAS role element in the jazn-data.xml file:

   For example, developer is defined a role:

           <roles>
                   <role>
                          <name>developer</name>
                          <members>
                                 <member>
                                          <type>user<type>
                                          <name>john<name>
                                  </member>
                           </members>
                   </role>
            </roles>
   
   

   The jazn-data.xml file is discussed in Part 2, Chapter 4 of the OC4J Services Guide.

3. Integrate the definitions created in Step 1 and Step 2 using OC4J groups in the orion-application.xml file as follows:
   • Map the role-name defined in the web.xml file as a security role (sr_manager)

   • Map the role defined in jazn-data.xml as a OC4J group name (developer)

   For example, the sr_manager security role is mapped to the group named developer in the JAAS Provider:

   <security-role-mapping name="sr_manager">
      		<group name="developer" />
   	</security-role-mapping>
   
   

Because the developer group is mapped to the J2EE security role sr_manager, the user (john in this example) has access to the application resources defined by the sr_manager role.

RealmPrincipal Class

When the <role-name> element is set to a RealmPrincipal class name, the <description> element can also be set. For example:

<role-name>jazn.com/john</role-name> 
<description>oracle.security.jazn.spi.xml.XMLRealmUser </description> 

where jazn.com is the realm and the RealmPrincipal class name is john.

The filter attempts to look up the RealmPrincipal class object mapping to the security role (defined in the <description> element) and adds it to the subject.

If no mapping is found, the filter gets the RealmPrincipal class object based on the <role-name> element and optional <description> (RealmPrincipal class name) element, and adds it and its granted roles to the subject.

See Also: Java Servlet Specification Version 2.3 Part 2, Chapter 6, "Developing Secure J2EE Applications" of the OC4J Services Guide in the Oracle9iAS Documentation Library Part 2, Chapter 3, "Integrating Oracle9iAS JAAS with Java2 Applications" of the OC4J Services Guide in the Oracle9iAS Documentation Library

Differences between <jazn> Tags and the <user-manager> Property

The <jazn> tags are very similar to the <user-manager> property and currently either can be used to configure Oracle support for JAAS. However, the following important reasons make using the <jazn> tags the preferred way to configure JAAS:

• <jazn> tags, which include <jazn>, <jazn-web-app>, can specify a greater range of functionality than that specified with the <user-manager> property.

• <jazn> tags are more secure because they support password obfuscation.

• <jazn> tags are easier to use.

• The <user-manager> property will not be supported beyond this current release of Oracle9i Application Server.

Consequently, Oracle Corporation recommends that <jazn> tags be used whenever possible.

Note: Currently, the <user-manager> property is only used when applications are deployed with the Oracle9iAS Containers for J2EE (OC4J) Deploy Application wizard, a GUI tool for deploying J2EE applications.

As previously described, the <jazn> tag is very similar to the <user-manager> property. When you transform the attributes of <jazn> tag into the properties of <user-manager>, that results in an almost equivalent configuration. For example, the attributes of the <jazn> tag compare to the properties of <user-manager> as follows:

<jazn> Tag Attribute Names	<user-manager> Properties
provider	provider.type
location	location
default-realm	realm-default
persistence	persistence
config	config

Similary, the attributes of the <jazn-web-app> tag compare to the properties of <user-manager> as follows:

<jazn-web-app> Tag Attribute Names	<user-manager> Properties
runas-mode	runas.mode
doasprivileged-mode	doasprivileged.mode
auth-method	authentication.method

See Also: Oracle9iAS Containers for J2EE Services Guide in the Oracle9iAS Documentation Library for more information about <jazn> tags and how to use them.