3
Configuring And Deploying the JAAS Provider

This chapter describes the configuration tasks you must perform to use the Java Authentication and Authorization (JAAS) Provider in a Java 2 Platform, Enterprise Edition (J2EE) environment under Oracle Application Server Containers for J2EE (OC4J). It also has a high-level overview of J2EE and OC4J deployment descriptors. This chapter contains these topics:

• LDAP-Based Provider Environment Settings

• J2EE Deployment Descriptors

• OC4J Deployment Descriptors

• JAAS Provider Configuration Files

• Specifying Authentication (auth-method)

• Configuring Servlet Authorization (runas-mode and doasprivileged-mode) in <jazn-web-app>

• Mapping Security Roles In Servlets (run-as)

• Configuring RealmLoginModule

• Configuring the JAAS Provider To Use SSL With Oracle Internet Directory

• Configuring For EJB RMI Client Access

• Configuring Caching (LDAP-Based Provider Only)

• Specifying a UserManager In orion-application.xml

  Notes: This chapter does not describe how to configure OC4J as a whole. See the Oracle Application Server Containers for J2EE User's Guide for those instructions. To use the LDAP provider, you must install Oracle Application Server and Oracle Internet Directory (OID). For details, see the Oracle Application Server 10g Installation Guide.

Before using your JAAS-based application, you must configure the JAAS Provider components. This chapter discusses configuring JAAS in an OC4J and J2EE environment.

LDAP-Based Provider Environment Settings

The JAAS LDAP-based provider depends on the OID client library ldapjclnt9.jar in the directory:

[ORACLE_HOME]/jlib

The OID client library depends on a native library (for example, libldapjclnt9.so in Solaris) in the directory:

[ORACLE_HOME]/lib

These dependencies affect how you launch the JAZN Admintool, especially when you are using the LDAP-based provider. Before launching the Admintool, you must:

• Ensure that your classpath contains:

  [ORACLE_HOME]/jlib/ldapjclnt9.jar
  
  
  
  

• Ensure that the operating-system-specific environment variable controlling loading of dynamic libraries (for example, LD_LIBRARY_PATH in Solaris) includes:

  [ORACLE_HOME]/lib 
  
  

When you manage OC4J with the Enterprise Manager, it sets these two variables automatically.

J2EE Deployment Descriptors

J2EE provides the following XML deployment descriptors that have security implications:

Table 3-1 J2EE Deployment Descriptors

Filename	Security Tags
web.xml	For Web applications, servlets, and Gasps, module-level security roles, security constraints, and authorization constraints
ejb-jar.xml	For EJBs, module-level and method-level security roles, security constraints, and authorization constraints
application.xml (the file contained in an application's EAR file)	For applications, application-level descriptors for multiple modules

Note: For a full discussion of these descriptors, see the Oracle Application Server Containers for J2EE User's Guide; this chapter discusses only the security-related aspects of these descriptors.

OC4J Deployment Descriptors

OC4J provides the following container-specific XML deployment descriptor files that have security implications:

Table 3-2 OC4J Configuration Files

File	Security-related Tags
The global application.xml	mappings, user manager, <jazn>, <security-role-mapping>, <jazn-web-app> embedded in <jazn>.
orion-web.xml	<jazn-web-app>
orion-application.xml	<jazn> tag, <jazn-web-app> embedded in <jazn> .

JAAS Provider Configuration Files

The JAAS provider stores configuration information in various files; sample configuration files are provided with the product. You edit the JAAS Provider configuration files using the JAZN Admintool or manually, using a text editor.

Caution: If you edit these configuration files manually and you are not running OC4J standalone, you must run dcmctl updateconfig to propagate your changes throughout the cluster.

You configure the JAAS Provider in all of the files listed in Table 3-2, as well as in the following JAAS-specific files:

• jazn.xml

  The JAAS Provider configuration file; this specifies the default configuration for the JAAS provider, including whether the provider is LDAP-based (uses OID as the data store) or XML-based (uses jazn-data.xml as the data store).

• jazn-data.xml

  The XML-based provider stores user, role, and policy information in this file; you edit it with the JAZN Admintool.

  Note: If you use the LDAP-based provider, you use DAS to manage users and groups. See the Oracle Internet Directory Administrator's Guide. for details.

• java2.policy

  The standard Java 2 policy file granting permissions to codebases. This file is located in $ORACLE_HOME/j2ee/home/config.

Specifying JAAS as the Policy Provider (Optional)

If you use the JVM shipped with Oracle Application Server 10g, the Oracle 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. By default, the JVM uses the Sun JAAS provider.

To specify the JAAS Provider 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
   

Locating jazn.xml

The file jazn.xml is the configuration file for both the XML-based and LDAP-based JAAS providers. The JAAS Provider must locate a valid jazn.xml file before it can begin running.

When the JAAS provider starts up, it searches for jazn.xml in order through the directories specified by:

1. oracle.security.jazn.config (system property)

2. java.security.auth.policy (system property)

3. $J2EE_HOME/config ($J2EE_HOME is specified by the system property oracle.j2ee.home)

4. $ORACLE_HOME/j2ee/home/config ($ORACLE_HOME is specified by the system property oracle.home)

5. ./config

The JAAS provider stops searching after locating a jazn.xml file. If no file is found, you receive the error message "JAZN has not been properly configured."

The <jazn> Tag

You use the <jazn> tag to configure the JAAS Provider. The <jazn> tag can appear in any of the following locations

• The application's orion-application.xml

• The global application.xml

• jazn.xml

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

The tag supports different attributes depending on whether you are using the XML-based Provider or the LDAP-based provider. This section discusses the two separately, in the following sections:

• The <jazn> Tag and the XML-Based Provider

• The <jazn> Tag and the LDAP-Based Provider

• The <property> Subelement Of <jazn>

  Note: You cannot edit the <jazn> tag using Enterprise Manager.

The <jazn> Tag and the XML-Based Provider

When you are using the XML-based Provider, the <jazn> tag supports the attributes shown in Table 3-3.

Table 3-3 (XML-Based Provider) The <jazn> Tag In orion-application.xml

Attribute	Value (default is bold)	Example
provider	XML or LDAP	provider="XML"
location	(Required) Path to file containing provider data. This can be an absolute path, or a path relative to the jazn.xml file. The JAAS Provider first looks for jazn-data.xml in the directory containing jazn.xml.	location="./jazn-data.xml"
persistence	NONE Do not persist (write) changes to jazn-data.xml. ALL Persist changes after every modification. VM_EXIT Persist changes when JVM exits.	persistence="ALL"
default-realm	The realm used whenever an authentication or authorization request does not specify a realm explicitly. This attribute is not needed if you have configured only one realm in the repository.	default-realm="myrealm"
config	If a config attribute appears, the JAAS provider reads all provider properties from the file specified in the pathname. This attribute cannot be combined with any other attribute; it must appear alone.	config="./jazn.xml"

See: "Specifying Authentication (auth-method)" for information on the <jazn-web-app> element and its attributes auth-method, runas-mode, and doasprivileged-mode.:

The <jazn> Tag and the LDAP-Based Provider

You configure your application to use LDAP-based provider by adding an entry to the orion-application.xml file similar to the following example:

<jazn provider="LDAP"/> 
 

This assumes that the OC4J instance has been properly associated with OID using either the installer or Enterprise Manager.

When you associate an OC4J instance with an Oracle Application Server Infrastructure (including the Oracle Internet Directory (OID)), your application can leverage the LDAP-based provider for central management of users. You can specify the use of the LDAP-based provider in several different configuration files (see Chapter 3, "Configuring And Deploying the JAAS Provider" of the Oracle Application Server Containers for J2EE Security Guide)

If you specify the LDAP-based provider globally in the application.xml configuration file, then you must set up the following users and groups in OID DAS:

• An administrators group

• An admin user that is a member of the administrators group

You must then grant the following permissions to the administrators group using the JAZN Admintool:

• com.evermind.server.AdministrationPermission ("administration")

• com.evermind.server.rmi.RMIPermission("login")

You can set additional attributes and properties. The <jazn> tag in orion-application.xml has the attributes shown in Table 3-4.

Table 3-4 (LDAP-Based Provider) The <jazn> Tag in orion-application.xml

Attribute	Value (default is bold)	Example
provider	XML or LDAP (this attribute can also be specified	provider="LDAP"
location	The URL of an LDAP server.	Avoid using. See Note.
default-realm	The realm used whenever an authentication or authorization request does not specify a realm explicitly. This attribute is not needed if you have configured only one realm.	default-realm="us"
config	If a config attribute appears, the JAAS provider reads all provider properties from the file specified in the pathname. This attribute cannot be combined with any other attribute; it must appear alone.	config="configpath"
persistence	ALL Persist changes after every modification. "The LDAP-based Provider always sets this value to ALL.

Notes: If you do not specify the provider attribute in the <jazn> tag in orion-application.xml, you can specify it in jazn.xml. The provider and location attributes can be edited using Enterprise Manager; all other attributes must be edited by hand. The JAAS LDAP-based provider does not depend on the location attribute in the <jazn> element. If you do not specify this attribute (it is not specified by default), then the JAAS runtime obtains infrastructure information from configured system settings. The system settings are configured when you use Enterprise Manager to associate a mid-tier to an infrastructure. To take advantage of this feature, we recommend that you do not set the location attribute in the <jazn> element in any JAAS configuration files, including jazn.xml and orion-application.xml.

The <jazn> tag can contain a <jazn-web-app> tag that specifies authentication information.

See: "Specifying Authentication (auth-method)" for information on the <jazn-web-app> element and its attributes auth-method, runas-mode, and doasprivileged-mode.:

If you want to permit anonymous, read-only logins to the application, do not assign values to these attributes.

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

The <property> Subelement Of <jazn>

The <jazn> tag can contain a <property> element. Most of these properties can be set only on a per-VM business, in the global jazn.xml. The only exceptions are ldap.password and ldap.user. The syntax of the <property> subelement is:

<property name="propname" value="propvalue">

Table 3-5 lists the supported properties.

Table 3-5 Values For <property> Element of <jazn> Tag

Property Name	Default	Value
classpath		This property, when set, tells the JAAS Provider where to look for third-party classes and JAR files if they cannot be found elsewhere. classpath="./loginmodules"
external.synchronization	false	When set to true, the XML-based JAAS Provider monitors its data repository (normally jazn-data.xml) for external updates. When you add new users outside your application (for example, by using the Admintool), these users will be picked up automatically by OC4J. If you do not set this property, you must stop and restart OC4J in order to make the new users visible. Set to false for production environments.
role.mapping.dynamic	false	role.mapping.dynamic="true" When set to true, the JAAS Provider does authorization checks based on the current Subject instead of using static configurations. When set to false, the JAAS Provider uses static configurations as the basis for authorization checks.
jndi.ctx_pool.init_size	5	Initial size for JNDI/LDAP connection pool.
jndi.ctx_pool.inc_size	10	Pool increment size for JNDI/LDAP connection pool -- number of connections added to pool whenever the supply of connections in the pool is exhausted.
ldap.cache.*	See "Configuring the JAAS Provider To Use SSL With Oracle Internet Directory" and Table 3-9 for details.
ldap.connect.max.retry	5	Number of times the JAAS Provider attempts to create an LDAP connection before giving up.
ldap.connect.sleep	5000	Number of milliseconds the JAAS Provider waits before retrying a failed LDAP connection attempt.
ldap.password		Obfuscated password for the LDAP user name. For example: {903}oZZYqmGc/iyCaDrD4qs2FHbXf3LAWtMN See "Password Obfuscation In jazn-data.xml and jazn.xml" for details on obfuscation.
ldap.user		LDAP username or DN. For example: orcladmin or cn=orcladmin
ldap.walletloc		Pathname for the Oracle Wallet.
ldap.walletpwd		Obfuscated password for the Oracle Wallet. See "Password Obfuscation In jazn-data.xml and jazn.xml" for details on obfuscation.

Notes: To specify a cleartext ldap.password or ldap.walletpwd entry, place an exclamation point (!) in front of the password value:, as in !welcome. The entry will be automatically obfuscated. When set to false, the XML-based JAAS Provider does not check the file system periodically for external updates to the XML-based data repository. To enable dynamic external synchronization, set the external.synchronization property to true in the <jazn> tag.

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.

Specifying auth-method in web.xml

To specify authentication method at the global level, you use the <login-config> element of web.xml. For example:

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

In web.xml, auth-method can have the values shown in Table 3-6:

Table 3-6 Values for auth-method in web.xml

Setting	Meaning
BASIC (default)	The application uses basic authentication, the standard J2EE authentication.
FORM	The application uses form-based authentication.
DIGEST	The application uses HTTP DIGEST authentication
CLIENT-CERT	The application requires the client to supply its own certificate for use with SSL.

These values can be overridden at the application level by using the <jazn-web-app> element in orion-web.xml or orion-application.xml.

Specifying auth-method in orion-web.xml and orion-application.xml

The auth-method supplied in the top-level <jazn-web-app> element overrides the auth-method in web.xml.

There is only one possible value for the auth-method in orion-web.xml and orion-application.xml: SSO, meaning that the application uses Oracle Single Sign-On.

A sample entry for orion-web.xml would look like:

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

A sample entry for orion-application.xml would look like:

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

Specifying auth-method in orion-application.xml

The auth-method supplied in the <jazn-web-app> element of the <jazn> element overrides the auth-method in web.xml. There are two possible values: SSO, meaning that the application uses Oracle SSO, and BASIC, meaning that the application uses whatever authentication method is specified in web.xml. A sample entry would look like:

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

<!-- default values for this application -->
   <jazn-web-app
      auth-method="SSO" 
    />
</jazn>

Configuring Servlet Authorization (runas-mode and doasprivileged-mode) in <jazn-web-app>

If you want a servlet to be invoked using subject.doAs() or subject.doAsPrivileged(), you must set the runas-mode and doasprivileged-mode attributes of the <jazn-web-app> element in the orion-web.xml or orion-application.xml files.

• subject.doAs() invokes the servlet using the privileges of a particular subject. A subject is defined by an instance of the javax.security.auth.Subject class and includes a set of facts regarding a single entity, such as a person. Such facts include identities and security-related attributes, such as passwords and cryptographic keys. The JAAS Provider passes in the Subject instance in the method call.

  When the doAs() method is used, an AccessControlContext instance is retrieved from the current thread (from the server).

• subject.doAsPrivileged() uses the privileges of a particular subject without being limited by the access-control restrictions of the server.

  When the doAsPrivileged() method is used, the JAAS Provider invokes the method with a null java.security.AccessControlContext instance, in order to start the action fresh and execute the servlet without the restrictions of the current server AccessControlContext instance.

runas-mode and doasprivileged-mode control whether the servlet is invoked with subject.doAsPrivileged() or subject.doAs(). By default, runas-mode is set to false, which means that neither subject.doAsPrivileged() or subject.doAs() is invoked.

Note: runas-mode is unrelated to the servlet.runAs method.

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

If runas-mode is Set To	And doasprivileged-mode Is Set To	Then the servlet is invoked with:
false (default)	true or false	No special privileges

Thus, to have your servlet invoked using subject.doAsPrivileged() you should have a <jazn-web-app> element that looks like this:

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

Mapping Security Roles In Servlets (run-as)

You can map J2EE security roles to JAAS roles using 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.

Note: The run-as element is unrelated to runas-mode.

If the run-as element is specified, then 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 within a role:

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

An XSD schema for jazn-data.xml is provided in Appendix B, "JAAS Provider Schemas".

3. Integrate the definitions created in Step 1 and Step 2. Use 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.

   See Also: Java Servlet Specification, available at http://java.sun.com/products/servlet/download.html Chapter 6, "Security and J2EE Applications"

Configuring 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 SSO authentication.

See Also: Oracle Application Server 10g Installation Guide for SSO configuration tasks.

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

Enabling RealmLoginModule Using A Text Editor

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>

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

Table 3-8 RealmLoginModule Options

Name	Meaning	Default
debug	If set to true, prints debugging messages.	false
addRoles	If set to true, the RealmLoginModule adds all directly granted roles of the user to the Subject after successful authentication.	true
addAllRoles	If set to true, the RealmLoginModule adds all directly or indirectly granted roles of the user to the Subject after successful authentication.	true
storePrivateCredentials	If set to true, the RealmLoginModule adds all private credentials (for instance, password credentials) to the Subject after successful authentication.	false
supportCSIv2	If set to true, the RealmLoginModule supports CSIv2.	false
supportNullPassword	If set to true, the RealmLoginModule does not check to see if the supplied password is null or empty. If set to false, authentication fails if the supplied password is null or empty.	false

See Also: The JAAS Provider Javadoc. "Adding and Removing Login Modules"

Configuring the JAAS Provider To Use SSL With Oracle Internet Directory

This section discusses configuring the JAAS provider to use SSL with OID. For information on how to configure OID to use SSL, see the Oracle Internet Directory Administrator's Guide and Servlet Developer's Guide.

There are three ways to use SSL to communicate with OID:

1. NULL authentication--data are encrypted with the Anonymous Diffie-Hellman cipher suite, but no certificates are used for authentication.

   Note: See Table 11-1, "Cipher Suites Supported By OracleSSL" for a list of supported cipher suites.

2. Server-side authentication only (one-way authentication)--server authenticates itself to client with a digital certificate, but client does not authenticate itself.

3. Client and server authentication (two-way authentication)--both client and server authenticate themselves using digital certificates.

For NULL authentication (case 1), add a <property> tag to the <jazn> tag to specify a protocol (note that you do not specify a wallet location or password, because NULL authentication does not use certificates):

<?xml version = '1.0' encoding = 'UTF-8'?>
<jazn provider="LDAP" location="ldap://pichan-sun.us.oracle.com:5000" 
default-realm="us">

   <property name="ldap.protocol" value="ssl"/>  

</jazn>

<property name="ldap.protocol" value="ssl"/>

For either one-way or two-way authentication (cases 2 and 3), use the <property> tag to specify protocol, wallet location, and wallet password:

<?xml version = '1.0' encoding = 'UTF-8'?>
<jazn provider="LDAP" location="ldap://pichan-sun.us.oracle.com:5000" 
default-realm="us">

   <property name="ldap.protocol" value="ssl"/>  
   <property name="ldap.walletloc" 
value="/private/oracle/oid/ssl2/testwallet.txt"/>
   <property name="ldap.walletpwd" value="!welcome1"/>

</jazn>

Configuring For EJB RMI Client Access

(LDAP-Based Provider Only)

To enable fat client access to EJBs via RMI, you must grant the correct permissions using the JAZN Admintool. You must grant the RMIPermission (login) to your user or role. For example:

java -jar jazn.jar -grantperm myrealm -role administrators \
  com.evermind.server.rmi.RMIPermission login

Configuring Caching (LDAP-Based Provider Only)

The LDAP-based JAAS Provider supports caching, providing improved performance and scalability. There are three separate caches:

• Policy cache, which stores grantees and permissions

• Realm cache, which stores realms, users and roles, and a role graph.

• Session cache, which stores users and role graphs in an HTTP session object. (This cache is available only to web-based clients with cookies enabled.)

The caching service maintains a global HashMap, which is used to store and retrieve cached objects. A daemon thread runs periodically in the background to invalidate and clean up expired objects in the HashMap. Objects in the cache expire based on a time-to-live algorithm; expiration time can be set with the cache properties, described in Table 3-9.

Note: Only the LDAP-based Provider provides these caches. The XML-based Provider defaults to caching the entire XML document.

Session Cache Details

HttpSession objects persist for the duration of the server-side session. An application can terminate a session explicitly, by invoking HttpSession.invalidate(); a container can terminate a session based on the <session-timeout> value.

See Also: The Oracle HTTP Server Administrator's Guide for more information about session support in OC4J.

The default session timeout for the OC4J server is 20 minutes. You can change this default by editing web.xml and changing the <session-timeout>.

<session-config> 
  <session-timeout>10 </session-timeout> 
</session-config> 

The JAAS Provider invokes HttpSession.invalidate() to invalidate the session explicitly as appropriate. For example, when WebSSOUtil.logout() is invoked, the JAAS Provider invalidates the session.

Note: Objects stored in an HttpSession instance must implement the java.io.Serializable interface in order to be deployed with the <distributable /> flag in web.xml.

Disabling Caching

Caching is enabled by default. You should disable the caches when performing management and administrative tasks. In particular:

• Disable the policy cache when managing policy. If the policy cache is enabled, calling Policy.grant() or Policy.revoke() causes an UnsupportedOperationException.

• Disable the realm cache when managing realms. This includes adding realms, dropping realms, granting roles, and revoking roles.

• Disable the session cache when you disable HTTP session cookies.

The following is a sample excerpt from jazn.xml showing how to disable caching:

<jazn provider="LDAP">
   <property name="ldap.user" value="cn=orcladmin"/>
   <property name="ldap.password" 
value="{903}3o4PTHbgMzVlzbVfKITIO5Bgio6KK9kD"\/>
   <property name="ldap.cache.session.enable" 
value="false" />
   <property name="ldap.cache.realm.enable" 
value="false" />
   <property name="ldap.cache.policy.enable" 
value="false" />
</jazn>

Configuration

The following table describes the cache properties and their default values. You can set these properties only at the virtual machine level, in the <jazn> tag in the global jazn.xml file.

Table 3-9 LDAP Cache Properties

Property	Description	Default
ldap.cache.policy.enable (see Note)	If set to true, enables cache; if set to false, disables cache.	true
ldap.cache.realm.enable	If set to true, enables cache; if set to false, disables cache.	true
ldap.cache.session.enable	If set to true, enables cache; if set to false, disables cache.	true
ldap.cache.initial.capacity	Initial capacity for the HashMap.	20
ldap.cache.load.factor	Load factor for the HashMap.	.7
ldap.cache.purge.initial.delay	String containing an integer that represents the number of milliseconds the daemon thread waits before starts checking for expired objects.	3600000
ldap.cache.purge.timeout	The string representation of an integer that represents the number of milliseconds an object remains in cache before being invalidated and removed. It is also the sleep time for the daemon thread between each run looking for expired objects.	3600000

Note: ldap.cache.policy.enable replaces the deprecated property ldap.cache.enable.

A jazn.xml file with all caches enabled, a cache size of 100, and a 10000-millisecond timeout would look like:

< ?xml version="1.0" encoding="UTF-8" standalone='yes'?>
< !DOCTYPE jazn PUBLIC "JAZN Config" 
     "http://xmlns.oracle.com/ias/dtds/jazn.dtd">
< jazn provider="LDAP" location="ldap://example.com:389" >
   < property name="ldap.cache.initial capacity" value="100" />
   < property name="ldap.cache.purget.timeout" value="10000" /> 
</jazn> 

Specifying a UserManager In orion-application.xml

Every application, including the top-level default application, has an associated UserManager. The UserManager's primary function is to authenticate users who attempt to access web pages and EJBs. The UserManager is used to authenticate users connections are made to the application. These are specified using subelements within an <orion-application> element that define the configuration. There are three tags that can be used to specify a UserManager. They are:

Table 3-10 UserManager Tags

Tag	Meaning
<user-manager>	A user manager implemented by some user-defined class
<jazn>	A JAAS user manager.
<principals>	A user manager defined in a principals.xml file. See "Using the <principals> element and principals.xml"

.

There may be more than one of these three elements within a single <orion-application> element; Which element determines the UserManager is determined by the order the elements appear in the table: <user-manager> takes precedence over <jazn>, which takes precedence over <principals>. For example, if both a <jazn> and a <principals> element are present, the UserManager is based on the <jazn> element. If multiple elements with the highest-priority tag are present, then the UserManagers are chained together as parents. That is, the UserManager specified in the first tag becomes the parent of the UserManager specified in the second, and so on. The last UserManager specified then becomes the UserManager of the application. The parent of the first UserManager is the UserManager associated with the parent application (if any) of the application. The default application does not have a parent application and the parent of its UserManager is null.

If no user manager is specified, then the UserManager is determined according to the following rules.

• For the default application, a JAAS UserManager is created based on jazn-data.xml in the directory containing application.xml. If no jazn-data.xml is present in that directory, one is created. The default realm of the created jazn-data.xml is jazn.com.

• At deployment time, if the UserManager of the parent application is the JAAS UserManager, then a JAAS UserManager is created based on jazn-data.xml. If necessary, a jazn-data.xml file is created in the same way as the previous bullet. A <jazn> element is written into the orion-application.xml associated with the application.

• At deployment time, if the UserManager of the parent application is based on principals.xml, then the UserManager of the application will be a principals UserManager. If a principals.xml file is not present, then an empty file is created. A <jazn> element is written into the orion-application.xml associated with the application.

• If the UserManager of the parent application is user-written, then the parent's UserManager will become the UserManager of the application.

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 sub-elements, <groups> and <users>. The <groups> element contains one or more <group> elements, and the <users> element contains one or more <user> elements.

Note: The XMLUserManager class is supported for backward compatibility only. Oracle recommends that you use one of the JAAS provider types.

Table 3-11 Elements in principals.xml

Element	Can Contain	Attributes	Description
<principals>	<groups>, <users>	NA	Containing element in file
<groups>	<group>		A list of groups known to this user manager
<group>	<description>, <permission>	name	Identifies a single user group; name attribute specifies group name
<description>			Not used by JAAS provider, but is displayed in various circumstances.
<permission>		name	A java.security.Permission that is granted to principals. There are two special values: administrator--equivalent to com.evermind.security.AdministrationPermission() rmi:login-- equivalent to com.evermind.server.rm.RMIPermission("login")
<users>	<user>		List of users known to the UserManager
<user>	<description>, <group-membership>		Single user belonging to this group
		username	String used to identify the user
		password	Cleartext password used to authenticate the user. There is no mechanism for obfuscating this password.
		deactivated	Either true or false. If true, then this user will not be found in lookups and will not be able to be authenticated
<description>			Arbitrary content that may be displayed in various circumstances
<group-membership>		group	Name attribute of a <group> which contains this user

Groups in principals.xml correspond to roles in the JAAS Provider. The principals.xml file does not support any equivalent of the JAAS provider's 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.

Here is an example 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>