Creating a Custom Realm

You can create a custom realm by providing a custom Java Authentication
and Authorization Service (JAAS) login module class and a custom realm
class. Note that client-side JAAS login modules are not suitable for
use with the GlassFish Server.

To activate the custom login modules and realms, place the JAR
files in the domain-dir/lib directory or the
class files in the domain-dir/lib/classes directory. For more information about class loading in the GlassFish Server,
see Chapter 2, Class Loaders.

JAAS is a set of APIs that enable services to authenticate
and enforce access controls upon users. JAAS provides a pluggable
and extensible framework for programmatic user authentication and
authorization. JAAS is a core API and an underlying technology for
Java EE security mechanisms. For more information about JAAS, refer
to the JAAS specification for Java SDK, available at http://java.sun.com/javase/technologies/security/.

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 GlassFish 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
commitUserAuthentication(_username, _password,
_currentRealm, grpList);

Custom
realms must extend the com.sun.appserv.security.AppservRealm class
and implement the following methods:

This method is invoked during server startup when the realm
is initially loaded. The props argument contains
the properties defined for this realm. The realm can do any initialization
it needs in this method. If the method returns without throwing an
exception, the GlassFish Server assumes that 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.

The array passed to the commitUseAuthentication method
should be newly created and otherwise unreferenced. This is because
the group name array elements are set to null after authentication
as part of cleanup. So the second time your custom realm executes
it returns an array with null elements.

Ideally, your
custom realm should not return member variables from the authenticate method. It should return local variables as the default JDBCRealm does. Your custom realm can create a local String array in its authenticate method,
copy the values from the member variables, and return the String array. Or it can use clone on
the member variables.