Thursday Jan 08, 2009

Modularized OSGi Custom Realms in Glassfish v3

The Open Services Gateway Initiative (OSGi) defines an architecture for developing and deploying modular applications and libraries. Since Glassfish v3 is a modular, embeddable and an OSGi compliant  server, custom realms that are built based on the OSGi framework can be easily integrated and configured with GF v3.This facilitates the creation and configuration of a custom realm without any server restart.

 To be recognized as a valid custom realm  OSGi module, in addition to the OSGi mandated structure, the custom realm  should include the following:

i)The Realm class should include the @Service annotation, with the name attribute referring to the name of the custom realm to be configured:


where @Service is a hk2-specific annotation.

ii) There should be a file named  inside META-INF/services directory of the module archive file. The file should specify the fully qualified name of the Custom Login Module class as in:


A sample OSGi custom realm module can be downloaded from here. On dropping this file in <GF-HOME>/autodeploy-bundles directory, the module should be loaded. Do make sure   that the <GF-HOME>/<DOMAIN-DIR>/login.conf file has an entry for the jaas-context value, referring to the Module implementation class. This entry can be dynamically added to login.conf(before creating the realm). (This post provides a detailed description on creating a custom realm for GF.)

The realm can now be created from the admin console (name matching the service name specified in the Realm class). This should initialize the realm. No server restart required. On deploying and accessing an application utilizing this realm, the Login module should be initialized as well.This feature works with the latest GF v3 trunk installation.

Monday Dec 29, 2008

Custom Realms and Groups in Glassfish

Glassfish  provides support for Custom Realms and Custom Login Modules that are based on the JAAS framework. This post explains how to write a simple Realm class and its corresponding LoginModule, configure them with an illustration of a simple web application that uses this realm.

Custom Realm

The Custom Realm should extend The Realm class is basically meant to provide user and group-related information. The methods to be implemented are

i) public void init(Properties properties )throws BadRealmException, NoSuchRealmException

This method is invoked during server startup when the realm is initially loaded.  The realm can do any initialization it needs in this method. The Properties is a set of key-value pairs configured while creating the Realm and are present in domain.xml. Among the other custom properties, there is a property jaas-context (which is explained later in this post). This property should be set using the call setProperty method implemented in the parent class. 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.

ii) public String getAuthType() - This method returns a descriptive string representing the type of authentication done by this realm.

iii) public Enumeration getGroupNames(String user) throws InvalidOperationException, NoSuchUserException -
This method returns the group names the user belongs to as an Enumeration of Strings.

Custom LoginModule

The Custom LoginModule should extend This class should override the method

abstract protected void authenticateUser() throws LoginException

This method performs the actual custom authentication, by either using a database, or LDAP or a file or even a simple Hashtable as illustrated in the attached sample code. 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, password of the user to be authenticated and the currentRealm class.

protected String _username;

protected String _password;

protected  _currentRealm;

The authenticateUser() method should end with a call to the commitUserAuthentication(String[] authenticatedGroupList) method where the authenticatedGroupList is the list of groups the user belongs to.

As can be observed, the realm class is isolated from the LoginModule. The Realm is capable of capturing arbitrary configuration information and can help in obtaining the Group information. The Group information from the Realm can be  populated into the authenticated JAAS subject during commit() phase following a  successful LoginContext.login() call on the  authentication module. This populated group information is then used by the container in its authorization policy decisions.

Attached here is the source code of a simple sample realm class and the custom module. In this example, the Realm class stores the user-group information in a hashtable. The LoginModule class stores the user-password information in a hashtable and performs authentication. It obtains the authenticatedGroupList from the Realm class' getGroups(username) method.

To test this sample(it works with both GF v2 and v3), download and install Glassfish v3 from here, drop the binaries of this realm and custom module in <GF-ROOT>/domains/domain1/lib/, start the server and create the realm using the Admin console. The realm classname should be specified as com.samplerealm.SampleRealm.

An additional realm property jaas-context should be specified to say sampleRealm. This value should refer to the SampleLoginModule class in the


file as follows:

sampleRealm {
       com.samplerealm.SampleLoginModule required;

where sampleRealm refers to the value defined in the jaas-context property.

As can be seen from the source files, the users configured in this realm are userA, userB whose corresponding passwords are abc123, xyz123. userA has been configured in the group devGroup, while userB belongs to testGroup. To test this realm, this web-application can be used.

Observe that the web.xml of the web-app contains the following :


where  SampleRealm in the <login-conf><realm-name> element points to the name of the configured Realm as can be seen in the server's domain.xml

        <auth-realm classname="com.samplerealm.SampleRealm" name="SampleRealm">
          <property name="jaas-context" value="sampleRealm"></property>

To access the web-app using the group names of the user, the following mapping between the role and group is required in sun-web.xml:


where the role-name matches the configured role in the auth-constraint of web.xml


and group-name is the corresponding group the user belongs to as defined in the custom realm class. So if the application is accessed using the user/password: userA/abc123, the user is authorized to view the pages, since he belongs to the devGroup, but not userB/xyz123 (who belongs to testGroup).




« February 2017