9 Login Modules

Specification of the Oracle Login Configuration Provider

By default, OC4J specifies usage of the OracleAS JAAS Provider login configuration provider (oracle.security.jazn.spi.LoginConfigProvider) by the OC4J JVM, overriding usage of the Sun Microsystems default JAAS login configuration provider.

This is accomplished through the following configuration in the file ORACLE_HOME/j2ee/home/config/jazn.security.props:

login.configuration.provider=oracle.security.jazn.spi.LoginConfigProvider

The Oracle login configuration provider uses the system-jazn-data.xml file for login module configuration.

Login Module Notes and Tips

Be aware of the following notes regarding the use of login modules with OC4J:

• By convention, a setting of provider="XML" is required for an application using custom login modules (custom security provider). See related information about the custom.loginmodule.provider property in "Settings in <jazn> for Login Modules".

• When using custom login modules, it is possible to instruct the OracleAS JAAS Provider to base authorization checks on the authenticated subject instead of basing checks on the users and roles defined in system-jazn-data.xml or the application-specific jazn-data.xml file. See related information about the role.mapping.dynamic property in "Settings in <jazn> for Login Modules".

  To ensure that all relevant principals are taken into consideration during authorization, the login module must add the relevant principals (including any roles that the authenticated user belongs to) to the subject during the commit phase of the authentication process.

• Login module configuration (under the <jazn-loginconfig> element) cannot be in an application-specific jazn-data.xml file; it must be in system-jazn-data.xml. Configuration will be written to system-jazn-data.xml automatically if you configure login modules through Application Server Control or in your orion-application.xml file. (Also see "Settings in <jazn-loginconfig> in orion-application.xml".)

• If you use any identity repository other than the file-based provider or Oracle Internet Directory, you must define an administrative user account and administrator roles, grant the roles to the user, and grant necessary permissions to the roles, as discussed in "Creating the Administrative User and Roles and Granting RMI Permission".

• Because the JAAS specification does not cover user management, when you configure your application to use a custom login module, the use of the UserManager API within your application is not supported. The J2EE API, however, will continue to function within your application.

• See "OracleAS JAAS Provider Policy Management" regarding subject-based policy management when using a custom login module. The policy configuration must be in system-jazn-data.xml.

• "Using the File-Based Provider Across an OC4J Group" discusses how to maintain system-jazn-data.xml settings across multiple OC4J instances. This functionality also applies to login modules, using MBean operations such as setLoginModule, remLoginModule, and getLoginModuleControlFlagTypes.

RealmLoginModule

The RealmLoginModule class is the default login module, for use with the file-based provider or Oracle Identity Management, and is configured when you configure these security providers through Application Server Control. This configuration is reflected in a <login-module> element under <jazn-loginconfig> in the system-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-based, and so on).

RealmLoginModule supports the options shown in Table 9-2 (reflected in <name> and <value> subelements of an <option> element under <login-module>).

Here is sample configuration of RealmLoginModule, in system-jazn-data.xml. (We recommend that you not alter RealmLoginModule configuration manually; this example is just for illustrative purposes.)

<jazn-loginconfig>
   <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>
   <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>addAllRoles</name>
                  <value>true</value>
               </option>
            </options>
         </login-module>
      </login-modules>
   </application>
</jazn-loginconfig>

DBTableOraDataSourceLoginModule

The OC4J 10.1.3.1 implementation supplies a login module you can use if you have a user identity store in a database:

oracle.security.jazn.login.module.db.DBTableOraDataSourceLoginModule

This replaces previous functionality of the com.evermind.sql.DataSourceUserManager class, now deprecated (but still supported for backward compatibility, and still documented at the end of this section for completeness). It also replaces some authentication functionality of the deprecated com.evermind.security.User class.

Once you have created your database schema and an Oracle data source to connect to the database (as described in the data sources chapter of the Oracle Containers for J2EE Services Guide), you are ready to configure the login module.

DBTableOraDataSourceLoginModule supports a number of options for specifying such items as data location (table and column names) and password encryption. You can set these options through Application Server Control or the OracleAS JAAS Provider Admintool, with the settings being reflected in the <jazn-loginconfig> element of the system-jazn-data.xml file.

This section covers the following topics:

• DBTableOraDataSourceLoginModule Options

• Configuring DBTableOraDataSourceLoginModule in Application Server Control

• Configuring DBTableOraDataSourceLoginModule in the Admintool

• Sample DBTableOraDataSourceLoginModule Settings in system-jazn-data.xml

• Principals for DBTableOraDataSourceLoginModule

• Implementing DBLoginModuleEncodingInterface for Password Encryption

• Previous Functionality: DataSourceUserManager (Deprecated)

oracle.security.jazn.login.module.db.DBLoginModuleEncodingInterface

java -jar jazn.jar -addloginmodule application_name \
     oracle.security.jazn.login.module.db.DBTableOraDataSourceLoginModule \
     required data_source_name="jdbc/OracleDS" roles_fk_column="username" \
     table="userinfo"  groupMembershipTableName="groupinfo" \
     groupMembershipGroupFieldName="role" usernameField="username" \
     user_pk_column="username" passwordField="password" casing="sensitive"

<jazn-loginconfig>
   <application>
      <name>application_name</name>
      <login-modules>
         <login-module>
            <class>
              oracle.security.jazn.login.module.db.DBTableOraDataSourceLoginModule
            </class>
            <control-flag>required</control-flag>
            <options>
               <option>
                  <name>data_source_name</name>
                  <value>jdbc/OracleDS</value>
               </option>
               <option>
                  <name>table</name>
                  <value>userinfo</value>
               </option>
               <option>
                  <name>roles_fk_column</name>
                  <value>userName</value>
               </option>
               <option>
                  <name>groupMembershipGroupFieldName</name>
                  <value>role</value>
               </option>
               <option>
                  <name>user_pk_column</name>
                  <value>userName</value>
               </option>
               <option>
                  <name>passwordField</name>
                  <value>passWord</value>
               </option>
               <option>
                  <name>groupMembershipTableName</name>
                  <value>groupinfo</value>
               </option>
               <option>
                  <name>usernameField</name>
                  <value>userName</value>
               </option>
               <option>
                  <name>casing</name>
                  <value>sensitive</value>
               </option>
            </options>
         </login-module>
      </login-modules>
   </application>
   ...
</jazn-loginconfig>

% java -jar jazn.jar -grantperm \
       oracle.security.jazn.login.module.db.principals.DBUserPrincipal name \
       permissionclass [permission_parameters] 

% java -jar jazn.jar -grantperm \
       oracle.security.jazn.login.module.db.principals.DBRolePrincipal name \
       permissionclass [permission_parameters] 

oracle.security.jazn.login.module.db.DBLoginModuleEncodingInterface

<orion-application ... >
   ...
   <user-manager class="com.evermind.sql.DataSourceUserManager">
      <property name="dataSource" value="jdbc/OracleCoreDS" />
      <property name="table" value="j2ee_users" />
      <property name="usernameField" value="username" />
      <property name="passwordField" value="password" />
      <property name="groupMembershipTableName" value="second_table" />
      <property name="groupMembershipGroupFieldName" value="group" />
      <property name="groupMembershipUserNameFieldName" value="userId" />
   </user-manager>
   ...
</orion-application>

Packaging Login Modules within the J2EE Application

If your login modules are used by only a single J2EE application, then you can simply package the login modules as part of your application by including the login module JAR file in the application EAR file.

The login modules must be configured through <jazn-loginconfig> settings, in one of two places:

• In the system-jazn-data.xml file, as discussed in "Login Module Settings in system-jazn-data.xml"

• In the orion-application.xml file in your application EAR file, as discussed in "Settings in <jazn-loginconfig> in orion-application.xml"

Using the Application Server Control Console, you can configure custom login modules as you deploy an application, or later if you change the security provider to custom. This results in system-jazn-data.xml being updated automatically.

Administering custom login modules through the OracleAS JAAS Provider Admintool will also update system-jazn-data.xml settings for you.

Providing Login Modules as Optional Packages

If you deploy your login modules as an optional package (formerly known as a "standard extension"), the OracleAS JAAS Provider will be able to find them. No additional configuration is necessary. Deploying login modules as an optional package allows multiple applications to share them.

There are two ways to use the optional package mechanism:

• Use the login module classes as an installed optional package. Place the login module JAR file in the jre/lib/ext directory. Classes in JAR files in this directory can be used by applications without having to be included in the classpath.

• Use the login module classes as a download optional package. Specify the login module JAR file in the Class-Path header field in the manifest of other JAR files, as desired. In this way, classes in the login module JAR file can be used by classes in the other JAR files that reference it.

The login modules must also be configured in system-jazn-data.xml, as discussed in "Login Module Settings in system-jazn-data.xml".

Providing Login Modules as OC4J Shared Libraries

The OracleAS JAAS Provider is integrated with the OC4J class loading architecture. Because of this, you can make login modules available to applications by loading them as OC4J shared libraries, as documented in "Tasks to Share a Library".

Specifying and Configuring a Custom Security Provider during Deployment

When you plan to use a custom security provider and you deploy an application through Application Server Control, you have the opportunity to configure your custom login modules during deployment.

From the Deploy: Deployment Settings page (see "Deploying an Application through Application Server Control" for how to get to this page):

1. Go to the Select Security Provider task.

2. In the resulting Deployment Settings: Select Security Provider page, choose Custom from the Security Provider dropdown list.

3. Under "Configuration of Custom Security Provider" (which appears after you choose Custom), you can edit or delete any custom login module that is found with your application, or add a new custom login module.

   • To add a new custom login module, choose Add Login Module. See "Adding a Custom Login Module during Deployment".

   • To edit an existing custom login module, choose the Edit task for the appropriate module. See "Editing a Custom Login Module Configuration during Deployment".

   • To delete an existing custom login module, choose the Delete task for the appropriate module.

4. Still in the Deployment Settings: Select Security Provider page, choose OK to finish the security provider selection.

5. Back in the Deploy: Deployment Settings page, choose Deploy to complete the deployment, or choose another task, as desired. The list of tasks is noted in "Deploying an Application through Application Server Control".

Deploying or configuring a custom login module through Application Server Control results in the following required settings being inserted automatically in the orion-application.xml file:

<jazn provider="XML">
   <property name="role.mapping.dynamic" value="true" />
   <property name="custom.loginmodule.provider" value="true" />
</jazn>

Changing to a Custom Security Provider after Deployment

You can select a security provider for your application at deployment time, as described above. You can also change to a different security provider after deployment. You can change to a custom security provider as follows:

1. Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

2. In the Security Provider page, choose Change Security Provider.

3. In the Change Security Provider page, select "Custom Security Provider" from the dropdown.

4. Under "Login Modules" (which appears after you select Custom Security Provider in the dropdown), specify the first login module to be used, as follows. Later you can go back to the Security Provider to add more login modules, as described in the next section, "Adding a Login Module to the Custom Security Provider".

   • Specify your login module package and class name.

   • Specify a value for the login module control flag (from the dropdown list)—Required, Requisite, Optional, or Sufficient. See Table 9-5, "Login Module Control Flags" for information about these settings.

   • As desired, choose Add Another Row to create properties.

   • As desired, edit the name or value of any property in the Properties list.

   • As desired, use the Delete task for a property to remove that property.

   • Choose OK to finish the change.

This takes you back to the Security Provider page, where you are prompted to restart your application for the changes to take effect.

Adding a Login Module to the Custom Security Provider

Once you have established a custom security provider, either during or after deployment, you can add custom login modules as follows:

1. Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

2. In the Security Provider page, under "Login Modules", choose Create.

3. In the Add Login Module page:

   • Specify your login module package and class name.

   • Specify a value for the login module control flag (from the dropdown list): Required, Requisite, Optional, or Sufficient. See Table 9-5, "Login Module Control Flags" for information about these settings.

   • As desired, choose Add Another Row to create properties.

   • As desired, edit the name or value of any property in the Properties list.

   • As desired, use the Delete task for a property to remove that property.

   • Choose OK to finish the change.

This takes you back to the Security Provider page, where you can examine the settings.

Updating a Login Module in the Custom Security Provider

Once you have established a custom security provider, either during or after deployment, you can update custom login modules as follows:

1. Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

2. In the Security Provider page, in the list of login module classes, choose the Edit task for the login module you want to update.

3. In the Edit Login Module page:

   • As desired, update the value for the login module control flag (from the dropdown list): Required, Requisite, Optional, or Sufficient. See Table 9-5, "Login Module Control Flags" for information about these settings.

   • As desired, choose Add Another Row to create properties.

   • As desired, edit the name or value of any property in the Properties list.

   • As desired, use the Delete task for a property to remove that property.

   • Choose Apply to finish the change.

This leaves you in the Edit Login Module page. You can use the breadcrumbs at the top of the page to go back to the Security Provider page.

Deleting a Login Module in the Custom Security Provider

Once you have established a custom security provider, either during or after deployment, you can delete custom login modules as follows:

1. Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

2. In the Security Provider page, in the list of login module classes, choose the Delete task for the login module you want to delete.

3. Choose Yes in the Confirmation page.

This takes you back to the Security Provider page, where you can see that the login module was deleted.

Configuring Login Modules through the Admintool

Although Application Server Control is the preferred and recommended tool for adding and configuring custom login modules, it is also possible to use the OracleAS JAAS Provider Admintool. The following information is presented for reference:

• -addloginmodule: Configures a new login module for the named application. This includes specifying a control flag: one of required, requisite, sufficient or optional, as specified by javax.security.auth.login.Configuration and in Table 9-5, "Login Module Control Flags".

  If the login module supports options, specify each option and its value as an optionname=value pair. Each login module has its own individual set of options.

  For example, to add MyLoginModule, which we will assume supports a debug option, to the application myapp as a required module with debug set to true:

  % java -jar jazn.jar -addloginmodule myapp MyLoginModule required debug=true
  
  

• -remloginmodule: Removes the specified login module.

  To remove MyLoginModule from myapp:

  % java -jar jazn.jar -remloginmodule myapp MyLoginModule
  
  

• -listloginmodules: Displays all login modules for a specified application, or, if no application name is specified, displays login modules for all applications. Specifying a login module class after the application name displays information on only the specified class within the application.

  For example, to display all login modules for the application myapp:

  % java -jar jazn.jar -listloginmodules myapp
  
  

You can also execute these commands from the Admintool shell.

Granting RMI Permission through the Admintool

In case your application includes EJBs, note that to access an EJB through RMI, you must grant RMI permission "login" to the appropriate user, role, or principal. You can accomplish this through the Admintool, as in the following examples:

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

% java -jar jazn.jar -grantperm oracle.security.jazn.samples.SamplePrincipal \
       managers com.evermind.server.rmi.RMIPermission login

(Always specify a realm when granting permissions to a user or role, but not when granting permissions to a principal.)

If you are in an Oracle Application Server environment with multiple OC4J instances, then you must specify the appropriate instance name (and hence the appropriate home directory) for the applicable OC4J instance, so that the system-jazn-data.xml file for the appropriate OC4J instance is updated. Set %oracleas.oc4j.instance% appropriately for your environment.

% java -jar -Doracle.j2ee.home=%ORACLE_HOME%/j2ee/%oracleas.oc4j.instance% \
       jazn.jar -grantperm myrealm -role managers \
       com.evermind.server.rmi.RMIPermission login 

% java -jar -Doracle.j2ee.home=%ORACLE_HOME%/j2ee/%oracleas.oc4j.instance% \
       jazn.jar -grantperm oracle.security.jazn.samples.SamplePrincipal managers \
       com.evermind.server.rmi.RMIPermission login 

Login Module Settings in system-jazn-data.xml

The system-jazn-data.xml file is the repository for login module configuration.

Note that settings in system-jazn-data.xml are updated automatically when you administer login modules through Application Server Control or the OracleAS JAAS Provider Admintool.

The <jazn-loginconfig> element contains information that associates applications with login modules.

If this information is in the orion-application.xml file during deployment, as discussed in "Settings in <jazn-loginconfig> in orion-application.xml", the system-jazn-data.xml file will be updated accordingly.

<jazn-data>
  ..
  <jazn-loginconfig>
    <application>
      <name>myapp</name>
      <login-modules>
        <login-module>
          <class>mypath.MyLoginModule</class>
          <control-flag>required</control-flag>
          <options>
            <option>
              <name>myoptionname</name>
              <value>myoptionvalue</value>
            </option>
          </options>
        </login-module>
      </login-modules>
    </application>
  </jazn-loginconfig> 
  ..
</jazn-data>

This fragment associates the login module MyLoginModule with the application myapp.

Login Modules Settings in orion-application.xml

This section discusses particular settings for login modules in the OC4J application-level descriptor orion-application.xml. The following topics are covered:

• Settings in <jazn-loginconfig> in orion-application.xml

• Settings in <jazn> for Login Modules

• Settings in <namespace-access> for Access to JNDI Context

<jazn provider="XML" ... >
   <property name="role.mapping.dynamic" value="true" />
   <property name="custom.loginmodule.provider" value="true" />
</jazn>

<orion-application ... >
   ...
   <namespace-access>
      <read-access>
         <namespace-resource root="">
            <security-role-mapping name="sr_developer">
               <group name="developers"/>
            </security-role-mapping>
            <security-role-mapping name="sr_manager">
               <group name="managers"/>
            </security-role-mapping>
         </namespace-resource>
      </read-access>
   </namespace-access>
   ...
</orion-application>

Login Module Settings in oc4j-ra.xml (J2EE Connector Architecture)

When you configure resource adapters, each <connector-factory> element in the oc4j-ra.xml file can specify a different JAAS login module, as in the following example. This also shows <config-property> setup to connect to a database through Oracle JDBC.

<oc4j-connector-factories ... >
  ...
  <connector-factory connector-name="myBlackbox" location="eis/myEIS1"> 
     <config-property name="connectionURL"
                      value="jdbc:oracle:thin:@localhost:5521/myservice" />
     <security-config use="jaas-module">
        <jaas-module>
           <jaas-application-name>JAASModuleDemo</jaas-application-name>
        </jaas-module>
     </security-config>
  </connector-factory>
  ...
</oc4j-connector-factories>

Develop the Login Module

Develop a JAAS-compliant LoginModule implementation according to the JAAS service provider interface.

When a login module is associated with an application (which occurs in the <jazn-loginconfig> configuration shown earlier), OC4J uses the principals set in the subject to determine if the client has access to the requested J2EE resource. Thus, it is imperative that the login module correctly set all the roles the user is a member of.

In the following example, the login module authenticates the developer user. After the user is successfully authenticated, a principal corresponding to the roles associated with the user is added to the current authenticated subject. Assume the developer user is a member of the developers role.

if(username.equals("developer") && password.equals("welcome")) 
{
   _succeeded = true;
   _name = "developer";
   _password = password.toCharArray();
   _authPrincipals = new SamplePrincipal[2];
   //Adding username as principal to the subject
   _authPrincipals[0] = new SamplePrincipal("developer");
   //Adding role developers to the subject
   _authPrincipals[1] = new SamplePrincipal("developers");
}

Configure and Package the Login Module

"Summary of Choices for Packaging Login Modules" summarizes the various ways you can package a login module so that it is accessible to your application. The choices are:

• Package the login module with the application.

• Provide the login module as an optional package.

• Provide the login module as an OC4J shared library.

There are also choices for how you can specify the configuration of a login module:

• Manually configure the <jazn-loginconfig> element in your orion-application.xml file, as discussed in "Settings in <jazn-loginconfig> in orion-application.xml". This may be particularly appropriate if you are packaging the login module with your application. The <jazn-loginconfig> element in system-jazn-data.xml is updated accordingly.

• Use the Application Server Control Console to specify the login module settings, such as when you deploy your application, as discussed in "Configuring the Custom Security Provider in Application Server Control". The <jazn-loginconfig> element in system-jazn-data.xml is configured automatically.

• Use the OracleAS JAAS Provider Admintool to specify the login module settings, as discussed in "Using Admintool to Configure Login Modules and Grant RMI Permission". The <jazn-loginconfig> element in system-jazn-data.xml is configured automatically.

The following sections highlight key configuration details.

<jazn provider="XML" > 
   <property name="role.mapping.dynamic" value="true"/> 
   <property name="custom.loginmodule.provider" value="true"/>
</jazn>

<!-- Configuring a Login Module in an Application EAR file.  -->
<jazn-loginconfig>
  <application>
    <name>cutomjaas</name>
    <login-modules>
      <login-module>
        <class>oracle.security.jazn.samples.SampleLoginModule</class>
        <control-flag>required</control-flag>
        <options>
          <option>
            <name>debug</name>
            <value>true</value>
          </option>
        </options>
      </login-module>
    </login-modules>
  </application>
</jazn-loginconfig>

Configure Namespace Access and Role Mappings (as applicable)

Configure namespace access in orion-application.xml if the application includes any EJBs. This is to allow remote client access to JNDI bindings for read (lookup) or write (bind) operations as required on objects in the server-side JNDI context of the application. The following example shows how the namespace access is granted to roles named managers and developers.

<orion-application ... >
   ...
   <namespace-access>
      <read-access>
         <namespace-resource root="">
            <security-role-mapping name="sr_developer">
               <group name="developers"/>
            </security-role-mapping>
            <security-role-mapping name="sr_manager">
               <group name="managers"/>
            </security-role-mapping>
         </namespace-resource>
      </read-access>
   </namespace-access>
   ...
</orion-application>

This assumes the role mappings—mapping logical roles defined in the application to roles supported by the custom login module—have been properly defined, as in the following example from orion-application.xml:

<orion-application ... >
   ...
   <!-- Mapping the logical roles to the container roles -->
   <security-role-mapping name="sr_manager">
      <group name="managers" />
   </security-role-mapping>
   <security-role-mapping name="sr_developer">
      <group name="developers" />
   </security-role-mapping>
   ...
</orion-application>

You can specify role mappings through Application Server Control, as discussed in "Mapping Security Roles". This results in the orion-application.xml entries being added automatically.

Deploy the Login Module

"Summary of Choices for Packaging Login Modules" discusses how you can deploy your login module either with your application or separately (as an optional package or shared library).

"Specifying and Configuring a Custom Security Provider during Deployment" discusses how to configure and deploy your login module through Application Server Control when you deploy your application.

Grant RMI Permission (as applicable)

If your application includes EJBs, be aware that to access an EJB through RMI, you must grant RMI permission "login" to the appropriate users, roles, and principals. You can accomplish this through the Admintool, as shown in "Granting RMI Permission through the Admintool".

Set JNDI Properties (as applicable)

To access resources through JNDI, you must configure the jndi.properties file to set properties such as the provider URL, principal, and credential, as appropriate for your environment. Here is an example:

java.naming.factory.initial=
                    oracle.j2ee.naming.ApplicationClientInitialContextFactory
java.naming.provider.url=ormi://localhost:23791/customjaas
#java.naming.provider.url=opmn:ormi://localhost:6003:home/customjaas
java.naming.security.principal=manager
java.naming.security.credentials=welcome

(The ormi protocol is for standalone OC4J, while the opmn:ormi protocol is for an Oracle Application Server environment. Uncomment the appropriate one.)

SampleLoginModule Code

This section contains the code for the sample login module.

package oracle.security.jazn.samples;
 
import java.util.Set;
import java.util.Iterator;
import java.util.Map;
import java.security.Principal;
import javax.security.auth.Subject;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.login.LoginException;
import javax.security.auth.spi.LoginModule;
 
public class SampleLoginModule implements LoginModule {
 
    // initial state
    protected Subject _subject;
    protected CallbackHandler _callbackHandler;
    protected Map _sharedState;
    protected Map _options;
 
    // configuration options
    protected boolean _debug; 
 
    // the authentication status
    protected boolean _succeeded;
    protected boolean _commitSucceeded;
 
    // username and password
    protected String _name;
    protected char[] _password;
 
    protected Principal[] _authPrincipals;
 
    /*
     * Initialize this LoginModule.
     *
     * subject         the Subject to be authenticated.
     * callbackHandler a CallbackHandler for communicating
     *                 with the end user (prompting for usernames and
     *                 passwords, for example).
     * sharedState     shared LoginModule state.
     * options         options specified in the login
     *                 Configuration for this particular
     *                 LoginModule.
     */
    public void initialize(Subject subject,
                           CallbackHandler callbackHandler,
                           Map sharedState,
                           Map options) {
        this._subject = subject;
        this._callbackHandler = callbackHandler;
        this._sharedState = sharedState;
        this._options = options;
 
        // initialize any configured options
        _debug = "true".equalsIgnoreCase((String) _options.get("debug"));
 
        if (debug()) {
            printConfiguration(this);
        }
    }
 
    final public boolean debug() {
        return _debug;
    }
 
    protected Principal[] getAuthPrincipals() {
        return _authPrincipals;
    }
 
    /*
     * Authenticate the user by prompting for a username and password.
     *
     * return true if the authentication succeeded, or false if this
     *        LoginModule should be ignored.
     * throws FailedLoginException if the authentication fails.
     * throws LoginException       if this LoginModule
     *                             is unable to perform the authentication.
     */
    public boolean login() throws LoginException {
        if (debug())
            System.out.println("\t\t[SampleLoginModule] login");
 
        if (_callbackHandler == null)
            throw new LoginException("Error: no CallbackHandler available " +
                    "to garner authentication information from the user");
 
        // Setup default callback handlers.
        Callback[] callbacks = new Callback[] {
            new NameCallback("Username: "),
            new PasswordCallback("Password: ", false)
        };
 
        try {
            _callbackHandler.handle(callbacks);
        } catch (Exception e) {
            _succeeded = false;
            throw new LoginException(e.getMessage());
        }
 
        String username = ((NameCallback)callbacks[0]).getName();
        String password = 
                   new String(((PasswordCallback)callbacks[1]).getPassword());
 
        if (debug())
        {
            System.out.println("\t\t[SampleLoginModule] username : " + username);
        }
 
        // Authenticate the user. On successfull authentication add principals 
        // to the Subject. The name of the principal is used for authorization by
        // OC4J by mapping it to the value of the name attribute of the group 
        // element in the security-role-mapping for the application.
        if(username.equals("developer") && password.equals("welcome")) 
        {
            _succeeded = true;
            _name = "developer";
            _password = password.toCharArray();
            _authPrincipals = new SamplePrincipal[2];
            //Adding username as principal to the subject
            _authPrincipals[0] = new SamplePrincipal("developer");
            //Adding role developers to the subject
            _authPrincipals[1] = new SamplePrincipal("developers");
        }
        if(username.equals("manager") && password.equals("welcome")) 
        {
            _succeeded = true;
            _name = "manager";
            _password = password.toCharArray();
            _authPrincipals = new SamplePrincipal[3];
            //Adding username as principal to the subject
            _authPrincipals[0] = new SamplePrincipal("manager");
            //Adding roles developers and managers to the subject
            _authPrincipals[1] = new SamplePrincipal("developers");
            _authPrincipals[2] = new SamplePrincipal("managers");
        }
 
      if (username.equals("sirish") && password.equals("sirish"))
      {
            _succeeded = true;
            _password = password.toCharArray();
            _name = "sirish";
            _authPrincipals = new SamplePrincipal[1];
            _authPrincipals[0] = new SamplePrincipal("sirish");
       }
 
        ((PasswordCallback)callbacks[1]).clearPassword();
        callbacks[0] = null;
        callbacks[1] = null;
 
        if (debug())
        {
            System.out.println("\t\t[SampleLoginModule] success : " + _succeeded);
        }
 
        if (!_succeeded)
            throw new LoginException
                            ("Authentication failed: Password does not match");
 
        return true; 
    }
 
    /*
     * This method is called if the LoginContext's
     * overall authentication succeeded
     * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
     * succeeded).
     * 
     * If this LoginModule's own authentication attempt
     * succeeded (checked by retrieving the private state saved by the
     * login method, then this method associates a
     * Principal with the Subject located in the
     * LoginModule.  If this LoginModule's own
     * authentication attempted failed, then this method removes
     * any state that was originally saved.
     *
     * return true if this LoginModule's own login and commit
     *        attempts succeeded, or false otherwise.
     * throws LoginException if the commit fails.
     */
    public boolean commit()
            throws LoginException {
        try {
 
            if (_succeeded == false) {
                return false;
            }
 
            if (_subject.isReadOnly()) {
                throw new LoginException("Subject is ReadOnly");
            }
 
            // add authenticated principals to the Subject
            if (getAuthPrincipals() != null) {
                for (int i = 0; i < getAuthPrincipals().length; i++) {
                    if(!_subject.getPrincipals().contains(getAuthPrincipals()[i]))
{
                        _subject.getPrincipals().add(getAuthPrincipals()[i]);
                    }
                }
            }
 
            // in any case, clean out state
            cleanup();
            if (debug()) {
                printSubject(_subject);
            }
 
            _commitSucceeded = true;
            return true;
 
        } catch (Throwable t) {
            if (debug()) {
                System.out.println(t.getMessage());
                t.printStackTrace();
            }
            throw new LoginException(t.toString());
        }
    }
 
    /*
     * This method is called if the LoginContext's
     * overall authentication failed.
     * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
     * did not succeed).
     * 
     * If this LoginModule's own authentication attempt
     * succeeded (checked by retrieving the private state saved by the
     * login and commit methods),
     * then this method cleans up any state that was originally saved.
     *
     * return false if this LoginModule's own login and/or commit attempts
     *        failed, and true otherwise.
     * throws LoginException if the abort fails.
     */
    public boolean abort() throws LoginException {
        if (debug()) {
            System.out.println
                     ("\t\t[SampleLoginModule] aborted authentication attempt.");
        }
 
        if (_succeeded == false) {
            cleanup();
            return false;
        } else if (_succeeded == true && _commitSucceeded == false) {
            // login succeeded but overall authentication failed
            _succeeded = false;
            cleanup();
        } else {
            // overall authentication succeeded and commit succeeded,
            // but someone else's commit failed
            logout();
        }
        return true;
    }
 
    protected void cleanup() {
        _name = null;
        if (_password != null) {
            for (int i = 0; i < _password.length; i++) {
                _password[i] = ' ';
            }
            _password = null;
        }
    }
 
    protected void cleanupAll() {
        cleanup();
 
        if (getAuthPrincipals() != null) {
            for (int i = 0; i < getAuthPrincipals().length; i++) {
                _subject.getPrincipals().remove(getAuthPrincipals()[i]);
            }
        }
    }
 
    /*
     * Logout the user.
     * 
     * This method removes the Principal
     * that was added by the commit method.
     *
     * return true in all cases since this LoginModule
     *        should not be ignored.
     * throws LoginException if the logout fails.
     */
    public boolean logout() throws LoginException {
        _succeeded = false;
        _commitSucceeded = false;
        cleanupAll();
        return true;
    }
 
    // helper methods //
 
    protected static void printConfiguration(SampleLoginModule slm) {
        if (slm == null) {
            return;
        }
        System.out.println("\t\t[SampleLoginModule] configuration options:");
        if (slm.debug()) {
            System.out.println("\t\t\tdebug = " + slm.debug());
        }
    }
 
    protected static void printSet(Set s) {
        try {
            Iterator principalIterator = s.iterator();
            while (principalIterator.hasNext()) {
                Principal p = (Principal) principalIterator.next();
                System.out.println("\t\t\t" + p.toString());
            }
        } catch (Throwable t) {
        }
    }
 
    protected static void printSubject(Subject subject) {
        try {
            if (subject == null) {
                return;
            }
            Set s = subject.getPrincipals();
            if ((s != null) && (s.size() != 0)) {
                System.out.println
                     ("\t\t[SampleLoginModule] added the following Principals:");
                printSet(s);
            }
 
            s = subject.getPublicCredentials();
            if ((s != null) && (s.size() != 0)) {
                System.out.println
              ("\t\t[SampleLoginModule] added the following Public Credentials:");
                printSet(s);
            }
        } catch (Throwable t) {
        }
    }
}

SamplePrincipal Code

This section contains the code for the sample principal.

The login module sets the SamplePrincipal instance in the current Subject instance. To create the SamplePrincipal instance, the login module directly invokes the SamplePrincipal constructor, so the constructor is defined as public.

package oracle.security.jazn.samples;
 
import java.security.Principal;
 
/*
 * This class implements the Principal interface
 * and represents a Sample user.
 *
 * Principals such as this SamplePrincipal
 * may be associated with a particular Subject
 * to augment that Subject with an additional
 * identity.  Authorization decisions can then be based upon 
 * the Principals associated with a Subject.
 * 
 */ 
public class SamplePrincipal implements Principal {
 
    private String _name = null;
        
 
    /*
     * Create a SamplePrincipal with a Sample username.
     *
     */ 
    public SamplePrincipal(String name) {
       if (name == null) 
       throw new NullPointerException("name cannot be null");
        _name = name;
    }
 
    /*
     * Return a string representation of this SamplePrincipal.
     *
     */
    public String getName() {
        return _name;
    }
 
    /*
     * Return a hash code for this SamplePrincipal.
     *
     */
    public int hashCode() {
        return _name.hashCode();
    }
 
    /*
     * Return a string representation of this SamplePrincipal.
     *
     */
    public String toString() {
        return "[SamplePrincipal] : " + _name;
    }
 
    /*
     * Compares the specified Object with this SamplePrincipal
     * for equality.  Returns true if the given object is also a
     * SamplePrincipal and the two SamplePrincipals
     * have the same username.
     *
     */
    public boolean equals(Object o) {
      if (o == null)
          return false;
 
        if (this == o)
            return true;
 
        if (!(o instanceof SamplePrincipal))
            return false;
        SamplePrincipal that = (SamplePrincipal)o;
 
      if (this.getName().equals(that.getName()))
          return true;
      return false;
    }
}