Release 2 (9.0.2)
Part Number A90146-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9i Application Server Security Guide Release 2 (9.0.2) Part Number A90146-01 |
|
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:
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.
| For Applications in... | Follow These Configuration Tasks... |
|---|---|
|
J2SE Environments |
|
|
J2EE Environments |
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
J2SE and J2EE environments require several similar configuration tasks. Complete these tasks to configure JAAS components for applications developed in J2SE and J2EE environments.
If your application runs in the J2EE environment, then perform this task only if you do not need your application to be SSO-enabled.
Table 7-2 identifies required components for J2SE and J2EE environments. Ensure that you have installed the correct components for your environment.
| Component | Required For J2SE? | Required For J2EE? |
|---|---|---|
|
Yes |
Yes |
|
|
Yes |
Yes |
|
|
Yes |
Yes |
|
No |
Yes |
|
|
No |
YesFoot 2 |
|
|
No |
No |
|
|
No |
Yes |
|
|
No |
Yes |
|
|
No |
Yes |
|
|
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. |
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.
To load the JAZN schema and default entries into Oracle Internet Directory:
This information is used to configure JAAS support with Oracle Internet Directory in steps 4 through 5.
$ORACLE_HOME/jazn/install directory.
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.
.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 -hldaphost-pldapport-Dbinddn-wpassword-load All
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:
$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 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";
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:
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>
The configuration tasks that must be performed next depend on the environment in which the application runs, as indicated in Table 7-3.
| For... | Go To... |
|---|---|
|
J2SE Environments |
"Performing Configuration Tasks Unique to J2SE Environments" |
|
J2EE Environments |
"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".
Configure the JAAS property file, jazn.xml, in the $ORACLE_HOME/j2ee/home/config directory, according to the provider environment type being used:
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.
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 |
|---|---|---|
|
|
Optional |
|
|
|
Required |
|
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.
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>
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:
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>
Perform these configuration tasks after the configuration tasks described in "Performing Configuration Tasks Common to J2SE and J2EE Environments".
Configure the JAAS and enable the JAZNUserManager through the OC4J-specific configuration file, orion-application.xml. Indicate the JAAS environment type and related information:
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:
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.
A sample orion-application.xml file with all attributes and property names specified is provided in "orion-application.xml file".
|
See Also:
"Task 2: Configure an Authentication Method and Filter Modes" for information on the benefits of setting |
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:
The following property names can be set in orion-application.xml:
| Property Name | Status | Value |
|---|---|---|
|
|
Optional |
|
|
|
Optional |
A sample orion-application.xml file with all attributes and property names specified is provided in "orion-application.xml file".
|
See Also:
|
Integrate the JAAS with the type of authentication method you want to use:
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:
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.
| Precedence | Configuration File |
|---|---|
|
1 |
|
|
2 |
|
|
3 |
|
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.
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.
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.
If you require SSL, then perform the following steps:
When you configure an application to run in an SSL environment, you must
httpd.conf file
mod_oc4j.conf file
To configure an application for the SSL environment:
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>
SSLWallet file:/wallet_file_directory
$ORACLE_HOME/lib to the LD_LIBRARY_PATH environment parameter.
iasobf utility to create an encrypted server wallet password. The iasobf utility is located in the Apache/Apache/bin directory.
#SSLWalletPassword password
#SSLOptions +FakeBasicAuth +ExportCertData +CompatEnvVars +StrictRequire
SSLVerifyClient from none to require or optional.
#SSLVerifyClient require
mod_oc4j.conf file.
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. |
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:
$ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf.
Oc4jMount /reports Oc4jMount /reports/*
mod_oc4j.conf.
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:
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 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.
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.
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.
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:
Consequently, Oracle Corporation recommends that <jazn> tags be used whenever possible.
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 |
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|