This section covers the following topics:
The following realms are supported in the current release of the Enterprise Server:
In the JDBC realm, the server gets user credentials from a database. The Enterprise Server uses the database information and the enabled JDBC realm option in the configuration file. For digest authentication, a JDBC realm should be created with jdbcDigestRealm as the JAAS context.
The solaris realm is not supported in GlassFish v3 Prelude.
For information about configuring realms, see How to Configure a Realm.
You can configure a realm in one of these ways:
Use the asadmin create-auth-realm command to configure realms on local servers. For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
web-app element in web.xml
as-context element in sun-ejb-jar.xml
For more information about the deployment descriptor files and elements, see Appendix A, Deployment Descriptor Files, in Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.
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 Enterprise 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, then restart the server. For more information about class loading in the Enterprise 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/products/jaas/.
For general information about realms and login modules, see “Chapter 29: Introduction to Security in Java EE” in the Java EE 5 Tutorial.
For Javadoc tool pages relevant to custom realms, go to https://glassfish.dev.java.net/nonav/api/v3-prelude/index.html and click on the com.sun.appserv.security package.
Custom login modules must extend the com.sun.appserv.security.AppservPasswordLoginModule class. This class implements javax.security.auth.spi.LoginModule. Custom login modules must not implement 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 Enterprise 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);
public void init(Properties props) throws BadRealmException, NoSuchRealmException
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 Enterprise 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.
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.
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.