On the Application Server, the following options are configured
using the Admin Console:

A realm is a complete database of users and groups that identify valid users
of a web application (or a set of web applications) and are controlled by
the same authentication policy. For more information, read What Is a Realm?.

A user is an individual (or application program) identity that has been
defined in the Application Server. On the Application Server, a user generally
has a user name, a password, and, optionally, a list of groups to
which this user has been assigned. For more information, read What Is a User?.

A group is a set of authenticated users, classified by common traits, defined in the Application
Server. For more information, read What Is a Group?.

A principal is an entity that can be
authenticated by an authentication protocol in a security service that is
deployed in an enterprise.

During deployment, the deployer takes the information provided
in the application deployment descriptor and maps the roles specified for
the application to users and groups defined on the server using the Application
Server deployment descriptors sun-web.xml, sun-ejb-jar.xml, or sun-application.xml.

Declaring Security Roles

You can declare security role names used in web applications using
either the @DeclareRoles annotation (preferred) or the security-role-ref elements of the deployment descriptor. Declaring
security role names in this way enables you to link the security role names
used in the code to the security roles defined for an assembled application.
In the absence of this linking step, any security role name used in the code
will be assumed to correspond to a security role of the same name in the assembled
application.

A
security role reference, including the name defined by the reference, is scoped
to the component whose class contains the @DeclareRoles annotation
or whose deployment descriptor element contains the security-role-ref deployment
descriptor element.

You can also use the security-role-ref elements for
those references that were declared in annotations and you want to have linked
to a security-role whose name differs from the reference
value. If a security role reference is not linked to a security role in this
way, the container must map the reference name to the security role of the
same name. See Declaring and Linking Role References for
a description of how security role references are linked to security roles.

For an example using each of these methods, read the following sections:

Specifying Security Roles Using Annotations

Annotations are the best way to define security roles on a class or
a method. The @DeclareRoles annotation is used to define
the security roles that comprise the security model of the application. This
annotation is specified on a class, and it typically would be used to define
roles that could be tested (for example, by calling isUserInRole)
from within the methods of the annotated class.

Following is an example of how this annotation would be used. In this
example, employee is the only security role specified,
but the value of this parameter can include a list of security roles specified
by the application.

@DeclareRoles("employee")
public class CalculatorServlet {
//...
}

Specifying @DeclareRoles("employee") is equivalent
to defining the following in the web.xml:

<security-role>
<role-name>employee</role-name>
</security-role>

This annotation is not used to link application roles to other roles.
When such linking is necessary, it is accomplished by defining an appropriate security-role-ref in the associated deployment descriptor, as described
in Declaring and Linking Role References.

When a call is made to isUserInRole from the annotated
class, the caller identity associated with the invocation of the class is
tested for membership in the role with the same name as the argument to isUserInRole. If a security-role-ref has been
defined for the argument role-name, the caller is tested
for membership in the role mapped to the role-name.

Specifying Security Roles Using Deployment Descriptor
Elements

The following snippet of a deployment descriptor is taken from the simple sample application. This snippet includes all of the elements
needed to specify security roles using deployment descriptors:

In this example, the security-role element lists
all of the security roles used in the application: role1 and employee. This enables the deployer to map all of the roles defined
in the application to users and groups defined on the Application Server.

The auth-constraint element specifies the roles (role1, employee) that can access HTTP methods
(PUT, DELETE, GET, POST) located in the directory specified by the url-pattern element
(/jsp/security/protected/*). You could also have used the @DeclareRoles annotation in the source code to accomplish this task.

The security-role-ref element is used when an application
uses the HttpServletRequest.isUserInRole(String role) method.
The value of the role-name element must be the String used as the parameter to the HttpServletRequest.isUserInRole(String
role) method. The role-link must contain the
name of one of the security roles defined in the security-role elements.
The container uses the mapping of security-role-ref to security-role when determining the return value of the call.

Mapping Security Roles to Application Server Groups

To map security roles to application server principals and groups, use
the security-role-mapping element in the runtime deployment
descriptor (DD). The runtime deployment descriptor is an XML file that contains
information such as the context root of the web application and the mapping
of the portable names of an application’s resources to the Application
Server’s resources. The Application Server web application runtime DD
is located in /WEB-INF/ along with the web application
DD. Runtime deployment descriptors are named sun-web.xml, sun-application.xml, or sun-ejb-jar.xml.

A role can be mapped to specific principals, specific groups, or both.
The principal or group names must be valid principals or groups in the current
default realm. The role-name element must match the role-name in the security-role element of the corresponding
application deployment descriptor (web.xml, ejb-jar.xml) or the role name defined in the @DeclareRoles annotation.