JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server 3.1 Application Development Guide
search filter icon
search icon

Document Information


Part I Development Tasks and Tools

1.  Setting Up a Development Environment

2.  Class Loaders

3.  Debugging Applications

Part II Developing Applications and Application Components

4.  Securing Applications

Security Goals

GlassFish Server Specific Security Features

Container Security

Declarative Security

Application Level Security

Component Level Security

Programmatic Security

Roles, Principals, and Principal to Role Mapping

Realm Configuration

Supported Realms

How to Configure a Realm

How to Set a Realm for an Application or Module

Creating a Custom Realm

JACC Support

Pluggable Audit Module Support

Configuring an Audit Module

The AuditModule Class

The server.policy File

Default Permissions

System Properties

Changing Permissions for an Application

Enabling and Disabling the Security Manager

Configuring Message Security for Web Services

Message Security Providers

Message Security Responsibilities

Application Developer Responsibilities

Application Deployer Responsibilities

System Administrator Responsibilities

Application-Specific Message Protection

Using a Signature to Enable Message Protection for All Methods

Configuring Message Protection for a Specific Method Based on Digital Signatures

Understanding and Running the Sample Application

To Set Up the Sample Application

To Run the Sample Application

Programmatic Login

Programmatic Login Precautions

Granting Programmatic Login Permission

The ProgrammaticLogin Class

User Authentication for Single Sign-on

Adding Authentication Mechanisms to the Servlet Container

The GlassFish Server and JSR 196

Writing a Server Authentication Module

Sample Server Authentication Module

Compiling and Installing a Server Authentication Module

Configuring a Server Authentication Module

Binding a Server Authentication Module to Your Application

5.  Developing Web Services

6.  Using the Java Persistence API

7.  Developing Web Applications

8.  Using Enterprise JavaBeans Technology

9.  Using Container-Managed Persistence

10.  Developing Java Clients

11.  Developing Connectors

12.  Developing Lifecycle Listeners

13.  Developing OSGi-enabled Java EE Applications

Part III Using Services and APIs

14.  Using the JDBC API for Database Access

15.  Using the Transaction Service

16.  Using the Java Naming and Directory Interface

17.  Using the Java Message Service

18.  Using the JavaMail API


Realm Configuration

The following topics are addressed here:

Supported Realms

The following realms are supported in the current release of the GlassFish Server:

For information about configuring realms, see How to Configure a Realm.

How to Configure a Realm

You can configure a realm in one of these ways:

How to Set a Realm for an Application or Module

The following deployment descriptor elements have optional realm or realm-name data subelements or attributes that override the domain’s default realm:

If modules within an application specify realms, these are ignored. If present, the realm defined in glassfish-application.xml is used, otherwise the domain’s default realm is used.

For example, a realm is specified in glassfish-application.xml as follows:


For more information about the deployment descriptor files and elements, see Appendix C, Elements of the GlassFish Server Deployment Descriptors, in Oracle GlassFish Server 3.1 Application Deployment Guide.

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

For general information about realms and login modules, see Working with Realms, Users, Groups, and Roles in The Java EE 6 Tutorial.

For Javadoc tool pages relevant to custom realms, go to and click on the package.

Custom login modules must extend the class. This class implements 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 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 class and 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. 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.

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.

Custom realms that manage users must implement the following additional methods:

public abstract boolean supportsUserManagement();

This method returns true if the realm supports user management.

public abstract Enumeration getGroupNames() throws BadRealmException;

This method returns an Enumeration of all group names.

public abstract Enumeration getUserNames() throws BadRealmException;

This method returns an Enumeration of all user names.

public abstract void refresh() throws BadRealmException;

This method refreshes the realm data so that new users and groups are visible.

public abstract void persist() throws BadRealmException;

This method persists the realm data to permanent storage.

public abstract User getUser(String name) throws NoSuchUserException, 

This method returns the information recorded about a particular named user.

public abstract void addUser(String name, String password, String[] groupList) throws 
BadRealmException, IASSecurityException;

This method adds a new user, who cannot already exist.

public abstract void removeUser(String name) throws NoSuchUserException, 

This method removes a user, who must exist.

public abstract void updateUser(String name, String newName, String password, 
String[] groups) throws NoSuchUserException, BadRealmException, IASSecurityException;

This method updates data for a user, who must exist.

Note - 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.