Oracle® Application Server Containers for J2EE Security Guide
10g Release 2 (10.1.2) Part No. B14013-01 |
|
![]() Previous |
![]() Next |
This chapter discusses tasks related to configuring the complete security system. It contains the following parts:
As part of installing OC4J, you determine whether to use the LDAP-based or XML-based provider. This section gives guidelines on how to make that choice.
XML-based Provider—Use the XML-based provider in development environments and in deployed applications with a small user population.
LDAP-Based Provider—Use the LDAP-based provider in production environments.
Compared to the XML-based provider, the LDAP-based provider offers better security and performance. The centralized Oracle Internet Directory server scales gracefully as the number of applications and users grows. We recommend you take advantage of a centralized Oracle Internet Directory server in your production deployments, both for better performance and to take advantage of such features as centralized account creation and management, single passwords, and credential management.
The LDAP-based provider enables you to configure cache parameters to improve overall performance of authentication and authorization. If secure communications are needed between the Oracle Internet Directory server and OC4J, configure the system to use the level of security required.
When you install infrastructure, then associate the OC4J instance with a mid-tier Oracle Internet Directory or Oracle Application Server Single Sign-On instance, the installer automatically selects the LDAP-based provider. For details, see the Oracle Application Server Installation Guide . If you need to configure OC4J to use the LDAP-based Provider, see the instructions in the Oracle Application Server Administrator's Guide.
To configure the Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider, you must sometimes edit various configuration files using text editors. This section discusses how to locate the configuration files and the <jazn>
element.
The OracleAS JAAS Provider must locate a valid jazn.xml
file before it can begin running. The jazn.xml
file is used to configure the OracleAS JAAS Provider.
The bootstrap jazn.xml
is in ORACLE_HOME
/j2ee/home/config].
The OracleAS JAAS Provider reads the information in this file before OC4J is started up. This means that certain settings can only be made in the bootstrap file; if these changes are read after OC4J starts up, they have no effect on the OracleAS JAAS Provider. Optionally, users can specify a different location for jazn.xml
; see "Locating jazn.xml" for details.
The file jazn-data.xml
is the datastore for the XML-based JAAS provider. By default, OC4J expects the file jazn-data.xml
to be in ORACLE_HOME
/j2ee/
]instancename
/config
. You can specify an alternate path name for jazn-data.xml
in the <jazn provider="xml" location="
pathname
">
element in jazn.xml
.
The <jazn>
element is used to configure the OracleAS JAAS Provider. Most often, the <jazn>
element appears in one of two places:
The global application.xml, for global configuration
The application-specific orion-application.xml
The <jazn>
tag may also appear in the bootstrap <jazn.xml>
when it is used to configure virtual machine properties. For details, see "The Bootstrap jazn.xml File".
This section discusses basic information needed to understand and use the JAZN Admintool.
When you use the JAZN Admintool, by default it edits the file jazn-data.xml
under the config
directory of the OC4J home instance. For details on locating jazn-data.xml
, see "Locating jazn-data.xml". The password for the admin
user is set during installation time to the same value as the Oracle Application Server administrator (ias_admin
) password.
Before using the Admintool with the LDAP-based provider, be sure to set the correct environment settings as described in "Preparing To Use LDAP".
If you are using the XML-based provider, you must authenticate yourself to the JAZN Admintool before making administrative changes. You authenticate yourself in one of two ways:
Supplying the -user
and -password
switches, as in:
java -jar jazn.jar -usermyusername
-passwordmypassword
-listrealms
Note: If you specify the-user , -password , or -clustersupport options, you must specify them before all other options on the command line.
|
Supplying a username and password when prompted by the Admintool, as in:
java -jar jazn.jar -listrealms >RealmLoginModule username: martha >RealmLoginModule password: mypass
Caution: The Admintool does not require authentication when used with the LDAP-based provider; anyone who runs the tool can perform Admintool operations against the Oracle Internet Directory server. This means that it is vital to secure access to the production machine(s) on which OC4J uses the LDAP-based provider. If you specify the-user and -password options when using the LDAP-based provider, they are ignored.
|
-
clustersupportoracle_home
Specifying this option instructs the Admintool to propagate all JAAS configuration changes throughout a cluster. The oracle_home
argument specifies the absolute path name of ORACLE_HOME
, the Oracle home directory. You can combine -clustersupport
with the -shell
option.
Notes: If you are using the-clustersupport option, you must specify it before all other options on the command line.
The |
For example:
java -jar jazn.jar -clustersupport /oracle_home -shell
To specify which LoginModule
the JAZN Admintool uses to authenticate its users, you must add a <login-modules>
element to the application
element in jazn-data.xml
. For example:
<application> <name>oracle.security.jazn.tools.Admintool</name> <login-modules> <login-module> <class>oracle.security.jazn.realm.RealmLoginModule</class> <control-flag>required</control-flag> <options> <option> <name>debug</name> <value>false</value> </option> <option> <name>addAllRoles</name> <value>true</value> </option> </options> </login-module> </login-modules> </application>
If you try to run the JAZN Admintool without specifying a LoginModule
, the RealmLoginModule
with the default options is used. The default options are shown in Table 4-2, "RealmLoginModule Options".
If you use the Java Virtual Machine shipped with Oracle Application Server, the OracleAS JAAS Provider is automatically specified as the JAAS policy provider. If you use another JVM, you must explicitly specify oracle.security.jazn.spi.PolicyProvider
as the policy provider, because by default, the JVM uses the Sun JAAS provider.
Note: When you use OC4J, the JAAS configuration properties are set by default during OC4J startup, so in most circumstances you do not need to worry about setting these properties. You set them only when you are running a J2SE application outside OC4J. |
You can specifying Oracle-specific JAAS properties in a separate file and passing them to the JVM on the command line. Oracle supplies a default file (ORACLE_HOME/j2ee/home/config/jazn.security.props
) that specifies the OracleAS JAAS provider.
To replace all security properties with the Oracle properties:
java -Djava.security.properties==propfile
To append the Oracle-specific properties to the other properties:
java -Djava.security.properties=propfile
The bootstrap jazn.xml
file is inORACLE_HOME
/j2ee/home/config].
The OracleAS JAAS Provider reads the information in this file before OC4J is started up. This means that certain settings can only be made in the bootstrap file; if they are read after OC4J starts up, they have no effect on the OracleAS JAAS Provider. These properties are discussed in detail in Chapter 5, "Configuring the OC4J Instance".
To turn on OracleAS JAAS Provider debug logging, set the system property jazn.debug.log.enable
to true
during Java Virtual Machine (JVM) startup.
You do this by modifying the JVM startup settings for your OC4J instance. In Oracle Application Server, you normally manage JVM settings with Oracle Enterprise Manager, using the Java Options textbox on the Server Properties screen.
In standalone mode, you set this property using JVM command-line options. For instance, you might start OC4J standalone with a command line such as:
java -Djazn.debug.log.enable=true -jar oc4j.jar
Or you can start the Admintool shell in debug mode with the command:
java -Djazn.debug.log.enable=true -jar jazn.jar -shell
In Oracle Application Server, the debug output is captured by OPMN and written to log files associated with each OC4J instance in the directory ORACLE_HOME
/opmn/logs
.
The user manager, employing the user name and password, verifies the user's identity using information in the user repository. The user manager contains your definitions for users, groups, or roles. The default user manager is the JAZNUserManager
.
You can define a user manager for all applications or for specific applications.
Global user manager—The global (default) user manager is inherited by all applications within an instance that has not defined a specific user manager. The instance UserManager
is defined in application.xml
.
Specific user manager—This user manager is defined in orion_application.xml
solely for a single application. It is not used by any other application.
Note: Within a single OC4J instance you can specify different values for the application-specificUserManager instance and the global UserManager instance. When you do this, we recommend that you not mix custom UserManager s and Oracle-supplied UserManager s. You can use different custom UserManager s for the application and the global instance, and you can use different Oracle-supplied UserManager s for the application and the global instance, but you should avoid using a custom UserManager for the one instance and an Oracle-supplied UserManager for the other.
|
In some cases, if an application inherits from another application instead of inheriting from the global application, then the application's parent user manager will be the global UserManager
instance instead of the UserManager
instance specified in the parent application.
To specify a UserManager for an entire OC4J instance or for a specific application within that instance, use Enterprise Manager. For details, see the Enterprise Manager help screen "Modifying the User Manager for All Applications".
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.
Note: We strongly encourage you to useJAZNUserManager . User-defined UserManager s will stop being supported in a future release.
|
The UserManager
is used to authenticate users when connections are made to the application. These are specified using sub-elements within an <orion-application>
element that define the configuration. There are three tags that can be used to specify a UserManager
. They are:
Table 4-1 UserManager Tags
Tag | Meaning |
---|---|
<user-manager>
|
A user manager implemented by a user-defined class. |
<jazn>
|
JAZNUserManager .
|
<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 the user-manager configuration 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.
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 application 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.
The RealmLoginModule
class is the default LoginModule
that is configured through the jazn-data.xml
file. The RealmLoginModule
class authenticates user login credentials before the user can access J2EE applications. Authentication is performed using OC4J container-based authentication (HTTP BASIC
, FORM
, and so on). You do not need to enable the RealmLoginModule
class if your application uses OracleAS Single Sign-On authentication.
See Also: Oracle Application Server Installation Guide for OracleAS Single Sign-On configuration tasks. |
You can configure RealmLoginModule
either using the JAZN Admintool or by editing jazn-data.xml
. For details on using the Admintool, see "Adding and Removing Login Modules" .
The <login-module>
tag supports the following <option>
values:
Table 4-2 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. See Chapter 15, "Configuring CSIv2" for details.
|
false
|
supportNullPassword
|
(LDAP-based provider only) 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
|
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>oracle.security.jazn.oc4j.JAZNUserManager</name>
<login-modules>
<login-module>
<class>oracle.security.jazn.realm.RealmLoginModule</class>
<control-flag>required</control-flag>
<options>
<option>
<name>addRoles</name>
<value>true</value>
</option>
</options>
</login-module>
</login-modules>
</application>
</jazn-loginconfig>
</jazn-data>
You specify the authentication method (auth-method
) in one of several configuration files, using either the <jazn-web-app>
or <login-config>
elements. You must edit these files by hand.
To specify authentication method at the application level, you edit 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 4-3:
Table 4-3 Values for auth-method in web.xml
Setting | Meaning |
---|---|
BASIC (default)
|
The application uses basic authentication, the standard authentication. |
FORM
|
The application uses form-based 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-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 auth-method
in orion-application.xml
: SSO
, meaning that the application uses OracleAS Single Sign-On. If your installation includes LDAP, Oracle Enterprise Manager automatically sets auth-method
to SSO
. If you stop using OracleAS Single Sign-On, you must edit the file to remove this method.
A sample entry for orion-application.xml
would look like:
<jazn provider="LDAP" <jazn-web-app auth-method="SSO"/> </jazn>
J2EE defines a declarative authorization model that decouples applications from the underlying security infrastructure. This model allows an application's authorization policy to be expressed in a portable manner in the application's deployment descriptors. This model has proven to be hugely successful and suffice for most application's needs.
In some advanced scenarios, however, the J2EE authorization model may seem too static and coarse-grained - in these cases the JAAS authorization model can be used instead of (or in addition to) the J2EE security model. When compared to the J2EE authorization model, the JAAS authorization model is more powerful (fine-grained and dynamic) and more flexible (custom permission types supported). Such power and flexibility come at a cost, however, the JAAS authorization model is more complex to understand, deploy and administer than the J2EE authorization model.
Both models are fully supported in OC4J.
In most cases, URL authorization is sufficient for an application. However, if your application requires granular authorization, this extended authorization can be used to enforce JAAS Policy-based authorization at the method level.
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 contained in a <jazn>
element in either the orion-web.xml
or orion-application.xml
files. To do this, you open the appropriate file in a text editor.
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 OracleAS 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 OracleAS 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 4-4 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 |
true
|
true (default)
|
subject.doAsPrivileged()
|
true
|
false
|
subject.doAs()
|
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 sometimes deploy a servlet into a container that uses different role names than expected by the servlet. You do this by mapping the logical role (the role name used by the servlet) to the security role (the role name used by the container) in the file web.xml
.
For example, the following entity maps the security role corpmanagers
to the logical role to the logical role mgmt
:
<security-role-ref> <role-name>mgmt</role-name> <role-link>corpmanagers</role-link> </security-role-ref>
In this example, if a servlet running as a user belonging to corpmanagers
invokes isUserInRole("mgmt")
, the method will return true
. Whenever the container finds no security-role-ref
matching a security role, the container checks the <role-name>
against the entire list of security roles for the Web application.
It is often desirable to avoid parsing the principal returned by various method calls. You can configure OracleAS JAAS Provider so that the returned principal contains no realm name. To do this, you add a jaas.username.simple
property to the <jazn>
element in the file jazn.xml
, or, at application level, to the <jazn>
element in the file orion-application.xml
. If this property is set to true
, returned principals contain no realm name; if it is set to false
, the default, returned principals contain the complete realm name.
This property affects the return values of the following methods:
javax.servlet.http.HTTPServletRequest
, getRemoteUser
and getUserPrincipal
methods
javax.ejb.EJBContext
, getCallerIdentity
and getCallerPrincipal
methods
By default, the principal returned by these methods is in the format realm_name
/
simple_name
, such as jazn.com/john
. When you set jaas.username.simple
to true
, the returned principal is in the format simple_name
, such as john
.
You set jaas.username.simple
as follows:
Locate the file containing the <jazn>
element (see "Locating jazn.xml, jazn-data.xml, and the <jazn> element"), open the file in a text editor, and go to the <jazn>
element within the file.
Search for a <property name="jaas.username.simple">
sub-element within the <jazn>
element.
If the sub-element exists, change the value to true
or false
; if the sub-element does not exist, create one. In either case, you should have a sub-element that looks like:
<jazn provider="XML" location="./jazn-data.xml"> <property name="jaas.username.simple" value="true" /> </jazn>
Note: Do not edit any<jazn> properties except as specified in this chapter.
|
To enable fat client access to EJBs using RMI, you must grant the correct permissions using the JAZN Admintool. (For general information on using the Admintool, see "Admintool Overview" .) You must grant RMIPermission login
to your user, role, or group.
java -jar jazn.jar -grantperm myrealm -role administrators \
com.evermind.server.rmi.RMIPermission login
The Java 2 policy file grants permissions to trusted code or applications that you run. This enables code or applications to access Oracle support for JAAS or JDK APIs requiring specific access privileges.
A preconfigured Java 2 policy (java2.policy
) is provided in ORACLE_HOME
/j2ee/home/config
.
You need to modify the Java 2 policy file to grant permissions to trusted code or applications.
For example, the following section of a java2.policy
file grants java.security.AllPermission
to the trusted jazn.jar
.
/* grant the JAZN library AllPermission */ grant codebase "file:${oracle.home}/j2ee/home/jazn.jar" { permission java.security.AllPermission; };
The following example grants specific permissions to all applications running in the ORACLE_HOME
/appdemo
directory.
/* Assuming you are running your application demo in $ORACLE_HOME/appdemo/, */ /* Grant JAZN permissions to the demo to run JAZN APIs*/ grant codebase "file:/${oracle.ons.oraclehome}/appdemo/-" { permission oracle.security.jazn.JAZNPermission "getPolicy"; permission oracle.security.jazn.JAZNPermission "getRealmManager"; permission oracle.security.jazn.policy.AdminPermission "oracle.security.jazn.realm.RealmPermission$*$createRealm,dropRealm, createRole, dropRole,modifyRealmMetaData";
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: TheXMLUserManager class is deprecated, and is supported for backward compatibility only. Oracle will cease to support XMLUserManager and principals.xml in a future release.
|
Table 4-5 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 OracleAS JAAS Provider, but is displayed in various circumstances. |
<permission>
|
|
name
|
A java.security.Permission that is granted to principals. There are two special values:
|
<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 OracleAS JAAS Provider. The principals.xml
file does not support any equivalent of the OracleAS 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
.
The following 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>