Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

Creating a Custom Realm

You can create a custom realm by providing a Java Authentication and Authorization Service (JAAS) login module and a realm implementation. Note that client-side JAAS login modules are not suitable for use with the Application Server. For more information about JAAS, refer to the JAAS specification for Java 2 SDK, v 1.4, available at

Custom realms must extend the class. This class extends Custom realms must not extend LoginModule directly.

Custom login modules must provide an implementation for one abstract method defined in AppservPasswordLoginModule:

abstract protected void authenticateUser() throws LoginException

This method performs the actual authentication. The custom login module must not implement any of the other methods, such as login(), logout(), abort(), commit(), or initialize(). Default implementations are provided in AppservPasswordLoginModule which hook into the Application Server infrastructure.

The custom login module can access the following protected object fields, which it inherits from AppservPasswordLoginModule. These contain the user name and password of the user to be authenticated:

protected String _username;
protected String _password;

The authenticateUser() method must end with the following sequence:

String[] grpList;
// populate grpList with the set of groups to which
// _username belongs in this realm, if any
return commitUserAuthentication(_username, _password, 
  _currentRealm, grpList);

Custom realms must also implement a Realm class which extends the class.

Custom realms must implement the following methods:

public void init(Properties props) throws BadRealmException, 

This method is invoked during server startup when the realm is initially loaded. The props argument contains the properties defined for this realm in domain.xml. The realm can do any initialization it needs in this method. If the method returns without throwing an exception, the Application Server assumes the realm is ready to service authentication requests. If an exception is thrown, the realm is disabled.

public String getAuthType()

This method returns a descriptive string representing the type of authentication done by this realm.

public abstract Enumeration getGroupNames(String username) throws 
InvalidOperationException, NoSuchUserException

This method returns an Enumeration (of String objects) enumerating the groups (if any) to which the given username belongs in this realm.