OracleŽ Application Server Containers for J2EE Security Guide 10g (9.0.4) Part Number Part No. B10325-02 |
|
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:
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.
Notes:
Before using your JAAS-based application, you must configure the JAAS Provider components. This chapter discusses configuring JAAS in an OC4J and J2EE environment.
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:
[ORACLE_HOME]
/jlib/ldapjclnt9.jar
LD_LIBRARY_PATH
in Solaris) includes:
[ORACLE_HOME]/lib
When you manage OC4J with the Enterprise Manager, it sets these two variables automatically.
J2EE provides the following XML deployment descriptors that have security implications:
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 provides the following container-specific XML deployment descriptor files that have security implications:
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.
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
.
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:
$JAVA_HOME/jre/lib/security/java.security
file:
auth.policy.provider=oracle.security.jazn.spi.PolicyProvider login.configuration.provider=oracle.security.jazn.spi.LoginConfigProvider
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:
oracle.security.jazn.config
(system property)
java.security.auth.policy
(system property)
$J2EE_HOME
/config
(
$J2EE_HOME
is specified by the system property oracle.j2ee.home)
$ORACLE_HOME
/j2ee/home/config
($ORACLE_HOME
is specified by the system property oracle.home
)
./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
."
You use the <jazn>
tag to configure the JAAS Provider. The <jazn>
tag can appear in any of the following locations
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:
When you are using the XML-based Provider, the <jazn>
tag supports the attributes shown in Table 3-3.
See:
"Specifying Authentication (auth-method)" for information on the <jazn-web-app> element and its attributes auth-method , runas-mode , and doasprivileged-mode. :
|
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:
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.
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 <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.
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.
|
external.synchronization |
|
When set to
Set to |
role.mapping.dynamic |
|
When set to |
|
|
Initial size for JNDI/LDAP connection pool. |
|
|
Pool increment size for JNDI/LDAP connection pool -- number of connections added to pool whenever the supply of connections in the pool is exhausted. |
|
See "Configuring the JAAS Provider To Use SSL With Oracle Internet Directory" and Table 3-9 for details. |
|
|
|
Number of times the JAAS Provider attempts to create an LDAP connection before giving up. |
|
|
Number of milliseconds the JAAS Provider waits before retrying a failed LDAP connection attempt. |
|
|
Obfuscated password for the LDAP user name. For example:
See "Password Obfuscation In jazn-data.xml and jazn.xml" for details on obfuscation. |
|
|
LDAP username or
|
|
|
Pathname for the Oracle Wallet. |
|
|
Obfuscated password for the Oracle Wallet. See "Password Obfuscation In jazn-data.xml and jazn.xml" for details on obfuscation. |
You specify the authentication method (auth-method
) in one of several configuration files, using either the <jazn-web-app>
or <login-config>
elements.
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:
These values can be overridden at the application level by using the <jazn-web-app>
element in orion-web.xml
or 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>
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>
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.
If runas-mode is Set To | And doasprivileged-mode Is Set To | Then the servlet is invoked with: |
---|---|---|
|
|
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" />
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.
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:
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>
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".
orion-application.xml
file as follows:
role-name
defined in the web.xml
file as a security role (sr_manager
).
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:
|
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.
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" .
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:
See Also:
The JAAS Provider Javadoc. |
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:
See Table 11-1, "Cipher Suites Supported By OracleSSL" for a list of supported cipher suites.
Note:
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>
(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
The LDAP-based JAAS Provider supports caching, providing improved performance and scalability. There are three separate caches:
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.
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.
Caching is enabled by default. You should disable the caches when performing management and administrative tasks. In particular:
Policy.grant()
or Policy.revoke()
causes an UnsupportedOperationException.
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>
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.
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>
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:
Tag | Meaning |
---|---|
|
A user manager implemented by some user-defined class |
|
A JAAS user manager. |
|
A user manager defined in a |
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 UserManager
s 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.
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
.
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.
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.
UserManager
of the parent application is user-written, then the parent's UserManager
will become the UserManager
of the application.
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.
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>
|
![]() Copyright © 1996, 2003 Oracle Corporation. All Rights Reserved. |
|