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


Roles, Principals, and Principal to Role Mapping

For applications, you define roles in @DeclareRoles annotations or the Java EE deployment descriptor file application.xml. You define the corresponding role mappings in the GlassFish Server deployment descriptor file glassfish-application.xml. For individually deployed web or EJB modules, you define roles in @DeclareRoles annotations or the Java EE deployment descriptor files web.xml or ejb-jar.xml. You define the corresponding role mappings in the GlassFish Server deployment descriptor files glassfish-web.xml or glassfish-ejb-jar.xml.

For more information regarding Java EE deployment descriptors, see the Java EE Specification. For more information regarding GlassFish Server deployment descriptors, see Appendix C, Elements of the GlassFish Server Deployment Descriptors, in Oracle GlassFish Server 3.1 Application Deployment Guide.

Each security-role-mapping element in the glassfish-application.xml, glassfish-web.xml, or glassfish-ejb-jar.xml file maps a role name permitted by the application or module to principals and groups. For example, a glassfish-web.xml file for an individually deployed web module might contain the following:


A role can be mapped to either specific principals or to groups (or both). The principal or group names used must be valid principals or groups in the realm for the application or module. Note that the role-name in this example must match the @DeclareRoles annotations or the role-name in the security-role element of the corresponding web.xml file.

You can also specify a custom principal implementation class. This provides more flexibility in how principals can be assigned to roles. A user's JAAS login module now can authenticate its custom principal, and the authenticated custom principal can further participate in the GlassFish Server authorization process. For example:

    <principal-name class-name="CustomPrincipalImplClass">

You can specify a default principal and a default principal to role mapping, each of which applies to the entire GlassFish Server instance. The default principal to role mapping maps group principals to the same named roles. Web modules that omit the run-as element in web.xml use the default principal. Applications and modules that omit the security-role-mapping element use the default principal to role mapping. These defaults are part of the Security Service, which you can access in the following ways: