7
Custom LoginModules

This chapter discusses how to write and install a LoginModule to be used with the Oracle Application Server Containers for J2EE (OC4J) JAAS Provider. This chapter contains the following sections:

• Custom JAAS LoginModule Integration with OC4J

• Packaging and Deployment

• Configuration

• Simple Login Module J2EE Integration

  Note: Because the JAAS specification does not cover user management, when you configure your application to use a custom LoginModule, the use of the UserManager API within your application is effectively disabled. The J2EE API, however, will continue to function within your application.

Custom JAAS LoginModule Integration with OC4J

Because OC4J's support for JAAS fully complies with the JAAS 1.0 specification, users can plug in any JAAS-compliant LoginModule implementation, if desired. OC4J includes the LoginModule, RealmLoginModule that combines J2EE security constraints with either the XML-based or LDAP-based provider types for environments in which OracleAS Single Sign-On (SSO) is not available. When Oracle Internet Directory (OID) is in use, we recommend that you use Oracle Identity Management to integrate with other authentication and identity management systems.

See the Oracle Identity Management Concepts and Deployment Planning Guide for details.

A custom JAAS LoginModule may be desirable when OracleAS Identity Management is not available and users are defined in an external repository. For those cases, you can configure a LoginModule using the XML-based provider type, and the following preliminary questions need to be considered.

1. Development. Do you want to take advantage of J2EE security constraints?

2. Development, packaging, and deployment. Are you using the login modules that come with J2SE 1.4? Or are you deploying in-house or third-party login modules?

   Note: Custom login modules are supported only with the XML-based Provider.

Packaging and Deployment

If you are using one or more of the default login modules provided with J2SE 1.3 and 1.4 (such as the J2SE1.4 com.sun.security.auth.module.Krb5LoginModule), then no additional configuration is needed. The OracleAS JAAS Provider can locate the default login modules.

If you are deploying your application with a custom login module, then you must deploy the login module and configure the JAAS Provider properly so that the module can be found at runtime.

Four options are available when packaging and deploying your custom login modules:

• Deploying as Standard Extensions or Optional Packages

• Deploying Within the J2EE Application

• Using the OC4J Classloading Mechanism

• Using the JAAS Provider Classloading Mechanism

The remainder of this section discusses these options in greater detail.

Deploying as Standard Extensions or Optional Packages

If you deploy your login modules as standard extensions, the JAAS Provider will be able to find them. No additional configuration is necessary. Deploying login modules as standard extensions allows multiple applications to share the deployed login modules.

For example, one way to deploy your login modules as standard extensions is to deploy them to the ${java.home}/lib/ext directory.

See Also: http://java.sun.com/j2se/1.4/docs/guide/extensions

Deploying Within the J2EE Application

If your login module is used only by a single J2EE application rather than shared among multiple applications, then you can simply package your login module as part of your application, and the JAAS Provider will be able to find it. No additional configuration is necessary.

If a later application needs the same LoginModule, you must repackage the login module and any relevant classes with the new application.

If you want to allow multiple applications to share the same LoginModule but you cannot deploy the LoginModule as an extension, then you can consider using the OC4J classloading mechanism or the JAAS Provider classloading mechanism.

Using the OC4J Classloading Mechanism

The JAAS Provider is integrated with OC4J's classloading architecture. If you configure your application so that the deployed custom login modules are part of your application classpath, then the JAAS Provider can locate them.

One way to accomplish this is using the <library> element in either of the following files:

• application.xml

• orion-application.xml

  See Also: The Oracle Application Server Containers for J2EE Services Guide for more information about the <library> element.

Using the JAAS Provider Classloading Mechanism

If for some reason you cannot configure your application's classpath, you can take advantage of the JAAS Provider's classloading mechanism. Deploy your login modules and specify their location using the classpath property of the <jazn> tag. See Table 3-3, "(XML-Based Provider) The <jazn> Tag In orion-application.xml" for complete information on the <jazn> tag properties.

Configuration

You modify the following files to configure your application to take advantage of custom login modules:

• jazn-data.xml

• orion-application.xml

These files are discussed in greater detail below.

jazn-data.xml

This file serves as the repository for the XML-based provider.

Although many jazn-data.xml files can be associated with an OC4J instance, the jazn-data.xml specified in the default jazn.xml serves as the default repository for the OracleAS JAAS provider.

Note that Oracle supports only the XML-based provider in conjunction with custom login modules.

The following sections discuss these XML elements:

• <jazn-loginconfig>

• <jazn-policy>

<jazn-loginconfig>

This tag contains information that associates applications with login modules.

Example:

<jazn-loginconfig>
  <application>
    <name>sampleLM</name>
    <login-modules>
       <login-module>
          <class>sample.SampleLoginModule</class>
          <control-flag>required</control-flag>
       </login-module>
    </login-modules>
  </application>
</jazn-loginconfig>

This sample fragment associates the application sampleLM with the login module sample.SampleLoginModule.

<jazn-policy>

This tag contains information that associates grantees with permissions.

Example:

<jazn-policy>
  <grant>
   <grantee>
     <principals>
      <principal>
        <class>sample.SampleUser</class>
        <name>admin</name>
      </principal>
    </principals>
   </grantee>
   <permissions>
     <permission>
       <class>com.evermind.server.rmi.RMIPermission</class>
       <name>login</name>
     </permission>
   </permissions>
  </grant>
</jazn-policy>

This sample fragment grants the permission com.evermind.server.rmi.RMIPermission with target name login to the principal with class sample.SampleUser and name ray.

Note: Oracle recommends that you manage the contents of jazn-data.xml using the JAZN Admintool.

For more information about the JAZN Admintool, see Chapter 5, "Using the JAZN Admintool".

orion-application.xml

This file contains application configuration information specific to OC4J. The following tags are discussed in detail:

• <jazn>

• <security-role-mapping>

• <library>

<jazn>

For a full discussion of the <jazn> tag, see "The <jazn> Tag".

The following properties are specific to LoginModule configuration:

• role.mapping.dynamic

  This property, when set to true, instructs the JAAS Provider to perform authorization checks based on the current Subject instead of based on users and roles defined in the application specific jazn-data.xml.

  The LoginModule instance(s) must ensure that the appropriate principals (users, roles, or groups) are associated with the Subject instance during the commit phase of the authentication process, in order for the principals to be taken into consideration during the authorization process. This association of principals to the Subject is typically implemented using the standard JAAS API.

• 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. Example:

  <jazn provider="XML" location="./jazn-data.xml">
     <property name="classpath" 
  value="../../shared/lib/sample.jar;../../shared/lib/samplemodule.jar" />
     <property name="role.mapping.dynamic" value="true" />
  </jazn>
  
  

  For details, see Table 3-3, "(XML-Based Provider) The <jazn> Tag In orion-application.xml".

<security-role-mapping>

This optional tag describes static security-role mapping information. For details, see the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

<library>

This tag sets the classpath associated with your application. Whenever possible, use this tag instead of the classpath property in the <jazn> tag. Example:

<library path="../../shared/lib/sample.jar"/>
<library path="../../shared/lib/samplemodule.jar"/>

For details, see the Oracle Application Server Containers for J2EE User's Guide.

Simple Login Module J2EE Integration

Developing a simple LoginModule follows the standard development, packaging, and deployment cycle. The following sections discuss each step in the cycle.

Development

Develop a JAAS-compliant LoginModule according to the JAAS SPI (see the Javadoc for javax.security.auth.spi.LoginModule for more information).

Packaging

Package your LoginModule in one of two ways:

• Package your LoginModule classes as part of your application's EAR file. For Web applications, include the classes under the WEB-INF/classes.

• Package it separately and refer to it using the classloading mechanisms.

Deployment

To deploy your LoginModule in the global jazn-data.xml file:

1. Register your application's login module within the <application> tag.

   The following entry registers the login module sample.SampleLoginModule to be used for authenticating users accessing the sampleLM application.

    <application>
            <name>sampleLM</name>
            <login-modules>
               <login-module>
                  <class>sample.SampleLoginModule</class>
                  <control-flag>required</control-flag>
                  <options>
                     <option>
                        <name>debug</name>
                        <value>true</value>
                     </option>
                  </options>
               </login-module>
            </login-modules>
         </application>
   
   

2. Optional. Grant relevant permissions to your users and roles.

   For example, if the principal admin needs EJB access, then you must grant the permission com.evermind.rmi.RMIPermission to admin.

   <grant>
     <grantee>
       <principals>
         <principal>
           <class>sample.SampleUser</class>
           <name>admin</name>
         </principal>
       </principals>
     </grantee>
     <permissions>
       <permission>
         <class>com.evermind.server.rmi.RMIPermission</class>
         <name>login</name>
       </permission>
     </permissions>
   </grant>
   

To deploy your LoginModule in the application-specific orion-application.xml file:

1. Set the <jazn> property role.mapping.dynamic to true:

   <jazn provider="XML" location="./jazn-data.xml" >
     <property name="role.mapping.dynamic" value="true" />
   </jazn>
   

2. Create appropriate <security-role-mapping> entries.

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